FAST Query Language (FQL) Operators

Article
07/24/2014

Applies to: SharePoint Server 2010

In this article
Overview of FQL Operators
AND
ANDNOT
ANY
COUNT
DATETIME
ENDS-WITH
EQUALS
FILTER
FLOAT
INT
NEAR
NOT
ONEAR
OR
PHRASE
RANGE
RANK
STARTS-WITH
STRING
XRANK

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.

Overview of FQL Operators

FQL supports the following types of operators:

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
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,
Relevance	Enables you to impact the relevance evaluation of a query.	RANK, XRANK, FILTER

The following table provides a list of the 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 do not match the subsequent operands.	Boolean
ANY	Similar to the OR operator except that the dynamic rank (the relevance score in the result set) 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
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 do not match the operand. The operand may be any valid FQL expression.	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 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) 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
RANK	Enables you to increase the dynamic rank of items based on certain term occurrences without changing which items match the query. A RANK expression contains one component that must be matched, and one or more components that contribute only to dynamic rank.	Relevance
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 increase 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 rank. This operator is similar to the RANK operator, but with different performance characteristics and control of rank contribution.	Relevance

AND

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

Syntax

and(operand, operand [, operand]*)

Parameters

Not applicable.

Examples

Example 1. The following expression matches items for which the default full-text index contains "cat", "dog", and "fox".

and(cat, dog, fox)

ANDNOT

Returns only items that match the first operand and that do not match the subsequent operands. The operands may be a single term or any valid FQL sub-expression.

Syntax

andnot(operand, operand [,operand]*)

Parameters

Not applicable.

Examples

Example 1. The following expression matches items for which the default full-text index contains "cat" but not "dog".

andnot(cat, dog)

Example 2. The following expression matches items for which the default full-text index contains "dog" but neither "beagle" nor "chihuahua".

andnot(dog, beagle, chihuahua)

ANY

Similar to the OR operator except that the dynamic rank (the relevance score in the result set) is affected by neither the number of operands that match nor the distance between the terms in the item. The operands may be a single term or any valid FQL sub-expression.

The dynamic ranking component for this part of the query is based on the best matching term within the ANY expression.

Note

The difference from OR is related only to the ranking within the result set. The same total set of items will match the query.

Syntax

any(operand, operand [,operand]*)

Parameters

Not applicable.

Examples

Example 1. The following expression matches items for which the default full-text index contains "cat" or "dog".

If the index contains both "cat" and "dog", but "cat" is considered a better match, the 'item's dynamic rank will be based on "cat" with no consideration given to "dog".

any(cat, dog)

COUNT

Specifies the of number query term occurrences an item must include for the item to be returned as a result. The operand may be a single query term, a phrase, or a wildcard query term.

Syntax

property-spec:count(operand [,from=<numeric value>, to=<numeric value>])

Parameters

Parameter	Value	Description
from	<numeric_value>	The value of the from parameter must be a positive integer that specifies the minimum number of times that the specified operand must be matched. If the from parameter is not specified, no lower limit will exist.
to	<numeric_value>	The value of the to parameter must be a positive integer that specifies the non-inclusive maximum number of times that the specified operand must be matched. For example, a to value of 11 specifies 10 times or fewer. If the to parameter is not specified, no upper limit will exist.

from

<numeric_value>

The value of the from parameter must be a positive integer that specifies the minimum number of times that the specified operand must be matched.

If the from parameter is not specified, no lower limit will exist.

<numeric_value>

The value of the to parameter must be a positive integer that specifies the non-inclusive maximum number of times that the specified operand must be matched. For example, a to value of 11 specifies 10 times or fewer.

If the to parameter is not specified, no upper limit will exist.

Examples

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)

DATETIME

Provides explicit typing of date/time numeric values. The operand is a date/time string formatted according to the syntax specified in Date and Time Query Expressions.

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.

Syntax

datetime(<date/time string>)

Parameters

Not applicable.

ENDS-WITH

Specifies that a word or phrase must appear in the end of a managed property (boundary matching).

Boundary matching is not supported on numeric managed properties. Numeric managed properties will always be subject to exact or value range matching.

