A full-text contains expression returns a Boolean value. It returns true if there is some item returned by the RangeExpr that, after tokenization, matches the full-text selection FTSelection. See Section for more details. For the purpose of determining a match, certain descendants of nodes (identified by FTIgnoreOption) in the RangeExpr may be ignored, as specified in Section .

An XQuery and XPath Full Text processor SHOULD try to use the information available in xml:lang for processing of collations, as well as the various match options defined in Section .

The following example in XQuery Full Text returns the author of each book with a title containing a token with the same root as dog and the token cat. for $b in /books/book where $b/title ftcontains ("dog" with stemming) ftand "cat" return $b/author

The same example in XPath Full Text is written as: /books/book[title ftcontains ("dog" with stemming) ftand "cat"]/author

In the next example a ComparisonExpr is combined with an FTContainsExpr using the logical XQuery operator and. The query selects books that have a price of less than 50 and a title which contains a token with the same root as train:

The following example shows the combination of two ftcontains expressions the results of which are compared using the not-equals operator. The query selects books where either the title contains the token dog and the token cat and the content does not contain a token with the same root as train, or where the title fails to have one of the matching tokens but the content does:

Scoring may be influenced by adding weight declarations to search tokens, phrases, and expressions. Weight declarations are introduced syntactically in the FTSelection production, described in Section .

The weight MUST have an absolute value between 0.0 and 1000.0 inclusive.

The weights assigned are not related to any absolute standard, but typically have a relationship to other weights within the same FTContains expression.

The effect of weights on the resulting score is implementation-dependent. However, scoring algorithms MUST conform to these constraints:

The following example illustrates how different weights can be used for different search terms. for $b in /books/book let score $s := $b/content ftcontains ("web site" weight 0.5) ftand ("usability" weight 2) return <result score="{$s}">{$b}</result>

A language option modifies token matching by specifying the language of search tokens and phrases.

The StringLiteral following the keyword language designates one language. It must be castable to xs:language; otherwise, an error is raised: .

The "language" option influences tokenization, stemming, and stop words in an implementation-defined way. The "language" option MAY influence the behavior of other match options in an implementation-defined way.

The set of standardized language identifiers is defined in . The set of valid language identifiers among the standardized set is implementation-defined. An implementation MAY choose to use private extensions introduced by a singleton 'x' for additional language identifiers, or other singletons for registered extensions as described in sec. 2.2.6 of . It is implementation-defined what additional language identifiers, if any, are valid. If an invalid language identifier is specified, then the behavior is implementation-defined. If the implementation chooses to raise an error in that case, it must raise .

The default language is specified in the static context.

When an XQuery and XPath Full Text processor evaluates text in a document that is governed by an xml:lang attribute and the portion of the full-text query doing that evaluation contains an FTLanguageOption that specifies a different language from the language specified by the governing xml:lang attribute, the language-related behavior of that full-text query is implementation-defined.

This is an example where the language option is used to select the appropriate stop word list:

A wildcard option modifies token and phrase matching by specifying whether wildcards are used or not.

When the "with wildcards" option is used, wildcard indicators (represented by periods (.)) and qualifiers may be appended to or inserted into the query tokens. If the period is at the beginning of a query token, the wildcard is a prefix wildcard. If the period is at the end of a query token, it is a suffix wildcard. If the period is inserted into a query token, it is an infix wildcard.

Each indicator and qualifier in a query token will match zero or more characters within a token in the text being searched, as described below. The number of characters matched depends on the qualifier. Qualifiers available are none, question mark, asterisk, plus sign, and two numbers separated by a comma, both enclosed by curly braces.

When "with wildcards" is present and an indicator or qualifier character is intended to be taken literally (as itself), that character must be preceded by ("escaped by") a backslash (\). For example, a period (.) that is intended to be a sentence terminator or a decimal point must be preceded by a backslash so that it is not interpreted to be an indicator. Similarly a question mark (?), asterisk (*), or plus sign (+) that is intended to be interpreted as an ordinary text character must be preceded by a backslash so that it is not interpreted to be an indicator.

The "without wildcards" option finds tokens without recognizing wildcard indicators and qualifiers. Periods, question marks, asterisks, plus signs, and two numbers separated by a comma, both enclosed by curly braces, are always recognized as ordinary text characters.

The default is "without wildcards".

Note: Wildcard indicators and qualifiers may be token boundaries. How text with wildcard indicators and qualifiers is tokenized is implementation-defined.

The expression returns true, because the title element contains "improving":

The following expression returns true, because the title element contains "site":

The following expression returns true, because the p element contains "well":

