Retrieving the full path of hierarchical refinements

For managed attribute groups (which are groups of those attributes that contain hierarchy), you can request hierarchy information about a refinement with the ReturnFullPath specified in NavigationMenuConfig. In addition, for managed attribute values, hierarchy information is returned with DimensionHierarchy and DimensionValueWithPath types in any record list request.

Hierarchy information represents refinements behind a particular managed attribute. For example, if a ProductCategory managed attribute contains one level of hierarchy (CAT_COMPONENTS) and the current query is at the category components level, the full path of hierarchical refinements can be represented by the following list: 
ProductCategory > CAT_COMPONENTS > Brakes
Refinement values, in this case specific components, may still exist for the Brakes refinement to refine the query even further.

About navigation on attributes with hierarchy

Managed attributes represent a hierarchical relationship where records assigned to a particular value are implicitly assigned to all of the ancestors of that value. In the wine records example, the classification hierarchy includes the path Wine Type : Red > Merlot. This means that any record tagged to "Merlot" is implicitly tagged to "Red."

Refining to, or grouping by, "Red" will display all records mapped to "Merlot" (as well as any records mapped directly to "Red"). With hierarchical attributes, refinements continue to be generated for follow-on navigation. For example, the user may be able to click "Merlot" to see just the Merlots, excluding items tagged directly to "Red", or items tagged to "Cabernet" or another sibling of "Merlot."

To summarize, the expected behavior of managed attributes with hierarchy is that at any point in the navigation, Endeca Server not only returns attributes tagged with the user-selected value, but also those attributes that are implicitly tagged with the value that is above it in hierarchy. In other words, it is not possible to retrieve attribute values at single levels. This consideration is important when deciding which types of attributes — standard or managed, you should create for the records in your data domain. If, for example, the users of your front-end application would like to retrieve all records tagged with a particular value, then this value should belong to a standard (and not managed) attribute where hierarchy is not utilized.

Retrieving hierarchy information for attribute groups

To request the full path of hierarchical refinements for an attribute group, use the ReturnFullPath attribute on NavigationMenuConfig. The ReturnFullPath has the following values:
Attribute Description
ReturnFullPath Specifies whether to return the full path of hierarchical refinements with the response. This setting is relevant in navigation queries for refinements and breadcrumbs.

If set to true, the returned refinement contains the full path to its parent refinement values, as in ProductCategory > CAT_COMPONENTS > Brakes.

If set to false, returns only the refinement, without the path to its ancestors. The default is false.

The format of the NavigationMenuConfig is shown in this example. It uses the ReturnFullPath attribute set to true for the existing attribute group "ProductCategories": 
<NavigationMenuConfig Id="NavigationMenu" ReturnFullPath="true">
   <RefinementGroupConfig Name="ProductCategories" Expose="true"> 
     <RefinementConfig Name="CAT_COMPONENTS" Expose="true" MaximumCount="3"/>
   </RefinementGroupConfig>
</NavigationMenuConfig>

For a flat managed attribute with no hierarchy, the refinement parent will always be the attribute root, because there would be no further refinements if a value had already been selected for the attribute.

Refinements for a given managed attribute can only be returned on the same level within the attribute. For example, Endeca Server could never return a list of refinement choices that included a mix of countries, states, and regions. In all cases where hierarchy is explicitly defined for an attribute, only refinements on an equal level of hierarchy will be returned for a given query.

Retrieving hierarchy information for managed attribute values

To retrieve hierarchy information on managed attribute values, you can use a query that requests a record list, with the RecordListConfig type.

In the response to a RecordListConfig query, the following two types include hierarchy and path information for managed attributes:
  • The DimensionHierarchy complex type returns a collection of paths from specified managed attributes.
  • The DimensionValueWithPath complex type specifies a path to a refinement attribute value from the root of that managed attribute.
For example, consider this abbreviated example of a record list query: 
<ns:RecordListConfig Id="RecordList" MaxPages="60">
   <ns:Column>ProductCategory</ns:Column>
   <ns:RecordsPerPage>200</ns:RecordsPerPage>
   <ns:Page>2</ns:Page>
   <ns:Sort Key="Description" Direction="Ascending"/>
</ns:RecordListConfig>
This request returns hierarchy information and hierarchy paths for the managed attribute ProductCategory. In the following abbreviated example of the response, you can see the returned hierarchy information: 
<cs:DimensionHierarchy>
   <cs:DimensionValueWithPath>
      <cs:DimensionValue DimensionName="ProductCategory" 
       Spec="4">Handlebars</cs:DimensionValue>
      <cs:DimensionValue DimensionName="ProductCategory" 
        Spec="CAT_COMPONENTS">Components</cs:DimensionValue>
      <cs:DimensionValue DimensionName="ProductCategory" 
        Spec="/">ProductCategory</cs:DimensionValue>
   </cs:DimensionValueWithPath>
   <cs:DimensionValueWithPath>
      <cs:DimensionValue DimensionName="ProductCategory" 
        Spec="6">Brakes</cs:DimensionValue>
      <cs:DimensionValue DimensionName="ProductCategory" 
        Spec="CAT_COMPONENTS">Components</cs:DimensionValue>
      <cs:DimensionValue DimensionName="ProductCategory" 
        Spec="/">ProductCategory</cs:DimensionValue>
   </cs:DimensionValueWithPath>
</cs:DimensionHierarchy>