MarkLogic Server 11.0 Product Documentation

Search Developer's Guide — Chapter 14

Search for Points, Polygons, and Other Regions

In MarkLogic, you can construct searches based on either points (discrete locations) or regions (areas). A geospatial query can match points, polygons, and other regions in your documents against points, boxes, circles, polygons, complex polygons, and linestrings search criteria.

You can compare points for equality to other points or for containment in regions. You can compare polygons and other regions using a rich set of topological operators that includes containment, overlap, and intersection.

For example, you can use geospatial search in MarkLogic to find documents matching criteria such as the following:

• Match points against other points. For example, find documents containing this point.
• Match points within regions. For example, find documents containing a point within this circle.
• Match regions against each other: For example, find documents containing a polygon that overlaps this polygon, or find documents containing a region that intersects this linestring.

Notice that the first two query types match points in documents. These are called point queries. You can only use a point query to test for equality to another point or containment within a region.

To search for regions satisfying relationships such as intersection, containment, and overlap, use a region query.

For more details, see:

• Understanding Geospatial Query and Index Types
• Searching for Matching Points
• Searching for Matching Regions

Geospatial Type System

The geospatial interfaces in MarkLogic operate on a geospatial type hierarchy based on point and region primitive types. The type system includes region subtypes for specific region types, such as circle, box, and linestring.

The cts:point XQuery type and cts.point JavaScript type represents a point. Points are used as building blocks for the region types. The cts:region XQuery type and the cts.region JavaScript is the base type for all regions.

The geospatial interfaces include constructors for creating points and all supported region types. For example, you can create a polygon value using the cts:polygon XQuery constructor or the cts.polygon JavaScript constructor.

For more details, see Constructing Geospatial Point and Region Values.

Multiple Coordinate Systems

The geospatial data can be expressed in one of several coordinate systems, including WGS84, ETRS89, and raw. WGS84 and ETRS89 are earth-centered geodetic coordinate systems. Raw is a flat plane, cartesian coordinate system. For more details, see Supported Coordinate Systems.

MarkLogic also supports both single and double precision coordinates for each coordinate system. The precision is coupled with the coordinate system in most contexts. For example, when constructing a geospatial point index, your choice of coordinate system includes both wgs84 (single precision) and wgs84/double (double precision).

For details, see the following topics:

• Supported Coordinate Systems
• Controlling Coordinate System and Precision

Support for Common Geospatial Representations

Many MarkLogic interfaces work with geospatial data in common formats, such as Well Known Text (WKT), Well Know Binary (WKB), KML, GML, and GeoJson.

For more details, see:

• Converting To and From Common Geospatial Representations

Flexible Data Layout

Geospatial data in MarkLogic is stored in XML elements and/or attributes, and JSON properties. The coordinates of a point or region thus stored can be represented in several different ways. You can also identify the location of your geospatial data in several different ways.

For point queries, you can specify the location of coordinates in your documents by XPath expression, XML element name, XML element attribute name, or JSON property name. In addition, the coordinates of a point can be either a single, compound value ("10.5 32.7") or separate latitude and longitude values.

For region queries, specify the location of the region coordinates using an XPath expression. Region coordinates must be stored as WKT or serialized cts:region values.

Coordinates can also be stored, indexed, and interpreted as either single or double precision values. The original precision is always preserved in your documents, but the configured precision determines the precision at which coordinates are indexed and interpreted during computations.

For more details, see:

• Understanding Geospatial Query and Index Types
• Understanding Coordinate Systems

Support for Single and Double Precision Coordinates

You can evaluate geospatial queries and create geospatial indexes that interpret coordinates as either single (float) or double precision values. You should usually choose single precision, unless your application requires fine-grained accuracy (less than 1 meter).

The default precision depends on your evaluation context. If you do nothing to explictly configure the precision of your App Server or evaluation context, then single precision is used.

For details, see the following topics:

• Understanding Coordinate Systems
• Controlling Coordinate System and Precision

Geospatial Computational Utility Functions

MarkLogic provides a rich set of geospatial utility functions, including the following:

• Computing distance and bearing computations
• Counting region vertices
• Finding the point at which two arcs intersect
• Generating a set of bounding boxes that cover a region

For more details, see Summary of Other Geospatial Operations.

Geospatial Format Conversion Functions

MarkLogic provides XQuery and JavaScript library modules to translate Metacarta, GML, KML, GeoRSS, and GeoJSON formats to MarkLogic primitive geospatial types.

The functions in these libraries are designed to convert geospatial data in supported formats and convert it into primitive MarkLogic geospatial primitive types for use with geospatial query constructors and other geospatial operations.

For more details, see the following topics:

• Converting To and From Common Geospatial Representations

Support in Multiple APIs

This chapter focuses on performing geospatial queries in MarkLogic Server using the cts:search XQuery function or cts.search Server-Side JavaScript function. You can also configure and use geospatial search with the following MarkLogic APIs:

• Search API (XQuery or Server-Side JavaScript); see Appendix: Query Options Reference and Searching Using Structured Queries.
• JSearch API (Server-Side JavaScript); see Creating JavaScript Search Applications and the examples in this chapter.
• Client APIs for Node.js, Java, and REST; see Creating Point Queries with the Client APIs and Creating Region Queries Using the Client APIs
• REST Management API (for creating and managing geospatial indexes); see the Monitoring MarkLogic Guide and MarkLogic REST API Reference.

Understanding Points

A point represents a discrete location. In a geodetic coordinate system such as WGS84, a point represents a discrete location on the earth. In a Euclidean coordinate system such as raw, a point represents a discrete location in the Euclidean space.

A point is represented by an ordered pair of numbers called coordinates. In a geodetic coordinate system, these numbers represent latitude and longitude values on the earth; for more details, see Understanding Geodetic Coordinates. In a 2-dimensional Euclidean coordinate system, these numbers represent horizontal (x) and verical (y) values; for more details, see Understanding Euclidean Coordinates.

The cts:point XQuery type and cts.point JavaScript type represent a point in MarkLogic Server. Use the cts:point or cts.point constructor to construct a point from a pair of coordinates.

Points are also to used define the other regions in MarkLogic Server, and constructor functions are available for these regions, such cts:box in XQuery or cts.polygon in JavaScript. To learn about supported region types, see Understanding MarkLogic Geospatial Region Types.

Understanding Geodetic Coordinates

A geodetic coordinate system maps points to locations on the Earth. MarkLogic supports geodetic coordinate systems such as WGS84 and ETRS89.

The coordinates of a point in a geodetic coordinate system represent latitude and longitude positions on the Earth. A point has one latitude coordinate and one longitude coordinate. The latitude coordinate represents the north/south position of the point on the Earth. The longitude coordinate represents the east/west position of the point on the Earth.

Point coordinates are expressed in decimal degrees. Distance is measured in units such as miles, feet, kilometers, and meters.

In a geodetic coordinate system, the shortest distance between two points is a curve called a geodesic arc or simply a geodesic. (In a spherical coordinate system, a geodesic is the same as a great circle.) The edges of a polygon in a geodetic coordinate system are geodesics, not straight lines.

Latitude values are in the range -90 to 90 degrees. The equator has latitude zero. Negative latitude values are south of the equator, with -90 at the south pole. Positive latitude values are north of the equator, with 90 at the north pole.

Longitude values are in the range -180 to 180 degrees. The Prime Meridian has longitude 0. Negative longitude values span the 180 degrees west of the Prime Meridian. Positive longitude values span the 180 degrees east of the Prime Meridian.

Understanding Euclidean Coordinates

A Euclidean coordinate system maps points to locations on a two-dimensional Euclidean plane. The raw coordinate system in MarkLogic is a Euclidean coordinate system; for more details, see Raw Coordinate System.

A Euclidean coordinate can be used to represent non-Earth spatial data in local coordinate systems, such as for mathematical modeling or when projecting geographic points on to a flat plane.

A point in the raw coordinate system is represented by an (x,y) value pair, where x represents the horizontal position on the plane and y represents the vertical position. The interpretation of the coordinates is application specific, as is the range of values.

Point coordinates and distances in a Euclidean coordinate system are interpreted in an application-specific way. The units for x, y, and distance are assumed to be the same. The edges of a polygon are straight lines in a Euclidean coordinate system.

Most of the geospatial interfaces and documentation in MarkLogic refer to the coordinates of a point or region using latitude and longitude terminology. However, when working with a raw coordinate system, the coordinates do not actually represent latitude and longitude values. Instead, latitude refers to the x coordinate and longitude refers to the y coordinate.

Supported Coordinate Systems

MarkLogic Server supports the following coordinate systems for geospatial data:

• WGS84 Coordinate System
• ETRS89 Coordinate System
• Raw Coordinate System

The Governing Coordinate System

The governing coordinate system is the coordinate system/precision combination in effect during a geospatial operation. It affects the handling of input values, calculations, comparisons, and return values.

A precision is always implied by the coordinate system name. For example, wgs84 implies single precision, while wgs84/double implies double precision. However, some operations accept a precision option that enables you to override the precision implicit in the coordinate system name. For details, see Specifying a Per-Operation Coordinate System and Precision.

The governing coordinate system is based on a precedence ordering of the coordinate system and precision specified in the App Server configuration, a main module prolog (XQuery only), and the parameters or options of a geospatial function (from lowest to highest precedence). For details, see How MarkLogic Selects the Governing Coordinate System.

How Precision Affects Geospatial Operations

The governing coordinate system always has an associated precision, either float (single) or double. Some operations allow you to override the precision implied by the coordinate system through an option.

• The original precision of your data is always preserved in your documents.
• Geospatial data is indexed using the precision configured for the index.
• Geospatial points and regions are serialized at the precision of the governing coordinate system.
• Comparison operations on geospatial regions use the precision of the governing coordinate system.
• Functions operating on geospatial data interpret their input, perform their calculations, and return their results using the governing coordinate system.
• Functions that return geospatial points or regions return either single or double precision coordinates, depending on the governing coordinate system.
• Accessor functions for geospatial points or region return either a single or double precision value, depending on the governing coordinate system. This applies to XQuery functions such as cts:point-latitude, cts:circle-radius, cts:box-west, and their Server-Side JavaScript equivalents.
• Latitude and longitude bounds on box functions are not truncated to the single precision range if the governing coordinate system is double precision. This applies to XQuery functions such as cts:geospatial-boxes and cts:element-geospatial-boxes, and their Server-Side JavaScript equivalents.
• Geospatial operations perform calculations using the precision of the governing coordinate system. This applies to functions such as cts:distance, cts:polygon-contains, and cts:bounding-boxes, and their Server-Side JavaScript equivalents.
• The input pattern parameter to value-match functions can be either single or double precision, depending on the governing coordinate system. This applies to XQuery functions such as cts:element-geospatial-value-match and their Server-Side JavaScript equivalents.
• Searches involving geospatial queries use the precision of the governing coordinate system for determining matches and calculating scores.

Boxes

A geospatial box is a rectangular region consisting of all the points whose latitude and longitude coordinates are within the region bounds.

In a geodetic coordinate system, a box is a projection from the three-dimensional Earth onto a flat surface. On the surface of the Earth, the edges of a box are arcs. When you project the edges onto a flat plane, they become two-dimensional latitude and longitude lines, and the space defined by those lines forms a rectangle.

The following diagram uses a plate caree projection to illustrate the difference between the region defined by a box on the surface of the Earth and its projection into a rectangular region on a flat plane.

In a geodetic coordinate system, the north and south edges of a box are latitude lines, not geodesic arcs. The east and west edges of a box are longitude lines, which are geodesic arcs. A box is not equivalent to a polygon with the same four vertices.

A point is contained in a box if its latitude coordinate is between the north and south latitude coordinates of the box, and its longitude coordinate is between the west and east longitude coordinates of the box.

In a Euclidean coordinate system, a box is simply a rectangle with boundaries defined by north, south, east, and west coordinates. In a Euclidean coordinate system, a box is equivalent to a polygon with the same four vertices.

The following assumptions and restrictions only apply to boxes in a geodetic coordinate system:

• In a geodetic coordinate system, the west/east extent of a box is determined by starting at the western longitude coordinate and heading east toward the eastern longitude coordinate. If the west coordinate is less than the east coordinate, the box will not cross the anti-meridian. If the east coordinate is less than the west coordinate, the box crosses the anti-meridian.
• In a geodetic coordinate system, the south/north extent of a box is determined by starting at the southern latitude coordinate and heading north to the northern latitude coordinate. However, you cannot cross the pole: The northern coordinate must be greater than the southern coordinate.

The following assumptions and restrictions apply to boxes under both geodetic and Euclidean coordinate systems:

• If the western and eastern coordinates are the same, the box is a meridian line segment between the southern and northern coordinates passing through that longitude coordinate.
• If the southern and northern coordinates are the same, the box is a latitude line segment between the western and eastern coordinates passing through that longitude coordinate.
• If the western and eastern coordinates are the same, and the southern and northern coordinates are the same, then the box is a point specified by those coordinates.
• During a search, the query options determine whether the boundaries of a box are included in or excluded from the box. Various boundary options on the geospatial query constructors control this behavior).

In the raw coordinate system, the western coordinates are always less than or equal to the eastern coordinates, and the southern coordinates are always less than or equal to the northern coordinates.

The cts:box XQuery type and cts.box JavaScript type represent a box in MarkLogic Server. You can create a box using the cts:box XQuery constructor or the cts.box JavaScript constructor. You can also create a box using one of the conversion utility functions such as geogml:box (XQuery) or geojson.box (JavaScript). For more details, see Constructing Geospatial Point and Region Values.

Polygons

A geospatial polygon is a region with three or more sides. The following diagram illustrates several polygons.

In a geodetic coordinate system, a polygon can represent any area on the Earth (with the exceptions described below). For example, you might create a polygon to represent a country or a geographical region.

Polygons offer a large degree of flexibility compared to circles or boxes. In exchange for the flexibility, operations on geospatial polygons are not quite as fast or accurate as geospatial box and circle operations.

The efficiency of polygon operations is proportional to the number of sides to the polygon. For example, a typical 10-sided polygon will likely perform faster than a typical 1000-sided polygon. The speed is dependent on many factors, including where the polygon is, the nature of your geospatial data, and so on.

The following assumptions and restrictions apply to polygons only under a geodetic coordinate system in MarkLogic:

• A geodetic coordinate system treats the earth as an ellipsoid. In such a system, the edges of a polygon are geodesic arcs, not latitude lines.
• A polygon cannot include both poles and cannot have both poles as a boundary (regardless of whether the boundaries are included). Thus, a polygon cannot encompass the full 180 degrees of latitude.
• The span of the arc described by a polygon edge in a geodetic coordinate system must be between 0 and 180 degrees and cannot cross a pole. If you need to span more than 180 degrees, define multiple edges that cover the desired span.

  Latitude lines are distinct from geodesic arcs. Except for the equator, the shortest distance between two points at the same latitude does not follow the latitude line. The edges of polygons are geodesic arcs, not latitude lines. You can approximate a latitude line by adding vertices evenly spaced along the latitude line. The north and south edges of a box are latitude lines; if the region to be described is a box, use a cts:box or cts.box instead of a polygon.