The following expression returns false, because the p element does not contain the phrase "w ll":

(Note that, without wildcards, the sample tokenization will treat the period in "w.ll" as punctuation, thus producing "w" and "ll" as separate tokens.)

A thesaurus option modifies token and phrase matching by specifying whether a thesaurus is used or not. If thesauri are used, the thesaurus option specifies information to locate the thesauri either by default or through a URI reference. It also states the relationship to be applied and how many levels within the thesaurus to be traversed.

Thesauri add related tokens and phrases to the query or change query tokens. Thus, the user may narrow, broaden, or otherwise modify the query using synonyms, hypernyms (more generic terms), etc. The search is performed as though the user has specified all related query tokens and phrases in a disjunction (FTOr).

FTThesaurusID specifies the relationship sought between tokens and phrases written in the query and terms in the thesaurus and the number of levels to be queried in hierarchical relationships by including an FTRange "levels". If no levels are specified, the default is to query all levels in hierarchical relationships.

Relationships include, but are not limited to, the relationships and their abbreviations presented in and their equivalents in other languages. The set of relationships supported by an implementation is implementation-defined, but implementations SHOULD support the relationships defined in . The following list of terms have the meanings defined in . If a query specifies thesaurus relationships or levels not supported by the thesaurus, or does not specify a relationship, the behavior is implementation-defined.

The "with thesaurus" option specifies that string matches include tokens that can be found in one of the specified thesauri. When "default" is used in place of a FTThesaurusID, the thesauri specified in the static context are used, which are either given by the prolog declaration for the thesaurus option, or, if no such declaration exists a system-defined default thesaurus with a system-defined relationship. The default thesaurus may be used in combination with other explicitly specified thesauri.

The "without thesaurus" option specifies that no thesaurus will be used.

The default is "without thesaurus".

The following expression returns true, because it finds a content element containing "tasks" which the thesaurus identified as a synonym for "duties":

The following expression returns book elements, because it finds a content element containing "web site components", and narrower terms "navigation" and "layout":

Assuming the thesaurus available at URL "http://bstore1.example.com/UsabilitySoundex.xml" contains soundex capabilities, the following query returns a book element containing "Marigold" which sounds like "Merrygould":

A stemming option modifies token and phrase matching by specifying whether stemming is applied or not.

The "with stemming" option specifies that matches may contain tokens that have the same stem as the tokens and phrases written in the query. It is implementation-defined what a stem of a token is.

The "without stemming" option specifies that the tokens and phrases are not stemmed.

It is implementation-defined whether the stemming is based on an algorithm, dictionary, or mixed approach.

The default is "without stemming".

The following expression returns true, because the title of the specified book contains "improving" which has the same stem as "improve":

A case option modifies the matching of tokens and phrases by specifying how uppercase and lowercase characters are considered.

There are four possible character case options:

The default is "case insensitive".

The effect of the case options is also influenced by the query's default collation (see and ). The following table summarizes how these interact.

Case Matrix

Case option \ Default collation	UCC (Unicode Codepoint Collation)	CCS (some generic case-sensitive collation)	CCI (some generic case-insensitive collation)
case insensitive	compare as if both lower	case-insensitive variant of CCS if it exists, else error	CCI
case sensitive	UCC	CCS	case-sensitive variant of CCI if it exists, else error
lowercase	compare using UCC after applying fn:lower-case() to the query string	compare using CCS after applying fn:lower-case() to the query string	CCI
uppercase	compare using UCC after applying fn:upper-case() to the query string	compare using CCS after applying fn:upper-case() to the query string	CCI

The following expression returns false, because the title element doesn't contain "usability" in lower-case characters:

The following expression returns true, because the character case is not considered:

A diacritics option modifies token and phrase matching by specifying how diacritics are considered.

There are two possible diacritics options:

The default is "diacritics insensitive".

The effect of the diacritics options is also influenced by the query's default collation (see and ). The following table summarizes how these interact.

Diacritics Matrix

Diacritics option \ Default collation	UCC (Unicode Codepoint Collation)	CDS (some generic diacritics-sensitive collation)	CDI (some generic diacritics-insensitive collation)
diacritics insensitive	UCC comparison, but without considering diacritics	diacritics-insensitive variant of CDS if it exists, else error	CDI
diacritics sensitive	UCC	CDS	diacritics-sensitive variant of CDI if it exists, else error

The following expression returns true, because the token "Véra" in the editor element is matched, as the acute accent is not considered in the comparison:

This returns false, because the editor element does not contain the token "Vera" in this exact form, i.e. without any diacritics:

