Introduction to Query Rules | Yext Hitchhikers Platform

What You’ll Learn

In this section, you will learn:

  • What is a Query Rule
  • How is a Query Rule constructed
  • Common applications of query rules

Overview of Query Rules

In certain situations, a business might want to apply specific logic to adjust the search results within their Search Experience. While Search automatically returns results based on relevance, hardcoding certain business rules in certain scenarios can be beneficial. This is where Query Rules comes in.

Query Rules is a system that allows a Yext Administrator to modify the search engines in a rules-based way. Each experience can have any number of Query Rules. Each Query Rule contains:

  • Criteria - The criteria is what needs to be met in order to trigger the Query Rule. If all the criteria are met then the actions will be performed.
  • Action - An action is what happens if the criteria are met. This is the action that will somehow adjust the search results. Each Query Rule can have one or more actions.
  • Name - An optional name field is used for users to quickly get a sense of what the rule does.

When creating Query Rules, users need to specify certain criteria that then trigger a set of actions. If a query meets the conditions of a given Query Rule, the Search algorithm performs the actions specified in the rule to predetermine the search results based on the brand’s business needs. Users can also decide to make the modifications temporary or for a specific period of time, if desired, such as for a special event or promotion. We’ll learn more about this later in the module.

Example Use Cases

Examples of specific query rules in action include:

  • To prevent cancellations, a telecom company specifies that, if the user searches for “cancel my account,” the algorithm first returns a set of results that highlights how a customer can downgrade or pause his/her subscription, before displaying FAQ around how to cancel an account.

  • A financial services firm seeks to boost loan officers in their search results, if the user is in a high value segment.

  • These are just a few example use cases for Query Rules. We’ll cover more scenarios where Query Rules can be applied in detail in Unit 8 .

Where to Add Query Rules

Query rules can be added to an experience via the UI or the JSON editor. Each rule can have a name, criteria, and actions.

Add Query Rules with the UI

You can add query rules in the Configuration UI by clicking Query Rules in the navigation bar. From here, click “Add Query Rule”. You’ll be able to add a name to identify the rule, as well as the criteria and actions associated with the rule.

Add Query Rules UI

Add Query Rules with the JSON Editor

Query rules are contained in the ‘rules’ object in the search configuration. The rules object is a top level object in the config (just like verticals). Within the rules array, there can be multiple objects that each represent a query rule.

     "criteria": {
        "searchTermContains": [
      "actions": [
          "actionType": "BOOST_ENTITIES",
          "entityIds": [
          "verticalKey": "menuItems"
      "name": "Boost Menu Item"


Criteria are needed to trigger the Query Rule. Here are the different types of Criteria in Query Rules:

Type Details
Search Term Trigger rules based on the search term that the user enters.
Context Trigger rules based on the user’s context (you’ll learn about this in the next unit).
Referrer Page URL Trigger rules based on the webpage URL that the user searched from.
Search Type Trigger rules based on the type of search (vertical or universal).
Vertical Trigger rules based on the specific vertical.

Each Rule has a criteria that needs to be met and must have at least one property defined. If multiple properties are included, they can be concatenated together with the term “and.” If you want to create multiple distinct rules, simply use “or.” You’ll learn more about these types in the next unit.


Actions are what get performed when the Query Rule criteria are met and the rule is triggered. Actions specify how the algorithm adjusts the search results. Here are the different action types in Query Rules:

Type Details
Boost Entities Boost entities to the top of the vertical results.
Bury Entities Bury entities to the bottom of the vertical results.
Return No Results Return no results for a given query.
Add Filter Add an additional filter to the search results.
Boost Verticals Boost verticals to the top of the search results page.
Bury Verticals Bury verticals to the bottom of the search results page.
Boost Vertical Intent Adjust the vertical intent of a query. This can be used to boost or bury entire verticals in universal search. Note: This is being rolled out in favor of the Boost and Bury Verticals rules.
Return Pinned Result Return an exact hardcoded set of results. This will completely override the search algorithm.
Use Function Runs a Typescript function from a Yext plugin on our servers and forwards the return value to the front-end
Return Custom Data Returns a static JSON blob that signals to the front-end to trigger an action

Each Rule can have one or more actions. All actions will be performed if the criteria is met (assuming there aren’t any overlapping rules) and in the order specified. This module will walk through each rule in depth.

Learn more about the USE_FUNCTION and RETURN_CUSTOM_DATA query rule actions in the Serverless Functions in Query Rules guide.

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 Query Rules?

    Error Success Question 2 of 3

    What parameters are required for every Query Rule? Select all that apply.

    Error Success Question 3 of 3

    Where are Query Rules placed in the Search Configuration file?

    Wahoo - you did it! 🙌

    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