Implementing Numerical Facets | Yext Hitchhikers Platform

What You’ll Learn

In this section, you will learn:

• How to set up the Search backend configuration for numerical facets

Overview

Starting with Theme 1.29, you can also use numerical fields for facets, which is particularly useful for price ranges, multipack options, and more. To use numerical facets, set up the Search frontend how you normally would (check out the previous unit for a refresher). We’ll walk through how to set up the Search backend below.

Search Backend Configuration

For the Search backend, you’ll need to add the new facets object for each vertical you want numerical facets for, using one of three options to set the number ranges, in the JSON editor (this is not yet configurable in the UI).

Just as before, you will still need to set the field as a facet under searchableFields. This will look like the below:

{
  "$schema": "https://schema.yext.com/config/answers/answers-config/v1",
  "$id": "ecommerce",
  "name": "Ecommerce",
  "supportedLocales": [ ... ],
  "countryRestrictions": [],
  "verticals": {
      "products": {
          "name": "Products",
          "directAnswers": { ... },
          "entityTypes": [ ... ],
          "facets": {         
              "fields": [
                  {
                      "fieldId": "price",
                      "sortCriteria": "ASC",
                      "ranges": [ ... ] | { ... }
                  }
              ] 
          }, 
          "searchableFields": { 
              "price": {
                  "facet": true
              },
          ...  // other fields
          },
          "sortBys": [ ... ],
          "source": "KNOWLEDGE_MANAGER"
      }
      ... // other verticals
  },
// truncated 
}

The properties in the facets attribute are:

• fieldId: The field for which this config applies. Required.
• sortCriteria: How to sort the field. Options are ”ASC” or ”DESC”. If not specified, the default is ASC.
• ranges: There are three options to configure numerical facet ranges:
  • Explicitly set ranges (set with an array)
  • Generate either dynamic or static ranges with the backend (set with an object)

Ranges generated by the backend are created based on all the entities available for that vertical (not just the ones returned for a specific search query). This is a useful option if you know that entities are constantly being added/removed or data for the numerical field changes frequently. The backend will readjust the ranges to the data, whereas you would have to manually update explicitly set ranges to make adjustments for data.

If a number field is set as a facet in searchableFields or facets, but no facets config object is provided, the field will be set up as a dynamic range with four buckets. This is added on the next save.

Option 1: Explicitly Set Ranges

Explicitly set ranges that will not change when the results set changes. Static ranges with a result count of 0 are not returned. Also note that the display names will not be internationalized.

"facets": {
  "fields": [
      {
          "fieldId": "price",
          "sortCriteria": "ASC",
          "ranges": [
              {
                  "start": 0,
                  "end": 70,
                  "displayName": "Up to $70"
              },
              {
                  "start": 70,
                  "end": 100,
                  "displayName": "$70 - $100"
              },
              {
                  "start": 100,
                  "displayName": "Over $100"
              }
          ]
      }
  ]
}

ranges takes an array of objects with the following properties:

• start: The start of the range (inclusive). If not specified, the range is unbounded.
• end: The end of the range (exclusive). If not specified, the range is unbounded.
• displayName: The label for this facet option. If not specified, this defaults to
  • "[start] - [end]"
  • "> [start]" if end is not specified
  • "< [end]" if start is not specified

Option 2: Dynamic Range Generated by the Backend

Setting the algorithm property as ”DYNAMIC” will distribute all the entities (not just the ones returned for that search) roughly evenly across the maximum number of buckets specified by bucketCount. If not specified, bucketCount defaults to 4.

"facets": {
  "fields": [
      {
        "fieldId": "price",
        "sortCriteria": "ASC",
        "ranges": {
           "algorithm": "DYNAMIC",
           "bucketCount": 3
        }
     }
  ]
}

The above configuration may give the following buckets (results count in parentheses):

• 0 - 23 (20)
• 23 - 60 (20)
• 60 - 120 (20)

Option 3: Static Range Generated by the Backend

Setting the algorithm property as ”STATIC” will create buckets of length specified by bucketLength (required).

"facets": {
  "fields": [
    {
      "fieldId": "price",
      "sortCriteria": "ASC",
      "ranges": {
         "algorithm": "STATIC",
         "bucketLength": 24
      }
    }  
  ]
}

With the same set of data as the dynamic ranges example, the above configuration may give different buckets (results count in parentheses):

• 0 - 24 (19)
• 24 - 48 (10)
• 48 - 72 (12)
• 72 - 96 (14)
• 96 - 120 (5)