A stop word option controls matching of FTWords by specifying whether stop words are used or not. Stop words are tokens in the query that match any token in the text being searched. Normally a stop word matches exactly one token, but there may be implementation-defined conditions, under which a stop word may match a different number of tokens.

FTStopWords specifies the list of stop words either explicitly as a comma-separated list of string literals, or by the keyword at followed by a literal URI. If the URI specifies a list of stop words that is not found in the statically known stop word lists, an error is raised . Whether the stop word list is resolved from the statically known stop word lists or given explicitly, no tokenization is performed on the stop words: they are used as they occur in the list.

The "with stop words" option specifies that if a token is within the specified collection of stop words, it is removed from the search and any token may be substituted for it. Stop words retain their position numbers and are counted in FTDistance and FTWindow searches.

Multiple stop word lists may be combined using "union" or "except". The keywords "union" and "except" are applied from left to right. If "union" is specified, every string occurring in the lists specified by the left-hand side or the right-hand side is a stop word. If "except" is specified, only strings occurring in the list specified by the left-hand side but not in the list specified by the right-hand side are stop words.

The "with default stop words" option specifies that an implementation-defined collection of stop words is used.

The "without stop words" option specifies that no stop words are used. This is equivalent to specifying an empty list of stop words.

The default is "without stop words".

The following expression returns true, because the document contains the phrase "propagating few errors":

Note the asymmetry in the stop word semantics: the property of being a stop word is only relevant to query terms, not to document terms. Hence, it is irrelevant for the above-mentioned match whether "few" is a stop word or not, and on the other hand we do not want the query above to match "propagation" followed by 2 stop words, or even a sequence of 3 stop words in the document.

The following expression returns false. In this case specifying "few" as a stop word has no effect, since "few" does not appear in the query. Although the words "propagating" and "errors" appear in the text being searched, the phrase "propagating errors" cannot be matched, since that phrase does not occur.

The following expression returns false, because "of" is not in the p element between "propagating" and "errors":

The following expression uses the stop words list specified at the URL. Assuming that the specified stop word list contains the word "then", this query is reduced to a query on the phrase "planning X conducting", allowing any token as a substitute for X. It returns a book element, because its content element contains "planning then conducting". It would also return the book if the phrases "planning and conducting" and "planning before conducting" had been in its content:

The following expression returns books containing "planning then conducting", but not does not return books containing "planning and conducting", since it is exempting "then" from being a stop word:

An extension option is a match option that acts in an implementation-defined way.

An extension option consists of an identifying QName and a StringLiteral. Typically, a particular option will be recognized by some implementations and not by others. The syntax is designed so that option declarations can be successfully parsed by all implementations.

The QName of an extension option must resolve to a namespace URI and local name, using the statically known namespaces.

Each implementation recognizes an implementation-defined set of namespace URIs used to denote extension options.

If the namespace part of the QName is not a namespace recognized by the implementation as one used to denote extension option, then the extension option is ignored.

Otherwise, the effect of the extension option, including its error behavior, is implementation-defined. For example, if the local part of the QName is not recognized, or if the StringLiteral does not conform to the rules defined by the implementation for the particular extension option, the implementation may choose whether to report an error, ignore the extension option, or take some other action.

Implementations may impose rules on where particular extension options may appear relative to other match options, and the interpretation of an option declaration may depend on its position.

An extension option must not be used to change the syntax accepted by the processor, or to suppress the detection of static errors. However, it may be used without restriction to modify the set of tokens in the query or how they are matched against tokens in the text being searched. An extension option has the same scope as other match options.

The following examples illustrate several possible uses for extension options:

This extension option is set as part of the static context of all full-text expressions in the module and might be used to ensure that queries are insensitive to Arabic short-vowels.

This extension option applies only to the matching in the full-text selection in which it is found and might be used to specify how compound words should be matched.

An or-selection combines two full-text selections using the ftor operator.

An or-selection finds all matches that satisfy at least one of the operand full-text selections.

The following expression returns the book element written by "Millicent":

An and-selection combines two full-text selections using the ftand operator.

An and-selection finds matches that satisfy all of the operand full-text selections simultaneously. A match of an and-selection is formed by combining matches for each of the operand full-text selections as described in .

For example, "usability" ftand "testing" will find two matches in //book[@number="1"]/title: each of the two matches for the FTWords selection "usability" (the two occurrences of "usability" in the string value of the title element) is combined with the single match for the FTWords "testing" (only one occurrence of "testing" in the title). Since the above and-selection has at least one match, the following expression will return "true".

The following expression returns false, because "Millicent" and "Montana" are not contained by the same author element in any book element:

