cts.fieldValueQuery

cts.fieldvaluequeryctsfieldvaluequery

/apidoc/8.0/cts:field-value-query.xml

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.

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

field-name

String[]

The values to match. If multiple values are specified, the query matches if any of the values match (or-query semantics). For XML documents, the values should be strings. For JSON, the values can be strings, numbers or booleans. To match null, pass in the empty sequence.

text

(String | Number | Boolean | null)[]

Options to this query. The default is ().

Options include:

"case-sensitive"

A case-sensitive query.

"case-insensitive"

A case-insensitive query.

"diacritic-sensitive"

A diacritic-sensitive query.

"diacritic-insensitive"

A diacritic-insensitive query.

"punctuation-sensitive"

A punctuation-sensitive query.

"punctuation-insensitive"

A punctuation-insensitive query.

"whitespace-sensitive"

A whitespace-sensitive query.

"whitespace-insensitive"

A whitespace-insensitive query.

"stemmed"

A stemmed query.

"unstemmed"

An unstemmed query.

"wildcarded"

A wildcarded query.

"unwildcarded"

An unwildcarded query.

"exact"

An exact match query. Shorthand for "case-sensitive", "diacritic-sensitive", "punctuation-sensitive", "whitespace-sensitive", "unstemmed", and "unwildcarded".

"lang=iso639code"

Specifies the language of the query. The iso639code code portion is case-insensitive, and uses the languages specified by ISO 639. The default is specified in the database configuration.

"distance-weight=number"

A weight applied based on the minimum distance between matches of this query. Higher weights add to the importance of proximity (as opposed to term matches) when the relevance order is calculated. The default value is 0.0 (no impact of proximity). The weight should be between 64 and -16. Weights greater than 64 will have the same effect as a weight of 64. This parameter has no effect if the word positions index is not enabled. This parameter has no effect on searches that use score-simple or score-random (because those scoring algorithms do not consider term frequency, proximity is irrelevant).

"min-occurs=number"

Specifies the minimum number of occurrences required. If fewer that this number of words occur, the fragment does not match. The default is 1.

"max-occurs=number"

Specifies the maximum number of occurrences required. If more than this number of words occur, the fragment does not match. The default is unbounded.

"synonym"

Specifies that all of the terms in the $text parameter are considered synonyms for scoring purposes. The result is that occurrences of more than one of the synonyms are scored as if there are more occurrences of the same term (as opposed to having a separate term that contributes to score).

options

String[]

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.

weight

Number?

cts.fieldValueQuery

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.

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.

var contents = xdmp.unquote(
'  <Employee>\n\
    <name>\n\
      <fname>Jaz</fname>\n\
      <mname>Roy</mname>\n\
      <lname>Smith</lname>\n\
    </name>\n\
  </Employee>').next().value;
cts.contains(contents,
	cts.fieldValueQuery("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.

var contents = xdmp.unquote(
'  <Employee>\n\
    <name>\n\
      <fname>Jaz</fname>\n\
      <mname>Roy</mname>\n\
      <lname>Smith</lname>\n\
    </name>\n\
  </Employee>').next().value;
cts.contains(contents,
	cts.fieldValueQuery("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.

// In this query, the search is fully resolved in the index.

cts.search(
  cts.fieldValueQuery("myField","Jaz Smith"),
  "unfiltered")

=> Returns the document which has field "myField" and a match
   with the value of the field.