The following assumptions and restrictions apply to polygons under either a geodetic or Euclidean coordinate system in MarkLogic.

• No two edges of a polygon or complex polygon may overlap or cross.
• Coordinate system is considered at search time rather than when you construct a polygon value. Therefore, a search will throw a runtime exception if a polygon is not valid for the governing coordinate system.
• The boundaries of a polygon are either in or out of the polygon, depending on the operation and query options. The DE9IM operators include specific boundary behaviors; for other operations, you can use query constructor options to control the boundary behavior.

You can construct a polygon by specifying the points that make up the vertices of the polygon. All points that are bounded by the resulting region are defined to be contained within the region.

For details, see the cts:polygon XQuery function or the cts.polygon JavaScript function.

Complex Polygons

A complex polygon is a polygon with one more holes. For example, the following graphic illustrates the difference between polygon and a complex polygon. The complex polygon is the shaded region in the region on the right. The unshaded region, or inner polygon, represents a hole in the outer polygon.

You can construct a complex polygon by constructing an outer polygon with zero or more outer polygons. All inner polygons must be completely contained in the interior of the outer polygon. No two edges can cross or overlap. Use the cts:complex-polygon XQuery function or the cts.complexPolygon JavaScript function to construct a complex polygon.

You can also cast a cts:complex-polygon or cts.complexPolygon with no holes (that is, with no inner polygons) to a cts:polygon or cts.polygon. If you specify multiple inner polygons, none of them should overlap each other.

Linestrings

A linestring is a connected sequence of edges. In a geodetic coordinate system, edges are geodesic arcs. In a Euclidean coordinate system such as raw, the edges are straight lines.

A linestring does not necessarily form a closed loop as the boundary of a polygon does, although it is permissible for a linestring to form a closed loop. The following diagram demonstrates some examples of linestrings.

You can compare linestrings for equality or inequality. Two linestrings are equal if all of their vertices are equal, or if they are both empty.

To construct a linestring, use the cts:linestring XQuery function or the cts.linestring JavaScript function.

Circles

A geospatial circle consists of all the points within a certain distance (the radius) of a given center point. A geospatial region that represents a circle is defined by its center point and radius. The points that are the distance of the radius from the center define the boundary of the region.

Use the cts:circle XQuery function or the cts.circle JavaScript function to construct a circle.

Introduction to Geospatial Query and Index Types

MarkLogic supports several types of query for searching geospatial data contained in documents. In general, geospatial queries fall into the following two categories, based on the kind of geospatial document content to be matched:

• Point query: Match points in documents against points or other regions specified as input criteria. For example, Find all documents containing a point within this circle.
• Region query: Match other regions in documents that satisfy one of a number of relationships when compared to regions specified as input criteria. For example, Find all documents containing polygons that intersect with this polygon.

For best performance, a point query should be supported by a corresponding geospatial index. A region query always requires a backing geospatial region index. MarkLogic supports several types of geospatial index, corresponding to the different geospatial query types.

Select a geospatial point query or index type based on the layout of your data. The query or index type varies depending on whether the data is represented in XML or JSON, and whether the point coordinates are represented as a single compound value (lat lon) or as distinct latitude and longitude values. For example, you might use a cts:element-geospatial-query and a geospatial element index for points represented as a single compound XML element value.

The data layout for a region query or region index must be WKT or a serialized cts region, such as a cts:polygon. The region data is located within a document using an XPath expression when creating a query or index. Therefore, you use a cts:geospatial-region-query and a geospatial region path index for querying by region.

The following table summarizes the query and index types MarkLogic supports, based on the axes of geospatial content type (point or other region) and layout.

<coords>1.0 2.0</coords>

<container>
  <coords>1.0 2.0</coords>
<container>

<coords>
  <lat>1.0</lat>
  <lon>2.0</lon>
</coords>

<coords lat="1.0" lon="2.0" />

{"coords": "1.0 2.0" }

{"coords": [1.0, 2.0] }

{"container": {
  {"coords": "1.0 2.0" }
}}

{"container": {
  {"coords": [1.0, 2.0] }
}}

{"coords": {
  "lat": 1.0,
  "lon": 2.0
}}

Geospatial Query Creation

You can create a geospatial cts query in the following ways.

• Using an XQuery or Server-Side JavaScript query constructor, such as cts:element-geospatial-query (XQuery) or cts.pathGeospatialQuery (JavaScript).
• Parsing query text containing a geospatial search term. For details, see Constructing a Point Query in XQuery or Constructing a Region Query from Query Text.

You can also create a geospatial structured query or Query By Example for use with the Search API or the Client APIs. The Java and Node.js Client APIs include builder interfaces for creating structured queries.

For more details, see the sections on each query/index type elsewhere in this section and the following topics:

• Searching for Matching Points
• Searching for Matching Regions

Geospatial Index Creation

Region queries require a region index, but an index is optional for some point queries. For best performance, you should usually create a geospatial index for both query types.

You must have a valid geospatial license key to create or use any geospatial indexes.

Use a geospatial region path index when matching regions in your documents. Use a geospatial point index when matching points in your documents; the type of point index depends on the layout of your content . For details, see Introduction to Geospatial Query and Index Types.

When creating a point index, you can specify the coordinate system, coordinate value precision, and point type (long-lat or lat-long). When creating a region index, you can specify the coordinate system and geohash precision. The default coordinate system is WGS84. The default coordinate precision is float (single precision), and the default point type is point (lat-long).

When you create an index using the Admin API, index properties such as coordinate system and precision are specified through the index reference constructor function, such as admin:database-geospatial-element-index or admin:database-geospatial-region-path-index. For an example of index creation using the Admin API, see Configuring the Indexes.

You can create a geospatial index using the following methods:

• Interactively, using the Admin Interface. See the Geospatial Point Indexes or Geospatial Region Indexes section under Database > database_name in the Admin Interface.
• Programmatically, using the server-side Admin API functions. For example, to create a geospatial element index, use the XQuery function admin:database-add-geospatial-element-index or the JavaScript function admin.databaseAddGeospatialElementIndex.
• Programmatically, using the REST Management API. For details, see the PUT /manage/v2/databases/{id|name}/properties method.

For more details, see the sections on each query/index type, below.

Geospatial XML Element Point Queries and Indexes

Use a geospatial element query when the point coordinates in your documents are represented as the value of a single XML element, with the latitude and longitude values separated by whitespace or punctuation (except +, -, or .). For example:

<coords>37.52  -122.25</coords>

By default, the first coordinate is the latitude value, and the second coordinate is the longitude value. You can override the default order by specifying a longitude-first ordering when creating queries and indexes.

If the element value contains other coordinates, they are ignored. For example, KML data can include an additional altitude coordinate. The altitude can be present but is ignored.

When you use a geospatial element query, you should also create a corresponding geospatial element index for best performance.

For JSON documents with similar layout, see Geospatial JSON Property Point Queries and Indexes.

You can use the following interfaces to create a geospatial element query:

com.marklogic.client.query.StructuredQueryBuilder.geoElement
  plus
com.marklogic.client.query.StructuredQueryBuilder.geospatial 

You can use the following interfaces to create a geospatial element index:

Geospatial XML Element Child Point Queries and Indexes

Use a geospatial element child index for geospatial point data when the coordinates are contained in an XML element value, separated by whitespace or punctuation (except +, -, or .), and you want to identify the container element as a child of another specific element. For example:

<parent-name>
  <child-name>37.52  -122.25</child-name>
</parent-name>

By default, the first coordinate is the latitude value, and the second coordinate is the longitude value. You can override the default order by specifying a longitude-first ordering when creating queries and indexes.

If the element value contains other coordinates, they are ignored. For example, KML data can include an additional altitude coordinate. The altitude can be present but is ignored.

When you use a geospatial element child query, you should also create a corresponding geospatial element child index for best performance.

For JSON documents with similar layout, see Geospatial JSON Property Child Point Queries and Indexes.

You can use the following interfaces to create a geospatial element child query:

com.marklogic.client.query.StructuredQueryBuilder.geoElement
  and
com.marklogic.client.query.StructuredQueryBuilder.geospatial

You can use the following interfaces to create a geospatial element child index:

Geospatial XML Element Pair Point Queries and Indexes

Use a geospatial element pair index for geospatial point data when the longitude and latitude are values in two different elements that are children of the same parent element. For example:

<container-name>
  <latitude>37.52</latitude>
  <longitude>-122.25</longitude>
</container-name>

For JSON data requirements, see Geospatial JSON Property Pair Point Queries and Indexes.

You can use the following interfaces to create a geospatial element pair query:

com.marklogic.client.query.StructuredQueryBuilder.geoElementPair
  and
com.marklogic.client.query.StructuredQueryBuilder.geospatial 

You can use the following interfaces to create a geospatial element pair index:

Geospatial XML Attribute Pair Point Queries and Indexes

Use a geospatial attribute pair index for geospatial point data when the longitude and latitude are values in two different attributes of the same parent XML element. For example:

<element-name latitude="37.52" longitude="-122.25"/>

When you use a geospatial attribute pair query, you should also create a corresponding geospatial attribute pair index for best performance.

You can use the following interfaces to create a geospatial element attribute pair query:

com.marklogic.client.query.StructuredQueryBuilder.geoElement
  and
com.marklogic.client.query.StructuredQueryBuilder.geospatial

You can use the following interfaces to create a geospatial element attribute pair index:

Geospatial Path Point Queries and Indexes

Use a geospatial path query and index for matching points when you want to express the location of the points using an XPath expression. The data layout must be one of the following:

• A single XML element value with the latitude and longitude coordinates separated by whitespace or punctuation, as for a geospatial element query.
• A single JSON property value with the latitude and longitude coordinates separated by whitespace or punctuation, as for a geospatial JSON property query.
• A JSON array value containing a latitude element and a longitude element, as for a geospatial JSON property query.

By default, the first coordinate is the latitude value, and the second coordinate is the longitude value. You can override the default order by specifying a longitude-first ordering when creating queries and indexes.

The path expression with which you define the index is limited to a subset of XPath for performance reasons. For details, see Path Field and Path-Based Range Index Configuration in the XQuery and XSLT Reference Guide.

The following table demonstrates the XPath expression to use when creating a path range index for several forms of example geospatial data.

XML

<a:data>
  <a:geo>37.52 -122.25</a:geo>
</a:data>

/a:data/a:geo

XML

<a:data>
  <a:geo data="37.52 -122.25"/>
</a:data>

/a:data/a:geo/@data

JSON

{ "geometry" : {
    "type": "Point",
    "coordinates": [37.52,-122.25]
  }
}

/geometry[type="Point"]/array-node("coordinates")

Once you create a geospatial path range index, you cannot change the path expression. To change the path, you must remove the existing geospatial path range index and create a new one.

You can use the following interfaces to create a geospatial path query:

com.marklogic.client.query.StructuredQueryBuilder.geoPath
  and
com.marklogic.client.query.StructuredQueryBuilder.geospatial

You can use the following interfaces to create a geospatial path index:

Geospatial JSON Property Point Queries and Indexes

Use a geospatial element index to index geospatial data in JSON documents when the point coordinates are contained in a single JSON property. The geospatial data must be represented in the property value as either whitespace/punctuation separated values in a string, or as an array of values. For example:

"prop-name": "37.52 -122.25"
"prop-name": [37.52, -122.25]

By default, the first coordinate is the latitude value, and the second coordinate is the longitude value. You can override the default order by specifying a longitude-first ordering when creating queries and indexes. The property value can include other entries, but they are ignored (for example, KML has an additional altitude coordinate, which can be present but is ignored).

You can use the following interfaces to create a geospatial JSON property query:

com.marklogic.client.query.StructuredQueryBuilder.geoJSONProperty
  and
com.marklogic.client.query.StructuredQueryBuilder.geospatial

You can use the following interfaces to create an index for a geospatial JSON property query. Note you should create a geospatial element index, even though you are indexing JSON content.

Geospatial JSON Property Child Point Queries and Indexes

Use a geospatial element child index to index geospatial data in JSON when you want to limit the index to coordinate properties contained in a specific property. The geospatial data must be represented in the child property value as either whitespace/punctuation separated values in a string, or as an array of values.

For example, if your data looks like one of the following, you could create a geospatial element child index specifying "theParent" as the parent element (property) and "theChild" as the child element (property).

"theParent": {
  "theChild": "37.52 -122.25"
}
"theParent": {
  "theChild": [37.52, -122.25]
}

By default, the first coordinate is the latitude value, and the second coordinate is the longitude value. You can override the default order by specifying a longitude-first ordering when creating queries and indexes. The property value can include other entries, but they are ignored (for example, KML has an additional altitude coordinate, which can be present but is ignored).

You can use the following interfaces to create a geospatial JSON property child query:

com.marklogic.client.query.StructuredQueryBuilder.geoJSONProperty
  and
com.marklogic.client.query.StructuredQueryBuilder.geospatial

You can use the following interfaces to create an index for a geospatial JSON property child query. Note you should create a geospatial element child index, even though you are indexing JSON content.

Geospatial JSON Property Pair Point Queries and Indexes

Use a geospatial element pair index to index geospatial data in JSON when the point coordinates are contained in sibling JSON properties. For example, use this type of index when working with data similar to the following:

"theParent" : {
  "latitude": 37.52,
  "longitude": -122.25
}

You can use the following interfaces to create a geospatial JSON property pair query:

com.marklogic.client.query.StructuredQueryBuilder.geoJSONPropertyPair
  and
com.marklogic.client.query.StructuredQueryBuilder.geospatial 

You can use the following interfaces to create an index for a geospatial JSON property pair query. Note you should create a geospatial element pair index, even though you are indexing JSON content.

Geospatial Region Queries and Indexes

Use a geospatial region path index to index geospatial regions, such as polygons, rather than points. A geospatial region path index supports operations such as the cts:geospatial-region-query XQuery function and the cts.geospatialRegionQuery JavaScript function. These functions enable you to test for relationships between regions, such as overlaps and contains.

Region indexes over geodetic coordinate systems are based on geohashing. Geohashes of circles are calculated by approximating the circle by a polygon. The approximation is accurate to within 0.001% of the radius of the circle. If you require more precision, use geo:circle-polygon to convert circles in your data.

When working with large circular regions, you might need to adjust the tolerance in your geospatial operations. For details, see Understanding Tolerance.

The path expression with which you define a region index is limited to a subset of XPath for performance reasons. For details, see Path Field and Path-Based Range Index Configuration in the XQuery and XSLT Reference Guide.

The content referenced by the path expression in a geospatial region index must be a region represented as either WKT or a serialized cts:region. For example:

XML

<a:data>
  <a:region>POLYGON ((30 10, 40 40, 20 40, 10 20, 30 10))</a:region>
</a:data>

/a:data/a:region

XML

