How to Set Entity Sorting in the Configuration | Yext Hitchhikers Platform

New Release Feature

This unit references the new Search Platform: Key Improvements feature from the Spring ‘23 Release. To turn this feature on in your account, navigate to Account Settings > Account Features and select Spring ‘23: Search Platform: Key Updates & Improvements (early access).

What You’ll Learn

In this section, you will learn:

• What the default sorting behavior is
• Where and how to implement custom entity sorting in the Search Configuration
• How to set up sortOptions in the frontend to appear in your vertical search

In this unit, you’ll learn how to override the default sorting and implement customized entity sorting within the Search Configuration as well as how to setup sortOptions in the frontend.

Default Vertical Sorting

In every experience, the default sorting behavior for a vertical is Relevance and Distance. All entities will therefore sort based on relevance according to the algorithm and location bias (when relevant) to the user. The default sorting can be customized, which we will cover in this module.

If you customize the "sortBys" property as described below, your vertical configuration will no longer have the default relevance sorting. It is a best practice to make sure you add back relevance to your override sorting to make sure that when a user is searching, they still see the most relevant entities to their query first, and then the sorting can be configured to the business logic. We will dive futher into this below.

How to Customize Vertical Sorting

Under each vertical, use the "sortBys” property to set each of these sorting options.

Note

If you are sorting using the “by a custom field” option, make sure to create the Knowledge Graph custom field (number, text, date or boolean) and populate that field for the appropriate entities before updating the backend config.

For each sorting configuration, you need to set the corresponding type property with the following names:

• RELEVANCE - sorts based on relevance according to the algorithm and, when relevant, location bias
• RANDOM - randomizes the ordering on each search, e.g., if you have a lot of doctors in a single office, they’ll show up in a different order each time.
• ENTITY_DISTANCE - sorts based on entity distance alone
• FIELD - sorts based on a field with the direction specified

The first sortby type will be considered primary. If you specify sortBys, but don’t include RELEVANCE, any phrase or text matches will effectively be ignored when ranking results. This means that if you just add ENTITY_DISTANCE as a sortBy, entities will only be returned by distance without any relevance calculation to the query. You can, and should, set more than one type property (such as “Relevance” and “Field” together) so long as they do not conflict with each other (e.g., sorting by RANDOM first will cancel anything after it).

Here is an example of sorting by Relevance and then by Entity Distance type:

"sortBys": [
  {
    "type": "RELEVANCE"
  },
  {
    "type": "ENTITY_DISTANCE"
  }
]

Let’s take a look at the Bucketed Distance feature, which allows you to group distances together in “buckets” and further customize how you can sort results. With Bucketed distance, the algorithm will first sort by which distance bucket the location falls in, then by relevance, and then finally, by continuous distance.

• Bucketed Distance: The algorithm first sorts by bucketed distance. Let’s take, for example, an admin makes three distance buckets - one for 5 miles, 50 miles, and 100 miles (N.B. distances must be expressed in meters). This means the algorithm first shows all locations within 5 miles - even if they’re less relevant - then locations within 50, then locations within 100.
• Relevance: Next, the algorithm sorts on relevance. So if there are two locations that are both within 5 miles, the algorithm will sort them on relevance instead of distance. It doesn’t matter if one is 4 miles away and the other is 3 miles away.
• Distance: Finally, the algorithm sorts on (continuous) distance. This means that if two locations are in the same distance bucket and are equally relevant, then it will sort them based on the exact distance. Continuous distance would be used a tiebreaker.

Here’s how you would configure bucketed distance for this example:

{
  "sortBys": [
    {
      "type": "ENTITY_DISTANCE",
      "buckets": [
        8046.72, // 5 miles
        80467.20, // 50 miles
        160934.00 // 100 miles
        ]
    },
    {
      "type": "RELEVANCE"
    },
    {
      "type": "ENTITY_DISTANCE"
    }
  ]
} 

For the FIELD sorting option, in addition to type property, you also have to set the direction property (either ASC or DESC) and the Knowledge graph “field” API Name it keys off of. You do not need to include these properties for the other sorting options.

Consider this example:

"sortBys": [
  {
    "type": "RELEVANCE"
  },
  {
    "direction": "ASC",
    "field": "c_acceptingNewPatients",
    "type": "FIELD"
  }
],

In the above example, the primary sorting option is relevance to the query. After that, it sorts the entities in ascending order by those accepting new patients. This way, if a user searches “doctors named John”, they will first see doctors named John (relevance), and then all “John” entities will then be sorted by “accepting new patients” (field).

As a reminder, it is always a best practice to add relevance to your sortBys object to ensure that relevant entities show up based on the query and then are sorted by the desired business logic.

When you set the sortBys property, you will also need to indicate the field that is “sortable” under Searchable Fields as such:

"searchableFields": {
  "c_acceptingNewPatients": {
    "sortable": true
  }
}

By indicating this custom field as “sortable,” you are making this field eligible for sorting.