MarkLogic 12 EA 1 Product Documentationcts:field-value-query
cts:field-value-query( $field-name as xs:string*, $text as xs:anyAtomicType*, [$options as xs:string*], [$weight as xs:double?] ) as cts:field-value-query
Summary
Returns a query matching text content containing a given value in the
specified field. If the specified field does not exist,
cts:field-value-query throws an exception.
If the specified field does not have the index setting
field value searches enabled, either for the database or
for the specified field, then a cts:search with a
cts:field-value-query 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 values to match. If multiple values are specified, the query matches if any of the values match (or-query semantics). For XML and metadata, the values should be strings. For JSON, the values can be strings, numbers or booleans to match correspondingly typed nodes. To match null, pass in the empty sequence. |
| 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-value-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 values are within 3 words in the whole document,
For a code example illustrating this, see the
second example
below.
Values are determined based on words (tokens)of values of elements that are included in the field. Field values span all the included elements. They cannot span excluded elements (this is because MarkLogic Server breaks out of the field when it encounters the excluded element and start it again field when it encounters the next included element). Field values will also span included sibling elements.
If neither "case-sensitive" nor "case-insensitive" is present, $text is used to determine case sensitivity. If $text contains no uppercase, it specifies "case-insensitive". If $text contains uppercase, it specifies "case-sensitive".
If neither "diacritic-sensitive" nor "diacritic-insensitive" is present, $text is used to determine diacritic sensitivity. If $text contains no diacritics, it specifies "diacritic-insensitive". If $text contains diacritics, it specifies "diacritic-sensitive".
If neither "punctuation-sensitive" nor "punctuation-insensitive" is present, $text is used to determine punctuation sensitivity. If $text contains no punctuation, it specifies "punctuation-insensitive". If $text contains punctuation, it specifies "punctuation-sensitive".
If neither "whitespace-sensitive" nor "whitespace-insensitive" is present, the query is "whitespace-insensitive".
If neither "wildcarded" nor "unwildcarded" is present, the database configuration and $text determine wildcarding. If the database has any wildcard indexes enabled ("three character searches", "two character searches", "one character searches", or "trailing wildcard searches") and if $text contains either of the wildcard characters '?' or '*', it specifies "wildcarded". Otherwise it specifies "unwildcarded".
If neither "stemmed" nor "unstemmed" is present, the database configuration determines stemming. If the database has "stemmed searches" enabled, it specifies "stemmed". Otherwise it specifies "unstemmed". If the query is a wildcarded query and also a phrase query (contains two or more terms), the wildcard terms in the query are unstemmed.
When you use the "exact" option, you should also enable "fast case sensitive searches" and "fast diacritic sensitive searches" in your database configuration.
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
let $contents :=
<Employee>
<name>
<fname>Jaz</fname>
<mname>Roy</mname>
<lname>Smith</lname>
</name>
</Employee>
return
cts:contains($contents,cts:field-value-query("myField","Jaz Roy Smith"))
=> false, assuming the field "myField" is defined to include element
"name" and exclude element "mname". The field must exist in the
database against which this query is evaluated.
Example
let $contents :=
<Employee>
<name>
<fname>Jaz</fname>
<mname>Roy</mname>
<lname>Smith</lname>
</name>
</Employee>
return
cts:contains($contents,cts:field-value-query("myField","Jaz Smith"))
=> true, assuming the field "myField" is defined to include element
"name" and exclude element "mname". The field must exist in
the database against which this query is evaluated.
Example
In this query, the search is fully resolved in the index.
cts:search(
fn:doc("/Employee/jaz.xml"),
cts:field-value-query("myField","Jaz Smith"),
"unfiltered")
=> Returns the doc which has field "myField" and a match
with the value of the field.