Geoshape search


Hibernate Search already supports spatial search whereby:

  • Documents are assigned coordinates (latitude, longitude)

  • A query specifies a range by means of coordinates and a radius

  • Documents whose coordinates are within the query range are found

The goal would be to expand spatial search to support the following:

  • Documents are assigned a range by means of coordinates and a radius

  • A query specifies a range by means of coordinates and a radius

  • Documents whose ranges intersect the query range are found

Elasticsearch provides GeoShape queries allowing documents with locations defined by means of shapes to be matched by similarly defined queries. Different shapes (e.g. polygon, circle) and spatial relation operators (e.g. intersection, disjunction) are supported. Apparently, there's even support for multiple locations per document.

The first version of this new Hibernate Search functionality could support a subset of what's provided by Elasticsearch, namely the possibility to search for documents associated with a single shape circle defined location using a query specifying a single shape circle defined location and the spatial relation operator intersection, fulfilling the following use case:

Users find each other when their ranges, defined by tuples (latitude, longitude, radius), intersect. 2 users, located at 2 different coordinates, are 10 km apart. Assuming they define the same radius, they will find each other when the radii is set to at least 5 km.

Initial discussion:




Yoann Rodière
June 25, 2018, 7:05 AM

Thank you very much for you report. We will try to address this in 6.0, or maybe 6.1 considering the amount of work already planned for 6.0.

You (or anyone else, of course) may be interested in contributing this feature to Hibernate Search to make it happen sooner. I am not sure you are, but just in case, I will add some insights below.

The place to start would currently be the Hibernate Seardch 6 proof-of-concept, which we will ultimately be merging into the main repository:

Be warned, implementing this feature will be quite complex, in particular on the Lucene side. It would be wiser to start implementing it for Elasticsearch only, and only when it works start having a look at the Lucene integration: the Elasticsearch integration is mainly about delegating to Elasticsearch, which is much easier.
You will need to:

  • Add one or several interfaces specific to Hibernate Search to represent "shapes", similar to

  • Add one or several "shape" types to the field definition DSL, i.e. add one or several addXXX() methods to

  • Add implementations for the methods you just added, both for the Lucene backend (, as said above you'd better start with a stub there) and the Elasticsearch backend (

  • Add implementations for the "model" of a "shape" field. The easiest way to do that would be to have a look at the package, copy/paste everything with GeoPoint in its name and adapt it to your needs.

  • Add an integration test. As a first step, you could add something to, where you have an example of defining a field in the constructor of, examples of populating the index in, and an example of running a native Elasticsearch query in

  • Then we can talk about adding something to the DSL, and about doing the same for Lucene, but that can definitely be a second step.

An external contributor will very likely need help; we (the Hibernate Search maintainers) are available on our chat platform, HipChat, at this address:

There is some information about generating the technical documentation in the README; this documentation should help understanding the general architecture should you be interested, but is not very useful in this specific cases: it's more about the higher-level aspects of entity mapping than the lower-level aspects of field types and index management.

July 16, 2018, 9:53 AM

You're welcome, Yoann. That could be an interesting project, but time availability is scarce unfortunately.







Suitable for new contributors


Pull Request


Feedback Requested



Fix versions

Affects versions