Manage query rules in SharePoint Server

APPLIES TO: yes-img-132013 yes-img-162016 yes-img-192019 yes-img-seSubscription Edition no-img-sopSharePoint in Microsoft 365

Without using any custom code, a Search service application administrator, site collection administrator, or site owner can improve classic search results by creating and managing query rules. Query rules help searches respond to the intent of users.

In a query rule, you specify conditions and correlated actions. When a query meets the conditions in a query rule, the search system performs the actions specified in the rule to improve the relevance of the search results, such as by narrowing results or changing the order in which results are displayed. For example, a query rule condition could be that a term in a query matches a particular term in a SharePoint Server term set, or that a query is frequently performed on a particular result source in a search system, such as videos. When the query rule condition is satisfied, a correlated action could be to show a specific item at the top of the search results.

You can configure query rules for one or more result sources, and you can specify the time period during which the query rule is active.

Note

A query rule also affects the modern search experience in SharePoint Server 2019 when:

  • The action in the rule is to promote an individual result towards the top of search results.
  • The rule is defined for the default result source.
  • The rule is defined at the Search service application level.

Users only see such a promoted result in the modern search experience when:

  • They’ve searched for results across all of SharePoint.
  • The search results page is filtered to All result types (default view).

Creating query rules at different levels in a SharePoint Server farm

You can create a query rule for a Search service application, a site collection, or a site. The following table shows the permissions that are required to create a query rule in each case, and where the query rule can be used.

Levels and permissions for query rules

When you create a query rule at this level You must have this permission The query rule can be used in
Search service application
Search service application administrator
All site collections in web applications that consume the Search service application
Site collection
Site collection administrator
All sites in the site collection
Site
Site owner
The site

To add or edit a query rule, you must go to the Manage query rules page. Depending on the level at which you are creating the query rule, use one of the following procedures to go to the Manage query rules page.

To go to the Manage query rules page for a Search service application

  1. Verify that the user account that performs this procedure is an administrator for the Search service application.

  2. In Central Administration, in the Application Management section, click Manage service applications.

  3. Click the Search service application to which you want to add query rules.

  4. On the Search Administration page for the Search service application, in the Quick Launch, in the Queries and Results section, click Query Rules.

To go to the Manage query rules page for a site collection

  1. Verify that the user account that performs this procedure is a site collection administrator.

  2. On the Settings menu for the site collection, click Site Settings.

  3. On the Site Settings page, in the Site Collection Administration section, click Search Query Rules.

To go to the Manage query rules page for a site

  1. Verify that the user account that performs this procedure is a member of the Owners group for the site.

  2. On the Settings menu for the site, click Site Settings.

  3. On the Site Settings page, in the Site Administration section, click Query Rules.

Create a query rule

  1. Specify a result source for this query rule. Use the Select a Result Source menu, on the Manage Query Rules page.

  2. Click New Query Rule.

  3. Give the query rule a name. Use the Rule name field on the Add Query Rule page.

  4. If relevant, restrict this rule to queries performed on a particular result source. Click to expand the Context section, and under Query is performed on these sourcesselect one of the following:

  • To apply the query rule to all result sources, select All sources.

  • To restrict the query rule to one or more specific result sources, select One of these sources. By default, the result source that you specified in step 1 is selected.

  1. If relevant, restrict the rule to be performed from a particular category —for example, that a query rule should fire only when a term from your managed navigation term set is included in the query. In the Context section, under Query is performed from these categories select one of the following:
  • To restrict the query rule to a particular category, click One of these categories and then add the category. In the Import from Taxonomy dialog, select a term that when you include it in a query will cause the query rule to fire, and then click Save.

  • To remove any restrictions, click All categories.

  1. If relevant, restrict the rule to be performed by a particular user segment. In the Context section, under Query is performed by these user segments select one of the following::
  • To restrict the query rule to a particular user segment, click One of these user segments and then add the user segment. Enter a title for the user segment and then click Add user segment term. In the Import from Taxonomy dialog, select a term that when you include it in a query will cause the query rule to fire, and then click Save.

  • To remove any restrictions, click All user segments.

  1. Specify when a query makes this rule fire. You can have more than one condition, and the rule will fire when any condition is true. In the Query Conditions section do one of the following:
  • Select one of the conditions listed in Overview of conditions that make a query rule fire.

  • Add an alternate condition.

  • Click Remove Condition to configure this query rule to fire for every query that users type at the level at which you are creating the rule. For example, if you are creating this rule for a site collection, click Remove Condition if you want this rule to fire for every query that users type inside any search box in the site collection.

  1. Specify the action to take when the query rule fires. In the Actions section you can:
  • Promote individual results so that they appear towards the top of search results. You can add several individual promoted results. When there is more than one promoted result, you can specify the relative ranking. To promote, click Add Promoted Result (in SharePoint 2010 Products this was called Best Bets). In the Add Promoted Result dialog give the promoted result a name and enter the URL of the result to promote. You can define that the URL is rendered as a banner instead of as a hyperlink.

  • Promote a group of search results, click Add Result Block. For more information, see Create and display a result block later in this article.

  • Change ranked search results, click Change ranked results by changing the query. For more information, see Change ranked search results later in this article.

  1. To make the query rule active during a particular time period, click Publishing, and then specify the period.

