Number Facets (Spring '22 Release)

Product/Library Releases & New Features Spring '22 Release
1

We have made a number of updates to our faceting framework to better support numerical facets. You can now use static number ranges as facets using the Answers Hitchhikers Theme, which is particularly useful for price ranges, multipack options, and more.

To use numerical facets, Admins will have to make changes in both the frontend and backend:

  • Backend Answers Configuration: Add the new facets attribute to each vertical using one of three options to set number facet ranges. Set the field as a facet under searchableFields.
  • Frontend Answers Theme: Turn on facets how you normally would. If facets are already on for this vertical, no other changes need to be made. Note you must be on Theme 1.29 or higher to use this feature.
  • Turn on the Spring '22 Release: Numerical Facet Updates (early access) account feature to use this feature during the Early Access period. This feature will automatically be turned on for all accounts at General Availability for the Spring '22 Release.

Note: This theme version includes breaking changes. Be sure to follow the upgrade implications in the breaking changes post.

:spiral_calendar: This feature is available in Early Access in English on the branch early-access-spring-22. Here’s how to use the Early Access branches of the Theme and SDK!

Backend Answers Configuration

You will need to add the new facets attributes to each vertical object 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)

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)

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.

Frontend Answers Theme

Turn on facets how you normally would. If facets are already on for this vertical, no other changes need to be made. Note you must be on Theme 1.29 and Search UI SDK 1.14 or higher to use this feature.

For a refresher on how to add facets to your frontend, check out the Implementing Facets training unit.