MarkLogic Server 11.0 Product Documentationcts.geospatialRegionQuery
cts.geospatialRegionQuery( geospatial-region-reference as cts.reference[], operation as String, regions as cts.region[], [options as String[]], [weight as Number?] ) as cts.geospatialRegionQuery
Summary
Construct a query to match regions in documents that satisfy a specified relationship relative to other regions. For example, regions in documents that intersect with regions specified in the search criteria.
| Parameters | |
|---|---|
| geospatial-region-reference | Zero or more geospatial path region index references that identify regions in your content. To create a reference, see cts.geospatialRegionPathReference. |
| operation |
The match operation to apply between the regions specified in the
$geospatial-region-reference parameter and the
regions in the $regions parameter. Allowed values:
contains, covered-by, covers,
disjoint, intersects, overlaps,
within, equals, touches,
crosses. See the Usage Notes for details.
|
| regions |
Criteria regions to match against the regions specified in the
$geospatial-region-reference parameter. These regions
function as the right operand of $operation.
|
| options |
Options to this query. The default is (). Available options:
|
| weight | A weight for this query. The default is 1.0. |
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
geospatial-region-reference parameter.
The database configuration must include a geospatial path region index corresponding to each R1 region. For details, see Geospatial Region Queries and Indexes in the Search Developer's Guide.
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.
"disjoint"- R1 is disjoint from R2 if they have no points in common.
"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.
"within"- R1 is within R2 if every point of R1 is also a point of R2, and their interiors intersect.
"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.
"touches"- R1 touches R2 if they have a boundary point in common but no interior points in common.
"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.
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.
If either the geospatial-region-reference or
regions parameter is an empty list, the query will not
match any documents.
The query uses the coordinate system and precision of the geospatial
region index reference supplied in the
geospatial-region-reference parameter. If multiple index
references are specified and they have conflicting coordinate systems,
an XDMP-INCONSCOORD error is thrown.
See Also
- Geospatial Region Queries and Indexes in the Search Developer's Guide
- Searching for Matching Regions in the Search Developer's Guide
Example
cts.geospatialRegionQuery(
cts.geospatialRegionPathReference('//item/region'),
'contains', cts.box(10, 20, 30, 40))