Overview of conditions that make a query rule fire

Query condition Description Configuration Example
Query Matches Keyword Exactly
Select this option if you want the query rule to fire when a query exactly matches a word or phrase that you specify.
In the Query exactly matches one of these phrases text box, type one or more phrases separated by semicolons.
You type "picture; pic" in the Query contains one of these phrases box. The query rule will fire when a user types "picture" or "pic" in a search box. The rule will not fire if a user types "pictures" or "sunny picture."
Query Contains Action Term
Select this option if you want the query rule to fire when a query contains a term that indicates something that the user wants to do. The term must be at the beginning or end of the query.
The action term can be one of several phrases that you enter. Alternatively the action term can be an entry in a dictionary, where you import the term.
You type the word "download" in the Action term is one of these phrases text box. When a user types "download Contoso Electronics datasheet" in a search box, the user is probably not searching for a document that contains the words "download," "Contoso," "Electronics," and "datasheet." Instead, the user is probably trying to download a Contoso Electronics datasheet. When a user types "download Contoso Electronics datasheet" in a search box, the query rule fires, and only the words "Contoso," "Electronics," and "datasheet" are passed to the search index.
Query Matches Dictionary Exactly
Select this option if you want the query rule to fire when the query exactly matches a dictionary entry.
From the ** Query contains an entry in this dictionary ** menu, select a dictionary. To specify a different dictionary, click Import from taxonomy, and then from the Import from taxonomy dialog, select a term from a term set, and then click Save.
A word that a user types in a search box matches an entry in the pre-configured People Names dictionary.
Query More Common in Source
Select this option if you want the query rule to fire if the query was frequently issued by users on a different result source that you specify.
In the Query is more likely to be used in this source menu, select a result source.
In the Query is more likely to be used in this source menu, you select Local Video Results. The query rule will fire if a user types the word "training" in a search box and that word was frequently typed in a search box in the Videos vertical.
Result Type Commonly Clicked
Select this option if you want the query rule to fire if other users frequently clicked a particular result type after they typed the same query.
In the Commonly clicked results match result type menu, select a result type.
In the Commonly clicked results match result type box, you select SharePoint MicroBlog post. If users frequently click a microblog post in search results, then in the Actions section, you might want to configure the most recent microblog post as the first promoted result, and the next most recent microblog post as the second promoted result.
Advanced Query Text Match
Select this option if you want to use a regular expression, a phrase, or a dictionary entry that will cause the query rule to fire.
To match all phone numbers that are in a certain format, you specify a regular expression in the Query matches this regular expression box.
To match all phone numbers that are in the format nnn-nnn-nnnn, you specify the regular expression "(?(\d{3}))?-?(\d{3})-(\d{4})".

Create and display a result block

