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 class Event
{
    public string Id { get; set; }

    public string Name { get; set; }

    public double Latitude { get; set; }

    public double Longitude { get; set; }
}

public class Events_ByNameAndCoordinates : AbstractIndexCreationTask<Event>
{
    public Events_ByNameAndCoordinates()
    {
        Map = events => from e in events
                        select new
                        {
                            Name = e.Name,
                            Coordinates = CreateSpatialField(e.Latitude, e.Longitude)
                        };
    }
}

public class EventWithWKT
{
    public string Id { get; set; }

    public string Name { get; set; }

    public string WKT { get; set; }
}

public class EventsWithWKT_ByNameAndWKT : AbstractIndexCreationTask<EventWithWKT>
{
    public EventsWithWKT_ByNameAndWKT()
    {
        Map = events => from e in events
                        select new
                        {
                            Name = e.Name,
                            WKT = CreateSpatialField(e.WKT)
                        };
    }
}

private class Events_ByNameAndCoordinates : AbstractJavaScriptIndexCreationTask
{
    public Events_ByNameAndCoordinates()
    {
        Maps = new HashSet<string>
        {
            @"map('events', function (e){
                return { 
                    Name: e.Name  ,
                    Coordinates: createSpatialField(e.Latitude, e.Longitude)
                };                            
            })"
        };

    }
}

Options

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

public class SpatialOptionsFactory
{
    public GeographySpatialOptionsFactory Geography;

    public CartesianSpatialOptionsFactory Cartesian;
}

// GeohashPrefixTree strategy with maxTreeLevel set to 9
SpatialOptions Default(SpatialUnits circleRadiusUnits = SpatialUnits.Kilometers);

SpatialOptions BoundingBoxIndex(SpatialUnits circleRadiusUnits = SpatialUnits.Kilometers);

SpatialOptions GeohashPrefixTreeIndex(int maxTreeLevel, SpatialUnits circleRadiusUnits = SpatialUnits.Kilometers);

SpatialOptions QuadPrefixTreeIndex(int maxTreeLevel, SpatialUnits circleRadiusUnits = SpatialUnits.Kilometers);

SpatialOptions BoundingBoxIndex();

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 class Events_ByNameAndCoordinates_Custom : AbstractIndexCreationTask<Event>
{
    public Events_ByNameAndCoordinates_Custom()
    {
        Map = events => from e in events
                        select new
                        {
                            Name = e.Name,
                            Coordinates = CreateSpatialField(e.Latitude, e.Longitude)
                        };

        Spatial("Coordinates", factory => factory.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