Some applications may require that you are able to perform an exact match of a managed property. For example, this may be a product name managed property, where the full name of one product is a substring of another product name.

Syntax

ends-with(<term or phrase>)

Parameters

Not applicable.

Examples

Example 1. 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

Example 1. 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

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

Syntax

filter(<any valid FQL operator expression>)

Parameters

Not applicable.

Examples

Example 1. The following expression matches items that have a title managed property that contains "sonata" and a doctype managed property that contains only the token "audio". No linguistic matching will be performed on "audio". Because the FILTER token will be used to match "audio", that text will not be highlighted in the hit highlighted summary.

and(title:sonata, filter(doctype:equals("audio")))

Remarks

If you must restrict your query to match at least one of a large set of integer values in a numeric property, you can express this in two functionally equivalent ways:

and(string("hello world"), filter(property-spec:or(1, 20, 453, ... , 3473)))
and(string("hello world"), filter(property-spec:int("1 20 453 ... 3473", mode="or")))

The second example uses the INT operator by using a string with the set of numeric values in double quotation marks. This provides a significantly better query performance when filtering with a large set of numeric values.

If you must filter a large set of values, you should consider using numeric values instead of string values, and express your queries by using the optimized syntax.

FLOAT

Provides explicit typing of floating point numeric values. The operand is a floating point value according to the syntax specified in Numeric Term Expressions.

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.

Syntax

float(<floating point value>)

Parameters

Not applicable.

INT

Provides explicit typing of integer values. The operand is an integer value according to the syntax specified in Numeric Term Expressions.

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.

The INT operator can also be used to express a set of integer values as arguments to Boolean FQL operators. This provides a performance efficient way to provide a set of integer values in a query, as the values that are passed by using the INT operator are not parsed by the FQL query parser but passed directly to the query matching component.

Syntax

int(<integer value>)

int("value, value, … , value")

The first syntax specifies a single integer. The second syntax specifies a comma-separated list of integer values enclosed in double quotation marks.

Parameters

Not applicable.

Examples

Example 1. If you need to restrict your query to match at least one of a large set of integer values in a numeric property, you can express this by using the INT operator:

and(string("hello world"), filter(id:int("1 20 49 124 453 985 3473", mode="or")))

NEAR

Restricts the result set to items that have N terms within a certain distance of one another.

The order of the query terms is not important for the matching, only the distance.

Any number of terms can be combined with the NEAR operators.

NEAR operands may be single terms, phrases, or Boolean OR or ANY operator expressions. Wildcards are accepted.

If multiple operands of the NEAR operator match the same indexed token, they are considered near one another.

Syntax

near(arg, arg [, arg]* [, N=<numeric value>])

Parameters

Parameter	Value	Description
N	<numeric_value>	Specifies the maximum number of words that is allowed to appear between the terms (explicit proximity). If NEAR includes more than two operands, the maximum number of words allowed between the terms (N) is counted within the whole expression. Default: 4

<numeric_value>

Specifies the maximum number of words that is allowed to appear between the terms (explicit proximity).

If NEAR includes more than two operands, the maximum number of words allowed between the terms (N) is counted within the whole expression.

Default: 4

Examples

Example 1. The following expression matches strings that contain both "cat" and "dog" if no more than four indexed tokens (default) separate them.

near(cat, dog)

Example 2. The following expression matches strings that contain "cat", "dog", "fox", and "wolf" if no more than four indexed tokens separate them.

near(cat, dog, fox, wolf)

The following table contains examples of managed property string values and states whether they match the previous expression in Example 2.

Match?	Text
Yes	The picture shows a cat, a dog, a fox, and a wolf.
Yes (with stemming)	Dogs, foxes, and wolves are canines, but cats are felines.
No	The picture shows a cat with a dog, a fox, and a wolf.

The following expression matches all the strings in the previous table.

near(cat, dog, fox, wolf, N=5)

Example 3. The following expression matches a managed property that contains only the indexed token "clarinet" because both "c*t" and "clarinet" match and are considered near one another, even though both search tokens match the same indexed token.

near("c*t", "clarinet")