A result block is several search results that are displayed as a group. For example, for a query that contains "Fabrikam sales report", a query rule might use a taxonomy dictionary to recognize "Fabrikam" as a customer, and then display a result block with pertinent results about Fabrikam from your customer relationship management (CRM) system.

In the same manner as you can promote a specific result, you can promote a result block when a specified query condition applies.

When you configure the query to run for a result block, you can use query variables. Query variables are placeholders for values that you don't know when you specify the query. However, when the query is run, this information is known and can be used when the system sends the query to the index. Examples are {User.Name}, which represents the display name of the user who typed the query, or {searchBoxQuery}, which represents the query that a user typed in a search box. See Query variables in SharePoint Server for a list of available query variables.

If you're not familiar with query variables, you can use the Query Builder to configure the query (see step 3 in the following procedure).

To create a result block

  1. In step 8 of the previous procedure, on the Add Query Rule page, in the Actions section, click Add Result Block.

  2. Enter the title that shall appear in the result block in the Title field in the Block Title section. Enter a title for each language that's relevant.

  3. Configure the query that gives results for the block. In the Query section, click Launch Query Builder, and on the BASIC tab do the following:.

  • Select which content to search by selecting a result source from the drop-down list in the Select a query section.

  • Specify your query in the Query text box. You can select pre-defined query variables from the Keyword filter drop-down list, and then add them to the Query text box by clicking Add keyword filter.

  • If relevant, use property filters to query the content of managed properties that are set to queryable in the search schema. You can select managed properties from the Property filter drop-down list. Click Add property filter to add the filter to the query.

  • Test the query by clicking Test query.

  1. Specify how the search results within your result block should be sorted. Sorting of search results is case sensitive. On the SORTING tab, in the Sort by drop-down list, select a managed property, and then select Descending or Ascending. The list only contains managed properties that are set as sortable in the search schema. You can also sort by rank. To add more sorting levels, click Add sort level:

  2. If you chose to sort by rank, you can optionally:

  • Select which model to use for ranking search results (this selection is optional). Use the Ranking Model drop-down list.

  • Define rules for dynamically changing the ordering of results. In the Dynamic ordering section, define when to change ranking by selecting a condition from the drop-down list and then specifying whether to promote or demote the result. To add more rules, click Add dynamic ordering rules

  1. Preview the final query that will be run by the Content Search Web Part, on the TEST tab. The preview is based on the original query template where dynamic variables are substituted with current values. Other changes to the query may have to be made as part of query rules. Click Show more to display additional information.
  • The Query template box shows the content of the query template that is applied to the query.

  • The Query template variables section shows the query variables that will be applied to the query, and the values of the variables that apply to the current page. You can type other values to test the effect they will have on the query. Click the Test Query button to preview the search results.

  1. Define which result source this result block should be applied to. Use the Search this Source drop-down list in the Query section.

  2. Define how many results ro show in the result block. Use the In the Items drop-down list, in the Query section.

  3. The result block will only display the number of search results that you specified in the previous step. However, you can add a SHOW MORE link at the bottom of the result block that will show all search results for the result block. To add a SHOW MORE link, expand the Settings section, select "More" link goes to the following URL, and then type a URL. You can use query variables in this URL — for example, http://www.<site>/search/results.aspx?k={subjectTerms} .

  4. Skip the Routing section.

  5. Click OK.

Change ranked search results

The ranking model calculates a ranking order of search results. You can change this ranking by promoting or demoting items within the search results. For example, for a query that contains "download toolbox," you can create a query rule that recognizes the word "download" as an action term, and change the ranked search results to promote a URL of a particular download site on your intranet. You can also change the sorting order of the search results dynamically, based on several variables such as file name extension or specific keywords. Changing ranked search results by changing the query has the advantage that the results are security trimmed and refinable. Moreover, the search results will not appear if the document is no longer available.