<a:data>
  <a:loc region="POLYGON ((30 10, 40 40, 20 40, 10 20, 30 10))"/>
</a:data>

/a:data/a:loc/@region

JSON

{ "location" : {
    "region": "POLYGON ((30 10, 40 40, 20 40, 10 20, 30 10))"
  }
}

/location/region

If your data is not in the expected format, you can use an envelope pattern to encapsulate your original data along with a supported format. For more details, see Example: Using the Envelope Pattern to Encode Regions.

You can use the following interfaces to create a geospatial region path query. For more details, see Searching for Matching Regions.

com.marklogic.client.query.StructuredQueryBuilder.geoRegionPath
  and
com.marklogic.client.query.StructuredQueryBuilder.geospatial

You can use the following interfaces to create a geospatial region path index.

Geospatial Index Positions

Each geospatial point index has a range value positions option. Enabling range value positions speeds up queries that constrain a search by the distance between geospatial data and other search terms in a document, such as when using cts:near-query in XQuery or cts.nearQuery in Javascript.

Additionally, enabling element positions improves index resolution (more accurate estimates) for XML element and JSON property queries that involve geospatial point queries (with a geospatial index with positions enabled for the geospatial data).

Geospatial Lexicons

Geospatial point indexes enable geospatial lexicon lookups. The lexicon lookups enable very fast retrieval of geospatial values. For details on geospatial lexicons, see Geospatial Lexicons.

Index Reference Resolution

Many geospatial operations either require or will take advantage of available geospatial indexes. Depending on the operation, the index reference might be explicit or implicit. For example, if you supply a cts:reference to an operation, the index reference is explicit. By contrast, when you supply an XPath expression, XML element QName, or JSON property name to a query constructor, the index reference is implicit.

Often, an index reference doesn't fully specify the characteristics of an index. For example, if you create a region path query and specify no options, you've only supplied the type of index (geospatial region path index) and the path. You have not explicitly specified the coordinate system, precision, or point type. Thus, they implicitly default to wgs84, single, and point, respectively.

MarkLogic attempts to resolve an index reference from the information in the call, including options, plus the defaults. If this is sufficient to identify a unique index, that index will be used. If it is not, an error is raised.

For example, suppose you create a geospatial region index on the path /coordinates, with coordinate-system and precision wgs84/double. If you then construct a region query on the path /coordinates and specify the option coordinate-system=wgs84, the precision is implicitly single precision, which will not match the only available index. You will get a XDMP-GIDXNOTFOUND error.

Similarly, suppose you create one geospatial region index on the path /coordinates, with coordinate-system and precision wgs84/double and another on the same path with wgs84 (single precision). If you then create a region path query on /coordinates and do not specify the coordinate system, the index reference is ambiguous and you will get a XDMP-GIDXAMBIGUOUS error.

Point Search Overview

A point query finds documents containing one or more points that match search criteria regions. The search criteria regions can be points, circles, linestrings, polygons, or any other cts region type. (To find matching regions, rather than points, see Searching for Matching Regions).

The following are key features of searching with point queries:

• A point matches a criteria region if it is contained in the region.
• You can use options to control whether or not the criteria region boundaries should be considered in the match. Boundaries are included by default.
• You can use point queries with the same search framework as other kinds of queries, such as cts:search, cts.search, jsearch.documents, search:search, or the Client APIs.
• You can use a point query by itself or as a component of a more complex query, such as a cts:and-query (XQuery) or cts.andQuery (JavaScript).
• You can construct a geospatial point query using an XQuery or JavaScript query constructor, by parsing query text, or using the REST, Java, or Node.js Client APIs.
• Creating appropriate geospatial point indexes can improve speed and accuracy.

  Indexes are required for certain kinds of queries, such as range queries. Indexes are optional for queries such as value queries, but only if you use unfiltered search. For details, see Fast Pagination and Unfiltered Searches in the Query Performance and Tuning Guide.

For example, the following search uses an element child geospatial query to match documents containing at least one point in the circle with center (37.5073428,-122.2465038) and radius 1 mile. The circle criteria region is constructued using the cts:circle XQuery function or cts.circle JavaScript function.

xquery version "1.0-ml";
cts:search(fn:collection("geo-example"),
  cts:element-child-geospatial-query(
    fn:QName("http://www.opengis.net/kml/2.2", "Point"),
    fn:QName("http://www.opengis.net/kml/2.2", "coordinates"),
    cts:circle(1, cts:point(37.5073428,-122.2465038)),
    ("type=long-lat-point")
  )
)//*:name/fn:data()

(: returns just the names of the matched places :)

import * as jsearch from '/MarkLogic/jsearch.mjs';
const geoSamples = jsearch.collections('geo-example');
const matchedPlaces = [];

geoSamples.documents()
  .where(cts.elementChildGeospatialQuery(
    fn.QName('http://www.opengis.net/kml/2.2', 'Point'),
    fn.QName('http://www.opengis.net/kml/2.2', 'coordinates'),
    cts.circle(1, cts.point(37.5073428,-122.2465038)),
    ['type=long-lat-point']
  ))
  .result().results.forEach(function(result) {
    // extract just the names of the matched places
    matchedPlaces.push(
      result.document.xpath('//*:name/fn:data()'))
  });
matchedPlaces

(The above queries were written for sample documents containing KML geospatial data, so an element child query is used to confine matches to coordinates in KML <Point/> elements. The long-lat point type is used because KML coordinates are expressed in longitude-first order.)

The MarkLogic APIs also include geospatial utility functions useful for constructing criteria and analyzing search matches. For example, you can use the geo:region-contains XQuery function or the geo.regionContains JavaScript function to test whether one region contains another. The utility functions are usable with in-memory geospatial data, as well as data in documents in the database. For details, see Summary of Other Geospatial Operations.

Example: Point Query Using XQuery

This example uses XQuery to demonstrate the following type of point queries:

• Find documents containing this point
• Find documents containing points in this region

For an equivalent Server-Side JavaScript example, see Example: Point Query Using JavaScript. The example assumes the data and database configuration from Preparing to Run the Examples.

The sample data is XML documents containing KML data of the following form. For more details on the sample documents, see Overview of the Sample Data.

<envelope>
  <Placemark xmlns="http://www.opengis.net/kml/2.2">
    <name>MarkLogic HQ</name>
    <Point>
      <coordinates>-122.2465038,37.5073428</coordinates>
    </Point>
  </Placemark>
</envelope>

The example uses cts:element-child-geospatial-query to find matches in coordinates element of a KML Point element. Limiting the scope to coordinates in a Point element prevents false positives from the documents containing other kinds of regions. For example:

