Using collections in queries

You can specify a collection in a query state.

The CollectionName element of the State type lets you specify the name of a collection to be used in a query. You can specify a maximum of one collection per state. However, you can use multiple states in a query, with each state potentially specifying a collection name.

Once you associate a collection with a state, then operations performed by that state will reference that collection. For example, a record search in a state with a collection name will search for records only in that collection. However, if the collection has one or more filter rules configured, then a SelectionFilter or SelectedRefinementFilter query will trigger that filter rule, which will make use of records in the target collection. For more information on filter rules (see Filter Rules).

The query syntax for specifying a collection name is:

<Request>
   ...
   <State>
      <Name>?</Name>
      <CollectionName>?<CollectionName>
      ...
   </State>
   ...
</Request>

where:

Name is the name of the state.
CollectionName is the name of an existing collection.

If you have a named state, you can then specify it in a ContentElementConfig in the query.

Example of using collections in queries

This query has one state (SalesRecs) that specifies the Sales collection and a second state (Resellers) associated with the Resellers collection. In addition, there is a filter rule that has the Sales collection as the source collection and the Resellers collection as the target collection. The RecordCountConfig type is associated with the SalesRecs state and will list the number of records from the query:

<Request xmlns="http://www.endeca.com/MDEX/conversation/3/0">
   <Language>en</Language>
   <State>
      <Name>SalesRecs</Name>
      <CollectionName>Sales</CollectionName>
      <SelectionFilter Id="SalesFltr">
         <filterString>FactSales_SalesAmount > 1000</filterString>
      </SelectionFilter>
   </State>
   <State>
      <Name>ResellerRecs</Name>
      <CollectionName>Resellers</CollectionName>
   </State>
   <RecordListConfig Id="Results">
      <StateName>SalesRecs</StateName>
   </RecordCountConfig>
</Request>

The results from the query may look like this abbreviated example:

<cs:Results ...>
   <State ...>
      <Name>SalesRecs</Name>
      <CollectionName>Sales</CollectionName>
      <DataSourceFilter>
         <filterString>"FactSales_ProductKey" IS NOT NULL</filterString>
      </DataSourceFilter>
      <SelectionFilter Id="SalesFltr">
         <filterString>FactSales_SalesAmount > 1000</filterString>
      </SelectionFilter>
   </State>
   <State ...>
      <Name>ResellerRecs</Name>
      <CollectionName>Resellers</CollectionName>
      <DataSourceFilter>
         <filterString>"DimReseller_ResellerKey" IS NOT NULL</filterString>
      </DataSourceFilter>
      <SelectionFilter>
         <filterString>"DimReseller_AnnualSales" > 1000</filterString>
         <AppliedFilterRule>
            <Source FilterId="SalesFltr">
               <StateName>SalesRecs</StateName>
            </Source>
            <TargetPropertyKey>DimReseller_AnnualSales</TargetPropertyKey>
         </AppliedFilterRule>
      </SelectionFilter>
   </State>
   <cs:RecordCount Id="Results">
      <cs:NumRecords>115</cs:NumRecords>
   </cs:RecordCount>
</cs:Results>

In the response, note that the ResellerRecs state shows that a SelectionFilter implicit filter was run on the Resellers collection. The AppliedFilterRule element lists the source (filter ID and state) of the implicit filter.

Note that if you specified a non-existent collection, the query will fail with this fault string:

<Fault>
   <faultcode>env:Server</faultcode>
   <faultstring>OES-000190: Collection 'Producs' does not exist.</faultstring>
   <detail>
      <Fault xmlns:ns2="http://www.endeca.com/MDEX/eql_parser/types" 
             xmlns:ns3="http://www.endeca.com/MDEX/conversation/3/0"/>
   </detail>
 </Fault>

Automatic addition of data source filter

During processing of a query, Endeca Server will automatically create and add a DataSourceFilter to all states that provide a collection name. The filter is similar to the example above:

<cs:Results ...>
   <State ...>
      <Name>ResellerRecs</Name>
      <CollectionName>Resellers</CollectionName>
      <DataSourceFilter>
         <filterString>"DimReseller_ResellerKey" IS NOT NULL</filterString>
      </DataSourceFilter>
      <SelectionFilter>
         <filterString>"DimReseller_AnnualSales" > 1000</filterString>
         <AppliedFilterRule>
            <Source FilterId="SalesFltr">
               <StateName>SalesRecs</StateName>
            </Source>
            <TargetPropertyKey>DimReseller_AnnualSales</TargetPropertyKey>
         </AppliedFilterRule>
      </SelectionFilter>
   </State>
   ...
</cs:Results>

The purpose of adding the DataSourceFilter with the collection's unique property key ("ProductKey" in the example) is to limit the search to the records in the collection.

Using collections in EQLConfig queries

A FROM clause in an EQL query cannot directly reference a collection, but it can reference a state. However, if the state specifies a collection name, then the collection can be used via the state.

This simple EQL query uses the EQLConfig type:

<Request>
   <Language>en</Language>
   <State>
      <Name>TotalSales</Name>
      <CollectionName>Sales</CollectionName>
   </State>
   <ns:EQLConfig Id="EQLQuery">
      <StateName>TotalSales</StateName>
      <EQLQueryString>
         RETURN Results AS
         SELECT ARB(FactSales_SalesAmount) AS totalAmount
         FROM TotalSales
         GROUP BY FactSales_OrderQuantity
      </EQLQueryString>
   </EQLConfig>
</Request>

The FROM clause specifies the TotalSales state as the source. Because the TotalSales state specifies the Sales collection, the records from that collection are used.