Keyword Query Language (KQL) syntax reference

SharePoint

Learn to construct KQL queries for Search in SharePoint. This syntax reference describes KQL query elements and how to use property restrictions and operators in KQL queries.

Elements of a KQL query

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).

Constructing free-text queries using KQL

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:

  • Aword(includes one or more characters without spaces or punctuation)
  • Aphrase(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 theANDoperator.

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.

Property restriction queries in KQL

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.

Table 1. Valid property restriction syntax

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 namebudget.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"

Property operators that are supported in property restrictions

Search in SharePoint 2013 supports several property operators for property restrictions, as shown in Table 2.

Table 2. Valid property operators for property restrictions

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. /
  • Text
  • DateTime
  • Integer
  • Decimal
  • Double
  • YesNo

= / Returns search results where the property value is equal to the value specified in the property restriction.
Note
We do not recommend combining the=operator together with asterisk (*) when you do exact matching.
/
  • Text
  • DateTime
  • Integer
  • Decimal
  • Double
  • YesNo

Returns results where the property value is less than the value specified in the property restriction. /
  • DateTime
  • Integer
  • Decimal
  • Double

Returns search results where the property value is greater than the value specified in the property restriction. /
  • DateTime
  • Integer
  • Decimal
  • Double

<= / Returns search results where the property value is less than or equal to the value specified in the property restriction. /
  • DateTime
  • Integer
  • Decimal
  • Double

>= / Returns search results where the property value is greater than or equal to the value specified in the property restriction. /
  • DateTime
  • Integer
  • Decimal
  • Double

Returns search results where the property value does not equal the value specified in the property restriction. /
  • DateTime
  • Integer
  • Decimal
  • Text
  • Double
  • YesNo

.. / 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. /
  • DateTime
  • Integer
  • Decimal
  • Double

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.

Table 3. Valid data type mappings for managed property types

Managed type / Data type
Text / String
Integer / Int64
Double / System.Double
Decimal / Decimal
DateTime() / DateTime
YesNo / Boolean

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 theFullTextQueriableproperty is set totruefor 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 theNoWordBreakerproperty 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 theInteger,Double, andDecimalmanaged types, the property restriction is matched against the entire value of the property.

Date or time values for properties

KQL provides thedatetimedata type for date and time.The following ISO 8601-compatible datetime formats are supported in queries:

  • YYYY-MM-DD
  • YYYY-MM-DDThh:mm:ss
  • YYYY-MM-DDThh:mm:ssZ
  • YYYY-MM-DDThh:mm:ssfrZ

In thesedatetimeformats:

  • YYYYspecifies a four-digit year.

Note
Only four-digit years are supported.
  • MMspecifies a two-digit month. For example, 01 = January.
  • DDspecifies a two-digit day of the month (01 through 31).
  • Tspecifies the letter "T".
  • hhspecifies a two-digits hour (00 through 23); A.M./P.M. indication is not allowed.
  • mmspecifies a two-digit minute (00 through 59).
  • ssspecifies a two-digit second (00 through 59).
  • frspecifies an optional fraction of seconds, ss; between 1 to 7 digits that follows the.after the seconds. For example, 2012-09-27T11:57:34.1234567.

All date/time values must be specified according to the UTC (Coordinated Universal Time), also known as GMT (Greenwich Mean Time) time zone. The UTC time zone identifier (a trailing "Z" character) is optional.

Relevant date intervals supported by KQL

KQL enables you to build search queries that support relative "day" range query, with reserved keywords as shown in Table 4. Use double quotation marks ("") for date intervals with a space between their names.

Name of date interval / Description
today / Represents the time from the beginning of the current day until the end of the current day.
yesterday / Represents the time from the beginning of the day until the end of the day that precedes the current day.
this week / Represents the time from the beginning of the current week until the end of the current week. The culture in which the query text was formulated is taken into account to determine the first day of the week.
this month / Represents the time from the beginning of the current month until the end of the current month.
last month / Represents the entire month that precedes the current month.
this year / Represents the time from the beginning of the current year until the end of the current year.
last year / Represents the entire year that precedes the current year.

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 theORBoolean 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 theANDBoolean operator, as follows:

author:"John Smith" AND filetype:docx

KQL operators for complex queries

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 5 lists the supported Boolean operators.

Table 5. Boolean operators supported in KQL

Operator / Description
AND / Returns search results that include all of the free text expressions, or property restrictions specified with theANDoperator. You must specify a valid free text expression and/or a valid property restriction both preceding and following theANDoperator. 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 theNOToperator. 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 theORoperator.

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:NEARandONEAR.

NEAR operator

TheNEARoperator matches the results where the specified search terms are within close proximity to each other, without preserving the order of the terms. The syntax forNEARis as follows:

<expression> NEAR(n=4) <expression>

Wherenis an optional parameter that indicates maximum distance between the terms. The value ofnis an integer >= 0 with a default of8.

The parameterncan be specified asn=vwherevrepresents the value, or shortened to onlyv; such asNEAR(4)wherevis 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 theNEARoperator no longer preserves the ordering of tokens. In addition, theNEARoperator now receives an optional parameter that indicates maximum token distance. However, the default value is still8. If you must use the previous behavior, useONEARinstead.

ONEAR operator

TheONEARoperator matches the results where the specified search terms are within close proximity to each other, while preserving the order of the terms. The syntax forONEARis as follows, wherenis an optional parameter that indicates maximum distance between the terms. The value ofnis an integer >= 0 with a default of8.

<expression> ONEAR(n=4) <expression>

The parameterncan be specified asn=vwherevrepresents the value, or shortened to onlyv; such asONEAR(4)wherevis 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 termsmustmatch 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 termsmustmatch for an item to be returned:

"acquisition" ONEAR(n=3) "debt"

Synonym operators

You use theWORDSoperator to specify that the terms in the query are synonyms, and that results returned should match either of the specified terms. You can use theWORDSoperator 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 theWORDSoperator, 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 6.

Table 6. Operators for including and excluding content in results

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 theANDoperator.
Exclusion / "-" / Excludes content with values that match the exclusion. This is the same as using theNOToperator.

Dynamic ranking operator

You use theXRANKoperator to boost the dynamic rank of items based on certain term occurrences within thematch expression, without changing which items match the query. AnXRANKexpression contains one component that must be matched, thematch expression, and one or more components that contribute only to dynamic ranking, therank expression. At leastoneof the parameters, excludingn, must be specified for anXRANKexpression to be valid.