cts:element-child-geospatial-query(
      fn:QName("http://www.opengis.net/kml/2.2", "Point"),
      fn:QName("http://www.opengis.net/kml/2.2", "coordinates"),
      cts:point(37.5073428, -122.2465038), 
      ("type=long-lat-point")

The query includes the type=long-lat-point option because KML uses longitude-first coordinate order while the default in MarkLogic is latitude-first ("type=point").

The database configuration includes a corresponding geospatial element child index on kml:Point/kml:coordinates with long-lat point type.

The following code performs one search for documents containing the coordinates of the MarkLogic headquarters (cts:point(37.5073428, -122.2465038)) and one search for documents containing points in the MarkLogic Neighborhood polygon. The polygon coordinates are extracted from one of the sample documents, but you could also construct them inline.

xquery version "1.0-ml";

(: Find docs containing a point that matches another point.
 : The criteria point corresponds to the MarkLogic HQ feature :)
let $point-matches :=
  cts:search(fn:collection("geo-xml-examples"),
    cts:element-child-geospatial-query(
      fn:QName("http://www.opengis.net/kml/2.2", "Point"),
      fn:QName("http://www.opengis.net/kml/2.2", "coordinates"),
      cts:point(37.5073428, -122.2465038), 
      ("type=long-lat-point")
    )
  )
(: Find docs containing a point contained in a region. The
 : MarkLogic Neighborhood polygon is used as the criteria region. :)
let $region-matches :=
  cts:search(fn:collection("geo-xml-examples"),
    cts:element-child-geospatial-query(
      fn:QName("http://www.opengis.net/kml/2.2", "Point"),
      fn:QName("http://www.opengis.net/kml/2.2", "coordinates"),
      fn:doc("/geo-examples/MarkLogic-Neighborhood.xml")//cts-region, 
      ("type=long-lat-point")
    )
  )
(: Format results for display in QC :)
return (
  fn:concat("Features containing the cirteria point: ", 
            fn:string-join($point-matches//*:name/data(), ", ")),
  fn:concat("Features containing points in the criteria region: ", 
            fn:string-join($region-matches//*:name/data(), ", "))
)

If you run this query in Query Console, it produces output similar to the following:

Features containing the cirteria point: MarkLogic HQ
Features containing points in the criteria region: 
   Restaurant, Museum, MarkLogic HQ

You can compose complex queries by combining geospatial queries with other query types. For example, the following code matches documents that contains points within a circle and that also contain the word MarkLogic:

cts:search(fn:collection("geo-xml-examples"),
  cts:and-query((
    cts:word-query("MarkLogic"),
    cts:element-child-geospatial-query(
      fn:QName("http://www.opengis.net/kml/2.2", "Point"),
      fn:QName("http://www.opengis.net/kml/2.2", "coordinates"),
      cts:circle(1, cts:point(37.5073428,-122.2465038)),
      ("type=long-lat-point")
    )
  ))
)//*:name/data()

Though the previous examples only searched the XML sample documents, you can apply a geospatial query to either XML or JSON documents, or both. For example, the following code searches both the XML and JSON sample documents by combining two geospatial queries in an OR query. (The point search criteria matches the MarkLogic HQ feature in the sample documents.)

let $matches :=
  cts:search(fn:collection("geo-examples"),
    cts:or-query((
      cts:path-geospatial-query(
        'geometry[type = "Point"]/array-node("coordinates")',
        cts:point(37.5073428, -122.2465038),
        ('type=long-lat-point')
      ),
      cts:element-child-geospatial-query(
        fn:QName('http://www.opengis.net/kml/2.2', 'Point'),
        fn:QName('http://www.opengis.net/kml/2.2', 'coordinates'),
        cts:point(37.5073428, -122.2465038), 
        ('type=long-lat-point')
      )
    ))
  )
return
  for $match in ($matches) 
  return xdmp:node-uri($match)

Running this query in Query Console produces the following output:

/geo-examples/MarkLogic-HQ.json
/geo-examples/MarkLogic-HQ.xml

Example: Point Query Using JavaScript

This example uses Server-Side JavaScript to demonstrate the following type of point queries:

• Find documents containing this point
• Find documents containing points in this region

For an equivalent XQuery example, see Example: Point Query Using XQuery. This example assumes the data and database configuration from Preparing to Run the Examples.

The sample data includes JSON documents containing GeoJSON data of the following form. For more details on the sample documents, see Overview of the Sample Data.

{ "envelope": {
  "feature": {
    "type": "Feature", 
    "geometry": {
      "type": "Point", 
      "coordinates": [ -122.2465038, 37.5073428 ]
    }, 
    "properties": { "name": "MarkLogic HQ" }
} } }

The example uses cts.pathGeospatialQuery to find matching documents. You must use a path query for point queries on GeoJSON for the reasons described in Geospatial Data in the Application Developer's Guide. The following path addresses the coordinates array of a point feature in the sample documents:

geometry[type = "Point"]/array-node("coordinates")

Thus, the core of the search is a path query of the following form. The query includes the type=long-lat-point option because GeoJSON uses longitude-first coordinate order while the default in MarkLogic is latitude-first ("type=point").

cts.pathGeospatialQuery(
  'geometry[type = "Point"]/array-node("coordinates")',
  cts.circle(0.25, cts.point(37.5073428, -122.2465038)), 
  ("type=long-lat-point")
)

The database configuration must include a corresponding geospatial path index. The instructions in Preparing to Run the Examples include creating a suitable index.

The following code uses the JSearch API to perform 2 searches: one search for documents containing a point (cts.point(37.5073428, -122.2465038)), and one for documents containing points in a region. The region coordinates are extracted from one of the sample documents for convenience, but you could also construct the region inline using a geospatial constructor such as cts.polygon.

'use strict';
import * as jsearch from '/MarkLogic/jsearch.mjs';
const geoSamples = jsearch.collections('geo-examples');

// Find docs containing a point that matches another point.
// The criteria point corresponds the MarkLogic HQ feature.
const pointMatches =
  geoSamples.documents().where(
    cts.pathGeospatialQuery(
      'geometry[type = "Point"]/array-node("coordinates")',
      cts.point(37.5073428, -122.2465038), 
      ("type=long-lat-point")
    )
  ).map(desc => desc.document.envelope.feature.properties.name)
  .result();
const regionMatches =
  geoSamples.documents().where(
    cts.pathGeospatialQuery(
      'geometry[type = "Point"]/array-node("coordinates")',
      fn.head(fn.doc('/geo-examples/MarkLogic-Neighborhood.json'))
        .toObject().envelope.ctsRegion,
      ["type=long-lat-point"]
    )
  ).map(desc => desc.document.envelope.feature.properties.name)
  .result();

// Format the results for display.
const results = 'Features containing the cirteria point: ' 
  + pointMatches.results.join(", ")
  + '\nFeatures containing points in the criteria region: '
  + regionMatches.results.join(', ');
results;

If you run this query in Query Console, it produces output similar to the following:

Features containing the cirteria point: MarkLogic HQ
Features containing points in the criteria region: 
   Restaurant, Museum, MarkLogic HQ

Note that a lambda expression and the map method are used to extract just the feature names from the matched documents:

geoSamples.documents()
    .where(...)
    .map(desc => desc.document.envelope.feature.properties.name)
    .result();

This is a contrivance used to keep the example output brief. If you remove the map call, the search returns a Sequence of document descriptors that include the full document. For more details, see Creating JavaScript Search Applications.

You can also use cts.search to perform an equivalent search. For example:

// Find docs containing a point that matches another point.
// The criteria point corresponds the MarkLogic HQ feature.
const pointMatches =
  cts.search(
    cts.andQuery([
      cts.collectionQuery('geo-json-examples'),
      cts.pathGeospatialQuery(
        'geometry[type = "Point"]/array-node("coordinates")',
        cts.point(37.5073428, -122.2465038), 
        ('type=long-lat-point')
    )
    ])
  );
// Find docs containing points contained in a region. The MarkLogic
// Neighborhood polygon is used as the criteria to be matched.
const regionMatches =
  cts.search(
    cts.andQuery([
      cts.collectionQuery('geo-json-examples'),
      cts.pathGeospatialQuery(
        'geometry[type = "Point"]/array-node("coordinates")',
        fn.head(fn.doc('/geo-examples/MarkLogic-Neighborhood.json'))
          .toObject().envelope.ctsRegion,
        ['type=long-lat-point']
      )
    ])
  );

// Format the results for display.
const results = 'Features containing the cirteria point: ';
const featureNames = [];
for (let doc of pointMatches) {
  featureNames.push(doc.toObject().envelope.feature.properties.name);
}
results += featureNames.join(', ');

results += '\nFeatures containing points in the criteria region: ';
featureNames = [];
for (let doc of regionMatches) {
  featureNames.push(doc.toObject().envelope.feature.properties.name);
}
results + featureNames.join(', ');

You can include multiple criteria in a single query; when you do so, encapsulate the criteria in an array. For example, you could search for matches to both the point and the region with a query such as the following. A document matches if it matches any one of the criteria

cts.andQuery([
  cts.collectionQuery('geo-json-examples'),
  cts.pathGeospatialQuery(
    'geometry[type = "Point"]/array-node("coordinates")',
    [cts.point(37.5073428, -122.2465038), 
     fn.head(fn.doc('/geo-examples/MarkLogic-Neighborhood.json'))
       .toObject().envelope.ctsRegion],
    ['type=long-lat-point']
) ])

Since the MarkLogic HQ feature document satisfies both cirteria and the Museum and Restaurant feature documents satisfy the region criteria, the above query matches the Restaurant, Museum, and MarkLogic HQ features.

You can compose complex queries by combining geospatial queries with other query types. Notice that the above cts.search example search uses a cts.andQuery to combine the geospatial path query with a collection query that constrains the search to the JSON documents in the sample set.

To include the XML sample documents in the search, add a cts.elementChildGeospatialQuery on the KML data. For example, the following query finds documents containing the MarkLogic HQ coordinates in either the XML or JSON sample documents, and prints out the URIs of the matched documents:

'use strict';
import * as jsearch from '/MarkLogic/jsearch.mjs';
const geoSamples = jsearch.collections('geo-examples');

geoSamples.documents().where(
  cts.orQuery([
    cts.pathGeospatialQuery(
      'geometry[type = "Point"]/array-node("coordinates")',
      cts.point(37.5073428, -122.2465038),
      ['type=long-lat-point']
    ),
    cts.elementChildGeospatialQuery(
      fn.QName('http://www.opengis.net/kml/2.2', 'Point'),
      fn.QName('http://www.opengis.net/kml/2.2', 'coordinates'),
      cts.point(37.5073428, -122.2465038), 
      ['type=long-lat-point']
    )
  ])
).map(desc => desc.uri)
 .result().results;

Running the above query in Query Console, produces the following output:

["/geo-examples/MarkLogic-HQ.json", 
 "/geo-examples/MarkLogic-HQ.xml"]

Constructing a Point Query in XQuery

This section is a quick reference of available XQuery geospatial point query constructors. These functions create a cts:query object. For an equivalent JavaScript reference, see Constructing a Point Query in JavaScript. To create geospatial queries from query text, see Constructing a Point Query from Query Text.

Use the following functions to construct a point query. Select the query constructor that corresponds to the type of region and layout of the data to be searched, as described in Understanding Geospatial Query and Index Types. You can use these constructors with each other and with other cts:query constructors to build up complex queries.

• cts:element-attribute-pair-geospatial-query
• cts:element-child-geospatial-query
• cts:element-geospatial-query
• cts:element-pair-geospatial-query
• cts:json-property-child-geospatial-query
• cts:json-property-geospatial-query
• cts:json-property-pair-geospatial-query
• cts:path-geospatial-query

Every query constructor includes parameters that identify the content to search, either by path, name, or index reference; and one or more geospatial values to match. For example:

cts:element-geospatial-query(
  xs:QName("feature"),                         (: element to search :)
  cts:circle(20, cts:point(37.65, -122.42))    (: criteria :)
)

A geospatial query is constrained to the XML elements, XML attributes, and JSON properties identified in the query constructor. To cross multiple formats in a single search, use cts:or-query to combine multiple geospatial queries.

For a complete example, see Example: Point Query Using XQuery. For more details about constructing geospatial search criteria, see Constructing Geospatial Point and Region Values and Converting To and From Common Geospatial Representations.

Constructing a Point Query in JavaScript

This section is a quick reference of available Server-Side JavaScript geospatial point query constructors. These functions create a cts.query object. For an equivalent XQuery reference, see Constructing a Point Query in XQuery. To create geospatial queries from query text, see Constructing a Point Query from Query Text.

The following JavaScript geospatial query constructors are available. You can use these constructors with each other and with other cts:query constructors to build up complex queries. Select the query constructor that corresponds to the type of region and layout of the data to be searched, as described in Understanding Geospatial Query and Index Types.

• cts.elementAttributePairGeospatialQuery
• cts.elementChildGeospatialQuery
• cts.elementGeospatialQuery
• cts.elementPairGeospatialQuery
• cts.jsonPropertyChildGeospatialQuery
• cts.jsonPropertyGeospatialQuery
• cts.jsonPropertyPairGeospatialQuery
• cts.pathGeospatialQuery

Every query constructor includes parameters that identify the content to search, either by path, name, or index reference; and one or more geospatial values to match. For example:

cts.elementGeospatialQuery(
  "feature",                                   // element to search
  cts.circle(20, cts.point(37.65, -122.42))    // criteria
)

A geospatial query is constrained to the XML elements, XML attributes, and JSON properties identified in the query constructor. To cross multiple formats in a single search cts.orQuery to combine multiple geospatial queries.

For a complete example, see Example: Point Query Using XQuery. For more details about constructing geospatial search criteria, see Constructing Geospatial Point and Region Values.

Constructing a Point Query from Query Text

You can use the cts:parse XQuery function or the cts.parse JavaScript function to create a geospatial point query from query text. The parse creates a cts query object. This grammar is only supported by the cts parser; the grammar used by search:search or search:resolve does not support geospatial terms.

The cts parse grammar supports search terms expressing points, circles, boxes, polygons, and other regions, bound a geospatial index reference. For details, see Binding to a Geospatial Index Reference.

The following example queries create a geospatial element child query over KML point coordinates. The bindings define the interpretation of the poi (point of interest) tag as a reference to a geospatial element child index. The query text @1 -122.2465038,37.5073428 represents a circle with radius 1 mile (the default units) and center (37.5073428, -122.2465038). The query includes the option type=long-lat-point because KML uses longitude-first ordering for points, while the MarkLogic default ordering is latitude-first.

xquery version "1.0-ml";
let $bindings := map:map()
let $_ := map:put(
  $bindings, "poi", 
  cts:geospatial-element-child-reference(
    fn:QName("http://www.opengis.net/kml/2.2", "Point"),
    fn:QName("http://www.opengis.net/kml/2.2", "coordinates"),
    ("type=long-lat-point")
  ) )
return 
  cts:parse('poi:"@1 -122.2465038,37.5073428"', $bindings)

const bindings = {
  'poi': cts.geospatialElementChildReference(
    fn.QName("http://www.opengis.net/kml/2.2", "Point"),
    fn.QName("http://www.opengis.net/kml/2.2",
             "coordinates"),
    ["type=long-lat-point"])
};
cts.parse('poi:"@1 -122.2465038,37.5073428"', bindings);

The parse produces a cts query similar to the following:

cts:element-child-geospatial-query(
  fn:QName("http://www.opengis.net/kml/2.2","Point"), 
  fn:QName("http://www.opengis.net/kml/2.2","coordinates"), 
  cts:circle("@1 -122.2465,37.507343"), 
  ("type=long-lat-point"), 1)

cts.elementChildGeospatialQuery(
  [fn.QName("http://www.opengis.net/kml/2.2","Point")],
  [fn.QName("http://www.opengis.net/kml/2.2","coordinates")],
  cts.circle("@1 -122.2465,37.507343"),
  ["type=long-lat-point"], 1)

For more details, see Creating a Query From Search Text With cts:parse.

Creating Point Queries with the Client APIs

The REST, Java, and Node.js Client APIs expose geospatial queries through the use of structured queries and query builders, rather than through standalone query constructor functions.

The following topics provide examples of using a point query from the Client APIs:

• Java Client API
• Node.js Client API

You can also use a serialized cts query or a structured query with the Node.js, Java, or REST Client APIs and Search API functions such as search:resolve. See the following topics for details on including a point query in a structured query:

• geo-elem-query
• geo-elem-pair-query
• geo-attr-pair-query
• geo-path-query
• geo-json-property-query
• geo-json-property-pair-query

DatabaseClient client = ...;
QueryManager qm = client.newQueryManager();
StructuredQueryBuilder sqb = qm.newStructuredQueryBuilder();
...
sqb.geoElement(
  sqb.element(new QName("http://www.opengis.net/kml/2.2", "Point")),
  sqb.element(
    new QName("http://www.opengis.net/kml/2.2", "coordinates"))),
...

package examples;

import com.marklogic.client.DatabaseClient;
import com.marklogic.client.DatabaseClientFactory;
import com.marklogic.client.io.SearchHandle;
import com.marklogic.client.query.MatchDocumentSummary;
import com.marklogic.client.query.QueryManager;
import com.marklogic.client.query.StructuredQueryBuilder;
import com.marklogic.client.query.StructuredQueryBuilder.FragmentScope;
import com.marklogic.client.query.StructuredQueryDefinition;

import javax.xml.namespace.QName;


public class GeoPointQuery {
    public static void main(String[] args) {
public static void main(String[] args) {
    // MODIFY THIS CALL TO MATCH YOUR ENV
    DatabaseClient client = DatabaseClientFactory.newClient(
        hostname, port, databaseName,
        new DatabaseClientFactory.DigestAuthContext(
            username, password));

    QueryManager qm = client.newQueryManager();
    StructuredQueryBuilder sqb = qm.newStructuredQueryBuilder();
    SearchHandle results = new SearchHandle();
    StructuredQueryDefinition query = sqb.geospatial(
        sqb.geoElement(
            sqb.element(new QName("http://www.opengis.net/kml/2.2",
                        "Point")),
            sqb.element(new QName("http://www.opengis.net/kml/2.2",
                        "coordinates"))),
        FragmentScope.DOCUMENTS, 
        new String[] {"type=long-lat-point"},
        sqb.circle(37.507, -122.246, 0.25));
    qm.search(query, results);
    for (MatchDocumentSummary match : results.getMatchResults()) {
        System.out.println(match.getUri());
    }

    client.release();
}
}

/geo-examples/MarkLogic-HQ.xml

const marklogic = require('marklogic');

// MODIFY THIS VAR TO MATCH YOUR ENV
const connInfo = {
    host: 'localhost',
    port: 8000,
    user: username,
    password: password,
    database: 'Documents'
  };
const db = marklogic.createDatabaseClient(connInfo);
const qb = marklogic.queryBuilder;

db.documents.query(
  qb.where(
    qb.geospatial(
      qb.geoElement(
        qb.qname('http://www.opengis.net/kml/2.2', 'Point'),
        qb.qname('http://www.opengis.net/kml/2.2', 'coordinates')),
      qb.fragmentScope('documents'),
      qb.geoOptions('type=long-lat-point'),
      qb.circle(0.25, qb.latlon(37.507, -122.246))
   ))
).result( function(results) {
  for (let result of results) {
    console.log(result.uri);
  }
});

/geo-examples/MarkLogic-HQ.xml

Creating Geospatial Facets

Faceted navigation of search results enables users to filter large or complex search results by properties of the data. For example, filter a list of clothing items by size, color, and material. One technique for faceting the results of a point query is to define geospatial boxes that enclose the matched points.

If you divide a geospatial box into a grid of boxes, you can bucket matched points by the sub-divisions. Each subdivision represents a facet.

For example, the following diagram plots a series of matched points on a 5x5 grid.

You can use the number of points in each box and the box extent with mapping APIs like Google Maps to generate a heat map from the search results.

You can generate such geospatial facet data using the cts:*-geospatial-boxes XQuery functions and the cts.*GeospatialBoxes Server-Side JavaScript functions, such as cts:element-geospatial-boxes or cts.elementGeospatialBoxes. You can use the cts:frequency XQuery function or the cts.frequency JavaScript function to compute the number of points in each box.

The XQuery Search API, JavaScript jsearch API, and the Client APIs an equivalent capability at a higher level of abstraction through the heatmap component of a geospatial constraint definition.

All of these interfaces enable you to define the extent of the box over which to generate facets, and the latitudes and longitudes of the subdivisions.

You can also control whether the returned facet box extents are based on an even grid or the minimum bounding box that encompasses the points in a given bucket, as shown in the following diagram. By default, MarkLogic generates the minimum bounding boxes. Use the gridded option to override the default.

The following diagram illustrates the difference between gridded and non-gridded faceting:

The following XQuery example generates geospatial facets and their counts cts:element-pair-geospatial-boxes:

xquery version "1.0-ml";

(: compute even divisions between two coordinates :)
declare function local:compute-divs($coord1, $coord2, $ndivs)
as xs:double*
{
  let $bound-size := abs(($coord1 - $coord2) div $ndivs)
  let $start := if ($coord2 < $coord1) then $coord2 else $coord1
  return 
    for $count in (1 to $ndivs)
    return ($start + ($count - 1) * $bound-size)
};

(: box dimensions :)
let $n := 49.0
let $s := 24.0
let $e := -67.0
let $w := -125.0

(: number of latitude and longitude divisions for facet bucketing :)
let $n-lat-divs := 5
let $n-lon-divs := 5

(: query with which to constrain points to facet :)
let $query := cts:and-query((
  cts:element-range-query(xs:QName("magnitude"), ">", 7),
  cts:element-pair-geospatial-query(
      xs:QName("quake"), xs:QName("lat"), xs:QName("long"),
      cts:box($s, $w, $n, $e))
))

(: facet the matching points :)
let $boxes := cts:element-pair-geospatial-boxes(
  xs:QName("quake"), xs:QName("lat"), xs:QName("long"),
  local:compute-divs($n, $s, $n-lat-divs),
  local:compute-divs($e, $w, $n-lon-divs),
  "gridded",
  $query)

(: count the points in each facet :)
let $counts := cts:frequency($boxes)
return for $i in (1 to fn:count($boxes))
  return (fn:subsequence($boxes, $i, 1), 
          fn:subsequence($counts, $i, 1))

For the Server-Side JavaScript jsearch API, use jsearch.makeHeatMap with FacetDefinition.groupInto to define geospatial facets. For details, see Grouping Values and Facets Into Buckets.

For the XQuery SearchAPI and the client APIs, use the heatmap component of a geospatial constraint query option. In these interfaces, you need only specify the faceting box extent and the number of latitude and longitude divisions in the heatmap component. The underlying API computes the grid, the facet boxes, and the counts for you. For example:

<options xmlns="http://marklogic.com/appservices/search">
  <constraint name="geo">
    <geo-elem-pair> 
      <parent ns="" name="quake"/> 
      <lat ns="" name="lat"/> 
      <lon ns="" name="long"/>
      <heatmap s="24.0" n="49.0" e="-67.0" w="-125.0" 
               latdivs="5" londivs="5" />
      <facet-option>gridded</facet-option>
    </geo-elem-pair>
  </constraint>
  <return-facets>true</return-facets>
</options>

For a more complete example, see Geospatial Constraint Example.

Region Match Overview

A region query matches geospatial regions in your documents against one or more criteria regions. The relationship between the regions that must be satisfied for a match is determined by the operator configured into the query. For example, you can create a query that matches documents containing a region that overlaps or intersects your criteria region(s).

MarkLogic Server does not support region queries using multi-part (WKT/WKB) geometries. Multi-part geometries (MULTI*) include MULTIPOINT, MULTIPOLYGON, and so on. For a list of WKT/WKB geometries, see Mapping of WKT and WKB Types to MarkLogic Types.

To construct a region query, use the XQuery cts:geospatial-region-query function or the JavaScript cts.geospatialRegionQuery function. Region queries require a geospatial region path index.

For example, the following code snippet creates a query the matches documents containing a region the intersects a circle. For a complete example, see Example: Simple Intersection Region Query.

cts:geospatial-region-query(
  cts:geospatial-region-path-reference("/envelope/cts-region"),
  "intersects", 
  cts:circle(0.25, cts:point(37.507343,-122.2465))
)

cts.geospatialRegionQuery(
  cts.geospatialRegionPathReference('/envelope/ctsRegion'),
  'intersects', 
  cts.circle(0.25, cts.point(37.507343,-122.2465))
)

The following are key points about using region queries:

• One region matches another if it satisfies the topological operator configured into the query. You can choose from the following operators: contains, covered-by, covers, crosses, disjoint, equals, intersects, overlaps, within. For details, see cts:geospatial-region-query in the MarkLogic XQuery and XSLT Function Reference or cts.geospatialRegionQuery in the MarkLogic Server-Side JavaScript Function Reference.
• You must define a geospatial region path index on any regions you want to search with a region query. For details, see Geospatial Region Queries and Indexes.
• The regions in your documents must be in WKT or serialized cts:region format. If your data is not in one of these formats, you must transform it to conform. For one possible solution, see Example: Using the Envelope Pattern to Encode Regions.
• You can use a region query with the same search framework as other kinds of queries, such as cts:search, cts.search, jsearch.documents, search:search, or the Client APIs.
• You can use a region query by itself or as a component of a more complex query, such as a cts:and-query (XQuery) or cts.andQuery (JavaScript).
• You can construct a geospatial region query using an XQuery or JavaScript query constructor, by parsing query text, or using the REST, Java, or Node.js Client APIs.
• For best performance, when matching against individual points in your documents, you should usually use a point query rather than a region query.
• For highest accuracy when using a region query to match regions in documents, include only one region per document.

The MarkLogic APIs also include geospatial utility functions useful for constructing criteria and analyzing search matches. For example, you can use the cts:region-contains XQuery function or the cts.region-contains JavaScript function to test whether one region contains another. The utility functions are usable with in-memory geospatial data, as well as data in documents in the database. For details, see Summary of Other Geospatial Operations.

Example: Simple Intersection Region Query

This example depends on the data and configuration in Preparing to Run the Examples.

Run one of the following queries in Query Console to find documents that contain a region that intersects with a polygon. The criteria polygon corresponds to the MarkLogic Neighborhood region in the sample data. The query produces the feature names from the matched documents.

xquery version "1.0-ml";
declare namespace kml="http://www.opengis.net/kml/2.2";

(: This region corresponds to the MarkLogic Neighborhood polygon :)
let $criteria-region := cts:polygon((
  cts:point(37.519087, -122.26346), 
  cts:point(37.521299, -122.24805), 
  cts:point(37.512279, -122.24462), 
  cts:point(37.50336,  -122.24556),
  cts:point(37.506185, -122.25981), 
  cts:point(37.513436, -122.26337), 
  cts:point(37.519087, -122.26346)
))
return cts:search(
  fn:collection("geo-xml-examples"),
  cts:geospatial-region-query(
    cts:geospatial-region-path-reference("/envelope/cts-region"),
    "intersects", $criteria-region
  )
)/envelope/kml:Placemark/kml:name/fn:data()

// This region corresponds to the MarkLogic Neighborhood polygon
const criteriaRegion = cts.polygon([
  cts.point(37.519087, -122.26346), 
  cts.point(37.521299, -122.24805), 
  cts.point(37.512279, -122.24462), 
  cts.point(37.50336,  -122.24556),
  cts.point(37.506185, -122.25981), 
  cts.point(37.513436, -122.26337), 
  cts.point(37.519087, -122.26346)
])

// Perform the search
const results = cts.search(cts.andQuery([
  cts.collectionQuery('geo-json-examples'),
    cts.geospatialRegionQuery(
    cts.geospatialRegionPathReference('/envelope/ctsRegion'),
    'intersects', criteriaRegion
  )
]))

// Iterate over the results, accumulating the feature names in
// an array for convenient display in Query Console.
const matchedRegions = [];
for (let result of results) {
  matchedRegions.push(
    result.toObject().envelope.feature.properties.name)
}
matchedRegions

If you run one of these queries in Query Console, the following feature names should be displayed:

• Holly St
• Wildlife Refuge
• Hwy 101
• Airport
• MarkLogic Neighborhood

You can also work with XML documents in JavaScript and work with JSON documents in XQuery, as shown below. The following example performs the same region search against the opposite document type.

xquery version "1.0-ml";
declare namespace kml="http://www.opengis.net/kml/2.2";

(: This region corresponds to the MarkLogic Neighborhood polygon :)
let $criteria-region := cts:polygon((
  cts:point(37.519087, -122.26346), 
  cts:point(37.521299, -122.24805), 
  cts:point(37.512279, -122.24462), 
  cts:point(37.50336,  -122.24556),
  cts:point(37.506185, -122.25981), 
  cts:point(37.513436, -122.26337), 
  cts:point(37.519087, -122.26346)
))
return cts:search(
  fn:collection("geo-json-examples"),
  cts:geospatial-region-query(
    cts:geospatial-region-path-reference("/envelope/ctsRegion"),
    "intersects", $criteria-region
  )
)/envelope/feature/properties/name

// This region corresponds to the MarkLogic Neighborhood polygon
const criteriaRegion = cts.polygon([
  cts.point(37.519087, -122.26346), 
  cts.point(37.521299, -122.24805), 
  cts.point(37.512279, -122.24462), 
  cts.point(37.50336,  -122.24556),
  cts.point(37.506185, -122.25981), 
  cts.point(37.513436, -122.26337), 
  cts.point(37.519087, -122.26346)
])

// Perform the search
const results = cts.search(cts.andQuery([
  cts.collectionQuery('geo-xml-examples'),
    cts.geospatialRegionQuery(
    cts.geospatialRegionPathReference('/envelope/cts-region'),
    'intersects', criteriaRegion
  )
]))

// Iterate over the results, accumulating the feature names in
// an array for convenient display in Query Console.
const matchedRegions = [];
for (let result of results) {
  matchedRegions.push(fn.head(result.xpath(
    '/envelope/kml:Placemark/kml:name/fn:data()',
    {kml: 'http://www.opengis.net/kml/2.2'})))
}
matchedRegions

Notice that the result processing in JavaScript is significantly different because you cannot handle the matched XML documents as native javascript objects.

The following example searches the combined set of both XML and JSON documents. Notice that you can pass multiple region index references into the geospatial region query constructor. A document satisfies the query if a match is found using any of the indexes.

xquery version "1.0-ml";

(: This region corresponds to the MarkLogic Neighborhood polygon :)
let $criteria-region := cts:polygon((
  cts:point(37.519087, -122.26346), 
  cts:point(37.521299, -122.24805), 
  cts:point(37.512279, -122.24462), 
  cts:point(37.50336,  -122.24556),
  cts:point(37.506185, -122.25981), 
  cts:point(37.513436, -122.26337), 
  cts:point(37.519087, -122.26346)
))
let $matches := cts:search(
  fn:collection("geo-examples"),
  cts:geospatial-region-query(
    (cts:geospatial-region-path-reference("/envelope/cts-region"),
     cts:geospatial-region-path-reference("/envelope/ctsRegion")),
    "intersects", $criteria-region
  )
)
for $doc in $matches order by xdmp:node-uri($doc)
return xdmp:node-uri($doc)

// This region corresponds to the MarkLogic Neighborhood polygon
const criteriaRegion = cts.polygon([
  cts.point(37.519087, -122.26346), 
  cts.point(37.521299, -122.24805), 
  cts.point(37.512279, -122.24462), 
  cts.point(37.50336,  -122.24556),
  cts.point(37.506185, -122.25981), 
  cts.point(37.513436, -122.26337), 
  cts.point(37.519087, -122.26346)
]);

// Perform the search
const results = cts.search(cts.andQuery([
  cts.collectionQuery('geo-examples'),
  cts.geospatialRegionQuery(
    [cts.geospatialRegionPathReference('/envelope/cts-region'),
     cts.geospatialRegionPathReference('/envelope/ctsRegion')],
    'intersects', criteriaRegion
  )
]));

// Accumulate the matched URIs in an array for
// convenient display of brief results in Query Console.
const matchedRegions = [];
for (let result of results) {
  matchedRegions.push(xdmp.nodeUri(result))
}
matchedRegions.sort()

If you run one of these queries in Query Console, it emits the following list of URIs:

/geo-examples/Airport.json
/geo-examples/Airport.xml
/geo-examples/Holly-St.json
/geo-examples/Holly-St.xml
/geo-examples/Hwy-101.json
/geo-examples/Hwy-101.xml
/geo-examples/MarkLogic-Neighborhood.json
/geo-examples/MarkLogic-Neighborhood.xml
/geo-examples/Wildlife-Refuge.json
/geo-examples/Wildlife-Refuge.xml

Example: Using Region Queries in a Composed Query

This example depends on the data and configuration in Preparing to Run the Examples.

You can use geospatial region queries along with other query types to compose more complex queries. For example, the following queries find documents containing a region that intersects with the MarkLogic Neighborhood region, but that do not contain a region that is covered by the MarkLogic Neighborhood region.

xquery version "1.0-ml";
declare namespace kml="http://www.opengis.net/kml/2.2";

(: This region corresponds to the MarkLogic Neighborhood polygon :)
let $criteria-region := cts:polygon((
  cts:point(37.519087, -122.26346), 
  cts:point(37.521299, -122.24805), 
  cts:point(37.512279, -122.24462), 
  cts:point(37.50336,  -122.24556),
  cts:point(37.506185, -122.25981), 
  cts:point(37.513436, -122.26337), 
  cts:point(37.519087, -122.26346)
))
return cts:search(
  fn:collection("geo-example"),
  cts:and-not-query(
    cts:geospatial-region-query(
      cts:geospatial-region-path-reference("/envelope/cts-region"),
       "intersects", $criteria-region
    ),
    cts:geospatial-region-query(
      cts:geospatial-region-path-reference("/envelope/cts-region"),
        "covered-by", $criteria-region
    )
  )
)/envelope/kml:Placemark/kml:name/fn:data()

const criteriaRegion = cts.polygon([
  cts.point(37.519087, -122.26346), 
  cts.point(37.521299, -122.24805), 
  cts.point(37.512279, -122.24462), 
  cts.point(37.50336,  -122.24556),
  cts.point(37.506185, -122.25981), 
  cts.point(37.513436, -122.26337), 
  cts.point(37.519087, -122.26346)
]);

// Perform the search
const results = cts.search(cts.andQuery([
  cts.collectionQuery('geo-example'),
  cts.andNotQuery(
    cts.geospatialRegionQuery(
      cts.geospatialRegionPathReference('/envelope/cts-region'),
       'intersects', criteriaRegion
    ),
    cts.geospatialRegionQuery(
      cts.geospatialRegionPathReference('/envelope/cts-region'),
        'covered-by', criteriaRegion
    )
  )
]));

// Iterate over the results. We accumulate the feature names in
// an array just for convenient display in Query Console.
const matchedRegions = [];
for (let result of results) {
  matchedRegions.push(fn.head(result.xpath(
    '/envelope/kml:Placemark/kml:name/fn:data()',
    {kml: 'http://www.opengis.net/kml/2.2'})))
}
matchedRegions

Query Console displays the following feature names if the query is successful:

Wildlife Refuge
Hwy 101

Constructing a Region Query Using a Constructor

This section demonstrates how to use the constructor functions cts:geospatial-region-query (XQuery) or cts.geospatialRegionQuery (JavaScript) to construct a region query on MarkLogic Server. You can also construct a region query from query text using cts:parse (XQuery) or cts.parse (JavaScript); for details, see Constructing a Region Query from Query Text.

A region query has the following form:

cts:geospatial-region-query(
  $region-index-references,
  $operator,
  $criteria-regions,
  $options,
  $weight)

cts.geospatialRegionQuery(
  [regionIndexReference, ...],
  operator,
  [criteriaRegion, ...],
  [option, ...],
  weight)

The options and weight parameters are optional. You can specify multiple region indexes and multiple criteria regions, which is treated as an implicit OR query. That is, a document matches if it satisfies any of the comparisons.

A region query must be backed by a corresponding geospatial region path index. For more details, see Geospatial Region Queries and Indexes.

For example, the following constructor creates a region query that matches region data located at the XPath /envelope/cts-region the overlap with a circle with center (-122.2465,37.507343) and radius 1 mile.

cts:geospatial-region-query(
  cts:geospatial-region-path-reference("/envelope/cts-region"),
  "overlaps", 
  cts:circle("@1 -122.2465,37.507343"))

cts.geospatialRegionQuery(
  [cts.geospatialRegionPathReference("/envelope/cts-region")],
  "overlaps", 
  cts.circle("@1 -122.2465,37.507343"))

The operator must be a string with one of the following values, corresponding to the DE9-IM predicates.

• contains
• covered-by
• covers
• crosses
• disjoint
• equals
• intersects
• overlaps
• touches
• within

You can construct your criteria regions using region constructors such as the cts:polygon (XQuery) or cts.polygon (JavaScript), the geospatial format conversion functions such as geogml:linestring (XQuery) or geojson.circle (JavaScript), or using WKT or WKB.

A geospatial query is constrained to the XML elements, XML attributes, and JSON properties identified in the query constructor. To cross multiple formats in a single search, use cts:or-query in XQuery or cts.orQuery in JavaScript to combine multiple geospatial queries.

For more details, see the following topics:

• Converting To and From Common Geospatial Representations
• Constructing Geospatial Point and Region Values
• cts:geospatial-region-query in the MarkLogic XQuery and XSLT Function Reference
• http://en.wikipedia.org/wiki/DE-9IM.

Constructing a Region Query from Query Text

You can use the cts:parse XQuery function or the cts.parse JavaScript function to create a geospatial region query from query text. If you bind a tag to a geospatial region path index, then you can use the tag in an expression of the following form in your query text:

boundTag operator criteriaRegion [options]

For example, if reg is the name of a tag bound to a geospatial region index, then the following expression parses to a geospatial region query than matches regions in your documents that overlap with the given polygon

reg DE9IM_OVERLAPS POLYGON((1 1,2 2,0 1,1 1))

The operator must be one of the following. For more details on the operators, see Operators Usable with Geospatial Queries and http://en.wikipedia.org/wiki/DE-9IM.

• DE9IM_CONTAINS
• DE9IM_COVERED_BY
• DE9IM_COVERS
• DE9IM_CROSSES
• DE9IM_DISJOINT
• DE9IM_EQUALS
• DE9IM_INTERSECTS
• DE9IM_OVERLAPS
• DE9IM_TOUCHES
• DE9IM_WITHIN

The following example queries illustrate the tag binding and parsing necessary to search using this query text. The binding specifies the tag reg represents a geospatial region path index reference for the XPath expression /envelope/cts-region. The query text @1 -122.2465038,37.5073428 represents a circle with radius 1 mile (the default units) and center (37.5073428, -122.2465038).

xquery version "1.0-ml";
let $bindings := map:map()
let $_ := map:put(
  $bindings, "reg", 
  cts:geospatial-region-path-reference(
    "/envelope/cts-region")
)
return cts:parse(
  'reg DE9IM_OVERLAPS "@1 -122.2465038,37.5073428"',
  $bindings
)

const bindings = {
  'reg': cts.geospatialRegionPathReference(
    '/envelope/cts-region')
};
cts.parse(
  'reg DE9IM_OVERLAPS "@1 -122.2465038,37.5073428"', 
  bindings);

The parse produces a cts query similar to the following:

cts:geospatial-region-query(
  (cts:geospatial-region-path-reference(
    "/envelope/cts-region",("coordinate-system=wgs84"))
  ), "overlaps", 
  cts:circle("@1 -122.2465,37.507343"), 
  (), 1)

cts.geospatialRegionQuery([
  cts.geospatialRegionPathReference(
      "/envelope/cts-region",
      ["coordinate-system=wgs84"])
    ], 
  "overlaps", 
  cts.circle("@1 -122.2465,37.507343"), 
  [], 1)

For more details, see Creating a Query From Search Text With cts:parse.

Creating Region Queries Using the Client APIs

See the following topics for an overview and example of using a region query in a search in the Client APIs.

• JavaClient API
• Node.js Client API
• REST Client API

DatabaseClient client = ...;
QueryManager qm = client.newQueryManager();
StructuredQueryBuilder sqb = qm.newStructuredQueryBuilder();
...
sqb.geoRegionPath(
    sqb.pathIndex("/envelope/cts-region"), 
    StructuredQueryBuilder.CoordinateSystem.WGS84)
...

package examples;

import com.marklogic.client.DatabaseClient;
import com.marklogic.client.DatabaseClientFactory;
import com.marklogic.client.io.SearchHandle;
import com.marklogic.client.query.MatchDocumentSummary;
import com.marklogic.client.query.QueryManager;
import com.marklogic.client.query.StructuredQueryBuilder;
import com.marklogic.client.query.StructuredQueryBuilder.GeoSpatialOperator;
import com.marklogic.client.query.StructuredQueryDefinition;


public class GeoRegionQuery {
    public static void main(String[] args) {
        // MODIFY THIS CALL TO MATCH YOUR ENV
        DatabaseClient client = DatabaseClientFactory.newClient(
            hostname, port, databaseName,
            new DatabaseClientFactory.DigestAuthContext(
                username, password));

        QueryManager qm = client.newQueryManager();
        StructuredQueryBuilder sqb = qm.newStructuredQueryBuilder();
        SearchHandle results = new SearchHandle();
        
        StructuredQueryDefinition query = sqb.geospatial(
            sqb.geoRegionPath(
                sqb.pathIndex("/envelope/cts-region"), 
                StructuredQueryBuilder.CoordinateSystem.WGS84),
            GeospatialOperator.INTERSECTS, 
            sqb.polygon(
                sqb.point(37.519087, -122.26346),
                sqb.point(37.521299, -122.24805),
                sqb.point(37.512279, -122.24462),
                sqb.point(37.50336,  -122.24556),
                sqb.point(37.506185, -122.25981),
                sqb.point(37.513436, -122.26337),
                sqb.point(37.519087, -122.26346)
                        ));
        qm.search(query, results);
        for (MatchDocumentSummary match : results.getMatchResults()) {
            System.out.println(match.getUri());
        }

        client.release();
    }
}

/geo-examples/Hwy-101.xml
/geo-examples/Holly-St.xml
/geo-examples/Wildlife-Refuge.xml
/geo-examples/Shopping-Center.xml
/geo-examples/MarkLogic-Neighborhood.xml
/geo-examples/Airport.xml

const marklogic = require('marklogic');

// MODIFY THIS VAR TO MATCH YOUR ENV
const connInfo = {
    host: 'localhost',
    port: 8000,
    user: username,
    password: password,
    database: 'Documents'
  };
const db = marklogic.createDatabaseClient(connInfo);
const qb = marklogic.queryBuilder;

db.documents.query(
  qb.where(
    qb.geospatialRegion(
      qb.geoPath('/envelope/ctsRegion', qb.coordSystem('wgs84')),
      'intersects',
      qb.polygon(
        qb.point(37.519087, -122.26346),
        qb.point(37.521299, -122.24805),
        qb.point(37.512279, -122.24462),
        qb.point(37.50336,  -122.24556),
        qb.point(37.506185, -122.25981),
        qb.point(37.513436, -122.26337),
        qb.point(37.519087, -122.26346))
   ))
).result( function(results) {
  for (let result of results) {
    console.log(result.uri);
  }
});

/geo-examples/Hwy-101.json
/geo-examples/Wildlife-Refuge.json
/geo-examples/Holly-St.json
/geo-examples/Airport.json
/geo-examples/Shopping-Center.json
/geo-examples/MarkLogic-Neighborhood.json

<query xmlns="http://marklogic.com/appservices/search">
  <geo-region-path-query coord="wgs84">
    <path-index>/envelope/cts-region</path-index>
    <geospatial-operator>intersects</geospatial-operator>
    <polygon>
      <point>
        <latitude>37.519087</latitude><longitude>-122.26346</longitude>
      </point>
      <point>
        <latitude>37.521299</latitude><longitude>-122.24805</longitude>
      </point>
      <point>
        <latitude>37.512279</latitude><longitude>-122.24462</longitude>
      </point>
      <point>
        <latitude>37.50336</latitude><longitude>-122.24556</longitude>
      </point>
      <point>
        <latitude>37.506185</latitude><longitude>-122.25981</longitude>
      </point>
      <point>
        <latitude>37.513436</latitude><longitude>-122.26337</longitude>
      </point>
      <point>
        <latitude>37.519087</latitude><longitude>-122.26346</longitude>
      </point>
    </polygon>
  </geo-region-path-query>
</query>

curl --anyauth --user user:password -X POST -i \
  -d @./body.xml -H "Content-type: application/xml" \
  'http://localhost:8000/v1/search'

/geo-examples/Hwy-101.xml
/geo-examples/Holly-St.xml
/geo-examples/Wildlife-Refuge.xml
/geo-examples/Shopping-Center.xml
/geo-examples/MarkLogic-Neighborhood.xml
/geo-examples/Airport.xml

{"query": {
  "geo-region-path-query": {
    "path-index": { "text": "/envelope/cts-region" },
    "coord": "wgs84",
    "geospatial-operator": "intersects",
    "polygon": [
      { "point": [
        { "latitude": 37.519087, "longitude": -122.26346 },
        { "latitude": 37.521299, "longitude": -122.24805 },
        { "latitude": 37.512279, "longitude": -122.24462 },
        { "latitude": 37.50336,  "longitude": -122.24556 },
        { "latitude": 37.506185, "longitude": -122.25981 },
        { "latitude": 37.513436, "longitude": -122.26337 },
        { "latitude": 37.519087, "longitude": -122.26346 }
      ] }
    ]
  }
}}

curl --anyauth --user user:password -X POST -i \
  -d @./body.json -H "Content-type: application/json" \
  'http://localhost:8000/v1/search'

Example: Using the Envelope Pattern to Encode Regions

Content you search with a region query must be in WKT or serialized cts:region format. This example illustrates using the envelope pattern to encapsulate the searchable region format with original data in an incompatible format. This is not the only solution to this problem. For example, you can tranform your content before ingesting it into MarkLogic, or you can replace the unsupported original format entirely, rather than persisting both.

The example reads in a file from the file system that contains an aggregate XML element contains a several KML Placemark elements. The data is disaggregated into one file per Placemark, and then each Placmark is wrapped in an envelope that contains both the original data and the serialized representation of a cts:region that corresponds to the region in the original data.

For example, if the original input file has the following structure:

<kml xmlns="http://www.opengis.net/kml/2.2">
  <Placemark>
    <name>Hwy 101</name>
    <description>...</description>
    <LineString>
      <extrude>0</extrude>
      <tessellate>1</tessellate>
      <altitudeMode>clampedToGround</altitudeMode>
      <coordinates>
        -122.2637558,37.5206187 -122.2428131,37.5020318
      </coordinates>
    </LineString>
  </Placemark>
  <Placemark>...</Placemark>
  ...
</kml>

Then the result is one document per Placemark, with the following structure. The envelope root element and the cts-region element are created by the ingest transformation.

<envelope>
  <cts-region>LINESTRING(-122.26376 37.520619,-122.24281 37.502032)</cts-region>
  <Placemark xmlns="http://www.opengis.net/kml/2.2">
    <name>Hwy 101</name>
    <description>...</description>
    <LineString>
      <extrude>0</extrude>
      <tessellate>1</tessellate>
      <altitudeMode>clampedToGround</altitudeMode>
      <coordinates>
        -122.2637558,37.5206187 -122.2428131,37.5020318
      </coordinates>
    </LineString>
  </Placemark>
<envelope>

The following example query ingests the original data and creates a document from the envelope it wraps around each Placemark:

xquery version "1.0-ml";
import module namespace geokml = "http://marklogic.com/geospatial/kml"
         at "/MarkLogic/geospatial/kml.xqy";
declare namespace kml="http://www.opengis.net/kml/2.2";

(: Convert the KML regions into cts regions :)
declare function local:region-convert(
  $nodes as node()*
) as cts:region*
{
  for $n in $nodes return
  typeswitch($n)
    case element(kml:Polygon) return geokml:parse-kml($n)
    case element(kml:LineString) return geokml:parse-kml($n)
    case element(kml:Point) return ()
    default return local:region-convert($n/node())
};

(: Create a doc for each KML Placemark, with a wrapper around
 : the KML that contains the cts region equiv of the KML region :)
let $file := xdmp:document-get("/space/geo/ml2.xml")
return
  for $place in $file//*:Placemark
  let $basename := fn:string-join(fn:tokenize($place/*:name, " "),"-")
  return xdmp:document-insert(
    fn:concat("/example/",$basename,".xml"),
    <envelope>{
     let $converted-region := local:region-convert($place)
     return if (fn:empty($converted-region)) 
       then ()
       else <cts-region>{$converted-region}</cts-region>
    }
    {$place}
    </envelope>,
    xdmp:default-permissions(), "geo-example")

Points are not translated by the above example simply because it was not necessary for this purpose. You can index and use point queries on in KML points without transformation. You only need to transform them if you want to use a region query on point data.

The Relationship Between Precision and Coordinate System

The coordinate system and precision are conflated in the coordinate system name in many operations that accept a coordinate system name as input.

For example, when you specify wgs84 as the value of the coordinate-system option in a query constructor, it also implicitly specifies single precision. Similarly, a value of wgs84/double specifies both the WGS84 coordinate system and double precision.

In many interfaces, you can use a precision option or parameter to override the precision implied by the coordinate system name.

Determining the Best Precision for Your Application

MarkLogic always preserves the precision of geospatial data in your documents. For example, if you ingest documents containing double precision coordinate values, those values retain full precision, even if the governing coordinate system during ingestion specifies single precision.

However, the precision of values in a geospatial index is determined by the configuration of the index. Thus, you might have double precision values in your documents, but single precision values in the corresponding geospatial index.

A double precision index enables a greater degree of accuracy when computing geospatial search matches, but at the cost of increased memory requirements and some computational overhead.

Greater precision does not equate to greater accuracy. Most applications do not require double precision indexing.

For example, geospatial queries against single precision indexes are accurate to within 1 meter for geodetic coordinate systems. If your application does not require sub-meter accuracy, then there is no reason to incur the overhead of a double precision index.

The following are examples of geospatial applications that might require double precision:

• Tracking equipment moving around a facility.
• Tracking room-to-room movements within a building.
• Tracking slow-moving objects that move in sub-meter increments, such as fault lines and tectonic plates.
• Tracking assets that require high placement precision, such on which side of a street a fire hydrant is located.

Excessive precision can cause difficulty for geospatial operations. For example, when comparing two points at double precision, they will fail a test for equality if the coordinate values differ when compared at the level of microns. Most applications would consider such a difference in the noise and consider these points the same. Comparison of double-precision coordinates assumes a tolerance of zero by default, meaning they must match exactly, at all digits of precision. This affects operations such as comparison of points, testing whether a point is on a edge, and testing two edges for adjacency. You can use the tolerance option available on some operations to enable less precise comparisons. For more details, see Understanding Tolerance.

An application can use a mix of single and double precision geospatial indexes and operations. For example, you can define both a single and a double precision index over the same data. You can specify precision per operation.

You can control geospatial precision in the following ways:

• Specify float or double precision when creating a geospatial point or region index. This determines the precision of values stored in the index. For details, see Determining the Best Precision for Your Application.
• Configure an App Server default precision. This specifies the precision to use in geospatial queries and computations when no other precision override is in effect. The default is single (float) precision. For details, see Specifying the App Server Default Coordinate System.
• In XQuery, you can specify a default precision for a main module. This overrides the App Server default precision. For details, see Specifying the Per-Module Coordinate System.
• Specify precision on an operation, such as when constructing a geospatial query, computing a distance, or accessing the coordinates of a box. This overrides the App Server and module default precision. For details, see Specifying a Per-Operation Coordinate System and Precision.

You can specify precision in conjunction with the coordinate system name in most MarkLogic geospatial interfaces. For example, the wgs84 and raw coordinate system names imply single precision, while the wgs84/double and raw/double coordinate system names specify double precision.

How MarkLogic Selects the Governing Coordinate System

When MarkLogic evaluates your XQuery or Server-Side JavaScript code, the governing coordinate system is the first of the following settings found. For more details, see The Governing Coordinate System.

• Per-operation coordinate system option or parameter
• Per-module coordinate system, as specified by the XQuery xdmp:coordinate-system prolog option. (This feature is only available in XQuery main modules.)
• App Server default coordinate system

If you specify a precision using the precision option of an operation, the specified precision always takes precedence over the precision implied by the governing coordinate system name.

The following examples illustrate the governing coordinate system applied in several calling contexts if the App Server default coordinate system is wgs84.

(: app server default is wgs84 :)
xquery version "1.0-ml";
<wrapper>
  <wgs84>{   (: app server default coord-sys :)
    geo:distance(cts:point(1.0,1.0), cts:point(2.0,2.0))
  }</wgs84>
  <wgs84d>{  (: per-operation coord-sys :)
    geo:distance(cts:point(1.0,1.0), cts:point(2.0,2.0), 
                 ("coordinate-system=wgs84/double"))
  }</wgs84d>
  <raw>{     (: per-op coord-sys, with precision override :) 
    geo:distance(cts:point(1.0,1.0), cts:point(2.0,2.0),
                 ("coordinate-system=raw/double",
                  "precision=float"))
  }</raw>
</wrapper>

(: produces:
  <wrapper>
    <wgs84>97.4783192326097</wgs84>
    <wgs84-d>97.4783199874495</wgs84-d>
    <raw>1.4142135623731</raw>
  </wrapper>
:)

(: app server default is wgs84 :)
xquery version "1.0-ml";
declare option xdmp:coordinate-system "raw";
<wrapper>
  <raw>{     (: per module coord-sys :)
    geo:distance(cts:point(1.0,1.0), cts:point(2.0,2.0))
  }</raw>
  <wgs84d>{  (: per-operation coord-sys :)
    geo:distance(cts:point(1.0,1.0), cts:point(2.0,2.0), 
                 ("coordinate-system=wgs84/double"))
  }</wgs84d>
  <wgs84>{   (: per-op coord-sys, with precision override :) 
    geo:distance(cts:point(1.0,1.0), cts:point(2.0,2.0),
                 ("coordinate-system=wgs84/double",
                  "precision=float"))
  }</wgs84>
</wrapper>

(: produces:
  <wrapper>
    <raw>1.4142135623731</raw>
    <wgs84d>97.4783199874495</wgs84d>
    <wgs84>97.4783192326097</wgs84>
  </wrapper>
:)

const result = {
  wgs84:    // app server default coord-sys
    geo.distance(cts.point(1.0,1.0), cts.point(2.0,2.0)),
  wgs84d:   // op specific coord-sys
    geo.distance(cts.point(1.0,1.0), cts.point(2.0,2.0), 
                 ['coordinate-system=wgs84/double']),
  raw:      // op specific coord-sys w precision override
    geo.distance(cts.point(1.0,1.0), cts.point(2.0,2.0), 
                 ['coordinate-system=raw/double',
                  'precision=float'])
};
result

/* produces:
  { "wgs84":97.4783192326097, 
    "wgs84d":97.4783199874495, 
    "raw":1.4142135623731
  }

 */

See the following topics for instructions on setting the coordinate system and precision at various levels:

• Specifying the App Server Default Coordinate System
• Specifying the Per-Module Coordinate System
• Specifying a Per-Operation Coordinate System and Precision

Probing the Governing Coordinate System Name

You can probe the governing coordinate system using the XQuery function geo:default-coordinate-system or the JavaScript function geo.defaultCoordinateSystem. (This function can only account for the App Server default and per-module settings.)

The following examples illustrate how to retrieve the name of the governing coordinate system.

xquery version "1.0-ml";
geo:default-coordinate-system();
(: returns the app server default coordinate system :)

xquery version "1.0-ml";
declare option xdmp:coordinate-system "wgs84/double";
geo:default-coordinate-system();
(: returns the per-module setting, wgs84/double :)

geo.defaultCoordinateSystem();

// returns the app server default coordinate system

Specifying the App Server Default Coordinate System

You can use the following Admin library functions to set and get the default coordinate system/precision combination for an App Server. If you do not explicitly set the coordinate system and precision, it is wgs84 (single precision).

• admin:appserver-set-coordinate-system
• admin:appserver-get-coordinate-system

For example, the following XQuery code sets the default coordinate system for the App Server named MyAppServer to wgs84/double.

xquery version "1.0-ml";
import module namespace admin = "http://marklogic.com/xdmp/admin" 
  at "/MarkLogic/admin.xqy";

let $config := admin:get-configuration()
let $groupid := admin:group-get-id($config, "Default")
return admin:save-configuration(
  admin:appserver-set-coordinate-system(
    $config, 
    admin:appserver-get-id($config, $groupid, "MyAppServer"), 
    "wgs84/double")
)

You can also use the XQuery Admin library module from Server-Side JavaScript. The following example is equivalent to the previous XQuery code.

const admin = require('/MarkLogic/admin');
const config = admin.getConfiguration();
const groupId = admin.groupGetId(config, 'Default');
admin.saveConfiguration(
  admin.appserverSetCoordinateSystem(
    config, 
    admin.appserverGetId(config, groupId, 'MyAppServer'), 
    'wgs84/double')
)

To determine the canonical name for a coordinate system/precision combination, use the XQuery function geo:coordinate-system-canonical or the JavaScript function geo.coordinateSystemCanonical.

For more details, see the XQuery and XSLT Reference Guide.

Specifying the Per-Module Coordinate System

In XQuery, you can use the xdmp:coordinate-system prolog option to override the App Server default coordinate system module-wide. This option is only available in XQuery. For example:

declare option xdmp:coordinate-system "wgs84/double";

The override only takes effect when you declare the option in an XQuery main module, but it affects any library module functions subsequently invoked from that main module.

REST, Java, and Node.js Client API resource extensions are library modules, so you cannot override the coordinate system in your extension implementation. Use the ad-hoc query (eval or invoke) of the Client APIs or a per-operation override if you need to override the App Server default with these APIs.

For example, if you create a library function that just returns the result of calling geo:default-coordinate-system, then the following main module will return wgs84/double for the coordinate system.

xquery version "1.0-ml";
import module namespace my = "http://marklogic.com/example/my-lib"
  at "/my/lib.xqy";

declare option xdmp:coordinate-system "wgs84/double";
my:get-coord-sys()

Specifying a Per-Operation Coordinate System and Precision

Many geospatial operations accept options for specifying the coordinate system and/or precision. A per-operation specification overrides the governing coordinate system. For example:

(: xquery :)
geo:distance(
  cts:point(1.0,1.0), cts:point(2.0,2.0), 
  ("coordinate-system=wgs84", "precision=double"))

(: javascript :)
geo.distance(
  cts.point(1.0,1.0), cts.point(2.0,2.0), 
  ['coordinate-system=wgs84', 'precision=double'])

Where both the coordinate-system and precision options are supported, you can specify the precision either as part of the coordinate system canonical name or independently. Where there is a conflict between the precision in the coordinate system name and the precision option, the precision option takes precedence.

The following example illustrates how the option settings interact:

coordinate-system=wgs84/double

wgs84/double

coordinate-system=wgs84
precision=double

wgs84/double

coordinate-system=wgs84/double
precision=float

You can get the canonical name for a coordinate system/precision combination using the XQuery function geo:coordinate-system-canonical or the JavaScript function geo.coordinateSystemCanonical.

Specifying Coordinate System During Index Creation

You can choose single or double precision when creating a geospatial index. This determines the precision of the values stored in the index. For example, you can create a single precision index over your geospatial data even if the data in your documents is double precision.

Specify precision during index creation through the coordinate system name. You can use the XQuery function geo:coordinate-system-canonical or the JavaScript function geo.coordinateSystemCanonical to generate the canonical name of the desired coordinate system and precision combination.

For example, the following code creates a geospatial element index for double precision wgs84 point values:

xquery version "1.0-ml";
import module namespace admin = "http://marklogic.com/xdmp/admin" 
  at "/MarkLogic/admin.xqy";

let $config := admin:get-configuration()
let $dbid := xdmp:database("Documents")
let $geo-index-spec := admin:database-geospatial-element-index(
  "/my/namespace", "elementname", 
  geo:coordinate-system-canonical("wgs84", "double"), 
  fn:false() )
return admin:save-configuration(
  admin:database-add-geospatial-element-index(
    $config, $dbid, $geo-index-spec)
)

const admin = require('/MarkLogic/admin');

const config = admin.getConfiguration()
const dbid = xdmp.database('Documents')
const geoIndexSpec = admin.databaseGeospatialElementIndex(
  '/my/namespace', 'elementName', 
  geo.coordinateSystemCanonical('wgs84', 'double'), 
  false)
admin.saveConfiguration(
  admin.databaseAddGeospatialElementIndex(config, dbid, geoIndexSpec)
)

For more details on geospatial indexes, see Understanding Geospatial Query and Index Types.

How Tolerance Affects Geometric Comparisons

Tolerance defines the largest acceptable error when comparing two points for equality.

For example, a tolerance of zero means two points only match if they're exactly the same, out to the least significant digit. Thus, two points separated by a distance measurable in microns would not match. If you're trying to determine whether a truck is parked at the door of a building, such a high degree of precision is a hindrance. Use tolerance to filter out differences that are in the noise.

The following diagram illustrates how tolerance affects point comparison. A, B, and C are points. The shaded circle describes the space within which points are considered equal to A, based on the tolerance. Point B falls within tolerance of A, so A and B are considered equal. Point C is further from A than the tolerance allows, so A and C are not considered equal.

When comparing edges, a point is considered as lying on the edge if the distance from the point to the edge is within the tolerance.

For example, in the following diagram, any point in the two circles coincides with an endpoint of the edge. Any point within the center region lies on the edge. Thus, point A coincides with an endpoint and point B lies on the edge. Point C is outside the the tolerance range, so it is not considered to lie on the edge.

Operations such as computing whether two polygons intersect require comparing two edges. Two edges overlap if both endpoints of one edge lie on the other, or if an endpoint of each edge lies on the other.

For example, the following diagram illustrates the effect of two different tolerance values on determining overlap. The circles represent the tolerance of each endpoint. With the smaller tolerance, the edges do not overlap. With the larger tolerance, both endpoints of one edge are within tolerance of the other edge, so the edges overlap.

Considerations for Tolerance Selection

If you do not explicitly set tolerance, MarkLogic uses the default tolerance appropriate for the coordinate system.

To ensure accuracy, MarkLogic enforces a minimum tolerance for each coordinate system. If tolerance is too precise, then the calculation of distance might not be accurate to the specified level of precision.

You cannot choose a tolerance value less than zero.

For most operations, MarkLogic interprets a tolerance of zero as the minimum tolerance for the coordinate system. The only exceptions are the XQuery function geo:bounding-boxes and the JavaScript function geo.boundingBoxes, as follows:

When computing bounding boxes, a non-zero tolerance causes the bounding boxes to be padded by the tolerance amount. This ensures the bounding box covers the thickened boundary of the region under consideration. If you set tolerance to zero when computing bounding boxes, then the bounding boxes are not padded at all.

When considering a polygon, tolerance effectively thickens the boundary of the polygon. If you set the tolerance too high relative to the size of the polygon, the polygon degenerates. This can result in unexpected results or errors.

You can use the XQuery geo:region-approximate or the Server-Side JavaScript function geo.regionApproximate to simply your region(s) before performing geometric computations. The simplification can sometimes help you balance tolerance against polygon degneration.

Geospatial computational and comparison operations that do not accept a tolerance option behave as if tolerance is set to zero.

Conversion Overview

You can use MarkLogic APIs to convert to and from the following common geospatial representations:

• Well-Known Text (WKT)
• Well-Known Binary (WKB)
• GML
• KML
• GeoJSON
• GeoRSS

For example, the following XQuery code uses geogml:parse-gml to convert a GML region into a cts:region (a polygon in this case). This function determines the output cts:region type from the kind of input GML region.

import module namespace geogml ="http://marklogic.com/geospatial/gml"
  at "/MarkLogic/geospatial/gml.xqy";

geogml:parse-gml(
  <gml:Polygon srsName="ML:wgs84"
      xmlns:gml="http://www.opengis.net/gml/3.2">
    <gml:exterior>
      <gml:LinearRing>
        <gml:posList srsDimension="2">
          5.0 1.0 8.0 1.0 8.0 6.0 5.0 7.0 5.0 1.0
        </gml:posList>
      </gml:LinearRing>
    </gml:exterior>
  </gml:Polygon>
)

If you know the input region type, you can also use one of the region-specific constructors to perform the equivalent conversion. For example, the above code could use geogml:polygon instead of geogml:parse-gml. For details, see Constructing Geospatial Point and Region Values.

The following Server-Side JavaScript code converts a GeoJSON polygon into a cts.polygon:

// Create a cts.polygon from a GeoJSON polygon
const geojson = require('/MarkLogic/geospatial/geojson.xqy');

geojson.polygon(
  { type: 'Polygon', 
    coordinates: [
      [[100.0,0.0], [101.0, 0.0], [101.0, 1.0], [100.0, 1.0], [100.0, 0.0]]
  ] }
)

For each format, the XQuery API includes a parse-format function for converting from the common representation to a MarkLogic geospatial primitive type, and the JavaScript API includes a parseFormat function for the same purpose. This operation is equivalent to calling the geo:parse XQuery function or the geo.parse JavaScript function with input of the same format. The API also includes a to-format XQuery function and toFormat JavaScript function for converting from a MarkLogic primitive type to the target format.

For example, the GeoJSON library module includes the following functions that can be used to convert data between GeoJSON and cts:region.

You can use the built-in geo:parse XQuery function or geo.parse JavaScript function to convert nodes in any of the supported formats into an equivalent MarkLogic geospatial primitive type, without regard to the input format or region type. For best performance, if you know the format, use the equivalent format-specific functions.

WKT and WKB Conversions in XQuery

MarkLogic represents geospatial data using the cts:region type and types derived from it, such as cts:point, cts:polygon, and cts:circle. You can convert from WKT or WKB into cts:region items and from cts:region into WKT or WKB.

Use the geo:parse-wkt function to convert WKT data into a sequence of cts:region items. Similarly, use geo:parse-wkb to convert WKB data into a sequence of cts:region items. You can use the resulting items in geospatial cts:query constructors or geospatial operations.

For example, the following call converts a WKT polygon with an inner and outer boundary into a cts:complex-polygon:

geo:parse-wkt("
 POLYGON(
  (0 0, 0 10, 10 10, 10 0, 0 0),
  (0 5, 0 7, 5 7, 5 5, 0 5) )" )

The input to geo:parse-wkb is a binary node that contains a WKB byte sequence. For example, the following code converts a WKB byte sequence representing the coordinates (-73.700380647, 40.739754168) into a cts:point:

geo:parse-wkb(
  binary { "010100000072675909D36C52C0E151BB43B05E4440" }
)

To convert from cts:region to WKT, use geo:to-wkt. For example, the following code returns a WKT POINT:

geo:to-wkt(cts:point(1, 2))

Similarly, the following code returns a WKB POINT:

geo:to-wkb(cts:point(1, 2))

You cannot convert a cts:circle or a cts:box to WKT. For more details on WKT, see http://en.wikipedia.org/wiki/Well-known_text.

WKT and WKB Conversions in JavaScript

MarkLogic represents geospatial data using the cts.region type and types derived from it, such as cts.point, cts.polygon, and cts.circle. MarkLogic provides the following conversions between WKT or WKB and cts.region: You can use the cts.region representation cts:query constructors or geospatial operations.

• Explict conversion from WKT or WKB to cts.region using the geo.parseWkt function. For example:

  // Convert WKT polygon into a cts.complexPolygon
  geo.parseWkt(
    'POLYGON((0 0, 0 10, 10 10, 10 0, 0 0),(0 5, 0 7, 5 7, 5 5, 0 5))'
  )
  
  // Convert WKB bye sequence representing the coordinates
  // (-73.700380647, 40.739754168) into a cts.point
  geo.parseWkb(
    new NodeBuilder()
      .addBinary('010100000072675909D36C52C0E151BB43B05E4440')
      .toNode()
  )

• Explicit converstion from cts.region to WKT or WKB using the geo.toWkt or geo.toWkb functions. For example:

  // cts.point to WKT
  geo.toWkt(cts.point(1, 2))
  
  // cts.point to WKB
  geo.toWkb(cts.point(1, 2))

• Implicit conversion from WKT to cts.region where the expected type is a cts.region. For example:

  // create a cts.polygon from WKT via implicit conversion
  cts.polygon('POLYGON ((30 10, 40 40, 20 40, 10 20, 30 10))')

Note that geo.parseWkt and geo.toWkt return a Sequence rather than an array or a single value. The input to geo.parseWkb is a binary node that contains a WKB byte sequence.

The supported conversions from WKT to cts.region mean all the following calls pass the same cts.polygon value to geo.polygonContains, which returns true.:

// Use a cts.polygon created from a set of cts.point values
geo.polygonContains(
  cts.polygon([
    cts.point(30,10), cts.point(40,40), cts.point(20,40),
    cts.point(10,30), cts.point(30,10)]),
  cts.point(25,25))

// Use a cts.polygon created by explicitly converting from WKT
geo.polygonContains(
  geo.parseWkt('POLYGON ((30 10, 40 40, 20 40, 10 20, 30 10))'),
  cts.point(25,25))

// Use a cts.polygon created by implicitly converting from WKT
geo.polygonContains(
  cts.polygon('POLYGON ((30 10, 40 40, 20 40, 10 20, 30 10))'),
  cts.point(25,25))

You cannot convert a cts.circle or a cts.box to WKT. For more details on WKT, see http://en.wikipedia.org/wiki/Well-known_text.

Mapping of WKT and WKB Types to MarkLogic Types

The following table shows how the WKT and WKB types map to the MarkLogic geospatial types. That is, the equivalent value type resulting from calling the geo:parse-wkt XQuery function or geo.parseWkt JavaScript function, or the WKB equivalents.

Overview of the Sample Data

The sample data contains points, linestrings, and polygons associated with landmarks near the MarkLogic headquarters. The following diagram approximates the relative positions of the features in the sample data.

This geospatial data is made available in two formats: KML (XML) and GeoJSON. Each document describes a single point or a region. The points and regions are the same in the two types of documents (XML and JSON). For example, the documents /geo-examples/Airport.xml and /geo-examples/Airport.json describe the same region.

The documents are added to the following collections to make it easy to select the type of data to work with just XML, just JSON, or both formats.

Each document uses the envelope pattern to encapsulate the original KML or GeoJSON region coordinates with a serialized cts region that is suitable for use with cts:geospatial-region-query. The unprocessed KML input is a single XML file that contains a series of KML Placemark elements. The following data snippet shows the structure of the raw input:

<kml xmlns="http://www.opengis.net/kml/2.2">
<Folder>
  <Placemark>
    <name>Hwy 101</name>
    <LineString>
      <extrude>0</extrude>
      <tessellate>1</tessellate>
      <coordinates>
        -122.2637558,37.5206187 -122.2428131,37.5020318
      </coordinates>
    </LineString>
  </Placemark>
  <Placemark>...</Placemark>
  ...
</Folder>
</kml>

The ingestion process splits the input into one document per Placemark. The envelope pattern is used to encapsulate the original Placemark with an equivalent serialized cts:region if the Placemark represents a non-point region. Region queries only operate on regions expressed as WKT or serialized cts:regions, so you cannot query the Placemark coordinates directly. (Point regions are left untranslated for convenience in demonstrating point queries; you could choose to treat them the same way.)

The following examples shows the final document format, with the envelope root element and the cts-region element created by the ingest transformation. If a Placemark represents a point, then no cts-region element is added because it is not needed.

<envelope>
  <cts-region>LINESTRING(-122.26376 37.520619,-122.24281 37.502032)</cts-region>
  <Placemark xmlns="http://www.opengis.net/kml/2.2">
    <name>Hwy 101</name>
    <LineString>
      <extrude>0</extrude>
      <tessellate>1</tessellate>
      <coordinates>
        -122.2637558,37.5206187 -122.2428131,37.5020318
      </coordinates>
    </LineString>
  </Placemark>
<envelope>

The GeoJSON data receives similar treatment. The raw input is a feature collection. Ingestion creates one document per feature. The envelope pattern is used to encapsulate each feature with an equivalent serialized cts:region to facilitate queries. Point regions are not transformed.

For example, the raw GeoJSON input has the following structure:

{ "type": "FeatureCollection",
  "features": [
    { "type": "Feature",
      "geometry": {
        "type": "Point", 
        "coordinates": [-122.2465038,37.5073428]},
      "properties": {"name": "MarkLogic HQ"}
    },
    { "type": "Feature", ...},
    ...
  ]
} 

Ingestion produces documents of the following form. For documents containing a region, the ingestion transformation adds the envelope wrapper and a ctsRegion. For documents containing a point, the ingestion transformation just adds the envelope wrapper.

{ "envelope": {
  "feature": {
    "type": "Feature", 
    "geometry": {
      "type": "LineString", 
      "coordinates": [...]
    }
    "properties": { "name": "Holly St" } }, 
  "ctsRegion": "LINESTRING(...))"
} }

You can thus use region queries on /envelope/cts-region (XML) or /envelope/ctsRegion (JSON) and point queries on /envelope/kml:Placemark/Point/coordinates (XML) or geometry[type = 'Point']/array-node('coordinates') (JSON).

Configuring the Indexes

This section walks through configuring a point index and a region index over the XML and JSON samples documents, for a total of 4 indexes. Separate indexes are used for each data set to showcase a variety of indexes and to make it easy to focus on one content type or the other.

Point indexes are optional for some types of geospatial point queries, but required for geospatial point range queries and lexicon operations. An index is usually recommended for best performance.

Geospatial region queries always required an index.

You can skip over indexes related to content that does not interest you. For example, you can skip the XML-related indexes if you are only interested in JSON. However, some examples in this chapter may not work properly without the related indexes.

Choose one of the following methods to create the indexes.

• Creating Indexes Using the Admin Interface
• Creating the Indexes with XQuery
• Creating the Indexes with JavaScript

You can also create indexes using the REST Management API. This method is not included here. For details, see the MarkLogic REST API Reference.

Creating the Input Data Files

Follow the instructions in this section to create two files containing the raw XML and JSON sample data. These files are used by the procedure in Loading the Sample Data. Create both files, unless you plan to skip the examples involving one document format.

• Creating the XML Input File
• Creating the JSON Input File

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
  <Placemark>
    <name>MarkLogic HQ</name>
    <description></description>
    <Point>
      <altitudeMode>clampedToGround</altitudeMode>
      <coordinates>-122.2465038,37.5073428</coordinates>
    </Point>
  </Placemark>
  <Placemark>
    <name>Restaurant</name>
    <description></description>
    <Point>
      <altitudeMode>clampedToGround</altitudeMode>
      <coordinates>-122.2581983,37.5128407</coordinates>
    </Point>
  </Placemark>
  <Placemark>
    <name>Hiller Aviation Museum</name>
    <description></description>
    <Point>
      <altitudeMode>clampedToGround</altitudeMode>
      <coordinates>-122.2527051,37.5128917</coordinates>
    </Point>
  </Placemark>
  <Placemark>
    <name>Hwy 101</name>
    <description>Length: 2.775 km (1.724 mi)</description>
    <visibility>1</visibility>
    <open>0</open>
    <LineString>
      <extrude>0</extrude>
      <tessellate>1</tessellate>
      <altitudeMode>clampedToGround</altitudeMode>
      <coordinates>
        -122.2637558,37.5206187 -122.2428131,37.5020318
      </coordinates>
    </LineString>
  </Placemark>
  <Placemark>
    <name>Holly St</name>
    <description>Length: 1.384 km (0.86 mi)</description>
    <visibility>1</visibility>
    <open>0</open>
    <LineString>
      <extrude>0</extrude>
      <tessellate>1</tessellate>
      <altitudeMode>clampedToGround</altitudeMode>
      <coordinates>
        -122.2598934,37.5096578 -122.2551727,37.5148321
        -122.2536278,37.5172148 -122.2523403,37.5185083
        -122.2520828,37.5202102
      </coordinates>
    </LineString>
  </Placemark>
  <Placemark>
    <name>Wildlife Refuge</name>
    <description>Length: 3.104 km (1.929 mi)</description>
    <visibility>1</visibility>
    <open>0</open>
    <Polygon>
      <extrude>0</extrude>
      <tessellate>1</tessellate>
      <altitudeMode>clampedToGround</altitudeMode>
      <outerBoundaryIs>
        <LinearRing>
          <coordinates>
            -122.2428131,37.5173510 -122.2468472,37.5131641
            -122.2422123,37.5069683 -122.2356892,37.5102365
            -122.2384787,37.5154788 -122.2428131,37.5173510
          </coordinates>
        </LinearRing>
      </outerBoundaryIs>
    </Polygon>
  </Placemark>
  <Placemark>
    <name>MarkLogic Neighborhood</name>
    <description>Length: 5.591 km (3.474 mi)</description>
    <visibility>1</visibility>
    <open>0</open>
    <styleUrl>#track</styleUrl>
    <Polygon>
      <extrude>0</extrude>
      <tessellate>1</tessellate>
      <altitudeMode>clampedToGround</altitudeMode>
      <outerBoundaryIs>
        <LinearRing>
          <coordinates>
            -122.2634554,37.5190870 -122.2480488,37.5212994
            -122.2446156,37.5122790 -122.2455597,37.5033596
            -122.2598076,37.5061853 -122.2633696,37.5134364
            -122.2634554,37.5190870
          </coordinates>
        </LinearRing>
      </outerBoundaryIs>
    </Polygon>
  </Placemark>
  <Placemark>
    <name>Shopping Center</name>
    <description>Length: 0.746 km (0.463 mi)</description>
    <visibility>1</visibility>
    <open>0</open>
    <styleUrl>#track</styleUrl>
    <Polygon>
      <extrude>0</extrude>
      <tessellate>1</tessellate>
      <altitudeMode>clampedToGround</altitudeMode>
      <outerBoundaryIs>
        <LinearRing>
          <coordinates>
            -122.2485638,37.5033937 -122.2465038,37.5015552
            -122.2478342,37.5003635 -122.2502375,37.5022020
            -122.2485638,37.5033937
          </coordinates>
        </LinearRing>
      </outerBoundaryIs>
    </Polygon>
  </Placemark>
  <Placemark>
    <name>Airport</name>
    <description>Length: 2.787 km (1.732 mi)</description>
    <visibility>1</visibility>
    <open>0</open>
    <styleUrl>#track</styleUrl>
    <Polygon>
      <extrude>0</extrude>
      <tessellate>1</tessellate>
      <altitudeMode>clampedToGround</altitudeMode>
      <outerBoundaryIs>
        <LinearRing>
          <coordinates>
            -122.2487354,37.5181339 -122.2481775,37.5121769
            -122.2457314,37.5086705 -122.2466755,37.5083982
            -122.2543144,37.5148321 -122.2537994,37.5157171
            -122.2509670,37.5177254 -122.2487354,37.5181339
          </coordinates>
        </LinearRing>
      </outerBoundaryIs>
    </Polygon>
  </Placemark>
</kml>

{ "type": "FeatureCollection",
  "features": [
    { "type": "Feature",
      "geometry": {"type": "Point", "coordinates": [-122.2465038,37.5073428]},
      "properties": {"name": "MarkLogic HQ"}
    },
    { "type": "Feature",
      "geometry": {"type": "Point", "coordinates": [-122.2581983,37.5128407]},
      "properties": {"name": "Restaurant"}
    },
    { "type": "Feature",
      "geometry": {"type": "Point", "coordinates": [-122.2527051,37.5128917]},
      "properties": {"name": "Museum"}
    },
    { "type": "Feature",
      "geometry": {
        "type": "LineString",
        "coordinates": [
          [-122.2637558,37.5206187], [-122.2428131,37.5020318]
        ]
      },
      "properties": { "name": "Hwy 101" }
    },
    { "type": "Feature",
      "geometry": {
        "type": "LineString",
        "coordinates": [
          [-122.2598934,37.5096578], [-122.2551727,37.5148321],
          [-122.2536278,37.5172148], [-122.2523403,37.5185083],
          [-122.2520828,37.5202102]
        ]
      },
      "properties": { "name": "Holly St" }
    },
    { "type": "Feature",
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [-122.2428131,37.5173510], [-122.2468472,37.5131641],
            [-122.2422123,37.5069683], [-122.2356892,37.5102365],
            [-122.2384787,37.5154788], [-122.2428131,37.5173510]
          ]
        ]
      },
      "properties": { "name": "Wildlife Refuge" }
    },
    { "type": "Feature",
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [-122.2634554,37.5190870], [-122.2480488,37.5212994],
            [-122.2446156,37.5122790], [-122.2455597,37.5033596],
            [-122.2598076,37.5061853], [-122.2633696,37.5134364],
            [-122.2634554,37.5190870]
          ]
        ]
      },
      "properties": { "name": "MarkLogic Neighborhood" }
    },
    { "type": "Feature",
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [-122.2485638,37.5033937], [-122.2465038,37.5015552],
            [-122.2478342,37.5003635], [-122.2502375,37.5022020],
            [-122.2485638,37.5033937]
          ]
        ]
      },
      "properties": { "name": "Shopping Center" }
    },
    { "type": "Feature",
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [-122.2487354,37.5181339], [-122.2481775,37.5121769],
            [-122.2457314,37.5086705], [-122.2466755,37.5083982],
            [-122.2543144,37.5148321], [-122.2537994,37.5157171],
            [-122.2509670,37.5177254], [-122.2487354,37.5181339]
          ]
        ]
      },
      "properties": { "name": "Airport" }
    }
  ]
}

Loading the Sample Data

The procedures in this section load the raw data from Creating the Input Data Files into documents of the form discussed in Overview of the Sample Data.

This section uses XQuery to load the XML documents and Server-Side JavaScript to load the JSON documents. You could use either language to load both, but the XML transformations flow more naturally in XQuery, while the JSON transformations flow more naturally in JavaScript.

You can load either or both data sets, but some examples in this chapter will not work if you do not load both. You do not need to be familiar with either XQuery or JavaScript to follow the instructions in this section.

• Loading the XML Sample Data
• Loading the JSON Sample Data