Chapter 9. Spatial

When setting the @Spatial.spatialMode attribute to SpatialMode.RANGE (which is the default) coordinates are indexed as numeric fields, so that range queries can be performed to narrow down the initial area of interest.

Pros:

Cons:

To index your entities for range querying you have to:

import org.hibernate.search.annotations.*;

@Entity
@Indexed
@Spatial
public class Hotel {

  @Latitude
  Double latitude

  @Longitude
  Double longitude

  // ...

When setting @Spatial.spatialMode to SpatialMode.HASH the coordinates are encoded in several fields representing different zoom levels. Each box for each level is labeled so coordinates are assigned matching labels for each zoom level. This results in a grid encoding of labels called spatial hashes.

Pros :

Cons :

To index your entities you have to:

@Spatial(spatialMode = SpatialMode.HASH)
@Indexed
@Entity
public class Hotel {

  @Latitude
  Double latitude;

  @Longitude
  Double longitude;

  // ...

Instead of using the @Latitude and @Longitude annotations you can choose to implement the org.hibernate.search.spatial.Coordinates interface.

import org.hibernate.search.annotations.*;
import org.hibernate.search.spatial.Coordinates;

@Entity
@Indexed
@Spatial
public class Song implements Coordinates {

  @Id long id;
  double latitude;
  double longitude;
  // ...

  @Override
  Double getLatitude() {
    return latitude;
  }

  @Override
  Double getLongitude() {
    return longitude;
  }

  // ...

As we will see in the section Section 9.3, “Multiple Coordinate pairs”, an entity can have multiple @Spatial annotations; when having the entity implement Coordinates, the implemented methods refer to the default @Spatial annotation with the default pair of coordinates.

An alternative is to use properties implementing the Coordinates interface; this way you can have multiple Spatial instances:

@Entity
@Indexed
public class Event {
  @Id
  Integer id;

  @Field(store = Store.YES)
  String name;

  double latitude;
  double longitude;

  @Spatial(spatialMode = SpatialMode.HASH)
  public Coordinates getLocation() {
    return new Coordinates() {
      @Override
      public Double getLatitude() {
        return latitude;
      }

      @Override
      public Double getLongitude() {
        return longitude;
      }
    };
  }

// ...

When using this form the @Spatial.name automatically defaults to the property name. In the above case to location.

When Hibernate Search indexes an entity annotated with @Spatial, it instantiates a SpatialFieldBridge to transform the latitude and longitude fields accessed via the Coordinates interface to the multiple index fields stored in the Lucene index.

Principle of the spatial index: the spatial index used in Hibernate Search is a grid based spatial index where grid ids are hashes derived from latitude and longitude.

To make computations easier the latitude and longitude field values will be projected into a flat coordinate system with the help of a sinusoidal projection. Origin value space is :

[-90 → +90],]-180 →; 180]

for latitude,longitude coordinates and projected space is:

]-pi → +pi],[-pi/2 → +pi/2]

for Cartesian x,y coordinates (beware of fields order inversion: x is longitude and y is latitude).

The index is divided into n levels labeled from 0 to n-1.

At the level 0 the projected space is the whole Earth. At the level 1 the projected space is divided into 4 rectangles (called boxes as in bounding box):

[-pi,-pi/2]→[0,0], [-pi,0]→[0,+pi/2], [0,-pi/2]→[+pi,0] and [0,0]→[+pi,+pi/2]

At level n+1 each box of level n is divided into 4 new boxes and so on. The numbers of boxes at a given level is 4^n.

Each box is given an id, in this format: [Box index on the X axis]|[Box index on the Y axis]. To calculate the index of a box on an axis we divide the axis range in 2^n slots and find the slot the box belongs to. At the n level the indexes on an axis are from -(2^n)/2 to (2^n)/2. For instance, the 5th level has 4^5 = 1024 boxes with 32 indexes on each axis (32x32 is 1024) and the box of Id "0|8" is covering the [0,8/32*pi/2]→[1/32*pi,9/32*pi/2] rectangle is projected space.

Beware! The boxes are rectangles in projected space but the related area on Earth is not rectangular!

Now that we have all these boxes at all these levels, we index points "into" them.

For a point (lat,long) we calculate its projection (x,y) and then we calculate for each level of the spatial index, the ids of the boxes it belongs to.

At each level the point is in one and only one box. For points on the edges the box are considered exclusive n the left side and inclusive on the right i-e ]start,end] (the points are normalized before projection to [-90,+90],]-180,+180]).

We store in the Lucene document corresponding to the entity to index one field for each level of the spatial hash grid. The field is named: HSSI[n]. [spatial index fields name] is given either by the parameter at class level annotation or derived from the name of the spatial annotated method of the entity, HSSI stands for Hibernate Search Spatial Index and n is the level of the spatial hashes grid.

We also store the latitude and longitude as a numeric field under [spatial index fields name]_HSSI_Latitude and [spatial index fields name]_HSSI_Longitude fields. They will be used to filter precisely results by distance in the second stage of the search.

Now that we have all these fields, what are they used for?

When you ask for a spatial search by providing a search discus (center+radius) we will calculate the box ids that do cover the search discus in the projected space, fetch all the documents that belong to these boxes (thus narrowing the number of documents for which we will have to calculate distance to the center) and then filter this subset with a real distance calculation. This is called two level spatial filtering.