Loading TOC...

cts.jsonPropertyPairGeospatialQuery

cts.jsonPropertyPairGeospatialQuery(
   $property-name as String[],
   $latitude-property-names as String[],
   $longitude-property-names as String[],
   $regions as cts.region[],
   [$options as String[]],
   [$weight as Number?]
) as cts.jsonPropertyPairGeospatialQuery

Summary

Returns a cts:query matching json properties by name which has specific property 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
$property-name One or more parent property names to match. When multiple names are specified, the query matches if any name matches.
$latitude-property-names One or more latitude 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.
$longitude-property-names One or more longitude property names to match. When multiple names are specified, the query matches if any name matches; however, only the first matching longitude child in any point instance will be checked.
$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.
raw
The raw (unmapped) 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.
"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.
"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 occurances of more than one of the synonyms are scored as if there are more occurance 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

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.

Example

// create a document with test data 
declareUpdate();
xdmp.documentInsert("/points.json",
{ "item" :  {
    "point" : {
       "lat" : 15.35,
       "long" : 35.34
    }
  }
});

// Now the following search:

cts.search(
  cts.jsonPropertyPairGeospatialQuery("point",
    "lat", "long", cts.box(10.0, 35.0, 20.0, 40.0)));

// =>  returns the document inserted above:
//     {"item":{"point":{"lat":15.35,"long":35.34}}}

// And the following search:

cts.search(
  cts.jsonPropertyPairGeospatialQuery("point",
    "lat", "long", cts.box(12.0, 20.0, 20.0, 35.0)));

// =>  returns ()

Comments

    Powered by MarkLogic Server 7.0-4.1 and rundmc | Terms of Use | Privacy Policy