Sign in with Microsoft
Sign in or create an account.
Select a different account.
You have multiple accounts
Choose the account you want to sign in with.

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

Need more help?

Want more options?

Explore subscription benefits, browse training courses, learn how to secure your device, and more.

Communities help you ask and answer questions, give feedback, and hear from experts with rich knowledge.

Was this information helpful?

What affected your experience?
By pressing submit, your feedback will be used to improve Microsoft products and services. Your IT admin will be able to collect this data. Privacy Statement.

Thank you for your feedback!