MarkLogic 9 Product Documentation
cts:element-geospatial-boxes

cts:element-geospatial-boxes(
   $element-names as xs:QName*,
   [$latitude-bounds as xs:double*],
   [$longitude-bounds as xs:double*],
   [$options as xs:string*],
   [$query as cts:query?],
   [$quality-weight as xs:double?],
   [$forest-ids as xs:unsignedLong*]
) as cts:box*

Summary

Returns boxes derived from the specified element point lexicon(s). Element point lexicons are implemented using geospatial indexes; consequently this function requires an element geospatial index for each element specified in the function. If there is not a geospatial index configured for each of the specified elements, an exception is thrown.

The points are divided into box-shaped buckets. The $latitude-bounds and $longitude-bounds parameters specify the number and the size of each box-shaped bucket. All included points are bucketed, even those outside the bounds. An empty sequence for both $latitude-bounds and $longitude-bounds specifies one bucket, a single value for both specifies four buckets, two values for both specify nine buckets, and so on.

For each non-empty bucket, a cts:box value is returned. By default, the box value is the minimum bounding box of all the points in the bucket. If the "gridded" option is specified, then if a bucket is bounded on a side, its corresponding cts:box side is the bound. Empty buckets return nothing unless the "empties" option is specified.

Parameters
element-names	One or more element QNames.
latitude-bounds	A sequence of latitude bounds. The values must be in strictly ascending order, otherwise an exception is thrown.
longitude-bounds	A sequence of longitude bounds. The values must be in strictly ascending order, otherwise an exception is thrown.
options	Use the following options to customize your lexicon query: "ascending" Boxes should be returned in ascending order. "descending" Boxes should be returned in descending order. "gridded" For each side that a bucket is bounded, return the corresponding bound as the edge of the box, instead of the extremum from the points in the bucket. "empties" Include fully-bounded ranges whose frequency is 0. Only empty ranges that have both their upper and lower bounds specified in the $bounds options are returned; any empty ranges that are less than the first bound or greater than the last bound are not returned. For example, if you specify 4 bounds and there are no results for any of the bounds, 3 elements are returned (not 5 elements). "any" Points from any fragment should be included. "document" Points from document fragments should be included. "properties" Points from properties fragments should be included. "locks" Points from locks fragments should be included. "frequency-order" Boxes should be returned ordered by frequency. "item-order" Boxes should be returned ordered by item. "fragment-frequency" Frequency should be the number of fragments with an included point. This option is used with `cts:frequency`. "item-frequency" Frequency should be the number of occurences of an included point. This option is used with `cts:frequency`. "coordinate-system=name" Use the lexicon that is configured with the specified coordinate system. Allowed values: "wgs84", "wgs84/double", "etrs89", "etrs89/double", "raw", "raw/double". "precision=value" Use the coordinate system at the given precision. Allowed values: `float` and `double`. "limit=N" Return no more than N boxes. You should not use this option with the "skip" option. Use "truncate" instead. "skip=N" Skip over fragments selected by the `query` to treat the Nth matching fragment as the first fragment. Points from skipped fragments are not included. This option affects the number of fragments selected by the `query` to calculate frequencies. Only applies when a `$query` parameter is specified. "sample=N" Return only boxes for buckets with at least one point from the first N fragments after skip selected by the `query`. This option does not affect the number of fragments selected by the `query` to calculate frequencies. Only applies when a `$query` parameter is specified. "truncate=N" Include only points from the first N fragments after skip selected by the `query`. This option affects the number of fragments selected by the `query` to calculate frequencies. Only applies when a `$query` parameter is specified. "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-logtfidf" Compute scores using the logtfidf method. Only applies when a `$query` parameter is specified. "score-logtf" Compute scores using the logtf method. Only applies when a `$query` parameter is specified. "score-simple" Compute scores using the simple method. Only applies when a `$query` parameter is specified. "score-random" Compute scores using the random method. Only applies when a `$query` parameter is specified. "score-zero" Compute all scores as zero. Only applies when a `$query` parameter is specified. "checked" Word positions should be checked when resolving the query. "unchecked" Word positions should not be checked when resolving the query. "too-many-positions-error" If too much memory is needed to perform positions calculations to check whether a document matches a query, return an XDMP-TOOMANYPOSITIONS error, instead of accepting the document as a match. "eager" Perform most of the work concurrently before returning the first item from the indexes, and only some of the work sequentially while iterating through the rest of the items. This usually takes the shortest time for a complete item-order result or for any frequency-order result. "lazy" Perform only some the work concurrently before returning the first item from the indexes, and most of the work sequentially while iterating through the rest of the items. This usually takes the shortest time for a small item-order partial result. "concurrent" Perform the work concurrently in another thread. This is a hint to the query optimizer to help parallelize the lexicon work, allowing the calling query to continue performing other work while the lexicon processing occurs. This is especially useful in cases where multiple lexicon calls occur in the same query (for example, resolving many facets in a single query). "map" Return results as a single map:map value instead of as a cts:box* sequence .
query	Only include points in fragments selected by this query, and compute frequencies from this set of included points. The points do not need to match the query, but they must occur in fragments selected by the query. The fragments are not filtered to ensure they match the query, but instead selected in the same manner as "unfiltered" `cts:search` operations.
quality-weight	A document quality weight to use when computing scores. The default is 1.0.
forest-ids	A sequence of IDs of forests to which the search will be constrained. An empty sequence means to search all forests in the database. The default is ().

