droplog

[SharePoint development overview]
[Search in SharePoint]

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

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

Constructing free-text queries using KQL

When you construct your KQL query by using free-text expressions, Search in SharePoint 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 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 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 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 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 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 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 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.

Date or time values for properties

KQL provides the datetime data 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 these datetime formats:

YYYY specifies a four-digit year.

Note
Only four-digit years are supported.
MM specifies a two-digit month. For example, 01 = January.
DD specifies a two-digit day of the month (01 through 31).
T specifies the letter "T".
hh specifies a two-digits hour (00 through 23); A.M./P.M. indication is not allowed.
mm specifies a two-digit minute (00 through 59).
ss specifies a two-digit second (00 through 59).
fr specifies 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 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 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 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 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 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 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.

Note

Query latency (and probability of timeout) increases when using complex queries and especially when using xrank operators. The increase in query latency depends on the number of XRANK operators and the number of hits in the match expression and rank expression components in the query tree.

Match expressions may be any valid KQL expression, including nested XRANK expressions. Rank expressions may be any valid KQL expression without XRANK expressions. If your KQL queries have multiple XRANK operators, the final dynamic rank value is calculated as a sum of boosts across all XRANK operators.

Note

Use parenthesis to explicitly indicate the order of computation for KQL queries that have more than one XRANK operator at the same level.

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 7 lists the basic parameters available for the XRANK operator.
Table 7. XRANK operator parameters

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.
Table 8. Advanced parameters for XRANK

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.

Examples

Example 1. The following expression matches items for which the default full-text index contains either "cat" or "dog". The expression increases dynamic rank of those items with a constant boost of 100 for items that also contain "thoroughbred".
(cat OR dog) XRANK(cb=100) thoroughbred
Example 2. The following expression matches items for which the default full-text index contains either "cat" or "dog". The expression increases dynamic rank of those items with a normalized boost of 1.5 for items that also contain "thoroughbred".
(cat OR dog) XRANK(nb=1.5) thoroughbred
Example 3. The following expression matches items for which the default full-text index contains either "cat" or "dog". The expression increases dynamic rank of those items with a constant boost of 100 and a normalized boost of 1.5, for items that also contain "thoroughbred".
(cat OR dog) XRANK(cb=100, nb=1.5) thoroughbred
Example 4. The following expression matches all items containing the term "animals", and boosts dynamic rank as follows:

Dynamic rank of items that contain the term "dogs" is boosted by 100 points.
Dynamic rank of items that contain the term "cats" is boosted by 200 points.
Dynamic rank of items that contain both the terms "dogs" and "cats" is boosted by 300 points.

(animals XRANK(cb=100) dogs) XRANK(cb=200) cats

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

Learn about constructing complex search queries for Search in SharePoint using the FAST Query Language (FQL). This reference describes the elements of an FQL query and how to use property specifications, token expressions, and operators in your FQL queries.

Introduction to FQL and query language subexpressions and expressions in SharePoint

The FAST Query Language (FQL) is a powerful query language that enables developers to perform exact searches and to narrow the scope of your search to values that belong to a specific managed property or a full-text index.
A query language expression can contain nested subexpressions that include query terms, property specifications, and operators, as described in Table 1.
Table 1. Subexpressions in query language expressions

Item	Description
Token expressions	One or more query terms, phrases, or numeric values to search for in a query.
Property specification	A property or full-text index to match with the affected expression.
Operators	Keywords that specify Boolean operations (such as AND, OR) or other constraints to operands (such as FILTER.)

FQL query example

The following FQL query example searches for the terms "hello" and "world" in the body managed property of an indexed item:
body:string("hello world", mode="and")
In the example:

body: limits the scope of the query to the body managed property within the item.
"hello world" is the operand to the STRING operator, which indicates the terms to search for.
mode="and" indicates that the logical query operator AND will be applied to "hello world".

The length of FAST Query Language queries is limited to 2,048 characters.

Property specification in FQL

