loading

Action - Boost and Bury Entities| 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 use individual entityIds or the filter property to specify the entities in bulk.

Key Type Example
entityIds Array of strings [“EntityID1”, “EntityID2”]
filter Object “filter”: {“savedSearchId”: {“$eq”: “01234”}}
verticalKey String “verticalName”
forceResults Boolean true/false

JSON Config Structure

Option A: Specific Entities

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

If you’re using the UI, you can paste this in to the input:

{"actionType":"BOOST_ENTITIES" or "BURY_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"
        }
      ]  

The following examples will reference the JSON editor, but you can use either.

Boosting Entities Example

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”.

No Boost

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!

Boost Added

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_ENTITES 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 third in the Jobs vertical, and appears in the Universal search.

Jobs Results without Bury

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.

Jobs Results - Bury

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

unit Quiz
+20 points
Daily Quiz Streak Daily Quiz Streak: 0
Quiz Accuracy Streak Quiz Accuracy Streak: 0
    Error Success Question 1 of 3

    What are the components of the Boost and Bury Entities action? Select all that apply.

    Error Success Question 2 of 3

    Which of the following is a good use case for the Boost Entities action?

    Error Success Question 3 of 3

    Which of the following is a good use case for the Bury Entities action?

    High five! ✋

    You've already completed this quiz, so you can't earn more points.You completed this quiz in 1 attempt and earned 0 points! Feel free to review your answers and move on when you're ready.
1st attempt
0 incorrect
Splash Loading