Query Rules | Yext Hitchhikers Platform

Query rules allows you to modify search results by adding precise rules. Check out the Query Rules unit for more details.

Search Configuration Schema

Within the Search configuration, the rules array defines the configuration settings for query rules. Each item in the array is an object that defines the query rule. Refer to the table below for the available fields. View where rules fits into the configuration in the Search Config Properties - Top Level reference doc.

See below for the possible options for criteria and actionType and the JSON structure for each.

Top-Level JSON

The JSON below is for demonstrative purposes only to show the structure of the rules object through the top-level properties. Find more detail about each criteria and action option, with sample code snippets, below.

{
  "rules": [
    {
      "criteria": {},
      "actions": [
        {},
        {}
      ],
      "name": "Query Rule 1"
    },
    {
      "criteria": {},
      "actions": [
        {},
        {}
      ],
      "name": "Query Rule 2"
    }
  ],
}

Criteria

The criteria outlines the conditions that need to be met to activate the query rule. All criteria must be met in order for the query rule to trigger. The possible criteria options are listed below:

Search Term Contains

Check for a token match on the search term with the criteria searchTermContains. If multiple tokens are included it will make sure they are all present.

For example, the search query “open jobs for executive chef” would trigger the criteria below:

      "criteria": {
        "searchTermContains": [
          "executive chef",
          "open jobs"
        ]
      },

Search Term Starts With

Check if the search term starts with exactly this phrase with the criteria searchTermStartsWith.

For example, the criteria below checks to see if the search term starts with “How do I”.

      "criteria": {
        "searchTermStartsWith": "How do I"
      },

Search Term Ends With

Check if the search term ends with exactly this phrase with the criteria searchTermEndsWith.

For example, the criteria below checks to see if the search term ends with the word “test”.

      "criteria": {
        "searchTermEndsWith": "test",
      },

Search Term Exactly Matches

Check if the search term exactly matches this phrase with the criteria searchTermExactlyMatches.

For example, the criteria below checks to see if the search term is exactly “cancel my account”.

      "criteria": {
        "searchTermExactlyMatches": "cancel my account",
      },

Search Term Matches Regex

Check if the search term matches this regular expression with the criteria searchTermMatchesRegex.

For example, the criteria below checks whether the query is a phone number with the format ###-###-####. Notice there are extra \ compared to the regex needed (^\d{3}-\d{3}-\d{4}$) as they are escape symbols to use the \.

      "criteria": {
        "searchTermMatchesRegex": "^\\d{3}-\\d{3}-\\d{4}$",
      },

Context Contains

Check if the context object contains a certain key with the criteria contextContainsKey. This criteria uses JSONPath to do the matching. Learn more about JSONPath  here . Learn how to set the context in the Search Integration - Setting Context guide.

For example, let’s say a user has the context below:

{
  jobProspect: true, 
  market: "Mid-Atlantic"
}

The following criteria checks whether the context contains the jobProspect key, i.e. whether the user is a job prospect because otherwise the key would not be set.

      "criteria": {
        "contextContainsKey": "$.jobProspect"
      },

Context Matches

Check if a property in the context object equals a specific value with the criteria contextMatches. This criteria uses the filter syntax. Check out the Entities API documentation for how to construct filters based on fields. Learn how to set the context in the Search Integration - Setting Context guide.

Using the same context above, the following criteria would check that the value of the jobProspect field equals true and the market field equals Mid-Atlantic.

      "criteria": {
        "contextMatches": {
          "$.jobProspect": {
            "$eq": true
          }, 
          "$.market": {
            "$eq": "Mid-Atlantic"
          }
        }
      },

Referrer Page URL Regex

Check if the referrer page URL, which is the user’s entry point into the Search experience, matches this regular expression with the criteria referrerPageURLRegex. This will stay consistent during their Search session.

For example, the criteria below checks to see if the user came from the Yext Help site with the domain “help.yext.com”.

      "criteria": {
        "referrerPageURLRegex": "^.*help.yext.com.*",
      },

Vertical

Restrict the rule to only one or more verticals with the criteria verticalKeys. For example, the criteria below restricts the rule to just the jobs vertical.

      "criteria": {
        "verticalKeys": [
          "jobs"
        ]
      },

Search Type

Restrict to just vertical or universal search with the criteria searchTypes. The default is all searches. Options are ALL, VERTICAL, or UNIVERSAL.

For example, the criteria below restricts to just universal search.

      "criteria": {
        "searchTypes": "UNIVERSAL",
      },

Actions

Actions will be performed in the order specified.

Boost and Bury Entities

Boost entities to the top of vertical results with the action BOOST_ENTITIES. Bury entities to the bottom of vertical results with the action BURY_ENTITIES.

Both the boost entities action and the bury entities action use the following properties. verticalKey is always required. You can choose to select individual entityIds or use the filter property to specify entities in bulk with filter syntax .

When configuring the action in JSON, the only difference between boosting and burying entities is whether you set the actionType as BOOST_ENTITIES or BURY_ENTITIES.

Boost entities by specifying entities: In the following example, the Menu Items entity with the ID “NEW-BURRITO” is boosted.

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

Boost entities by specifying filters: In the following example, the boosted Menu Item entities are referred to in bulk using the saved filter with ID “1234”. Check out the Entities API documentation for how to construct filters based on fields.

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