A property specification limits the scope of the affected expression to specific regions of the indexed content. Such a region can be identified by a full-text index or a managed property.
Managed properties of type Text and YesNo are evaluated as text. All other managed property types, including the Datetime type, are evaluated as numeric values.
If you don't include a property specification for an expression, the search engine attempts to match the default full-text index defined in the index schema.
The property name must always precede a colon ( In operator), and numeric operators must always include a property specification.
A property specification (the In Operator) may be applied to the following query entities:

A single term or phrase, as follows:
author:shakespeare
title:"to be or not to be"
An operator, for example, the STRING operator, as follows: title:string("to be or not to be") In this case the property specification applies to the complete operator expression.

Examples

Each of the following expressions matches items that have both "much" and "nothing" in the title managed property.
title:and(much, nothing)
and(title:much, title:nothing)
title:string("much nothing", mode="and")

Token expressions in FQL

Token expressions are words, phrases, or numeric values that are matched against the index.
A text token expression can be a single word or a phrase enclosed in double quotation marks.
A numeric token expression can be a single value or a value range expression.

Wildcard expressions

A wildcard expression indicates a single term or phrase that includes the Asterisk ("\*") character; asterisk implies a match of zero or more characters, excluding whitespace. FQL supports prefix search for individual text managed properties and full-text indexes.

Wildcard expression examples

The following is a list of valid uses of wildcard expressions in FQL:

text*
string("this examp*")

Numeric term expressions

Each numeric term expression must include a property specification of a compatible index schema data type. Table 2 lists the numeric data types that can be used in FQL.
Table 2. Numeric data types that can be used in FQL

FQL type	Compatible index schema types	Description
Int	Integer	64 bit integer.
Float	Double	64-bit (double precision) floating point.
Decimal	Decimal	128-bit decimal
Datetime	Datetime	A date and time value. The date/time support in FQL enables the same numeric operations on date/time values as on other numeric values.

Date and time query expressions

FQL provides the datetime data 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 these datetime formats:

YYYY specifies a four-digit year.

Note
Only four-digit years are supported.
MM specifies a two-digit month. For example, 01 = January.
DD specifies a two-digit day of the month (01 through 31).
T specifies the letter "T".
hh specifies a two-digits hour (00 through 23); A.M./P.M. indication is not allowed.
mm specifies a two-digit minute (00 through 59).
ss specifies a two-digit second (00 through 59).
fr specifies 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.

Reserved words, special characters, and escaping

The following words are reserved within FQL.
and, or, any, andnot, count, decimal, rank, near, onear, int, in32, int64, float, double, datetime, max, min, range, phrase, scope, filter, not, string, starts-with, ends-with, equals, words, xrank.
If you want to express any of these words as terms in a query expression, you must enclose them in double quotation marks as shown in the following examples:

or("any", "and", "xrank")
string("any and xrank", mode="OR")
phrase(this, is, a, "phrase")

Tip: Reserved words and characters are not case-sensitive, but using lowercase characters are recommended for future compatibility.

FQL does not always require a string to be enclosed in double quotation marks. For example, and(cat, dog) is valid FQL even though cat and dog are not in double quotation marks. However, we recommend that you use double quotation marks to avoid conflicts with reserved words.
The query terms are tokenized according to your locale setting. The tokenization process removes certain special characters. Because special characters are removed, the following FQL expressions are equivalent.
and("[king]", "<queen>")
and("king", "queen")
When a query includes terms from user input or another application, use the string("<query terms>", mode="AND|OR|PHRASE") operator to avoid conflict with reserved words in the query language. You must also remove possible double quotation marks from the user-provided query.

FQL Operators

FAST Query Language (FQL) operators are keywords that specify Boolean operations or other constraints to operands. The FQL operator syntax is as follows:
[property-spec:]operator(operand [,operand]* [, parameter="value"]*)
In the syntax:

property-spec is an optional property specification followed by the "in" operator.
operator is a keyword that specifies an operation to perform.
operand is a term expression or another operator.
parameter is the name of a value that changes the behavior of the operator.
value is the value to use for the parameter name.

