Indexes: Indexing Spatial Data

To support the ability to retrieve the data based on spatial coordinates, the spatial search has been introduced.

Creating Indexes

To take an advantage of the spatial search, first we need to create an index with a spatial field. To mark field as the spatial field, we need to use the CreateSpatialField method:

object CreateSpatialField(double? lat, double? lng);

object CreateSpatialField(string shapeWkt);

Where:

• lat/lng are latitude/longitude coordinates
• shapeWKT is a shape in the WKT format

Example

class Event {
    constructor(id, name, latitude, longitude) {
        this.id = id;
        this.name = name;
        this.latitude = latitude;
        this.longitude = longitude;
    }
}

class Events_ByNameAndCoordinates extends AbstractIndexCreationTask {
    constructor() {
        super();
        this.map = `docs.Events.Select(e => new {     
            name = e.name,     
            coordinates = this.CreateSpatialField(((double?) e.latitude), ((double?) e.longitude)) 
        })`;
    }
}

class EventWithWKT {
    constructor(id, name, wkt) {
        this.id = id;
        this.name = name;
        this.wkt = wkt;
    }
}

class EventsWithWKT_ByNameAndWKT extends AbstractIndexCreationTask {
    constructor() {
        super();

        this.map = `docs.EventWithWKTs.Select(e => new {     
            name = e.name,     
            wkt = this.CreateSpatialField(e.wkt) 
        })`; 
    }
}

Options

RavenDB supports both the Geography and Cartesian systems and multiple strategies for each one of them.

const spatialOptsFactory = new SpatialOptionsFactory();

spatialOptsFactory.geography();

spatialOptsFactory.cartesian();

spatialOptsFactory.geography().defaultOptions([circleRadiusUnits]);
spatialOptsFactory.geography().boundingBoxIndex([circleRadiusUnits]);
spatialOptsFactory.geography().geohashPrefixTreeIndex(maxTreeLevel, [circleRadiusUnits]);
spatialOptsFactory.geography().quadPrefixTreeIndex(maxTreeLevel, [circleRadiusUnits]);

spatialOptsFactory.cartesian().boundingBoxIndex();
spatialOptsFactory.cartesian().quadPrefixTreeIndex(maxTreeLevel, bounds);

Changing Default Behavior

By default, if no action is taken, the GeohashPrefixTree strategy is used with GeohashLevel set to 9. This behavior can be changed by using the spatial method from AbstractIndexCreationTask

class Events_ByNameAndCoordinates_Custom extends AbstractIndexCreationTask {
    constructor() {
        super();

        this.map = "docs.Events.Select(e => new { " +
            "    name = e.name, " +
            "    coordinates = this.CreateSpatialField(((double?) e.latitude), ((double?) e.longitude)) " +
            "})";

        this.spatial("coordinates", f => f.cartesian().boundingBoxIndex());
    }
}

Spatial search strategies

Precision

By default, the precision level (maxTreeLevel) for GeohashPrefixTree is set to 9 and for QuadPrefixTree the value is 23. This means that the coordinates are represented by a 9 or 23 character string. The difference exists because the QuadTree representation would be much less precise if the level would be the same.

Remarks