To change ranked search results by changing the query

  1. From step 8 of the procedure Create a query rule, on the Add Query Rule page, in the Actions section, click Change ranked results by changing the query. The Build Your Query dialog appears.

  2. On the BASIC tab do the following:.

  • Select which content to search by selecting a result source from the drop-down list in the Select a query section.

  • Specify your query in the Query text box. You can select pre-defined query variables from the Keyword filter drop-down list, and then add them to the Query text box by clicking Add keyword filter.

  • If relevant, use property filters to query the content of managed properties that are set to queryable in the search schema. You can select managed properties from the Property filter drop-down list. Click Add property filter to add the filter to the query.

  • Test the query by clicking Test query.

  1. Specify how the search results within your result block should be sorted. Sorting of search results is case sensitive. On the SORTING tab, in the Sort by drop-down list, select a managed property, and then select Descending or Ascending. The list only contains managed properties that are set as sortable in the search schema. You can also sort by rank. To add more sorting levels, click Add sort level:

  2. If you chose to sort by rank, you can optionally:

  • Select which model to use for ranking search results (this selection is optional). Use the Ranking Model drop-down list.

  • Define rules for dynamically changing the ordering of results. In the Dynamic ordering section, define when to change ranking by selecting a condition from the drop-down list and then specifying whether to promote or demote the result. To add more rules, click Add dynamic ordering rules

  1. Preview the final query that will be run by the Content Search Web Part, on the TEST tab. The preview is based on the original query template where dynamic variables are substituted with current values. Other changes to the query may have to be made as part of query rules. Click Show more to display additional information.
  • The Query template box shows the content of the query template that is applied to the query.

  • The Query template variables section shows the query variables that will be applied to the query, and the values of the variables that apply to the current page. You can type other values to test the effect they will have on the query. Click the Test Query button to preview the search results.

Make a query rule inactive

Query rules that are created at the Search service application level are inherited by site collections and sites that are in web applications that consume the Search service application. Similarly, query rules that are created at the site collection level are inherited by sites in the site collection. If you don't want a query rule to apply to a site that inherits it, you can set the query rule as inactive for the site.

To make a query rule inactive on a site

  1. Verify that the user account that performs this procedure is a member of the Owners group for the site.

  2. In the site collection, in the Settings menu, click Site Settings.

  3. On the Site Settings page, in the Search section, click Query Rules.

  4. On the Manage Query Rules page, on the Select a Result Source menu, select the result source that contains the query rule that you want to make inactive.

  5. In the Name column, point to the query rule that you want to make inactive, click the arrow that appears, and then click Make Inactive.

Rank query rules

When multiple query rules are active for a Search service application, a site collection, or a site, more than one rule can fire for a query that is performed at that level. By default, the rules do not fire in a prescribed order. You can control the order in which the rules fire by adding the query rules that you create to query groups. To do this, you select rules to add to a group, and then you specify the order in which the rules in the group will fire if they are triggered. You can also prevent query rules that rank lowest in a group from firing even if they are triggered.

To rank query rules for a site collection

  1. Verify that the user account that performs this procedure is a site collection administrator.

  2. In the site collection, on the Settings menu, click Site Settings.

  3. On the Site Settings page, in the Site Collection Administration section, click Search Query Rules.

  4. On the Manage Query Rules page, on the Select a Result Source menu, select the result source that contains the query rules that you want to group.

  5. For each query rule that you created that you want to add to a group, point to the rule and select the check box.

    Note

    Query rules that you created for this site collection are listed in the Defined for this site collection section.

  6. Click Order Selected Rules.

  7. In the Order Selected Rules dialog, do either of the following, and then click OK:

  • Select Move rules to new group with this name, and then type a name for the group.

  • Select Move rules to existing group and select a group in the drop-down list.

  1. On the Manage Query Rules page, do the following:

  2. To change the order in which a rule in a group will fire if it is triggered, change the numeric order of the rule.

  3. To prevent query rules that are ranked lowest in the group from firing, in the row for the group's query rule that should fire last, in the Actions column, in the Continue/Stop drop-down list, select Stop.

See also

Concepts

Plan to transform queries and order results in SharePoint Server

Overview of search result ranking in SharePoint Server

Query variables in SharePoint Server