While Search automatically returns results based on relevance, there are times when you might want to adjust results within your Search experience.

Query rules allow you to modify search results by adding precise rules. You can optimize and adjust the structure of your search results. Note that query rules are designed to complement your configuration — you should make adjustments to your configuration first before resorting to query rules.

Query rules are an if-this-then-that framework: if a query meets all the criteria of a given query rule, the Search algorithm performs all the actions specified in the rule. Each experience can have any number of query rules.

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.

Example Use Cases

With query rules, you can edit your search results by boosting or burying verticals or entities, or return no results, for example. Use cases 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 their subscription, before displaying an 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.
• A real estate group wants to roll out a series of Search experiences across hundreds of microsites, where each microsite returns results only for entities related to a specific property. You can do this based on the referrer page URL.
• To reduce strain on their call center, an insurance firm boosts the results for "Live Chat" if a customer searches for "call customer support."

Query Rule Structure

Each query rule has three parts:

• Criteria: The conditions that need to be met in order to trigger the query rule.
• Action: The action that will adjust the search results if all criteria are met.
• Name: An optional name field used to quickly identify what the rule does.

Criteria and actions are considered separately, so you are able to mix and match them.

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.

There are several possible criteria options that fall into five categories:

• Search Term: the search term that the user enters
• Context: the user's context, a JavaScript object with properties set about the user
• Referrer Page URL: the webpage URL that the user searched from
• Search Type: the type of search (vertical or universal)
• Vertical: the vertical returned

When specifying multiple criteria, you can only use each criteria option once in a rule.

Note: search term based criteria do not take synonyms into consideration. 

Search Term

Since search terms have infinitely many options, there are several criteria options to choose from. The search term can exactly match, contain, begin with, or start with a specific word or phrase. You can even use regular expressions to make it even more flexible.

Regular Expressions

Two criteria options allow you to check if the search term or the referrer page URL matches a regular expression. Regular expressions allow you to search for a pattern of characters, providing more flexibility when you're looking for query matches.

Common examples:

• Zip Code: Checks for any queries that have a 5-digit zip code.
• Single and Plural Words: Captures both singular and plural forms of the term you enter.

Useful resources for learning and testing regex:

• https://regexone.com/ - Walks through exercises of regex examples
• https://regex101.com/ - Allows you to test and validate your regex

For example, if users are entering their phone number into search (which would return no results) and you want to return FAQs related to accounts or logging in instead, you can set the criteria as the search term contains the regex ^\d{3}-\d{3}-\d{4}$, which looks for numbers in the format "###-###-####". Then set the action to boost the desired FAQs.

