MarkLogic 12 EA 2 Product Documentation
cts:json-property-child-geospatial-querycts:json-property-child-geospatial-query(
$parent-property-name as xs:string*,
$child-property-names as xs:string*,
$regions as cts:region*,
[$options as xs:string*],
[$weight as xs:double?]
) as cts:json-property-child-geospatial-query
Summary
Returns a query matching json properties by name which has
specific children representing latitude and longitude values for
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 |
parent-property-name |
One or more parent property names to match.
When multiple names are specified,
the query matches if any name matches.
|
child-property-names |
One or more child property names to match.
When multiple names are specified, the query matches
if any name matches; however, only the first matching latitude
child in any point instance will be checked. The property must specify
both latitude and longitude coordinates.
|
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=string"
- Use the given coordinate system. Valid values are:
- wgs84
- The WGS84 coordinate system with degrees as the angular unit.
- wgs84/radians
- The WGS84 coordinate system with radians as the angular unit.
- wgs84/double
- The WGS84 coordinate system at double precision with degrees as the angular unit.
- wgs84/radians/double
- The WGS84 coordinate system at double precision with radians as the angular unit.
- etrs89
- The ETRS89 coordinate system.
- etrs89/double
- The ETRS89 coordinate system at double precision.
- raw
- The raw (unmapped) coordinate system.
- raw/double
- The raw coordinate system at double precision.
- "precision=string"
- Use the coordinate system at the given precision. Allowed values:
float (default) and double .
- "units=value"
- Measure distance and the radii of circles in the specified units.
Allowed values:
miles (default), km ,
feet , meters .
- "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.
- "boundaries-endpoints-excluded"
- Points on linestrings' boundary (the endpoints) 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.
- "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).
|
weight |
A weight for this query. The default is 1.0.
|
Usage Notes
The point value is expressed in the content of the property as a child
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 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".
"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
Example
(: create a document with test data :)
xdmp:document-insert("/points.json",
object-node {
"item" : object-node {
"point" : object-node {
"pos" : "15.35, 35.34"
}
}
});
cts:search(doc("/points.json")//item,
cts:json-property-child-geospatial-query("point", "pos",
cts:box(10.0, 35.0, 20.0, 40.0)));
(:
returns the following node: {"point":{"pos":"15.35, 35.34"}}
:)
cts:search(doc("/points.json")//item,
cts:json-property-geospatial-query("point", cts:box(12.0, 20.0, 20.0, 35.0)));
(:
returns ()
:)
Stack Overflow: Get the most useful answers to questions from the MarkLogic community, or ask your own question.