Bury entities by specifying entities: In the following example, the Job entity with ID “job-16” is buried.

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

Bury entities by specifying filters: In the following example, the buried Menu Item entities are selected by filtering on whether the custom field c_oldItem is set to true. Check out the Entities API documentation for how to construct filters based on fields.

      "actions": [
        {
          "actionType": "BURY_ENTITIES",
          "entityIds": [],
          "filter": {
            "c_oldItem": {
              "$eq": true
            }
          },
          "verticalKey": "menuItems"
        }
      ]

Return No Results

Return no results for a given vertical with action RETURN_NO_RESULTS. Only one property is needed to specify the verticals.

In the following example, no results are returned for the Jobs vertical.

      "actions": [
        {
          "actionType": "RETURN_NO_RESULTS",
          "verticals": [ "jobs" ]
        }
      ]

Add Filter

Add an additional filter to the search results with action ADD_FILTER. Both properties are required. Check out the Entities API documentation for how to construct filters based on fields.

In the following example, a saved filter is applied to the FAQs, Jobs, and Locations verticals.

      "actions": [
        "actionType":"ADD_FILTER",
        "verticals": [
          "faqs", 
          "jobs", 
          "locations"
        ],
        "filter": {
          "savedFilterId":{
            "$eq":"21466424"
          }
        }
      ]

Boost and Bury Verticals

Boost verticals to the top of universal search results with the action BOOST_VERTICALS. Bury entities to the bottom of universal search results with the action BURY_VERTICALS.

Both the boost verticals action and the bury verticals action use the following properties only require one property to specify the verticals.

Boost verticals: In the following example, the FAQs and Help Articles verticals are boosted.

      "actions": [
        {
          "actionType": "BOOST_VERTICALS",
          "verticals": [ 
            "faqs",
            "help_articles"  
          ]
        }
      ]

Bury verticals: In the following example, the Events vertical is buried.

      "actions": [
        {
          "actionType": "BURY_VERTICALS",
          "verticals": [ 
            "faqs" 
          ]
        }
      ]

Boost Vertical Intent

Boost vertical intent is our legacy method for boosting and burying verticals in query rules. It is still supported, but may be removed in a future version of Search. Use the “Boost Verticals” and “Bury Verticals” actions instead.

In the following example, the Events vertical is boosted by a value of 5.

      "actions": [
        {
          "actionType": "BOOST_VERTICAL_INTENT",
          "boostValue": 5,
          "verticals": [
            "events"
          ]
        }
      ]

Return Pinned Result

Return an exact hardcoded set of results with the action RETURN_PINNED_RESULTS. This will completely override the search algorithm.

For the verticals object, include each an object for each vertical you want in the results. verticalKey is always required. For a Yext vertical, you can choose to select individual entityIds or use the savedFilterId property to specify entities in bulk with a saved filter. For a vertical that is not powered by the Yext platform, it will show the normal results from that backend – you cannot control the order of the results.

In the following example, a pinned result is returned with a direct answer from the name field of an entity in the Doctors vertical. The entity results returned are the Specialties vertical using a saved filter, the FAQs vertical with two entities, and the Links vertical.

      "actions": [
        "actionType": "RETURN_PINNED_RESULT",
        "directAnswer": {
          "entityId": "230s",
          "fieldId": "name",
          "verticalKey": "doctors"
        },
        "verticals": [
          {
            "verticalKey": "specialties",
            "savedFilterId": "21466424"
          },
          {
            "verticalKey": "faqs",
            "entityIds": [
              "FAQ-1",
              "FAQ-2"
            ]
          },
          {
            "verticalKey": "links"
          }
        ]
      ]

Use Function

Run a Typescript function from a Yext plugin on our servers and forward the return value to the front-end with the action USE_FUNCTION. Learn more in the Serverless Functions in Query Rules guide. This action is only available in the JSON editor.

In the example from the guide, we fetch stock prices. If the stock price meets a certain criteria, we want to use the function fetchStockData that we wrote, like so:

      "actions": [
        {
          "actionType": "USE_FUNCTION",
          "plugin": "stockDataPlugin",
          "function": "fetchStockData",
          "key": "stockData",
          "timeout": 250,
        }
      ]

If we want to make the function async instead of setting a timeout, it would look like:

      "actions": [
        {
          "actionType": "USE_FUNCTION",
          "plugin": "stockDataPlugin",
          "function": "fetchStockData",
          "key": "stockData",
          "async": true,
        }
      ]

Return Custom Data

Return a static JSON blob that signals to the front-end to trigger an action with RETURN_CUSTOM_DATA. Learn more in the Serverless Functions in Query Rules guide. This action is only available in the JSON editor.

The RETURN_CUSTOM_DATA action is somewhat similar to USE_FUNCTION except it skips the function invocation altogether and just returns some arbitrary JSON to the front-end. This means that we don’t have to worry about errors, timeouts, or asynchronous functions, since we aren’t actually executing any code.

Generally speaking, the JSON data that is returned in these rules will be some indicator that the front-end should perform some action, such as redirecting to another page or fetching from an API on the client-side.

In the following example, the action is basically informing the front-end that it should fetch and display the package data, but it’s up to the front-end to actually implement the logic.

      "actions": [
        {
          "actionType": "RETURN_CUSTOM_DATA",
          "key": "trackingInfo",
          "customData": {
            "action": "FETCH_PACKAGE_DATA",
          }
        }
      ]