Loading TOC...
XQuery cts:geospatial-region-query

MarkLogic Server 11.0 Product Documentation
cts.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:
"units=value"
Measure distances and the radii of circles using the given units. Allowed values: miles (default), km, feet, and meters. This option only affects regions provided in the $regions parameter, not regions stored in documents.
"score-function=function"
Use the selected scoring function. The score function may be:
linear
Use a linear function of the difference between the specified query value and the matching value in the index to calculate a score for this range query.
reciprocal
Use a reciprocal function of the difference between the specified query value and the matching value in the index to calculate a score for this range query.
zero
This range query does not contribute to the score. This is the default.
"slope-factor=number"
Apply the given number as a scaling factor to the slope of the scoring function. The default is 1.0.
"synonym"
Specifies that all of the terms in the $regions parameter are considered synonyms for scoring purposes. The result is that occurrences of more than one of the synonyms are scored as if there are more occurrence of the same term (as opposed to having a separate term that contributes to score).
"tolerance=distance"
Tolerance is the largest allowable variation in geometry calculations. If the distance between two points is less than tolerance, then the two points are considered equal. For the raw coordinate system, use the units of the coordinates. For geographic coordinate systems, use the units specified by the units option.
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

Example

cts.geospatialRegionQuery(
  cts.geospatialRegionPathReference('//item/region'),
    'contains', cts.box(10, 20, 30, 40))

Stack Overflow iconStack Overflow: Get the most useful answers to questions from the MarkLogic community, or ask your own question.