As another example, if you integrated your search bar on both the main home page and a help site, and you want to adjust results based on where users are coming from, you can set the criteria as the referrer page URL contains the regex of the subdomain of the help site, such as ^.*[help.yext.com](http://help.yext.com/).*.

Context

The context object is an arbitrary JavaScript object you can set with any properties you want. This is an incredibly flexible and powerful concept — you can pass in any data you want and use it in a rule. Context can be set either via a function in the Search JavaScript Library, or by using query parameters that are passed along when a user conducts a search.

You can check whether the context contains a particular key or matches a specific value in your criteria.

For example, on a job site, you might set values for whether the user is a job prospect and which market they're in. A user's context object may look like:

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

To target content only towards job prospects, set the criteria as context contains the key prospect. To further target users in the mid-Atlantic market, use the criteria the context market matches the value Mid-Atlantic.

For step-by-step instructions on how to set up context, check out the Search Integration - Setting Context guide.

Search Type

You can specify the criteria as all universal searches or all vertical searches. This is useful when you want to apply a rule across the board. For example, you may have a promo vertical to highlight content based on certain queries — you can apply a boost to this vertical for all universal searches.

Vertical

You can specify the criteria as a specific vertical or set of verticals, which would trigger any time this vertical is shown in results, whether in universal search or vertical search.

Actions

The action is what the Search algorithm will do to adjust search results if all criteria are met. The possible actions are:

• Boost and Bury Entities: Moves entities to the top or bottom of results
• Boost and Bury Verticals: Moves verticals to the top or bottom of results
• Return No Results: Hides all results for a specific vertical
• Add Filter: Applies a filter to the results
• Return Pinned Results: Returns the exact result set specified

Boost and Bury

Boosting and burying entities or verticals are common query rule actions. You might want to prioritize or deprioritize certain entities or verticals over others for specific queries.

For example, if your restaurant has a new menu item to promote, you can boost that entity in the Menu Items vertical. If you release several new items each quarter and have a saved filter tracking new items, you can boost the entities in that saved filter so the boost updates automatically when you update your Knowledge Graph.

Entities/verticals will rank in the following order:

1. Entities/verticals boosted as part of a boost action, in the order they appear in the rule.
2. All other entities/verticals.
3. Entities/verticals buried as part of a bury action, in the order they appear in the rule.

Some nuances to consider:

• If the entity is not returned in results without the action, the boost entities action will add the entity to the results set by default. To adjust this, set the forceResults option to false, which specifies that the boost entities action should only happen if the entities are already in the search results.
• Unlike boosted entities, buried entities will not be added to the results set if they aren't returned by that search term. Burying entities makes the specified entities appear at the bottom of a vertical, which could mean a result is bumped off the universal page altogether. However, the result will still return if it was already returned by the search term. If you want to hide a result completely, consider an Add Filter action.
• If you boost a vertical but there are no entities that return for that search, the vertical will still not appear. If you want entities to be returned, you should also boost entities.

Return No Results

You can specify to return no results for a specific vertical or set of verticals. For example, a restaurant wants to avoid returning job results for searches with "executive chef." You can use the Return No Results action to hide the jobs vertical completely for that query.

Add Filter

You can use any filter that the Yext APIs will accept, including a saved filter or constructing your own filter based on a field. Check out the Entities developer documentation for how to construct filters based on fields.

Return Pinned Results

When pinning results, you specify the entire result set you want returned, including verticals, which entities or saved filters for each vertical, and any direct answers.

Use pinned results sparingly. By pinning results, you are completely overriding the algorithm behavior for queries that match your criteria, which could have unintended consequences and be difficult to maintain. This is a very manual action that should be saved as a last resort, as it is not scalable.

Edit Query Rules

Edit via the Platform UI

To configure query rules in the UI:

1. Click Search in the navigation bar and click on the desired Search experience.
2. Click Query Rules.
3. Click Add Query Rule. A dialog box appears.
4. Enter the name of your rule.
5. Click + Add Criteria and select the criteria option that will trigger this rule. Enter the specific details in the textbox.
6. Click + Add Actions and select the action you want to trigger with this rule.
7. Click Save Query Rule.

You can also choose to Delete Rules or Duplicate Rules from the dropdown.

Edit via the JSON Editor

Query rules are contained in the rules object in the search configuration. Within the rules array, there can be multiple objects that each represent a query rule. Each object should contain a criteria object and an actions array.

"rules":[
  {
    "criteria": {
      "searchTermContainsAll": [
        "menu"
      ]
    },
    "actions": [
      {
        "actionType": "BOOST_ENTITIES",
        "entityIds": [
          "NEW-BURRITO"
        ],
        "verticalKey": "menuItems"
      }
    ],
    "name": "Boost Menu Item"
  }
]

Troubleshooting Query Rules

Before troubleshooting query rules specifically, follow the How to Start Debugging Backend Search Issues doc for general troubleshooting steps.

General Troubleshooting Steps

At a high level, compare the query rule configuration against what the algorithm returned (shown in the search log).

1. Open the query rule configuration:
   1. Navigate to Search > [Experience Name] > Query Rules.
   2. Review the criteria and actions configured.
2. Open the search log for the query you're seeing issues with. Either:
   • Navigate to Search > [Experience Name] > Test Search or a Configuration sub-tab. Run a test search and then select Debug Query from the drop-down menu.
   • If you've already run the search in a staging or production link, navigate to Search > [Experience Name] > Search Logs and click on the relevant search log.
3. Check whether the query rule was applied by seeing whether it's shown in the search factors box of the search log.
4. If the query rule isn't shown in the search log, double check the query rule criteria and confirm whether the search meets that criteria:
   • If the criteria uses regex, check the regex pattern against a debugging tool.
   • If the criteria uses context or referrer page URL, check whether it was picked up for the search. These would be listed under the Query Parameters attribute in the Search Factors box.
   • If the criteria uses vertical keys or search types, check the Searcher Type is correct in the search metadata. Also double check that the vertical key has not changed.
5. If the query rule appears (criteria is met) but the vertical or entity you expect is not in the result set:
   • If you reference a field API name, entity type API name, vertical key, or entity ID, make sure it matches exactly and hasn't changed.
   • Check that the actions are configured properly to match what you want. For example, if you're boosting entities, are they listed in the order you want them returned?

Query Rules and Synonyms

Query rules are meant to take precedence over everything in Search, since they are pieces of hardcoded logic meant to conditionally override the existing configuration. However, query rules will not work with synonyms.

For example, if your rule criteria is searchTermExactlyMatches "shoes" and you've created a one way synonym where "sneakers" → "shoes", the rule will not fire if "sneakers" is searched. To get around this, use a broader rule criteria (e.g., searchTermContains "shoes" or "sneakers") or create a separate rule for each synonym.