Remarks

NEAR/ONEAR Term Distance Considerations

N indicates the maximum number of words that are allowed to appear between the query terms within the matching segment of the item. If NEAR or ONEAR includes more than two operands, the maximum number of words allowed between the query terms (N) is counted within the segment of the item matching all the NEAR or ONEAR terms.

NEAR or ONEAR operates on tokenized text. This means that special characters such as comma (","), period ("."), colon (":"), or semicolon (";") will be treated as white space. The term "distance" relates to tokens within the indexed text.

If you use ONEAR or NEAR with equal operands, the operator will work as follows:

near(a, a, n=x)

This query will always return true if at least one instance of ''a'' appears within the context. This also means that NEAR cannot be used as a COUNT operator. For more information about counting term occurrences, see the COUNT operator.

NEAR applied to phrases will also match overlapping phrases in the text.

If a token in the matching segment matches more than one operand to the NEAR or ONEAR expression, the query may match even if the number of nonmatching tokens within the matching segment exceeds the value of 'N' in the NEAR or ONEAR operator expression. For example, an overlap can be overlapping phrases. If the number of token overlap matches is 'O', the query will match if not more than 'N+O' non-matching tokens appear within the matching segment of the item.

NEAR or ONEAR** with NOT**

The NOT operator cannot be used inside the NEAR or ONEAR operator. The following is incorrect FQL syntax:

near(audi,not(bmw),n=2)

NOT

Returns only items that do not match the operand. The operand may be any valid FQL expression.

Syntax

not(operand)

Parameters

Not applicable.

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 one another.

Syntax

onear(arg, arg [, arg]* [, N=<numeric value>])

Parameters

Parameter	Value	Description
N	<numeric_value>	Specifies the maximum number of words that are allowed to appear between the terms (explicit proximity). If ONEAR includes more than two operands, the maximum number of words allowed between the terms (N) is counted within the whole expression. Default: 4

<numeric_value>

Specifies the maximum number of words that are allowed to appear between the terms (explicit proximity).

If ONEAR includes more than two operands, the maximum number of words allowed between the terms (N) is counted within the whole expression.

Default: 4

Examples

Example 1. The following expression matches all the occurrences of the words "cat", "dog", "fox", and "wolf" that appears in order, if no more than four indexed tokens separate them.

onear(cat, dog, fox, wolf)

The following table contains examples of managed property string values, and states whether they match the previous expression.

Match?	Text
Yes	The picture shows a cat, a dog, a fox, and a wolf.
No	Dogs, foxes, and wolves are canines, but cats are felines.
No	The picture shows a cat with a dog, a fox, and a wolf.

Example 2. The following expression matches (with stemming) the text in the second row of the previous table.

onear(dog, fox, wolf, cat, N=5)

**Example 3.**The following expression matches the text in the first and third rows of the preceding table.

onear(cat, dog, fox, wolf, N=5)

Remarks

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) if more of the OR operands match. The operands may be a single term or any valid FQL sub-expression.

Syntax

or(operand, operand [,operand]*)

Parameters

Not applicable.

Examples

Example 1. The following expression matches all the items for which the default full-text index contains either "cat" or "dog". If an item's default full-text index contains both "cat" and "dog", it will match and have a higher dynamic rank than it would if it contained only one of the tokens.

or(cat, dog)

PHRASE

Searches for an exact string of tokens.

The PHRASE operands can be single terms. Wildcards are accepted.

Syntax

phrase(term [, term]*)

Parameters

Not applicable.

Remarks

RANGE

Use the RANGE operator for numeric and date/time managed properties. The operator enables range matching expressions.

Syntax

range(start, end [,from="GE"|"GT"] [,to="LE"|"LT"])

Parameters

Parameter	Value	Description
start	<numeric_value>\|<date/time_value>	Start value for the range. To specify that the range has no lower bound, use the reserved word min.
stop	<numeric_value>\|<date/time_value>	End value for the range. To specify that the range has no upper bound, use the reserved word max.
from	GE\|GT	Optional parameter that indicates the open or close start interval. Valid values: GE Greater than or equal to the start value (>= start of interval). GT Greater than the start value (> start of interval). Default: GE
to	LE\|LT	Optional parameter that indicates the open or close end interval. Valid values: LE Less than or equal to the end value (<= end of interval). LT Less than the end value (< end of interval). Default: LT