Usage Notes

Only one of "frequency-order" or "item-order" may be specified in the options parameter. If neither "frequency-order" nor "item-order" is specified, then the default is "item-order".

Only one of "fragment-frequency" or "item-frequency" may be specified in the options parameter. If neither "fragment-frequency" nor "item-frequency" is specified, then the default is "fragment-frequency".

Only one of "ascending" or "descending" may be specified in the options parameter. If neither "ascending" nor "descending" is specified, then the default is "ascending" if "item-order" is specified, and "descending" if "frequency-order" is specified.

Only one of "eager" or "lazy" may be specified in the options parameter. If neither "eager" nor "lazy" is specified, then the default is "eager" if "frequency-order" or "empties" is specified, otherwise "lazy".

Only one of "any", "document", "properties", or "locks" may be specified in the options parameter. If none of "any", "document", "properties", or "locks" are specified and there is a $query parameter, then the default is "document". If there is no $query parameter then the default is "any".

Only one of the "score-logtfidf", "score-logtf", "score-simple", "score-random", or "score-zero" options may be specified in the options parameter. If none of "score-logtfidf", "score-logtf", "score-simple", "score-random", or "score-zero" are specified, then the default is "score-logtfidf".

Only one of the "checked" or "unchecked" options may be specified in the options parameter. If neither "checked" nor "unchecked" are specified, then the default is "checked".

If "coordinate-system=name" is not specified in the options parameter, then the default coordinate system is used. If a lexicon with that coordinate system does not exist, an error is thrown.

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.

If "sample=N" is not specfied in the options parameter, then all boxes with included points may be returned. If a $query parameter is not present, then "sample=N" has no effect.

If "truncate=N" is not specfied in the options parameter, then points from all fragments selected by the $query parameter are included. If a $query parameter is not present, then "truncate=N" has no effect.

To incrementally fetch a subset of the values returned by this function, use fn:subsequence on the output, rather than the "skip" option. The "skip" option is based on fragments matching the query parameter (if present), not on values. A fragment matched by the query might produce multiple boxes or no boxes. The number of fragments skipped does not correspond to the number of boxes. Also, the skip is applied to the relevance ordered query matches, not to the ordered box list.

When using the "skip" option, use the "truncate" option rather than the "limit" option to control the number of matching fragments from which to draw values.

Example

(:
   Create a 15 degree latitude by 30 degree longitude grid over the
   Eastern part of the Northern hemisphere, figure out how many points in
   the element "point" are in each grid section, and return a box for each
   grid section, whether it has points in it or not. The box will have the
   actual min/max latitudes and longitudes of points in that grid section as
   its bounds. Order the boxes in increasing order of latitude and longitude,
   and return the frequency of points in the box and the box itself.
 :)
for $box in
  cts:element-geospatial-boxes(xs:QName("point"),
    (15, 30, 45, 60, 75), (0, 30, 60, 90, 120),
    ("ascending", "empties"))
return (cts:frequency($box), $box)

MarkLogic 9 Product Documentationcts:element-geospatial-boxes

Summary

Usage Notes

See Also

Example

MarkLogic 9 Product Documentation
cts:element-geospatial-boxes