Examples of Conversation Web Service query requests

Each request to the Conversation Web Service consists of a filter state and a list of content element configurations and operators to compute. This topic provides examples showing the contents of a typical request.

This topic includes examples of:

Example of a record search

The following request is used for a record search query. In this example, state and content element configuration are not shown and only the Operator element is shown. Operator is the base type for various types of operators, such as ApplySpellingSuggestionOperator, RefinementOperator, and SearchOperator.

In this example, the Operator is used with SearchOperator type that is used to add a text search component to the filter state. It specifies the search interface that must be used, and also the search terms entered by the user in the front-end application.

The SearchOperator specifies the options for the SearchFilter element. For example, you must specify Key (representing the name of the standard attribute, managed attribute, or search interface to use) and the text value of this element (representing the actual user-entered search terms):
<Operator xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:type="SearchOperator" Within="false">
   <SearchFilter Mode="AllPartial" RelevanceRankingStrategy="numfields"
      Key="PROD_CATEGORY" EnableSnippeting="false" Language="en">
      electronics
   </SearchFilter>
</Operator>

In general, for the SearchFilter type of Operator, you can specify various aspects of your request configuration, such as the name of the configured search interface, the search mode, the relevance ranking strategy, the language of the query (to be used for spelling correction, for example), and whether to enable snippeting.

Similarly, for other types of Operator, you can specify options of their own. For instance, for the RecordKindOperator, you can specify the record type on which the query will operate.

To remove an operator from the filter state, you can use PopName_of_operatorOperator, where Name_of_operator is the name of the operator that you want to remove, such as SearchOperator.

For more information on value search, search modes, and relevance ranking, see the dedicated sections in this guide. For more information on the detailed syntax of various types of operators, see the Oracle Endeca Server API Reference for the Conversation Web Service.

Example of retrieving a record list

The following example contains all three elements of a Conversation Web Service request — state, operator and content element configuration. This example uses the previously computed State to filter records, and then requests a list of those records. In this example of a query:
  • The filter State is represented by two record filters — SelectedRefinementFilter that narrows the record set to those records whose DimDate_MonthName attribute's value is May, and those records which contain the word "mountain".
  • The Operator element contains the RecordKind operator with the value data. This indicates that the request is aiming to request refinements among the records that represent the actual user's source data records (and not any other records, such as system or schema records).
  • The ContentElementConfig is of type RecordListConfig, which lets you request a list of records, and optionally specify the page and the number of records per page.
<Request xmlns:ns2="http://www.endeca.com/MDEX/lql_parser/types" 
    xmlns="http://www.endeca.com/MDEX/conversation/2/0">
  <State>
    <SelectedRefinementFilter Name="DimDate_MonthName" Spec="May"/>
    <SearchFilter Key="All">mountain</SearchFilter>
  </State>
  <Operator xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="RecordKindOperator">
    <RecordKind>data</RecordKind>
  </Operator>
  <ContentElementConfig xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
     xsi:type="RecordListConfig" 
     Id="RecordList" HandlerNamespace="http://www.endeca.com/MDEX/conversation/handlers/2010" 
     HandlerFunction="RecordListHandler">
     <RecordsPerPage>2</RecordsPerPage>
     <Page>0</Page>
   </ContentElementConfig>
</Request>

Example of retrieving refinements

The following example also contains all three elements of a Conversation Web Service request — state, operator and content element configuration. This example uses the previously computed State to first request a list of available refinements on filtered records, and then to compute and list the individual records under these refinements.

In this example:
  • The filter State is represented by two record filters, as in the previous example.
  • The Operator element is also the same as in the previous example and restricts the records to those that represent data.
  • The ContentElementConfig element is of type NavigationMenuConfig, which is the container for any sub-elements that are used for retrieving refinements configuration. It further contains RefinementGroupConfig for a group "Product" with Expose="true", which is a way to request the Endeca Server to compute and return refinements for this group. Further, RefinementGroupConfig includes a list of RefinementConfig elements for two attributes on the records — ProductCategoryName and ProductName, each with Expose="true" to request a computation and a listing of individual records, for these attributes; MaximumCount="10" indicates the number of records to return, for each refinement.
