MarkLogic 12 EA 1 Product Documentationcts.elementGeospatialQuery
cts.elementGeospatialQuery( element-name as xs.QName[], regions as cts.region[], [options as String[]], [weight as Number?] ) as cts.elementGeospatialQuery
Summary
Returns a 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.
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).
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.
Point and region coordinates are interpreted according to the governing coordinate system of the query. When using a geographic coordinate system such as wgs84 or wgs84/double the following also applies:
- Southern latitudes and Western longitudes take negative values.
- Longitudes are wrapped to the range (-180,+180).
- Latitudes are 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".
"score-function=linear" means that values that are further away from the bounds will score higher. "score-function=reciprocal" means that values that are closer to the bounds will score higher. The functions are scaled appropriately for different types, so that in general the default slope factor will provide useful results. Using a slope factor greater than 1 gives distinct scores over a smaller range of values, and produces generally higher scores. Using a slope factor less than 1 gives distinct scores over a wider range of values, and produces generally lower scores.
See Also
- Geospatial XML Element Point Queries and Indexes in the Search Developer's Guide
- Searching for Matching Points in the Search Developer's Guide
Example
// create documents with test data
declareUpdate();
xdmp.documentInsert("/point1.xml", xdmp.unquote(
' <item><point>10.5, 30.0</point></item>' )),
xdmp.documentInsert("/point2.xml", xdmp.unquote(
' <item><point>15.35, 35.34</point></item>' )),
xdmp.documentInsert("/point3.xml", xdmp.unquote(
' <item><point>5.11, 40.55</point></item>' ));
// ******
// Now the following search:
cts.search(cts.elementGeospatialQuery(xs.QName("point"),
cts.box(10.0, 35.0, 20.0, 40.0)));
// => The /point2.xml document (because
// <point>15.35, 35.34</point> matches).
// ******
// And the following search:
cts.search(cts.elementGeospatialQuery(xs.QName("point"),
cts.box(10.0, 40.0, 20.0, 35.0)));
// => The /point1.xml document(wrapping around the Earth):
******
// And the following search:
cts.search(cts.elementGeospatialQuery(xs.QName("point"),
cts.box(20.0, 35.0, 10.0, 40.0)));
=> throws an XDMP-BADBOX error (because latitudes do not wrap)