Spatial Search with Hibernate+Lucene

Lucene is a powerful full-text indexing and query library. It powers many popular web sites like Sourceforge and Wikipedia. With its popularity, Lucene has seen a variety of contributions from developers to add functionality like web crawlers with Solr and machine learning with Mahout.

One of the interesting developments is the addition of the Lucene-spatial module which provides power to perform queries on geo-coded data - for instance, find all coffee shops within 5 miles of your office. In this article, I will attempt to show some of the key points that will enable a typical Hibernate based application to add this piece of functionality.

Let's say we have a Hibernate model as follows:

@Entity
@Table(name = "coffee_shop")
@Indexed
public class CoffeeShop{
  private int id;
  private String name;
  private String address;
  private double lat;
  private double lng;

  //get/set accessors ...

}

This class is using the Hibernate Search's @Indexed annotation to indicate that this class is indexed by Lucene. Each coffee shop has  latitude and longitude information. If you know the address, it is generally fairly easy to derive latitude/longitude information with either online geo-coding services from the likes of Google Maps or offline processing with tools such as JGeocoder or its Perl equivalent.

The key to encoding the geo-information with Lucene-spatial is to index the geohash and the cartesian tier (Explained at http://wiki.apache.org/lucene-java/SpatialSearch). To do so with Hibernate search, you need to create a field-bridge, as follows, in your hibernate model class. 

	@Transient 
        @Field
        @FieldBridge(impl=CartesianTierFieldBridgeImpl.class)
	public LatLng getLatLng(){
		if(latitude==null || longitude==null){
			return null;
		}
		LatLng latLng=new FloatLatLng(latitude,longitude);
		return latLng;
	}

The field bridge allows you to inject behavior into Hibernate Search to define how the fields should be indexed as text. The field bridge is implemented as:

import java.util.LinkedList;
import java.util.List;

import org.apache.lucene.document.Document;
import org.apache.lucene.document.Field;
import org.apache.lucene.spatial.geometry.LatLng;
import org.apache.lucene.spatial.tier.projections.CartesianTierPlotter;
import org.apache.lucene.spatial.tier.projections.IProjector;
import org.apache.lucene.spatial.tier.projections.SinusoidalProjector;
import org.apache.solr.util.NumberUtils;
import org.hibernate.search.bridge.FieldBridge;
import org.hibernate.search.bridge.LuceneOptions;

/**
 * Cartesian Tier Plotter to work with hibernate search
 * 
 * 
 */
public class CartesianTierFieldBridgeImpl implements FieldBridge {
	private static List<CartesianTierPlotter> ctps = new LinkedList<CartesianTierPlotter>();
	private static IProjector project = new SinusoidalProjector();
	static {
		setUpPlotter(2, 15);
	}

	private static void setUpPlotter(int base, int top) {

		for (; base <= top; base++) {
			ctps.add(new CartesianTierPlotter(base, project, CartesianTierPlotter.DEFALT_FIELD_PREFIX));
		}
	}

	@Override
	public void set(String name, Object value, Document document, LuceneOptions luceneOptions) {
		LatLng latLng = (LatLng) value;
		if(latLng==null) return;
		for (int i = 0; i < ctps.size(); i++) {
			CartesianTierPlotter ctp = ctps.get(i);
			document.add(new Field(ctp.getTierFieldName(), 
					NumberUtils.double2sortableStr(ctp.getTierBoxId(latLng.getLat(), latLng.getLng())), Field.Store.YES,
					Field.Index.NOT_ANALYZED_NO_NORMS));
		}
	}

}

This field bridge allows the latitude/longitude information to be stored with the cartesian tier plotter supplied with Lucene-spatial package.

The other key piece is to map the geohash in your Hibernate model:

	@Transient
	@Field(index = Index.UN_TOKENIZED, store = Store.YES, name = "geohash")
	public String getGeohash() {
		if (latitude == null || longitude == null)
			return null;
		return GeoHashUtils.encode(latitude, longitude);
	}

Once your Hibernate model is equipped to index the cartesian tier IDs and geohash, you can perform spatial queries, like:

DistanceQueryBuilder builder = new DistanceQueryBuilder(lat, lng, radiusMiles, 
	        "geoHash", CartesianTierPlotter.DEFALT_FIELD_PREFIX, true);
searcher.search(builder.getQuery());

 which will find all instances within radiusMiles of latitude and longitude passed to it.

You can download the latest Lucene-spatial modules directly from Lucene's CI site at http://hudson.zones.apache.org/hudson/job/Lucene-trunk/lastSuccessfulBuild/artifact/maven_artifacts/lucene/lucene-spatial/2.4-SNAPSHOT/

Enjoy your spatial searching!