Action - Boost and Bury Entities | Yext Hitchhikers Platform

What You’ll Learn

In this section, you will learn:

• How to structure the Boost and Bury Entities action
• Example for Boost Entities action
• Example for Bury Entities action

Action Structure

The Boost Entities and Bury Entities actions has the following structure:

• The entityIds property accepts an array of Entity IDs
• The filter property accepts filter criteria based on Knowledge Graph
• The verticalKey property should be the vertical that contains these entities
• The forceResults property is by default set to true and can be added to set to false

verticalKey is always required. You can choose to select individual entityIds or the filter property to specify the entities in bulk.

Using the UI

When you select Boost Entities or Bury Entities as a query rule action in the UI, you have the option of selecting entities or filters.

If you select entities, you’ll get a drop down box of all the entities in your account organized by entity type. Choose the desired entities and click Apply. Then select the vertical that contains these entities. If you would like to select entities across different verticals in your experience, create separate actions for each vertical.

If you select filters, enter the filter criteria you’d like to use.

JSON Config Structure

The JSON structure differs based on which method you want to use to select the entities to boost or bury — selecting individual entities or applying filters. The below code snippets use BOOST_ENTITIES to boost entities. If you would like to bury entities instead, use BURY_ENTITIES.

Option A: Specific Entities

"actions": [
        {
          "actionType": "BOOST_ENTITIES",
          "entityIds": [ 
            "entityID1",
            "entityID2"
          ],
          "verticalKey": "verticalName"
        }
      ]
    }

Option B: Group Entities with a Saved Filter

"actions": [
        {
          "actionType": "BOOST_ENTITIES",
          "entityIds": [],
          "filter": {
             "savedFilterId": {
                 "$eq": "1234"
              }
            },
          "verticalKey": "verticalName"
        }
      ]  

Boosting Entities Example

We’ll use the JSON editor to set up these examples, but you can also use the UI.

There might be situations where you want to prioritize certain entities over others, especially if the query is generic. You can boost entities by their entity IDs using the BOOST_ENTITIES action. For example, let’s say we want to promote the new Chicken Burrito if someone searches for a query containing “menu”.

To accomplish this, we’ll do the following: Use the criteria searchTermContains to identify queries that contain “menu”. In actions, define a BOOST_ENTITIES action to boost entity ID “NEW-BURRITO” for the vertical “menuItems”

{
     "criteria": {
        "searchTermContains": [
          "menu"
        ]
      }, 
      "actions": [
        {
          "actionType": "BOOST_ENTITIES",
          "entityIds": [
            "NEW-BURRITO"
          ],
          "verticalKey": "menuItems"
        }
      ]
    }

Once this rule is added, you’ll see the Chicken Burrito at the top of the results!

Alternatively, let’s say you have not just one but several new menu items added each month that you want to boost. In Knowledge Graph, you keep track of these new menu items via a Yes/No field called “New Item”. First, you would add a Saved Filter in Knowledge Graph with a filter to capture any entities with “New Item” marked “Yes”. As a reminder of how to add a Saved Filter, visit this training here . Next, you can boost these entities dynamically and in bulk for a query with “menu” by adding the saved filter ID under actions. Your syntax could look like this:

{
     "criteria": {
        "searchTermContains": [
          "menu"
        ]
      }, 
      "actions": [
        {
          "actionType": "BOOST_ENTITIES",
          "entityIds": [],
          "filter": {
             "savedFilterId": {
                 "$eq": "1234"
              }
            },
          "verticalKey": "menuItems"
        }
      ]
    }

Anytime an entity fitting the saved filter criteria is added to Knowledge Graph, it will automatically pull into the filter and appear boosted for a query containing the term “menu”.

Note that if the entity is not returned in the results without the action, by default BOOST_ENTITIES will add the entity to the results set. To adjust this behavior, you can set forceResults option to false, which will specify that the BOOST_ENTITIES action should only happen if the entities are already in the search results.

Burying Entities Example

Burying entities will make sure that the specified entities appear at the bottom of a vertical. For a vertical with many results, this could mean that a result is bumped off of the universal page altogether.

In our example below, we no longer want to promote the Recruiting Manager position so highly, but still want it to appear in results in case someone searches for that specific position. Without any change, the Recruiting Manager (Entity ID = job-16) shows up as first in the Jobs vertical, and appears in the Universal search.

To bury that entity, we’ll: Use the criteria searchTermContains to identify queries that contain “job”. In actions, define a BURY_ENTITIES action to bury entity ID “job-16” for the vertical “jobs”

    {
      "criteria": {
        "searchTermContains": [
          "job"
        ]
      },
      "actions": [
        {
          "actionType": "BURY_ENTITIES",
          "entityIds": [
            "job-16"
          ],
          "verticalKey": "jobs"
        }
      ]
    }

Now, for generic job searches like “Job Openings”, Recruiting Manager will appear at the very bottom of the results. For this example, you would have to navigate to the Jobs vertical to find this result.

Unlike boosted entities, buried entities will not be added to the results set if they aren’t returned by that search term.