No author element in any book element contains both "Millicent" and "Montana". Therefore, for any such author element, there are either one match for the FTWords "Millicent" and zero matches for the FTWords "Montana", or vice versa, or no matches for both of them. In any of these cases, the and-selection will have zero matches.

A mild-not selection combines two full-text selections using the not in operator.

The not in operator is a milder form of the operator combination ftand ftnot. The selection A not in B matches a token sequence that matches A, but not when it is a part of a match of B. In contrast, A ftand ftnot B only finds matches when the token sequence contains A and does not contain B.

As an example, consider a search for "Mexico" not in "New Mexico". This may return, among others, a document which is all about "Mexico" but mentions at the end that "New Mexico was named after Mexico". The occurrence of "Mexico" in "New Mexico" is not considered, but other occurrences of "Mexico" are matched. Note that this document would not be matched by the full-text selection "Mexico" ftand ftnot "New Mexico".

A match to a mild-not selection must contain at least one token that satisfies the first condition and does not satisfy the second condition. If it contains a token that satisfies both the first and the second condition, the token is not considered as a match.

The following expression returns true, because "usability" appears in the title and the p elements and the token within the phrase "Usability Testing" in the title element is not considered:

Operands of a mild-not selection may not contain a full-text selection that evaluates to an AllMatches that contains a StringExclude. Such full-text selections are not-selection and FTWords with a cardinality constraint using at most, from ... to, and exactly occurrences ranges. If such an expression is encountered, an error is raised.

A not-selection is a full-text selection starting with the prefix operator ftnot.

A not-selection selects matches that do not satisfy the operand full-text selection. Details about how such matches are constructed are given in .

The following expression returns the empty sequence, because all book elements contain "usability":

The following expression returns true, because book elements contain "information" and "retrieval" but not "information retrieval":

The following expression returns book elements containing "web site usability" but not "usability testing":

An ordered selection consists of a full-text selection followed by the postfix operator "ordered". An ordered selection constrains the order of tokens and phrases to be the same as the order in which they are written in the operand selection.

The default is unordered. Unordered is in effect when ordered is not specified in the query. Unordered cannot be written explicitly in the query.

An ordered selection selects matches which satisfy the operand full-text selection and which also satisfy the following constraint: the order that the matching tokens or phrases have in the text being searched is the same order that the corresponding query tokens or phrases have in the operand selection. In both cases, the ordering is determined from the minimum start positions of the contituent tokens.

The following expression returns true, because titles of book elements contain "web site" and "usability" in the order in which they are written in the query, i.e., "web site" must precede "usability":

The following expression returns false, because although "Montana" and "Millicent" both appear in the book element, they do not appear in the order they are written in the query:

A window selection consists of a full-text selection followed by one of the (complex) postfix operators derived from FTWindow. A window selection selects matches which satisfy the operand full-text selection and for which the matched tokens and phrases, more precisely the individual StringIncludes of that match, are found within a number of FTUnits (words, sentences, and paragraphs). The number of FTUnits is specified by an AdditiveExpr that is converted as though it were an argument to a function with the expected type of xs:integer.

A window selection may cross element boundaries. The size of the window is not affected by the presence or absence of element boundaries. Stop words are included in the computation of the window size whether they are ignored by the query or not.

A window selection examines the matches generated by the preceding portion of the FTSelection, and selects those for which the matched tokens and phrases (more precisely, the individual StringIncludes of that match) are all found within a window whose size is a specified number of FTUnits (words, sentences, or paragraphs); for each such window, the window selection then generates a match containing the merge of those StringIncludes, plus any StringExcludes that fall within the window.

The following expression returns true, because "web", "site", and "usability" are within a window of 5 tokens in the title element:

The following expression returns true, because "web" and "site" in the order they are written in the query and either "usability" or "testing" are within a window of at most 10 tokens:

The following expression returns true, because the title element contains "Web Site Usability". A similar query on the p element would not return true, because its occurrences of "web site" and "usability" are not within a window of 3:

The following expression returns the sample book element, because its number attribute is 1 and it contains a window of 2 words which contains an occurrence of "efficient" but not an occurrence of "and". There is just one such matching window in the sample text and it contains "enable efficient".

The following expression returns the empty sequence, because in the selected book element, there is no occurrence of "efficient" within a window of 3 tokens which would not also contain an occurrence of "and":

In order to allow meaningful results for nested positional filters, e.g., a window selection embedded inside a distance selection, the resulting matches for window selections are formed from the input matches that satisfy the window constraint as follows. All StringIncludes of such a match are coerced into a single StringInclude that spans all token positions from the smallest to the largest position of any input StringIncludes. This is explained in more detail in Section .