Operator names, parameter names, and parameter text values are case-insensitive. White space is allowed within the operator body, but is ignored unless it is enclosed in double quotation marks. The length of FAST Query Language queries is limited to 2,048 characters.
Table 3 lists the types of operators supported by FQL.
Table 3. FQL supported operator types

Type	Description	Operators
String	Enables you to specify query operations on a string of terms. This is the most common operator to use on text terms.	STRING
Boolean	Enables you to combine terms and sub-expressions in a query.	AND, OR, ANY, ANDNOT, NOT, COUNT, COUNT
Proximity	Enables you to specify the proximity of the query terms in a matching sequence of text.	NEAR, ONEAR, PHRASE, STARTS-WITH, ENDS-WITH, EQUALS
Numeric	Enables you to specify numeric conditions in the query.	RANGE , INT, FLOAT, DATETIME, DECIMAL
Relevance	Enables you to impact the relevance evaluation of a query.	XRANK and FILTER

Table 4 provides a list of the supported operators.
Table 4. FQL supported operators

Operator	Description	Type
AND	Returns only items that match all AND* operands.*	Boolean
ANDNOT	Returns only items that match the first operand and that don't match the subsequent operands.	Boolean
ANY	Similar to the OR operator except that the dynamic rank (the relevance score in the result set.md) is affected by neither the number of operands that match nor the distance between the terms in the item.	Boolean
COUNT	Enables you to specify the number of query term occurrences an item must include to be returned as a result. The operand may be a single query term, a phrase, or wildcard query term.	Boolean
DATETIME	Provides explicit typing of numeric values. The explicit type conversion is optional and usually is not needed. The type of the query term is detected according to the type of the target numeric managed property.	Numeric
DECIMAL	Provides explicit typing of numeric values. The explicit type conversion is optional and usually is not needed. The type of the query term is detected according to the type of the target numeric managed property.	Numeric
ENDS-WITH	Specifies that a word or phrase must appear in the end of a managed property.	Proximity
EQUALS	Specifies that a word or phrase term or phrase must provide an exact token match with the managed property.	Proximity
FILTER	Used to query metadata or other structured data.	Relevance
FLOAT	Provides explicit typing of numeric values. The explicit type conversion is optional and usually is not needed. The type of the query term is detected according to the type of the target numeric managed property.	Numeric
INT	Provides explicit typing of numeric values. The explicit type conversion is optional and usually is not needed. The type of the query term is detected according to the type of the target numeric managed property.	Numeric
NEAR	Restricts the result set to items that have `N` terms within a certain distance of one another.	Proximity
NOT	Returns only items that exclude the operand.	Boolean
ONEAR	The ordered variant of NEAR, and requires an ordered match of the terms. The ONEAR operator can be used to restrict the result set to items that have `N` terms within a certain distance of Returns only items that don't match the operand. The operand may be any valid FQL expression.one another.	Proximity
OR	Returns only items that match at least one of the OR operands. Items that match will get a higher dynamic rank (relevance score in the result set.md) if more of the OR operands match.	Boolean
PHRASE	Returns only items that match an exact string of tokens.	Proximity
RANGE	Enables range matching expressions. The RANGE* operator is used for numeric and date/time managed properties.*	Numeric
STARTS-WITH	Specifies that a word or phrase must appear in the start of a managed property.	Proximity
STRING	Define a Boolean matching condition to a text string.	String
XRANK	Enables you to boost the dynamic rank of items based on certain term occurrences without changing which items match the query. A XRANK expression contains one component that must be matched, and one or more components that contribute only to dynamic ranking.	Relevance

Note

In SharePoint, the RANK operator is deprecated and will no longer have any effect. Use XRANK instead.

AND

Returns only items that match all AND operands. The operands may be a single term or any valid FQL sub-expression.

Syntax

