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

// ...

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.