Understanding query transforms

To provide search results that are appropriate for a user query, sometimes you have to change the query. For example, suppose you create a search vertical for Pictures. When someone types a query in the Pictures vertical, you have to change the query so that it returns only search results that are Pictures.

To change a query, you use the Query Builder to configure a query transform. You can configure a query transform to replace properties of a query, such as the result source that the query will use to get search results, or the sort order that it will use when it displays search results. The transform also replaces the text of the query by using a query template that you can configure. The query template is the text that will replace the query text, and the template can contain query variables.

A query variable is a placeholder for a value. When a transform replaces the text of a query with its query template, it also replaces the query variables in the template with specific values.

A transform replaces contextual query variables with values pertaining to the query context. The following table shows some examples of contextual query variables.

A transform replaces this contextual query variable

With this


Name of user who typed the query


Site where user typed the value


Today's date

A transform replaces bound query variables with certain text that is in the user's query. The following table shows some examples of bound query variables.

A transform replaces this bound query variable

With this


The query that the user typed


The query that the user typed, as changed by the most recent transform

You can use a bound query variable when you add a restriction to a query, such as when you restrict a query to a particular content type. For example, for a Pictures search vertical, you could configure a query transform that adds "contenttype:picture" to the query text by using the query template "{searchTerms} contenttype:picture". If a user types the query "moon" in that vertical, the transform replaces "{searchTerms}" with "moon". Thus, the query transform changes the query to "moon contenttype:picture".

You can configure query transforms in three places:

  • In a Web Part, such as a Search Results Web Part. Configure a transform in a Web Part when you do not need to make the same changes to queries elsewhere.

  • In a query rule, which specifies that certain actions will be performed only if certain conditions are satisfied. Two of these actions use a transform to change the query:

    • Add a result block on the search results page. This action creates a copy of the query, and its transform changes only the copy.

    • Change the ranked results. This action changes the query that the user typed.

  • In the result source that the query uses to get search results.

A user query is transformed by the Web Part, then by any query rules that apply, and finally by the result source. Therefore, when you configure a transform in a result source, you know that the transform changes will not be discarded or overridden, because the result source transforms the query last. For example, to make sure that a Pictures search vertical returns only pictures, you would configure the appropriate transform in a result source, and then configure the Web Part in the search vertical to use that result source.

For more information, see Overview of query processing on TechNet.

Top of Page

Share Facebook Facebook Twitter Twitter Email Email

Was this information helpful?

Great! Any other feedback?

How can we improve it?

Thank you for your feedback!