cts.nearQuery

cts.nearqueryctsnearquery

/apidoc/8.0/cts:near-query.xml

Returns a query matching all of the specified queries, where the matches occur within the specified distance from each other.

A sequence of queries to match.

queries

cts.query[]

A distance, in number of words, between any two matching queries. The results match if two queries match and the distance between the two matches is equal to or less than the specified distance. A distance of 0 matches when the text is the exact same text or when there is overlapping text (see the third example below). A negative distance is treated as 0. The default value is 10.

distance

Number?

Options to this query. The default value is ().

Options include:

"ordered"

Any near-query matches must occur in the order of the specified sub-queries.

"unordered"

Any near-query matches will satisfy the query, regardless of the order they were specified.

options

String[]

A weight attributed to the distance for this query. Higher weights add to the importance of distance (as opposed to term matches) when the relevance order is calculated. The default value 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. This parameter has no effect if the word positions index is not enabled.

distance-weight

Number?

cts.nearQuery

If the options parameter contains neither "ordered" nor "unordered", then the default is "unordered".

The word positions index will speed the performance of queries that use cts:near-query. The element word positions index will speed the performance of element-queries that use cts:near-query.

If you use cts:near-query with a field, the distance specified is the distance in the whole document, not the distance in the field. For example, if the distance between two words is 20 in the document, but the distance is 10 if you look at a view of the document that only includes the elements in a field, a cts:near-query must have a distance of 20 or more to match; a distance of 10 would not match.

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 details, see cts:field-word-query.

Expressions using the ordered option are more efficient than those using the unordered option, especially if they specify many queries to match.

// The following query searches for paragraphs containing
// both "MarkLogic" and "Server" within 3 words of each
// other, given the following document in a database:

// { "text": "MarkLogic Server is an enterprise-class database."}

cts.search(cts.nearQuery(
    [cts.wordQuery("MarkLogic"),
     cts.wordQuery("Server")],
     3))

=> A ValueIterator containing the document

var x = xdmp.unquote('<p>Now is the winter of our discontent</p>');
cts.contains(x, cts.nearQuery(
                    ["discontent", "winter"],
                    3, "ordered"))

=> false because "discontent" comes after "winter"

var x = xdmp.unquote('<p>Now is the winter of our discontent</p>');
cts.contains(x, cts.nearQuery(
                    ["discontent", "winter"],
                    3, "unordered"))

=> true because the query specifies "unordered",
        and it is still a match even though
        "discontent" comes after "winter"

var x = xdmp.unquote('<p>Now is the winter of our discontent</p>');
cts.contains(x, cts.nearQuery(
                    ["is the winter", "winter of"],
                    0))

=> true because the phrases overlap

var x = xdmp.unquote('<p>Now is the winter of our discontent</p>');
cts.contains(x, cts.nearQuery(
                    ["is the winter", "of our"],
                    0))

=> false because the phrases do not overlap
         (they have 1 word distance, not 0)