MarkLogic 12 EA 1 Product Documentationcts:field-word-query
cts:field-word-query( $field-name as xs:string*, $text as xs:string*, [$options as xs:string*], [$weight as xs:double?] ) as cts:field-word-query
Summary
Returns a query matching fields with text content containing a given phrase. If the specified field does not exist, this function throws an exception. A field is a named object that specified elements to include and exclude from a search, and can include score weights for any included elements. You create fields at the database level using the Admin Interface. For details on fields, see the chapter on "Fields Database Settings" in the Administrator's Guide.
| Parameters | |
|---|---|
| field-name | One or more field names to search over. If multiple field names are supplied, the match can be in any of the specified fields (or-query semantics). |
| text | The word or phrase to match. If multiple strings are specified, the query matches if any of the words or phrases match (or-query semantics). |
| options |
Options to this query. The default is ().
Options include:
|
| weight | A weight for this query. Higher weights move search results up in the relevance order. The default is 1.0. The weight should be between 64 and -16. Weights greater than 64 will have the same effect as a weight of 64. Weights less than the absolute value of 0.0625 (between -0.0625 and 0.0625) are rounded to 0, which means that they do not contribute to the score. |
Usage Notes
If you use cts:near-query with
cts:field-word-query, the distance supplied in the near query
applies to the whole document, not just to the field. For example, if
you specify a near query with a distance of 3, it will return matches
when the words or phrases are within 3 words in the whole document,
even if some of those words are not in the specified field. For a code
example illustrating this, see the
second example
below.
Phrases are determined based on words being next to each other (word positions with a distance of 1) and words being in the same instance of the field. Because field word positions are determined based on the fragment, not on the field, field phrases cannot span excluded elements (this is because MarkLogic Server breaks out of the field when it encounters the excluded element and start a new field when it encounters the next included element). Similarly, field phrases will not span included sibling elements. The second code example below illustrates this.
The phrase-through feature will be enabled once you include the path
element in the field setting. Field phrases will automatically phrase-through
all child elements of an included element, until it encounters an explicitly
excluded element. The
third example
below illustrates this.
An example of when this automatic phrase-through behavior might be
convenient is if you create a field that includes only the element
ABSTRACT. Then all child elements of ABSTRACT
are included in the field, and phrases would span all of the child
elements (that is, phrases would "phrase-through" all the child elements).
Negative "min-occurs" or "max-occurs" values will be treated as 0 and non-integral values will be rounded down. An error will be raised if the "min-occurs" value is greater than the "max-occurs" value.
Example
(: Assume the database configuration includes a field named "myField"
: on the paths /root/a/name and /root/b/name and a corresponding
: field range index.
:)
cts:search(fn:doc(), cts:field-word-query("myField", ("amy", "bill")))
(: Then the search matches all documents that contain either "amy" or
: "bill" in the value of /root/a/name or /root/b/name (the field).
: For example, it would match this document:
:
: <root><a><name>bill</name></a></root>
:
: But would not match this document:
:
: <root><c><name>bill</name></c></root>
:
: By contrast, if you defined an element index on the element "name"
: and queried using cts:element-word-query, both documents would match.
:)
Example
(: Assume the database configuration includes a field named "buzz"
: on the path /hello/buzz, with localname "buzz" as an include and
: localname "baz" as an exclude.
:)
let $x :=
<hello>word1 word2 word3
<buzz>word4 word5</buzz>
<baz>word6 word7 word8</baz>
<buzz>word9 word10</buzz>
</hello>
return (
cts:contains($x, cts:near-query(
(cts:field-word-query("buzz", "word5"),
cts:field-word-query("buzz", "word9")), 3)),
cts:contains($x, cts:near-query(
(cts:field-word-query("buzz", "word5"),
cts:field-word-query("buzz", "word9")), 4)),
cts:contains($x,
cts:field-word-query("buzz", "word5 word9")))
(:
: Returns the sequence ("false", "true", "false").
: The first part does not match because "word5" and "word9" do
: not occur within 3 words of each other; distance is calculated
: based on the whole node (or document if querying documents in
: the database), rather than on the field. The distance requirement
: of the second near-query (4) is met, so the query matches and
: returns true. The third query does not match because there
: are words between "word5" and "word9", and the phrase is based
: on the entire node, not on the field.
:)
Example
(: Assume the database configuration includes a field named "buzz"
: on the path /hello/buzz, with localname "buzz" as an include and
: localname "baz" as an exclude.
:)
let $x :=
<hello>
<buzz>word1 word2
<gads>word3 word4 word5</gads>
<zukes>word6 word7 word8</zukes>
word9 word10
</buzz>
</hello>
return (
cts:contains($x,
cts:field-word-query("buzz", "word2 word3")))
(: Returns "true" because the children of "buzz" are not excluded,
: and are therefore automatically phrased through.
:)