RefinementConfig

The RefinementConfig element controls the behavior of an individual attribute in a NavigationMenuConfig.

It specifies which attributes, out of all valid refinements returned with a navigation query, should return actual refinement values, and includes specifications about the order and number of refinement values. Also includes specifications on whether to return a full list of refinements (both suggested and applied, including those that are implicit). You can omit RefinementConfig in your request if you do not need any of its optional items.

Note: For hierarchical refinements that are derived from managed attributes, you can additionally retrieve their full path. For information, see Retrieving the full path of hierarchical refinements.

The RefinementConfig syntax is:

<RefinementConfig 
   Name="?" 
   Spec="?" 
   Expose="false" 
   OrderByRecordCount="false" 
   MaximumCount="?" 
   IncludeExplicitSelections="false" 
   IncludeImplicitSelections="false"/>

For a given attribute, you can use only one RefinementConfig element.

The descriptions of the attributes are:

Attribute	Description
`Name`	Required. The name of the attribute.
`Spec`	Optional. Used for walking down a hierarchy, without following the refinements as you navigate down the refinement tree. The `Spec` identifies the refinement parent for the query. For example, in an empty state, a `NavMenu` for the initial navigation state shows managed attribute `ProductCategory` to be available. The user expands `ProductCategory`; this puts a `RefinementConfig Name="ProductCategory"` into the `RefinementConfig` and sends it in to the Endeca Server. The `NavMenu` shows `ProductCategory` refinements, including `Electronics`, which is expandable. The user expands `Electronics`; this puts a `RefinementConfig Name="ProductCategory" Spec="Electronics"` into the `RefinementConfig` and sends it to the Endeca Server. Next, the response received from the Endeca Server contains `NavMenu` with the `ProductCategory` refinement starting at `Electronics`. For a refinement with hierarchy (which is based on values from a managed attribute), refinement values will be returned for any child managed attribute values of this spec. For example, `Spec="/"` refers to a root managed value (such as for `WineType`), while `Spec="Merlot"` refers to a child managed value.
`Expose`	Optional. Specify `false` (the default) to compute whether this attribute is a refinement at all, or `true` to compute whether it is a refinement and also to retrieve and expose individual refinements (if any are present).
`OrderByRecordCount`	Optional. Specify `true` to order by record count based on the individual query (dynamic ordering) or `false` (the default) to use the default order from the Dgraph, specified by the `system-navigation_Sorting` attribute in the PDR. For details, see Enabling the refinement order at query time.
`MaximumCount`	Optional. An integer that specifies a maximum limit on the number of refinements returned per standard or managed attribute. If this setting is not specified, the number of refinements returned per attribute in the Conversation Web Service response is dictated by the value of the MaximumRefinementCount attribute in the NavigationMenuConfig element in the Conversation Web Service request. If that value is not specified, the default is 10.
`IncludeExplicitSelections`	Optional. Controls whether explicitly-selected refinements are returned (along with suggested refinements, which are always returned, if available), for this specific attribute. The default is `false`. This setting controls retrieval of explicitly-selected refinements per individual attribute — it overrides the global setting for retrieving explicitly-selected refinements in NavigationMenuConfig.
`IncludeImplicitSelections`	Optional. Controls whether implicitly-selected refinements are returned, for this specific attribute. The default is `false`. This setting controls retrieval of implicitly-selected refinements per individual attribute — it overrides the global setting for retrieving implicit refinements in NavigationMenuConfig.

Notes on RefinementConfig

Note: Keep in mind that the RefinementConfig element is an optional query parameter. However, attributes for which RefinementConfig is not included will not return refinements (unless ExposeAllPropertyRefinements is used in the group). In other words, by default, attributes in groups and refinements are collapsed. If you would like to expose attributes that have refinements, either use RefinementConfig on each attribute whose refinements you want to expose, or use ExposeAllPropertyRefinements and expose refinements for all attributes at once. The following examples illustrate these use cases.

The Expose attribute is also optional and defaults to false. Expose="false" helps improve performance.

For example, in a simple data set with three attributes in a user-defined group "Sales-Characteristics", the query:

<Request xmlns="http://www.endeca.com/MDEX/conversation/3/0">
  <State/>
  <NavigationMenuConfig Id="NavigationMenu">
   <RefinementGroupConfig Name="Sales-Characteristics" Expose="false"/>
  </NavigationMenuConfig> 
 </Request>

will return information in HasRefineableProperties, but will not return refinements themselves. This is faster for the Oracle Endeca Server to compute. (To retrieve all attributes in the group, Expose should be set to true).

However, this query for the ProductType managed attribute:

<Request xmlns="http://www.endeca.com/MDEX/conversation/3/0">
  <State/>
  <NavigationMenuConfig Id="NavigationMenu">
     <RefinementGroupConfig Name="Sales-Characteristics" Expose="true"> 
       <RefinementConfig Name="ProductType" Expose="true" />
     </RefinementGroupConfig>
  </NavigationMenuConfig>
</Request>

will return all three managed attributes (since they are included in the Sales-Characteristics group), as well as the top-level refinement attribute values for the ProductType managed attribute. This is slightly more expensive for the Dgraph to compute, and returns the three root managed attribute values as well as the top-level managed attribute values for ProductType, but is necessary for selecting a valid refinement.

A more advanced query option returns all the top-level managed attribute value refinements for all attributes requested (instead of a single attribute). This option involves setting the ExposeAllRefinements attribute to true. If an application sets this attribute to true, the query:

<Request xmlns="http://www.endeca.com/MDEX/conversation/3/0">
  <State/>
  <NavigationMenuConfig Id="NavigationMenu" ExposeAllRefinements="true">
    <RefinementGroupConfig Name="Sales-Characteristics" Expose="true"/>
  </NavigationMenuConfig>
</Request>

will return three managed attributes, as well as all valid top-level managed attribute values for each of these attributes.

This is the equivalent of the query:

<Request xmlns="http://www.endeca.com/MDEX/conversation/3/0">
   <State/>
   <NavigationMenuConfig Id="NavigationMenu">
      <RefinementGroupConfig Name="Sales-Characteristics" Expose="true">
       <RefinementConfig Name="UnitPrice" Expose="true" /> 
       <RefinementConfig Name="OrderQuantity" Expose="true" /> 
       <RefinementConfig Name="CustomerPONumber" Expose="true" />
      </RefinementGroupConfig>
   </NavigationMenuConfig>
</Request>

This is the most expensive type of query for the Oracle Endeca Server to compute, and returns three root managed attribute values as well as all the top-level managed attribute values, creating a larger network and page size strain. This method, however, is effective for creating custom navigation solutions that require all possible refinement values to be displayed at all times.