Hibernate Search

Migration Guide from Hibernate Search 5.4 to 5.5

Here we are helping you migrate your existing Search application to the latest and greatest.

Upgrade to Search 5.5.x from 5.4.x

The aim of this guide is to assist you migrating an existing application using any version 5.4.x of Hibernate Search to the latest of the 5.5.x series. If you’re looking to migrate different versions see Hibernate Search migration guides.

This document provides pointers for a migration. It refers to Hibernate Search version 5.5.0.Final. If you think something is missing or something does not work, please contact us.


This version of Hibernate Search now requires using Apache Lucene 5.3.1.

If you have kept indexes generated by Lucene 3 i.e. haven’t rebuilt them with Hibernate 5.0 or later, you will get an IndexFormatTooOldException. We strongly encourage you to rebuild you indexes for example with the mass indexer. If you really really cannot do that, try to:

  • use Lucene’s IndexUpgrader

  • carefully update the Hibernate Search mappings in case their default behavior has changed (check the migration guide).

API changes

Method ContainedInMapping#numericField() has been deprecated and is scheduled for removal. Invoke field().numericField() instead.

There were no further relevant API changes within Hibernate Search itself; but Apache Lucene had a major upgrade from 4 to 5. So if your code was importing Lucene code directly, be it to provide powerful custom exctensions, or simply to create instances of org.apache.lucene.search.Query you will likely need to follow the Apache Lucene 5 migration guide. Also check out the Lucene 5 change log.

Sorting options

If your code was not precisely matching the Lucene field encoding for sorting options, chances are that with Lucene 4 it appeared to work correctly. Such a mistake will now be detected and result in runtime exceptions! To match the expected field encoding, remember that a field which is indexed as a String will need to have a single term (even after analysis), and a numeric field encoded as an Integer will have to match a SortField.Type.INT when creating an instance of org.apache.lucene.search.SortField, and similarly for other Numeric types: a Long needs to be sorted with SortField.Type.LONG, etc…​

Failing to match the correct type will result in exceptions described in depth at HSEARCH-1951: we hope to be able to improve at least the clarity of such error messages soon.

Lucene 5 allows for more performant sorting if the fields to sort on are known up-front. They then can be mapped via so-called doc value fields. For that purpose Hibernate Search 5.5 provides the new @SortableField annotation and its multi-valued companion @SortableFields. Although the query engine will fallback to the traditional approach of index un-inverting when detecting a sort field not mapped via @SortableField, it is highly recommended to do so for the sake of better runtime performance and less memory consumption. Check out this blog post which covers that topic in detail.

Sorting on the id field

If you are using a numeric id, sorting directly on the id field of your document will not work anymore.

You need to specify a different field used specifically for sorting and marked with the @SortableField annotation.

Faceting on Numeric Fields

Similarly to Sort options, you need now be careful to run the appropriate kind of Faceting Query on each target field. For example a Numeric Facet Query will have to target a field which was indexed exclusively via the matching Numeric type.

Null value tokens for numeric fields

When using @Field(indexNullAs=) to encode some null marker value in the index, the type of the marker is now required to be compatible with all other values which are indexed in that same field. This was problematic for numeric fields, the ones optimised for range queries on numbers, as we would previously allow you to encode a string keyword like 'null': this is no longer allowed, you will have to pick a number to be used to represent the null value, e.g. '-1'.

Back to top