Keyword Query Language (KQL) syntax reference
Updated: 2013/04/23
Learn to construct KQL queries for Search in SharePoint 2013. This syntax reference describes KQL query elements and how to use property restrictions and operators in KQL queries.
Applies to: SharePoint Foundation 2013 | SharePoint Server 2013
A KQL query consists of one or more of the following elements:
-
Free text-keywords—words or phrases
-
Property restrictions
You can combine KQL query elements with one or more of the available operators.
If the KQL query contains only operators or is empty, it isn't valid. KQL queries are case-insensitive but the operators are case-sensitive (uppercase).
Note
|
|---|
|
The length limit of a KQL query varies depending on how you create it. If you create the KQL query by using the default SharePoint search front end, the length limit is 2,048 characters. However, KQL queries you create programmatically by using the Query object model have a default length limit of 4,096 characters. You can increase this limit up to 20,480 characters by using the MaxKeywordQueryTextLength property or the DiscoveryMaxKeywordQueryTextLength property (for eDiscovery). |
When you construct your KQL query by using free-text expressions, Search in SharePoint 2013 matches results for the terms you chose for the query based on terms stored in the full-text index. This includes managed property values where FullTextQueriable is set to true.
Free text KQL queries are case-insensitive but the operators must be in uppercase. You can construct KQL queries by using one or more of the following as free-text expressions:
-
A word (includes one or more characters without spaces or punctuation)
-
A phrase (includes two or more words together, separated by spaces; however, the words must be enclosed in double quotation marks)
To construct complex queries, you can combine multiple free-text expressions with KQL query operators. If there are multiple free-text expressions without any operators in between them, the query behavior is the same as using the AND operator.
Using words in the free-text KQL query
When you use words in a free-text KQL query, Search in SharePoint 2013 returns results based on exact matches of your words with the terms stored in the full-text index. You can use just a part of a word, from the beginning of the word, by using the wildcard operator (*) to enable prefix matching. In prefix matching, Search in SharePoint 2013 matches results with terms that contain the word followed by zero or more characters.
For example, the following KQL queries return content items that contain the terms "federated" and "search":
federated search
federat* search
search fed*
KQL queries don’t support suffix matching.
Using phrases in the free-text KQL query
When you use phrases in a free-text KQL query, Search in SharePoint 2013 returns only the items in which the words in your phrase are located next to each other. To specify a phrase in a KQL query, you must use double quotation marks.
KQL queries don’t support suffix matching, so you can’t use the wildcard operator before a phrase in free-text queries. However, you can use the wildcard operator after a phrase.
Using KQL, you can construct queries that use property restrictions to narrow the focus of the query to match only results based on a specified condition.
Specifying property restrictions
A basic property restriction consists of the following:
<Property Name><Property Operator><Property Value>
Table 1 lists some examples of valid property restrictions syntax in KQL queries.
|
Syntax |
Returns |
|---|---|
|
author:"John Smith" |
Returns content items authored by John Smith. |
|
filetype:docx |
Returns Microsoft Word documents. |
|
filename:budget.xlsx |
Returns content items with the file name budget.xlsx. |
The property restriction must not include white space between the property name, property operator, and the property value, or the property restriction is treated as a free-text query. The length of a property restriction is limited to 2,048 characters.
In the following examples, the white space causes the query to return content items containing the terms "author" and "John Smith", instead of content items authored by John Smith:
author: "John Smith"
author :"John Smith"
author : "John Smith"
In other words, the previous property restrictions are equivalent to the following:
author "John Smith"
Specifying property names for property restrictions
You must specify a valid managed property name for the property restriction. By default, Search in SharePoint 2013 includes several managed properties for documents.
To specify a property restriction for a crawled property value, you must first map the crawled property to a managed property. See Managed and crawled properties in Plan the end-user search experience.
The managed property must be Queryable so that you can search for that managed property in a document. In addition, the managed property may be Retrievable for the managed property to be retrieved. However, the managed property doesn’t have to be Retrievable to carry out property searches.
Property operators that are supported in property restrictions
Search in SharePoint 2013 supports several property operators for property restrictions, as shown in Table 2.
|
Operator |
Description |
Supported managed property type |
|---|---|---|
|
: |
Returns results where the value specified in the property restriction is equal to the property value that is stored in the Property Store database, or matches individual terms in the property value that is stored in the full-text index. |
|
|
= |
Returns search results where the property value is equal to the value specified in the property restriction. |
|
|
< |
Returns results where the property value is less than the value specified in the property restriction. |
|
|
> |
Returns search results where the property value is greater than the value specified in the property restriction. |
|
|
<= |
Returns search results where the property value is less than or equal to the value specified in the property restriction. |
|
|
>= |
Returns search results where the property value is greater than or equal to the value specified in the property restriction. |
|
|
<> |
Returns search results where the property value does not equal the value specified in the property restriction. |
|
|
.. |
Returns search results where the property value falls within the range specified in the property restriction. For example, the range A..B represents a set of values from A to B where both A and B are inclusive. For date ranges this means from the beginning of day A to the end of day B. |
Specifying property values
You must specify a property value that is a valid data type for the managed property's type. Table 3 lists these type mappings.
|
Managed type |
Data type |
|---|---|
|
DateTime() |
|
Text property values
For text property values, the matching behavior depends on whether the property is stored in the full-text index or in the search index.
Property values in the full-text index
Property values are stored in the full-text index when the FullTextQueriable property is set to true for a managed property. You can configure this only for string properties. Property values that are specified in the query are matched against individual terms that are stored in the full-text index. Use the NoWordBreaker property to specify whether to match with the whole property value.
For example, if you're searching for a content item authored by Paul Shakespear, the following KQL query returns matching results:
author:Shakespear
author:Paul
Prefix matching is also supported. You can use the wildcard operator (*), but isn’t required when you specify individual words. Continuing with the previous example, the following KQL query returns content items authored by Paul Shakespear as matches:
author:Shakesp*
When you specify a phrase for the property value, matched results must contain the specified phrase within the property value that is stored in the full-text index. The following query example returns content items with the text "Advanced Search" in the title, such as "Advanced Search XML", "Learning About the Advanced Search Web Part", and so on:
title:"Advanced Search"
Prefix matching is also supported with phrases specified in property values, but you must use the wildcard operator (*) in the query, and it is supported only at the end of the phrase, as follows:
title:"Advanced Sear*"
The following queries do not return the expected results:
title:"Advan* Search"
title:"Advanced Sear"
Numerical values for properties
For numerical property values, which include the Integer, Double, and Decimal managed types, the property restriction is matched against the entire value of the property.
Using multiple property restrictions within a KQL query
Search in SharePoint 2013 supports the use of multiple property restrictions within the same KQL query. You can use either the same property for more than one property restriction, or a different property for each property restriction.
When you use multiple instances of the same property restriction, matches are based on the union of the property restrictions in the KQL query. Matches would include content items authored by John Smith or Jane Smith, as follows:
author:"John Smith" author:"Jane Smith"
This functionally is the same as using the OR Boolean operator, as follows:
author:"John Smith" OR author:"Jane Smith"
When you use different property restrictions, matches are based on an intersection of the property restrictions in the KQL query, as follows:
author:"John Smith" filetype:docx
Matches would include Microsoft Word documents authored by John Smith. This is the same as using the AND Boolean operator, as follows:
author:"John Smith" AND filetype:docx
KQL syntax includes several operators that you can use to construct complex queries.
Boolean operators
You use Boolean operators to broaden or narrow your search. You can use Boolean operators with free text expressions and property restrictions in KQL queries. Table 4 lists the supported Boolean operators.
|
Operator |
Description |
|---|---|
|
AND |
Returns search results that include all of the free text expressions, or property restrictions specified with the AND operator. You must specify a valid free text expression and/or a valid property restriction both preceding and following the AND operator. This is the same as using the plus ("+") character. |
|
NOT |
Returns search results that don't include the specified free text expressions or property restrictions. You must specify a valid free text expression and/or a valid property restriction following the NOT operator. This is the same as using the minus ("–") character. |
|
OR |
Returns search results that include one or more of the specified free text expressions or property restrictions. You must specify a valid free text expression and/or a valid property restriction both preceding and following the OR operator. |
Proximity operators
You use proximity operators to match the results where the specified search terms are within close proximity to each other. Proximity operators can be used with free-text expressions only; they are not supported with property restrictions in KQL queries. There are two proximity operators: NEAR and ONEAR.
NEAR operator
The NEAR operator matches the results where the specified search terms are within close proximity to each other, without preserving the order of the terms. The syntax for NEAR is as follows:
<expression> NEAR(n=4) <expression>
Where n is an optional parameter that indicates maximum distance between the terms. The value of n is an integer >= 0 with a default of 8.
The parameter n can be specified as n=v where v represents the value, or shortened to only v; such as NEAR(4) where v is 4.
For example:
"acquisition" NEAR "debt"
This query matches items where the terms "acquisition" and "debt" appear within the same item, where an instance of "acquisition" is followed by up to eight other terms, and then an instance of the term "debt"; or vice versa. The order of the terms is not significant for the match.
If you need a smaller distance between the terms, you can specify it. The following query matches items where the terms "acquisition" and "debt" appear within the same item, where a maximum distance of 3 between the terms. Once again the order of the terms does not affect the match.
"acquisition" NEAR(n=3) "debt"
|
Note
|
|---|
|
In SharePoint 2013 the NEAR operator no longer preserves the ordering of tokens. In addition, the NEAR operator now receives an optional parameter that indicates maximum token distance. However, the default value is still 8. If you must use the previous behavior, use ONEAR instead. |
ONEAR operator
The ONEAR operator matches the results where the specified search terms are within close proximity to each other, while preserving the order of the terms. The syntax for ONEAR is as follows, where n is an optional parameter that indicates maximum distance between the terms. The value of n is an integer >= 0 with a default of 8.
<expression> ONEAR(n=4) <expression>
The parameter n can be specified as n=v where v represents the value, or shortened to only v; such as ONEAR(4) where v is 4.
For example, the following query matches items where the terms "acquisition" and "debt" appear within the same item, where an instance of "acquisition" is followed by up to eight other terms, and then an instance of the term "debt". The order of the terms must match for an item to be returned:
"acquisition" ONEAR "debt"
If you require a smaller distance between the terms, you can specify it as follows. This query matches items where the terms "acquisition" and "debt" appear within the same item, where a maximum distance of 3 between the terms. The order of the terms must match for an item to be returned:
"acquisition" ONEAR(n=3) "debt"
Synonym operators
You use the WORDS operator to specify that the terms in the query are synonyms, and that results returned should match either of the specified terms. You can use the WORDS operator with free text expressions only; it is not supported with property restrictions in KQL queries.
The following query example matches results that contain either the term "TV" or the term "television". This matching behavior is the same as if you had used the following query:
WORDS(TV, Television)
TV OR Television
These queries differ in how the results are ranked. When you use the WORDS operator, the terms "TV" and "television" are treated as synonyms instead of separate terms. Therefore, instances of either term are ranked as if they were the same term. For example, a content item that contained one instance of the term "television" and five instances of the term "TV" would be ranked the same as a content item with six instances of the term "TV".
Wildcard operator
You use the wildcard operator—the asterisk character ("*")—to enable prefix matching. You can specify part of a word, from the beginning of the word, followed by the wildcard operator, in your query, as follows. This query would match results that include terms beginning with "serv", followed by zero or more characters, such as serve, server, service, and so on:
serv*
Inclusion and exclusion operators
You can specify whether the results that are returned should include or exclude content that matches the value specified in the free text expression or the property restriction by using the inclusion and exclusion operators, described in Table 5.
|
Name |
Operator |
Behavior |
|---|---|---|
|
Inclusion |
"+" |
Includes content with values that match the inclusion. This is the default behavior if no character is specified. This is the same as using the AND operator. |
|
Exclusion |
"-" |
Excludes content with values that match the exclusion. This is the same as using the NOT operator. |
Dynamic ranking operator
You use the XRANK operator to boost the dynamic rank of items based on certain term occurrences within the match expression, without changing which items match the query. An XRANK expression contains one component that must be matched, the match expression, and one or more components that contribute only to dynamic ranking, the rank expression. At least one of the parameters, excluding n, must be specified for an XRANK expression to be valid.
Match expressions may be any valid KQL expression, including nested XRANK expressions. Rank expressions may be any valid KQL expression.
You can use the XRANK operator in the following syntax:
<match expression> XRANK(cb=100, rb=0.4, pb=0.4, avgb=0.4, stdb=0.4, nb=0.4, n=200) <rank expression>
The XRANK operator's dynamic ranking calculation is based on this formula:
Table 6 lists the basic parameters available for the XRANK operator.
|
Parameter |
Value |
Description |
|---|---|---|
|
n |
<integer_value> |
Specifies the number of results to compute statistics from. This parameter does not affect the number of results that the dynamic rank contributes to; it is just a means to exclude irrelevant items from the statistics calculations. Default: 0. A zero value carries the semantic of all documents. |
|
nb |
<float_value> |
The nb parameter refers to normalized boost. This parameter specifies the factor that is multiplied with the product of the variance and average score of the rank values of the results set. f in the XRANK formula. |
Typically, normalized boost, nb, is the only parameter that is modified. This parameter provides the necessary control to promote or demote a particular item, without taking standard deviation into account.
The following advanced parameters are also available. However, typically they're not used.
|
Parameter |
Value |
Description |
|---|---|---|
|
cb |
<float_value> |
The cb parameter refers to constant boost. Default: 0. a in the XRANK formula. |
|
stdb |
<float_value> |
The stdb parameter refers to standard deviation boost. Default: 0. e in the XRANK formula. |
|
avgb |
<float_value> |
The avgb parameter refers to average boost. Default: 0. d in the XRANK formula. |
|
rb |
<float_value> |
The rb parameter refers to range boost. This factor is multiplied with the range of rank values in the results set. Default: 0. b in the XRANK formula. |
|
pb |
<float_value> |
The pb parameter refers to percentage boost. This factor is multiplied with the item's own rank compared to the minimum value in the corpus. Default: 0. c in the XRANK formula. |
Parenthesis
You can combine different parts of a keyword query by using the opening parenthesis character "(" and closing parenthesis character ")". Each opening parenthesis "(" must have a matching closing parenthesis ")". A white space before or after a parenthesis does not affect the query.
|
Date |
Description |
|---|---|
|
April 23, 2013 |
Updated to include a note describing the different KQL query length limits depending on how you create it. |
|
July 16, 2012 |
Initial publication |