Example 1. The following expression matches at least 5 occurrences of the word "cat".
count(cat, from=5)
Example 2. The following expression matches at least 5 but not 10 or more occurrences of the word "cat".
count(cat, from=5, to=10)
Example 3. Each of the following expressions matches at least 3 occurrences of a certain word, and that word can be either "cat" or "dog".
count(or(cat, dog), from=3)count(string("cat dog", mode="or"), from=3)
The following table contains examples of managed property string values and states whether they match the two expressions in Example 3.

Match?	Text
Yes	My cat likes my dog, but my dog hates my cat.
No	My bird likes my newt, but my dog hates my cat.

Examples

The following expression matches items with the values "Mr Adam Jones" and "Adam Jones" in the "author" managed property. It will not match items with the value "Adam Jones sr".
author:ends-with("adam jones")

Remarks

Boundary matching can be applied to all the text of the managed property, or to individual strings within a managed property that contains a list of string values, for example, a list of names. In this case, you may want to match the exact content of each string, and to avoid query matching across string boundaries.
To apply boundary match queries, you must configure the relevant managed property in the index schema.
By enabling the Boundary Match feature for the managed property, you can do the following:

Use explicit boundary match queries.
Prevent phrases from matching across string boundaries. For managed properties that contain multiple strings, this feature will ensure that a string does not match words before or after a boundary indication.

EQUALS

Specifies that a word or phrase must provide an exact token match with the managed property.

Syntax

equals(<term or phrase>)

Parameters

Not applicable.

Examples

The following example will match items with the values "Adam Jones" in the "author" managed property. It will not match items with the values "Adam Jones sr" or "Mr Adam Jones".
author:equals("adam jones")

Remarks

See also ENDS-WITH.

FILTER

Used to query metadata or other structured data.
Using the FILTER operator automatically implies the following for the specified query:

Linguistics will be set to linguistics="OFF".
Ranking will be disabled.
No query highlighting will be used in the hit highlighted summary for the query result hit.

Tip: If you use the STRING operator inside a FILTER expression, by default, linguistics is disabled. You can enable linguistics processing within each STRING expression inside FILTER by using the operand linguistics="ON".

The mode parameter specifies how to evaluate the <text string> value. The following list shows valid values. "PHRASE" - phrase(term [,term]*)

Mode	Equivalent operator expression
"PHRASE"	`phrase(term [,term])`*
"AND"	`and(term, term [,term])`*
"OR"	`or(term, term [,term])`*
"ANY"	`any(term, term [,term])`*
"NEAR"	`near(term, term [,term], N)`*
"ONEAR"	`onear(term, term [,term], N)`*

Default: "PHRASE"

n <numeric_value> This parameter indicates the maximum term distance for mode= "NEAR" or mode= "ONEAR".
The following expressions are equivalent: string("hello world", mode="NEAR", n=5) near(hello, world, n=5)
Default: 4

weight <numeric_value> This parameter is a positive numeric value indicating term weight for dynamic ranking.
A lower value indicates that a term should contribute less to the ranking. A higher value indicates that a term should contribute more to the ranking. A value of zero for the weight parameter specifies that a term should not affect dynamic rank.
The weight parameter applies to all the terms in the STRING expression. TIP: The weight parameter will affect only full-text index queries. Default: 100.

linguistics on|off Disables/enables all linguistics features for the string (lemmatization, synonyms, spelling checking) if they are enabled for the query.
You can use this parameter to switch off linguistic processing for a given term or string while you still want the term or string to contribute to ranking.
Default: "ON"

wildcard

on|off

This parameter controls wildcard expansion of terms inside the <text string>. This setting overrides any wildcard settings in query parameters, and allows extended wildcard characters to be enabled or disabled on specific parts of the query.
The following are valid values:

"ON" Specifies that the character "*" is evaluated as wildcard. A "*" character matches zero or more characters.
"OFF" Specifies that the characters "*" is not evaluated as wildcard.

Default: "ON"

Note

In SharePoint the minexpansion, maxexpansion and annotation_class parameters for the STRING operator are obsolete.

