Summary

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

Parameters

$queries

A sequence of queries to match.

$distance

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.

$options

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.

"minimum-distance"

The minimum distance between two matching queries. The results
match if the two queries match and the minimum distance between the two
matches is greater than or equal to the specified minimum distance. The
default value is zero. A negative distance is treated as 0.

$distance-weight

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.

Usage Notes

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. The same applies to minimum distance as well.

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. This too applies to the
minimum distance as well. 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.

Minimum-distance and distances apply to each near-query match. Therefore, if
minimum-distance is greater than distance there can be no matches.

Example

// 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 Sequence containing the document

Example

const 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"
const 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"

Example

const x = xdmp.unquote('<p>Now is the winter of our discontent</p>');
cts.contains(x, cts.nearQuery(
["winter", "discontent"],
5, ("ordered", "minimum-distance=4")))
=> false because the distance between the queries is greater than the minimum
distance
const x = xdmp.unquote('<p>Now is the winter of our discontent</p>');
cts.contains(x, cts.nearQuery(
["winter", "discontent"],
5, ("ordered", "minimum-distance=3")))
=> true because the distance between the queries is less than or equal to the
minimum distance