Deploying Dynamic Navigation Experience

Pilot Feature

In JavaScript Search Framework interfaces containing DynamicFacet and DynamicFacetManager components, the Coveo™ Machine Learning (Coveo ML) Dynamic Navigation Experience (DNE) feature can automatically reorder facets, and their values, and increase the ranking scores of query result items matching relevant field values.

This article details the required steps to deploy DNE in a Coveo Cloud platform solution.

DNE and dynamic facets are still beta features (see Dynamic Facet Limitations).

Eventually, DNE models will also be able to automatically recommend and automatically select relevant facet values.

Step 1 - Configure a DNE Model

If your Coveo Cloud organization was created on, or after the May 21, 2019 update, configure your DNE model using the administration console (see Review Organization Information Such As the Organization ID).

Otherwise, configure your DNE model using the Search API (not recommended).

Option A - Using the Administration Console

  1. Create a DNE model.
  2. Associate the DNE model with the desired query pipeline.
  • Only consider following this procedure if your organization was created before the May 21, 2019 update.
  • DNE models created with the Search API are not currently visible in the administration console. Rather than following this procedure, it is strongly recommended to wait for the UI to fully support the DNE feature.
  • This procedure assumes that the reader has programming skills and is familiar with REST APIs.
  1. Use the GET /rest/search/v1/admin/pipelines endpoint to retrieve the id of the query pipeline in which you want to configure a DNE model.

    Authenticate the request using an access token granting the View all access level on the Query Pipelines domain in the target organization (see Granting Privileges).

    If the target organization contains several query pipelines, you can use the filter parameter to limit the scope of your request.

    Request - Listing query pipelines matching the CommerceSearch filter

    GET https://platform.cloud.coveo.com/rest/search/v1/admin/pipelines?filter=CommerceSearch HTTP/1.1
      
    Accept: application/json
    Authorization: Bearer **********-****-****-****-************
    

    Successful response body excerpt (200 OK)

    [
      {
        "id": "54845187-85cb-4563-82d9-edfd13ee2ade",
        "name": "CommerceSearch",
        ...
      }
    ]
    
  2. Use the POST /rest/search/v1/admin/pipelines/{pipelineId}/statements endpoint to create a DNE model in the desired query pipeline.

    • In the request path, set {pipelineId} to the id value retrieved at step 1.

    • In the request body:

      • Set feature to facetSense.
      • Set definition to a valid query pipeline language (QPL) expression defining a Coveo ML DNE model (for reference, see Coveo ML Query Pipeline Features).

        Use the following definition to apply the recommended DNE model settings:

        facetSense exportPeriod: \"P3M\", refreshRate: \"P1W\", modifier: 50

        This defines a DNE model with a data period of three months, an update frequency of one week, and a maximum item score modifier of 500 points.

      • Set id to the empty string ("").
      • Set position to 0.
      • (Optional) Set description to a human-readable description for the model.

        The description property will be used as the model Name in the UI when support for QPL-defined DNE models is added in the administration console.

    Authenticate the request using an access token granting the Edit all access level on the Query Pipelines domain in the target organization.

    Request - Creating a DNE model in the CommerceSearch query pipeline.

    POST https://platform.cloud.coveo.com/rest/search/v1/admin/pipelines/54845187-85cb-4563-82d9-edfd13ee2ade/statements HTTP/1.1
     
    Content-Type: application/json
    Accept: application/json
    Authorization: Bearer **********-****-****-****-************
    

    Payload

    {
      "id": "",
      "description": "Commerce DNE model",
      "feature": "facetSense",
      "definition": "facetSense exportPeriod: \"P1W\", refreshRate: \"P1D\", modifier: 25",
      "position": 0
    }
    

    Successful response body (201 Created)

    {
      "id": "78df22c9-eed4-4985-9c16-7881194b4e30",
      "description": "Commerce DNE model",
      "feature": "facetSense",
      "definition": "facetSense exportPeriod: \"P1W\", refreshRate: \"P1D\", modifier: 25",
      "position": 1,
      "ready": false,
      "detailed": {
      "exportPeriod": "P1W",
      "refreshRate": "P1D",
      "modifier": "25"
      },
      "childrenCount": 0
    }
    
  3. (Optional) Use the GET /rest/search/v1/admin/pipelines/{pipelineId}/statements/{statementId} endpoint to monitor the model’s ready state (which will be set to true when the model finishes building).

    In the request path:

    • Replace {pipelineId} by the id value retrieved in the response at step 1.
    • Replace {statementId} by the id value returned in the response at step 2.

    Authenticate the request using an access token granting the View all access level on the Query Pipelines domain in the target organization (see Granting Privileges).

    Building a model may take up to a few hours, depending on the amount of usage analytics data it needs to process.

    If your model seems stuck on the ready: false state, ensure that its QPL definition is valid (see Coveo ML Query Pipeline Features).

    GET https://platform.cloud.coveo.com/rest/search/v1/admin/pipelines/54845187-85cb-4563-82d9-edfd13ee2ade/statements/78df22c9-eed4-4985-9c16-7881194b4e30 HTTP/1.1
     
    Accept: application/json
    Authorization: Bearer **********-****-****-****-************
    

    Successful response body excerpt (200 OK)

    {
      "id": "78df22c9-eed4-4985-9c16-7881194b4e30",
      "description": "Commerce DNE model",
      ...
      "ready": true,
      ...
    }
    

