Indexes: Indexing Spatial Data

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

This article describes how to setup a spatial field in static index. If you are interested in an automatic approach, please visit relevant spatial querying article that can be found here.

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

• Coordinates
• WKT

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)
                      };
  }
}

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;
}

• GeographySpatialOptionsFactory
• CartesianSpatialOptionsFactory

// 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

GeohashPrefixTree

Geohash is a latitude/longitude representation system that describes earth as a grid with 32 cells, assigning an alphanumeric character to each grid cell. Each grid cell is further divided into 32 smaller chunks, and each chunk has an alphanumeric character assigned as well, and so on.

E.g. The location of 'New York' in the United States is represented by the following geohash: DR5REGY6R and it represents the 40.7144 -74.0060 coordinates. Removing characters from the end of geohash will decrease the precision level.

More information about geohash uses, decoding algorithm and limitations can be found here.

QuadPrefixTree

QuadTree represents the earth as a grid with exactly four cells and similarly to geohash, each grid cell (sometimes called a bucket) has a letter assigned, and is divided further into 4 more cells and so on.

More information about QuadTree can be found here.

BoundingBox

More information about BoundingBox can be found here.

GeohashPrefixTree is a default SpatialSearchStrategy. Doing any changes to the strategy after an index has been created will trigger the re-indexation process.

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.

Geohash precision values

Source: unterbahn.com

Level	E-W Distance at Equator	N-S Distance at Equator
12	~3.7cm	~1.8cm
11	~14.9cm	~14.9cm
10	~1.19m	~0.60m
9	~4.78m	~4.78m
8	~38.2m	~19.1m
7	~152.8m	~152.8m
6	~1.2km	~0.61km
5	~4.9km	~4.9km
4	~39km	~19.6km
3	~157km	~157km
2	~1252km	~626km
1	~5018km	~5018km

Quadtree precision values

Level	Distance at Equator
30	~4cm
29	~7cm
28	~15cm
27	~30cm
26	~60cm
25	~1.19m
24	~2.39m
23	~4.78m
22	~9.56m
21	~19.11m
20	~38.23m
19	~76.23m
18	~152.92m
17	~305.84m
16	~611.67m
15	~1.22km
14	~2.45km
13	~4.89km
12	~9.79km
11	~19.57km
10	~39.15km
9	~78.29km
8	~156.58km
7	~313.12km
6	~625.85km
5	~1249km
4	~2473km
3	~4755km
2	~7996km
1	~15992km

Remarks

You can read more about spatial search in a dedicated querying article available here.

Distance by default is measured in kilometers.