Loading TOC...

cts:element-geospatial-query

cts:element-geospatial-query(
   $element-name as xs:QName*,
   $regions as cts:region*,
   [$options as xs:string*],
   [$weight as xs:double?]
) as cts:element-geospatial-query

Summary

Returns a cts:query matching elements by name whose content represents a point contained within the given geographic box, circle, or polygon, or equal to the given point. Points that lie between the southern boundary and the northern boundary of a box, travelling northwards, and between the western boundary and the eastern boundary of the box, travelling eastwards, will match. Points contained within the given radius of the center point of a circle will match, using the curved distance on the surface of the Earth. Points contained within the given polygon will match, using great circle arcs over a spherical model of the Earth as edges. An error may result if the polygon is malformed in some way. Points equal to the a given point will match, taking into account the fact that longitudes converge at the poles. Using the geospatial query constructors requires a valid geospatial license key; without a valid license key, searches that include geospatial queries will throw an exception.

Parameters
$element-name One or more element QNames to match. When multiple QNames are specified, the query matches if any QName matches.
$regions One or more geographic boxes, circles, polygons, or points. Where multiple regions are specified, the query matches if any region matches.
$options Options to this query. The default is ().

Options include:

"coordinate-system=wgs84"
Use the WGS84 coordinate system.
"units=miles"
Distance (for circles) is measured in miles.
"boundaries-included"
Points on boxes', circles', and polygons' boundaries are counted as matching. This is the default.
"boundaries-excluded"
Points on boxes', circles', and polygons' boundaries are not counted as matching.
"boundaries-latitude-excluded"
Points on boxes' latitude boundaries are not counted as matching.
"boundaries-longitude-excluded"
Points on boxes' longitude boundaries are not counted as matching.
"boundaries-south-excluded"
Points on the boxes' southern boundaries are not counted as matching.
"boundaries-west-excluded"
Points on the boxes' western boundaries are not counted as matching.
"boundaries-north-excluded"
Points on the boxes' northern boundaries are not counted as matching.
"boundaries-east-excluded"
Points on the boxes' eastern boundaries are not counted as matching.
"boundaries-circle-excluded"
Points on circles' boundary are not counted as matching.
"cached"
Cache the results of this query in the list cache.
"uncached"
Do not cache the results of this query in the list cache.
"type=long-lat-point"
Specifies the format for the point in the data as longitude first, latitude second.
"type=point"
Specifies the format for the point in the data as latitude first, longitude second. This is the default format.
$weight A weight for this query. The default is 1.0. This option is currently ignored; geospatial queries do not contribute to the score.

Usage Notes

The point value is expressed in the content of the element as a pair of numbers, separated by whitespace and punctuation (excluding decimal points and sign characters).

Point values and boundary specifications of boxes are given in degrees relative to the WGS84 coordinate system. Southern latitudes and Western longitudes take negative values. Longitudes will be wrapped to the range (-180,+180) and latitudes will be clipped to the range (-90,+90).

If the northern boundary of a box is south of the southern boundary, no points will match. However, longitudes wrap around the globe, so that if the western boundary is east of the eastern boundary, then the box crosses the anti-meridian.

Special handling occurs at the poles, as all longitudes exist at latitudes +90 and -90.

If neither "cached" nor "uncached" is present, it specifies "cached".

Example

(: create a document with test data :)
xdmp:document-insert("/points.xml",
<root>
  <item><point>10.5, 30.0</point></item>
  <item><point>15.35, 35.34</point></item>
  <item><point>5.11, 40.55</point></item>
</root> );

cts:search(doc("/points.xml")//item, 
  cts:element-geospatial-query(xs:QName("point"), cts:box(10.0, 35.0, 20.0, 40.0)))
(:
  returns the following node: 
  <item><point>15.35, 35.34</point></item>
:)
;

cts:search(doc("/points.xml")//item, 
  cts:element-geospatial-query(xs:QName("point"), cts:box(10.0, 40.0, 20.0, 35.0)))
(:
  returns the following nodes (wrapping around the Earth):
  <item><point>10.5, 30.0</point></item>
:)
;

cts:search(doc("/points.xml")//item, 
  cts:element-geospatial-query(xs:QName("point"), cts:box(20.0, 35.0, 10.0, 40.0)))
(:
  throws an error (latitudes do not wrap)
:)
;

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