Here we are helping you migrate your existing Search application to the latest and greatest.
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
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
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
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).
ContainedInMapping#numericField() has been deprecated and is scheduled for removal. Invoke
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.
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
and similarly for other Numeric types: a Long needs to be sorted with
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
Although the query engine will fallback to the traditional approach of index un-inverting when detecting a sort field not mapped via
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.
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
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.
@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'.