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.
|
Requirements
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'.