Examples

Example 1. Because the default string mode is " PHRASE ", each of the following expressions returns the same results.
"what light through yonder window breaks"string("what light through yonder window breaks")string("what light through yonder window breaks", mode="phrase")phrase(what, light, through, yonder, window, breaks)
Example 2. The following string token expression and the AND operator expression return the same results.
string("cat dog fox", mode="and")and(cat, dog, fox)
Example 3. The following string token expression and OR operator expression return the same results.
string("coyote saguaro", mode="or")or(coyote, saguaro)
Example 4. The following string token expression and ANY operator expression return the same results.
string("coyote saguaro", mode="any")any(coyote, saguaro)
Example 5. The following string token expression and NEAR operator expression return the same results.
string("coyote saguaro", mode="near")near(coyote, saguaro)
Example 6. The following string token expression and NEAR operator expression return the same results.
string("cat dog fox wolf", mode="near", N=4)near(cat, dog, fox, wolf, N=4)
Example 7. The following string token expression and ONEAR operator expression return the same results.
string("cat dog fox wolf", mode="onear")onear(cat, dog, fox, wolf)
Example 8. The following string token expression matches the word "nobler" with linguistic features disabled, so other forms of the word (such as "ennobling") are not matched by using stemming.
string("nobler", linguistics="off")
Example 9. The following expression matches items that contain either "cat" or "dog ", but the expression increases the dynamic rank of items that contain "dog" more than items that contain "cat".
or(string("cat", weight="200"), string("dog", weight="500"))

Remarks

Relevance weight for dynamic ranking
The main effect of the weight parameter is for OR queries. It can also have some effect on AND queries. The dynamic rank algorithm can imply that different terms give different rank contribution depending on where in the item the term match occurs.
The difference in rank contribution can also be based on term frequency and inverse item frequency. The following is an example:

Query: and(string("a"), string("b", weight=200))
Index schema: The title managed property has more weight than the body managed property.
Index item 1 includes term 'a' in the title and term 'b' in the body.
Index item 2 includes term 'a' in the body and term 'b' in the title.

In this example, item 2 will get the highest total rank, as the items with higher dynamic rank contribution will get even more boost.

Tip: The relative term boost (positive or negative) is applied to the dynamic rank component of the total rank. However, proximity boost (distance between words) rank calculations are not affected by the term weighting. The relative weighting does not always imply that the total rank for the item is modified according to the percentage given. > The following query will search for the terms "peter", "paul", or "mary", where "peter" will have twice as much rank contribution as the two other terms. > or(peter, string("paul mary", mode="OR", weight=50))

Handling strings with special characters
Special characters such as comma (","), semicolon (";"), colon (":"), period ("."), minus ("-"), underline ("_"), or forward slash ("/") are treated as white space inside a string expression enclosed in double quotation marks. This is related to the tokenization process. These characters also imply an implicit phrasing of the tokens separated by these characters.
The following query expressions are equivalent.
title:string("animals birds", mode="phrase")title:"animals/birds"title:string("animals/birds", mode="and")title:string("animals/birds", mode="or")
The following query expressions are equivalent.
title:or(string("animals birds", mode="phrase"), string("animals insects", mode="phrase"))title:string("animals/birds animals/insects", mode="or")
The following query expressions are equivalent.
body:string("help contoso com", mode="phrase")body:string("help@contoso.com")
Tokenized phrase matching
You can search for an exact string of tokens by using the STRING operator with mode="phrase" or the PHRASE operator.
All such phrase operations imply a tokenized phrase match. This means that special characters such as comma (" , "), semicolon (" ; "), colon (" : "), underscore (" _ "), minus (" - "), or forward slash (" / ") are treated as white space. This is related to the tokenization process.

XRANK

Boosts the dynamic rank of items based on certain term occurrences within the match expression, without changing which items match the query. An XRANK expression consists of 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 FQL expression, including nested XRANK expressions. Rank expressions may be any valid FQL expression without XRANK expressions. If your FQL queries have multiple XRANK operators, the final dynamic rank value is calculated as a sum of boosts across all XRANK operators.