Step 2 - Configure Dynamic Facets in Your Search Interface

Coveo JavaScript Search Framework 2.6063 (May 2019)

The DynamicFacet and DynamicFacetManager components, which are necessary to leverage the DNE feature in a Coveo JavaScript Search Framework interface, are still beta features.

Be sure to review the dynamic facet limitations before including those components in your search interface.

In the search interface whose queries are routed to the query pipeline associated with (or containing) the DNE model configured at Step 1:

  • Replace all Facet components with DynamicFacet components.
  • Replace all FacetRange components with DynamicFacetRange components.
    • Dynamic facets do not currently support automatic range generation. Therefore, when configuring a DynamicFacetRange, you must use the ranges option to request specific facet range values .

    • You may also want to replace FacetSlider and TimespanFacet components with DynamicFacetRange components.

Embed all dynamic facets within a DynamicFacetManager component, otherwise you will not be able to leverage the DNE facet reordering feature.

To maximize the usefulness and quality of output of the DNE facet reordering feature, all relevant facets should be included and made visible in the search interface.

In a Coveo-powered eCommerce search page, the facet markup configuration currently is:

<div class="coveo-facet-column">
  <div class="CoveoFacet"
       data-title="Category"
       data-field="@prd_category"></div>
  <div class="CoveoFacet"
       data-title="Brand"
       data-field="@prd_brand"></div>
  <div class="CoveoFacet"
       data-title="Screen size"
       data-field="@prd_screen_size"></div>
  <div class="CoveoFacet"
       data-title="Wall mountable"
       data-field="@prd_wall_mountable"></div>
  <div class="CoveoFacet"
       data-title="Processor speed"
       data-field="@prd_processor_speed"></div>
  <div class="CoveoFacet"
       data-title="Resolution"
       data-field="@prd_resolution"></div>
</div>

In order to leverage DNE in this search interface, the following changes would have to be made:

<div class="coveo-facet-column">
  <div class="CoveoDynamicFacetManager">
    <div class="CoveoDynamicFacet"
         data-title="Category"
         data-field="@prd_category"></div>
    <div class="CoveoDynamicFacet"
         data-title="Brand"
         data-field="@prd_brand"></div>
    <div class="CoveoDynamicFacet"
         data-title="Screen size"
         data-field="@prd_screen_size"></div>
    <div class="CoveoDynamicFacet"
         data-title="Wall mountable"
         data-field="@prd_wall_mountable"></div>
    <div class="CoveoDynamicFacet"
         data-title="Processor speed"
         data-field="@prd_processor_speed"></div>
    <div class="CoveoDynamicFacet"
         data-title="Resolution"
         data-field="@prd_resolution"></div>
  </div>
</div>

See Using Dynamic Facets for examples and advanced use cases.