cts.matchRegions

cts.matchregionsctsmatchregions

/apidoc/8.0/cts:match-regions.xml

Find regions in documents that have a spatial relationship to one or more caller-supplied regions.

References to range indexes that store the string serialization of regions to match against.

range-indexes

cts.reference[]

The operation to test. Must be one of the following: "contains", "within", "overlaps", or "intersects". See the Usage Notes for details.

operation

String

One or more cts:region values to test against. A region matches if if it matches against any of these regions.

regions

cts.region[]

String options you can use to control the operation. The following options are supported:

"coordinate-system=value"

Use the given coordinate system. Valid values are raw and wgs84 (default).

"units=miles"

Compute distances and the radii of circles using the given units. Other units should be converted using the geo:distance-convert-units function.

"strings"

Return results as strings instead of as cts:region values.

"any"

Co-occurrences from any fragment should be included.

"document"

Co-occurrences from document fragments should be included.

"properties"

Co-occurrences from properties fragments should be included.

"locks"

Co-occurrences from locks fragments should be included.

"fragment-frequency"

Frequency should be the number of fragments with an included co-occurrence. This option is used with cts:frequency.

"item-frequency"

Frequency should be the number of occurrences of an included co-occurrence. This option is used with cts:frequency.

"checked"

Word positions should be checked when resolving the query.

"unchecked"

Word positions should not be checked when resolving the query.

"too-many-positions-error"

If too much memory is needed to perform positions calculations to check whether a document matches a query, return an XDMP-TOOMANYPOSITIONS error, instead of accepting the document as a match.

"concurrent"

Perform the work concurrently in another thread. This is a hint to the query optimizer to help parallelize the lexicon work, allowing the calling query to continue performing other work while the lexicon processing occurs. This is especially useful in cases where multiple lexicon calls occur in the same query (for example, resolving many facets in a single query).

options

String[]

Limit the region comparison to documents that match this query. Also, compute frequencies from the set of included regions. The values do not need to match the query, but they must occur in fragments selected by the query. The fragments are not filtered ot ensure they match the query. Instead, they are selected in the same manner as "unfiltered" cts:search operations.

query

cts.query?

A sequence of IDs of forests to which the search should be constrained. An empty sequence means search all forests in the databse. The default is an empty sequence.

forest-ids

String[]

ValueIterator

This function matches regions in documents in the database satisfying the relationship R1 op R2, where R1 is a region in a database document, op is the operator provided in the operation parameter, and R2 is any of the regions provided in the regions parameter. The R1 regions under considerations are those in the indexes provided in the range-indexes parameter. The R1 regions can be further constrained to those in documents that match a query.

The operations have the following semantics:

"contains"

Matches regions in the given indexes that contain any of the regions in $regions. That is, regions where geo:region-contains($r1,$r2) returns true for some region $r1 occurring in the supplied indexes and region $r2 in $regions.

"intersects"

Matches regions in the given indexes that intersect with any of the regions in $regions. That is, regions where geo:region-intersects($r1,$r2) returns true for some region $r1 occurring in the supplied indexes and region $r2 in $regions.

"overlaps"

Matches regions in the given indexes that intersect with any of the regions in $regions, exclusive of boundaries, and neither region contains the other. That is, regions where geo:region-intersects($r1,$r2, ("boundaries-excluded") ) for some region $r1 occurring in the supplied indexes and region $r2 in $regions; and neither region includes the other.

"within"

Matches regions in the given indexes that are contained by any of of the regions in $regions. That is, regions where geo:region-contains($r2,$r1) returns true for some region $r1 occurring in the supplied indexes and region $r2 in $regions.

The return value is either an iterator over cts:region values or an iterator over strings containing the serialized regions, depending on whether or not the strings option is included.

If the range indexes provided through the range-indexes parameter contain any string that cannot be parsed into a region, an error is thrown.

Only one of "fragment-frequency" or "item-frequency" may be specified in the options parameter. If neither "fragment-frequency" nor "item-frequency" is specified, then the default is "fragment-frequency".

Only one of "any", "document", "properties", or "locks" may be specified in the options parameter. If none of "any", "document", "properties", or "locks" are specified and there is a $query parameter, then the default is "document". If there is no $query parameter then the default is "any".

Only one of the "checked" or "unchecked" options may be specified in the options parameter. If neither "checked" nor "unchecked" are specified, then the default is "checked".

If "coordinate-system=name" is not specified in the options parameter, then the default coordinate system is used. If a lexicon with that coordinate system does not exist, an error is thrown.

cts.matchRegions(cts.elementReference('parcel'), 'intersects',
  [cts.polygon('POLYGON((1 1,2 2,0 1,1 1))'), cts.circle(10,cts.point(7,0))])

==> Any parcel that intersects either the triangle with vertices 
    (1,1), (2,2), (0,1), or the circle of radius 10 centered at (7,0).

var africa = cts.polygon(
  'POLYGON((32.34375 34.74161249883172,37.265625 ' +
  '28.149503211544566,56.07421875 8.059229627200192,46.23046875 ' +
  '-41.244772343082076,4.04296875 -39.77476948529545,-33.75 ' +
  '29.53522956294847,7.03125 39.50404070558415,32.34375 34.74161249883172))')
cts.matchRegions(
  cts.jsonPropertyReference('country'), 'within', 
    africa, ['coordinate-system=wgs84'], 
    cts.jsonPropertyValueQuery('state-bird', ['eagle','turkey']))

==> Every country in Africa that has either an eagle or a turkey as 
    its state bird.

var regionStrings = cts.matchRegions(
  cts.jsonPropertyReference('zone'), 'overlaps',
  cts.polygon([
    cts.point(0,0), cts.point(1,1),
    cts.point(0,2), cts.point(2,2),
    cts.point(2,0), cts.point(0,0)
  ]),
  ['coordinate-system=raw', 'strings']);
cts.search(cts.jsonPropertyRangeQuery('zone', '=', regionStrings))

==> Every document that contains a zone which overlaps with the specified 
    polygon.