Note

In SharePoint Server 2010, the XRANK operator had two parameters: boost and boostall, as well as the following syntax: xrank(operand, rank-operand [, rank-operand]* [,boost=n] [,boostall=yes]). This syntax along with its parameters is deprecated in SharePoint. We recommend the use of the new syntax and parameters instead.

Syntax

xrank(<match expression> [, <rank-expression>]*, rank-parameter[, rank-parameter]*)

Formula

Parameters

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

Advanced parameters

The following advanced parameters are also available. However, typically they aren't 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. This factor is multiplied with the average rank value of the results set. 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.

Examples

Example 1. The following expression matches items for which the default full-text index contains either "cat" or "dog". The expression increases dynamic rank of those items with a constant boost of 100 for items that also contain "thoroughbred".
xrank(or(cat, dog), thoroughbred, cb=100)
Example 2. The following expression matches items for which the default full-text index contains either "cat" or "dog". The expression increases dynamic rank of those items with a normalized boost of 1.5 for items that also contain "thoroughbred".
xrank(or(cat, dog), thoroughbred, nb=1.5)
Example 3. The following expression matches items for which the default full-text index contains either "cat" or "dog". The expression increases dynamic rank of those items with a constant boost of 100 and a normalized boost of 1.5, for items that also contain "thoroughbred".
xrank(or(cat, dog), thoroughbred, cb=100, nb=1.5)
Example 4. The following expression matches all items containing the term "animals", and boosts dynamic rank as follows:

Dynamic rank of items that contain the term "dogs" is boosted by 100 points.
Dynamic rank of items that contain the term "cats" is boosted by 200 points.
Dynamic rank of items that contain both the terms "dogs" and "cats" is boosted by 300 points.

xrank(xrank(animals, dogs, cb=100), cats, cb=200) (2)

(1) Keyword Query Language (KQL) syntax reference [lookup: managed properties]
(2) FAST Query Language (FQL) syntax reference [lookup: managed properties]

Thursday, March 17, 2022

Content Search Web Part and AGILE Carousel (news rotator)

Wednesday, April 28, 2021

New thoughts on collaborative platforms

Wednesday, May 20, 2020

Debug JavaScript in Safari

Thursday, April 30, 2020

Metrics for URL defined Subsites with Matomo

Using SVG with CSS3 and HTML5

Sunday, April 26, 2020

SVG and SVG tools

Saturday, October 27, 2018

Keyword Query Language (KQL) and FAST Query Language (FQL)

Constructing free-text queries using KQL

Using words in the free-text KQL query

Using phrases in the free-text KQL query

Property restriction queries in KQL

Specifying property restrictions

Specifying property names for property restrictions

Property operators that are supported in property restrictions

Specifying property values

Text property values

Property values in the full-text index

Numerical values for properties

Date or time values for properties

Relevant date intervals supported by KQL

Using multiple property restrictions within a KQL query

KQL operators for complex queries

Boolean operators

Proximity operators

NEAR operator

ONEAR operator

Synonym operators

Wildcard operator

Inclusion and exclusion operators

Dynamic ranking operator

Examples

Parenthesis

Introduction to FQL and query language subexpressions and expressions in SharePoint

FQL query example

Property specification in FQL

Examples

Token expressions in FQL

Wildcard expressions

Wildcard expression examples

Numeric term expressions

Date and time query expressions

Reserved words, special characters, and escaping

FQL Operators

AND

Syntax

Parameters

Examples

ANDNOT

Syntax

Parameters

Examples

ANY

Syntax

Parameters

Examples

COUNT

Syntax

Parameters

Examples

DATETIME

Syntax

Parameters

DECIMAL

Syntax

Parameters

ENDS-WITH

Syntax

Parameters

Examples

Remarks

EQUALS

Syntax

Parameters

Examples