Examples

Example 1. The following expression matches a description property starting with the phrase "olympic games" appearing in items with a size of at least 10 000 bytes.

and(size:range(10000, max), description:starts-with("olympic games"))

RANK

Boosts the dynamic rank of items based on certain term occurrences without changing which items match the query. A RANK expression contains one component that must be matched, and one or more components that contributes only to dynamic rank.

The differences between the RANK operator and the XRANK operator are as follows:

XRANK is much more efficient than RANK when terms in the RANK operands generate many hits.
For XRANK, the boost level can be set through the boost parameter, at query time.
XRANK adds a constant rank value, whereas RANK adds rank value associated with the operands.
XRANK will add rank to items that have not received any dynamic rank.
The XRANK operands can also address managed properties (not only full-text indexes).

The RANK operator takes two or more operands. The first operand is the main query expression that is matched. It contributes to recall or precision as any other term or expression. The subsequent operands contribute to boost dynamic rank, but do not affect which items match the query. The operands may be single terms or any valid FQL sub-expression.

The RANK operator can be used only against full-text indexes.

Syntax

rank(operand, rank-operand [, rank-operand]*)

Parameters

Not applicable.

Examples

Example 1. The following expression matches items for which the index contains "dog". The expression will increase an item's dynamic rank if its index also contains "cat". If the index contains "cat" but not "dog", the item will not match the expression.

rank(dog, cat)

Example 2. The following expression matches items for which the index contains "dog". The expression will increase an item's dynamic rank if the index also contains "boxer" or "pointer".

rank(dog, boxer, pointer)

Example 3. The following expression matches the same items as the preceding expression but will increase an item's dynamic rank if the index also contains the phrase "thoroughbred beagle".

rank(dog, "thoroughbred beagle")

Example 4. The following expression matches items for which the title managed property contains both "dog" and "beagle". The expression increases the dynamic rank of items for which the title managed property also contains the indexed token "thoroughbred".

and(title:dog, rank(title:beagle, title:thoroughbred))

STARTS-WITH

Specifies a word or phrase that must appear at the start of a managed property.

Syntax

starts-with(<term or phrase>)

Parameters

Not applicable.

Examples

Example 1. The following expression will match items with the values "Adam Jones sr" and "Adam Jones" in the author managed property. It will not match items with the value "Mr Adam Jones".

author:starts-with("adam jones")

Remarks

For additional remarks on boundary matching, see ENDS-WITH.

STRING

Defines a Boolean matching condition to a text string.

The operand is a text string (one or more terms) that is to be matched. The string is followed by zero or more parameters.

The STRING operator can also be used as a type conversion. The query string("24.5"), for example, will treat the numeric value "24.5" as a text string.

Syntax

string("<text string>"

[, mode=<mode>]

[, n=<near>]

[, weight=<n>]

[, linguistics=<on|off>]

[, wildcard=<on|off>]

[, minexpansion=<n>]

[, maxexpansion=<n>]

[, annotation_class=<annotation_string>])

Parameters

mode

<mode>

The mode parameter specifies how to evaluate the <text string> value. The following table shows valid values.

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)
"SIMPLEALL"	The string is formatted according to the simple query language "ALL" syntax. For details, see FQL Simple Query Language.
"SIMPLEANY"	The string is formatted according to the simple query language "ANY" syntax. For details, see FQL Simple Query Language.

Default: "PHRASE"

<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 for 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 characters "?" and "*" are evaluated as wildcards. A "?" character matches any single character, and a "*" character matches zero or more characters.
"OFF" Specifies that the characters "?" and "*" are not evaluated as wildcards.

Default: "ON"

minexpansion

<positive_integer>

This parameter defines the minimum length of a substring in wildcard expansion.

The <string> value must be a wildcard expression with a single asterisk.

Default: 0

maxexpansion

<positive_integer>