Note: While this example is an illustration for how to request refinements and expose (list) their underlying records, for detailed information about working with refinements, and using the Conversation Web Service for them, see Working with Attributes and Refinements.
<Request xmlns:ns2="http://www.endeca.com/MDEX/lql_parser/types" 
   xmlns="http://www.endeca.com/MDEX/conversation/2/0">
 <State>
   <SelectedRefinementFilter Name="DimDate_MonthName" Spec="May"/>
   <SearchFilter Key="All">mountain</SearchFilter>
 </State>
 <Operator xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="RecordKindOperator">
   <RecordKind>data</RecordKind>
 </Operator>
 <ContentElementConfig xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:type="NavigationMenuConfig" 
    Id="NavMenu" 
    HandlerNamespace="http://www.endeca.com/MDEX/conversation/handlers/2010" 
    HandlerFunction="NavigationMenuHandler">
    <RefinementGroupConfig Name="Product" Expose="true">
      <RefinementConfig Name="ProductCategoryName" Expose="true" MaximumCount="10"/>
      <RefinementConfig Name="ProductName" Expose="true" MaximumCount="10"/>
    </RefinementGroupConfig>
 </ContentElementConfig>
</Request>

Example or retrieving breadcrumbs

The following example is used to request breadcrumbs in a search query that also returns spelling correction information. Such a request needs to include all three parts — state, operator, and content element configuration:
  1. The initial state that must be passed to the Oracle Endeca Server (it is empty in this example).
  2. The Operator of type SearchOperator, which uses SearchFilter to specify the actual user-entered search term that requires spelling correction, and the search mode.
  3. The content element configuration, represented by ContentElementConfig. In this example, it contains a configuration requesting breadcrumbs (via BreadCrumbConfig type) and a configuration requesting spelling correction (via SearchAdjustmentConfig type).
    Note: In general, the ContentElementConfig complex type can contain many subtypes, such as AttributeGroupListConfig, BreadCrumbConfig (as in the example below), LQLConfig, RecordListConfig, PropertyListConfig, or ValueSearchConfig. Each of these subtypes specifies a particular configuration, such as whether to return breadcrumbs, how to return lists of records or attributes, or which options to use when searching for attribute values.
To return to the example, it contains state, operator, and content element configuration, as follows:
<Request xmlns="http://www.endeca.com/MDEX/conversation/2/0">
 <State/>
 <Operator xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:type="SearchOperator" Within="false">
    <SearchFilter Mode="All" Key="PROD_NAME" Language="fr">
     envoy
    </SearchFilter>
 </Operator>
 <ContentElementConfig 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:type="BreadcrumbConfig" ReturnFullPath="true" 
    HandlerFunction="BreadcrumbHandler" 
    HandlerNamespace="http://www.endeca.com/MDEX/conversation/2/0"
    Id="Breadcrumbs"/>
 <ContentElementConfig
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:type="SearchAdjustmentConfig"
    HandlerFunction="SearchAdjustmentHandler"
    HandlerNamespace="http://www.endeca.com/MDEX/conversation/2/0"
    Id="SearchAdjustments"/>
 <PassThrough/>
</Request>

For more information on requesting breadcrumbs, see Using Breadcrumbs.

Example of an EQL query

In this example, the state and operators are the same as in the previous example, but ContentElementConfig is of type LQLConfig, which is the type that should be used to issue queries using EQL statements. The contents of the EQL statement is included in the LQLQueryString.

The EQL statement in this example performs the following actions:
  • Divides the corpus of records into groups of records/assignments which share the same value of DimGeography_StateProvinceName. For example, this might produce one group for Massachusetts and another group for Vermont.
  • Within each group, performs two calculations: computes how many transactions occurred within that state/province, and sums up the individual sales amounts within that state/province.
  • Produces a report, called "results", containing three columns: the name of each state/province, the number of transaction in the state/province, and the total amount sold in that province, with one row for each state/province.

For additional examples and details on EQL, see the Oracle Endeca Server EQL Guide.

<Request xmlns:ns2="http://www.endeca.com/MDEX/lql_parser/types" 
    xmlns="http://www.endeca.com/MDEX/conversation/1/0">
  <State>
    <SelectedRefinementFilter Name="DimDate_MonthName" Spec="May"/>
    <SearchFilter Key="All">mountain</SearchFilter>
  </State>
  <Operator xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="RecordKindOperator">
    <RecordKind>data</RecordKind>
  </Operator>
  <ContentElementConfig xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
   xsi:type="LQLConfig" Id="EQL" 
   HandlerNamespace="http://www.endeca.com/MDEX/conversation/handlers/2010" 
   HandlerFunction="LQLHandler">
		   <LQLQueryString>
           RETURN "results" AS SELECT COUNT(1) AS numtransactions, 
           SUM("FactSales_SalesAmount") AS totalsales 
           GROUP BY "DimGeography_StateProvinceName"
     </LQLQueryString>
  </ContentElementConfig>
</Request>