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

public static class Event {
    private String id;
    private String name;
    private double latitude;
    private double longitude;

    public String getId() {
        return id;
    }

    public void setId(String id) {
        this.id = id;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public double getLatitude() {
        return latitude;
    }

    public void setLatitude(double latitude) {
        this.latitude = latitude;
    }

    public double getLongitude() {
        return longitude;
    }

    public void setLongitude(double longitude) {
        this.longitude = longitude;
    }
}

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

public static class EventWithWKT {
    private String id;
    private String name;
    private String wkt;

    public String getId() {
        return id;
    }

    public void setId(String id) {
        this.id = id;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getWkt() {
        return wkt;
    }

    public void setWkt(String wkt) {
        this.wkt = wkt;
    }
}

public static class EventsWithWKT_ByNameAndWKT extends AbstractIndexCreationTask {
    public EventsWithWKT_ByNameAndWKT() {
        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.

public static class SpatialOptionsFactory {
    public GeographySpatialOptionsFactory geography()

    public CartesianSpatialOptionsFactory cartesian()
}

public SpatialOptions defaultOptions()

public SpatialOptions defaultOptions(SpatialUnits circleRadiusUnits)

public SpatialOptions boundingBoxIndex()

public SpatialOptions boundingBoxIndex(SpatialUnits circleRadiusUnits)

public SpatialOptions geohashPrefixTreeIndex(int maxTreeLevel)

public SpatialOptions geohashPrefixTreeIndex(int maxTreeLevel, SpatialUnits circleRadiusUnits)

public SpatialOptions quadPrefixTreeIndex(int maxTreeLevel)

public SpatialOptions quadPrefixTreeIndex(int maxTreeLevel, SpatialUnits circleRadiusUnits)

public SpatialOptions boundingBoxIndex()

public SpatialOptions quadPrefixTreeIndex(int maxTreeLevel, SpatialBounds 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

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

        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