This parameter defines the maximum length of a substring in wildcard expansion.

The <string> value must be a wildcard expression with a single asterisk.

Default: infinity

annotation_class

<annotation_string>

The STRING parameter annotation_class="user" is used to annotate a STRING node to indicate that this node is user generated.

Certain relevancy features are applied only to the part of the query that is user generated. This includes query boosting based on anchor text and click-through query logs.

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. Because the question mark ("?") and asterisk ("*") characters are evaluated as wildcard characters, the following string token expressions match "cat", "cot", and any other three-letter indexed token that begins with "c" and ends with "t".

string("c?t")
string("c*t")

Example 9. 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 10. 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"))

Example 11. The following expression matches all terms starting with "prefix" and ending with "suffix", where the substring between "prefix" and "suffix" has a maximum length of 4 characters.

string("prefix*suffix",maxexpansion=4)

Example 12. The following string token expression matches the words "microsoft corporation". The addition of the annotation_class parameter ensures that items with exactly the same anchor text in a link pointing to the item will get additional rank boost.

string("Microsoft corporation", annotation_class="user")

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 without changing which items match the query. An XRANK expression contains one component that must be matched, and one or more components that contributes only to dynamic rank.

The differences between the RANK operator and the XRANK operator are as follows:

XRANK is much more efficient than RANK when terms in the RANK operands generate many hits.
For XRANK, the boost level can be set through the boost parameter, at query time.
XRANK adds a constant rank value, whereas RANK adds rank value associated with the operands.
XRANK will add rank to items that have not received any dynamic rank.
The XRANK operands can also address managed properties (not only full-text indexes).

The XRANK operator takes two or more operands. The operands may be single terms or any valid FQL sub-expression.

The first operand is the main query expression that is matched. It contributes to recall or precision as any other term or expression.

The subsequent operands do not affect the total number of items that match, but affect the dynamic ranking in the way that items matching terms within the following operands will get increased rank within the result set. If you have more than one subsequent operand, the match of each operand will add a boost value of n to the item's total rank.

This operator can be used to boost dynamic rank according to certain text terms found, but where these terms do not have to be found to give a match.

The XRANK operator can be used against full-text indexes and managed properties.

XRANK supports unary boosting. xrank(a,boost=n) will add a boost value of n to every item that match a. You can use this syntax when you combine multiple XRANK expressions using an AND or ANY operator.

Syntax

xrank(operand, rank-operand [, rank-operand]* [,boost=n] [,boostall=yes])

Parameters

Parameter	Value	Description
boost	<numeric_value>	Specifies that the dynamic rank of matching items will increase by the specified number. The dynamic rank component will not be lower than zero (negative resulting rank is not supported). You may still get a positive resulting rank because of the static rank component. Default: 100
boostall	yes\|no	Specifies whether the increase in dynamic rank will apply to items that do not already have a dynamic rank. yes Specifies that the increase in dynamic rank will apply to all the matching items, even if they do not already have dynamic rank values. no Specifies that the increase in dynamic rank will apply only to those matching items that already have dynamic rank values. Default: no

boost

<numeric_value>

Specifies that the dynamic rank of matching items will increase by the specified number.

The dynamic rank component will not be lower than zero (negative resulting rank is not supported). You may still get a positive resulting rank because of the static rank component.

Default: 100

boostall

yes|no

Specifies whether the increase in dynamic rank will apply to items that do not already have a dynamic rank.

yes Specifies that the increase in dynamic rank will apply to all the matching items, even if they do not already have dynamic rank values.
no Specifies that the increase in dynamic rank will apply only to those matching items that already have dynamic rank values.

Default: no

Examples

Example 1. The following expression matches items for which the default full-text index contains either "cat" or "dog". The expression increases the dynamic rank of those items that also contain "thoroughbred".

xrank(or(cat, dog), thoroughbred)

Example 2. The following expression matches items for which the default full-text index contains either "cat" or "dog". The expression increases the dynamic rank of those items that contain "thoroughbred" by 500 instead of by the default of 100, even for items that previously had no rank.

xrank(or(cat, dog), thoroughbred, boost=500, boostall=yes)