XQuery cts:match-regions

MarkLogic Server 11.0 Product Documentation
cts.matchRegions

cts.matchRegions(
   range-indexes as cts.reference[],
   operation as String,
   regions as cts.region[],
   [options as String[]],
   [query as cts.query?],
   [forest-ids as (Number|String)[]]
) as Sequence

Summary

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

Parameters
range-indexes References to range indexes that store the string serialization of regions to match against.
operation The operation to test. Must be one of the following: contains, covered-by, covers, crosses, disjoint, equals, intersects, overlaps, touches, within. See the Usage Notes for details.
regions One or more cts:region values to test against. A region matches if it matches against any of these regions.
options 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 wgs84, wgs84/double, etrs89, etrs89/double, raw and raw/double. Defaults to the governing coordinating system.
"precision=value"
Use the coordinate system at the given precision. Allowed values: float and double. Defaults to the precision of the governing coordinate system.
"units=value"
Compute distances and radii of circles using the given units. Allowed values: miles (default), km, feet, and meters.
"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).
query 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 to ensure they match the query. Instead, they are selected in the same manner as "unfiltered" cts:search operations.
forest-ids A sequence of IDs of forests to which the search should be constrained. An empty sequence means search all forests in the database. The default is an empty sequence.

Usage Notes

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 are defined by the Dimensionally Extended nine-Intersection Model (DE-9IM) of spatial relations. They have the following semantics:

"contains"
R1 contains R2 if every point of R2 is also a point of R1, and their interiors intersect.
"covered-by"
R1 is covered-by R2 if every point of R1 is also a point of R2.
"covers"
R1 covers R2 if every point of R2 is also a point of R1.
"crosses"
R1 crosses R2 if their interiors intersect and the dimension of the intersection is less than that of at least one of the regions.
"disjoint"
R1 is disjoint from R2 if they have no points in common.
"equals"
R1 equals R2 if every point of R1 is a point of R2, and every point of R2 is a point of R1. That is, the regions are topologically equal.
"intersects"
R1 intersects R2 if the two regions have at least one point in common.
"overlaps"
R1 overlaps R2 if the two regions partially intersect -- that is, they have some but not all points in common -- and the intersection of R1 and R2 has the same dimension as R1 and R2.
"touches"
R1 touches R2 if they have a boundary point in common but no interior points in common.
"within"
R1 is within R2 if every point of R1 is also a point of R2, and their interiors intersect.

Note: the operation covers differs from contains only in that covers does not distinguish between points in the boundary and the interior of geometries. In general, covers should be used in preference to contains. Similarly, covered-by should generally be used in preference to within.

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.

The value of the precision option takes precedence over that implied by the governing coordinate system name, including the value of the coordinate-system option. For example, if the governing coordinate system is "wgs84/double" and the precision option is "float", then the query uses single precision.

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 governing coordinate system is used.

The value of the precision option takes precedence over that implied by the governing coordinate system name, including the value of the coordinate-system option. For example, if the governing coordinate system is "wgs84/double" and the precision option is "float", then the operation uses single precision.

See Also

Example

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

Example

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

Example

const 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.
Powered by MarkLogic Server | Terms of Use | Privacy Policy