Hibernate Search 6.0.11.Final: Migration Guide from 5.11

Hibernate Search 6 includes a temporary additional "migration helper" module that provides partial compatibility with Hibernate Search 5 APIs backed by the Hibernate Search 6 implementations.

This module should make migration easier by making sure that code relying on the most-frequently-used APIs (mapping annotations, search DSL, …​) continues to compile and run. The idea is to use the migration helper temporarily to make most of the application code (search queries, …​) work, making it easier to focus on migrating configuration and to assess the effort required to migrate the remaining code.

To use the migration helper, add the following dependency to your project:

Then, try to recompile your application. Compilation errors should point you to the most significant API changes that require your immediate attention; most of the code that still compiles should work as it used to in Hibernate Search 5.

First, the migration helper only works with a Lucene backend. Hibernate Search 5 APIs are not well suited to Elasticsearch, so applications relying on Hibernate Search 5’s experimental Elasticsearch integration should migrate to the more adapted Hibernate Search 6 APIs right away.

Second, the migration helper only addresses Java API compatibility. This excludes in particular:

Finally, even for Java APIs, not all APIs from Hibernate Search 5 are present in the migration helper. You should get compilation errors when APIs are missing, which should make them easy to spot, but here are the main pitfalls:

Most configuration properties changed in Hibernate Search 6. In most cases it’s only a matter of changing the prefix of a configuration property (due to the different structure of Hibernate Search 6), but in a few cases the relevant feature changed so much that a new approach was necessary for configuration.

For a quick introduction to the basics of configuration in Hibernate Search 6, refer to the getting started guide, section "configuration".

For more details, see the main "configuration" section of the reference documentation.

For a complete list of Hibernate Search 5 properties and their equivalent in Hibernate Search 6, refer to the section below.

In Hibernate Search 5, constants for configuration property keys used to be provided through org.hibernate.search.cfg.Environment and org.hibernate.search.elasticsearch.cfg.ElasticsearchEnvironment.

In Hibernate Search 6, constants are provided through classes whose name ends with Settings:

Below is a list of Hibernate Search 5 properties in alphabetical order, along with their equivalent in Hibernate Search 6.

Hibernate Search 6 does not provide JMX support at the moment.

The current plans are to implement support for tracing in a future release (HSEARCH-4057). This would provide a more powerful solution to users looking for insight into the behavior of their application.

If you need this feature urgently, we’ll gladly help anyone interested in contributing a patch: feel free to contact us.

Hibernate Search 6 does not provide support for the JGroups or JMS backends at the moment, nor does it support the related filesystem-master/filesystem-slave/infinispan directory providers.

If you need to scale your application to multiple nodes, consider switching to the Elasticsearch backend.

To ensure robustness of distributed indexing, consider upgrading directly to Hibernate Search 6.1, which provides a feature called coordination, and in particular the database-polling coordination strategy. When used together with the Elasticsearch backend, the database-polling coordination strategy enables distributed applications, as the JMS/JGroups backends in Hibernate Search 5 do, though through a different implementation relying on the database instead of JMS/JGroups queues.

Programmatic mapping was overhauled to match the new mapping annotations.

See here for the entry point, and refer to the javadoc for details.

Analysis definition providers are now called analysis configurers. The interfaces are slightly different but follow the same general principle.

See here for Lucene, or here for Elasticsearch.

The bridge API was completely reworked in Hibernate Search 6 to offer a more powerful, Lucene-independent solution. New features include:

If your application relied on custom bridges with Hibernate Search 5, and you need to re-implement them with Hibernate Search 6, see mapping custom property types.

The new bridge API is quite different from Hibernate Search 5, but most changes should be addressed rather easily, especially for the simpler bridges which will be implemented through ValueBridge.

Perhaps the only change to note is that bridges must declare the index fields they will create at bootstrap. To set the value of new fields with random names dynamically at runtime, you will have to rely on field templates.

Entity indexing interceptors were used in Hibernate Search 5 to implement conditional indexing.

Conditional indexing can be implemented in Hibernate Search 6 with a different, but equivalent solution: the RoutingBridge.

The idea is for the RoutingBridge to decide, based on the state of an entity, whether its document should be routed to the index (indexed) or not (not indexed).

See this section of the documentation for more information.

The ErrorHandler interface was replaced with the FailureHandler interface, and the related configuration properties changed.

See this section of the documentation for more information about background failure handling.

Also, be aware that the MassIndexer now exposes a failureHandler parameter, to handle failures during mass indexing differently (e.g. report to the web console from which mass indexing was initiated). More information here.

Hibernate Search 6.0 does not support named full-text filters at the moment. In most cases, you can replace them with static methods.

For example, let’s take this filter from a Hibernate Search 5 application:

The filter could be used this way:

In Hibernate Search 6, you can define the filter as a static method:

And then simply add it to the root boolean predicate when searching:

The @Factory annotation does not exist in Hibernate Search 6 anymore.

You are encouraged to rely on a proper dependency injection framework if you need such a feature: just reference the bean name instead of referencing the bean class in your Hibernate Search mapping/configuration. See the section of the documentation about beans in Hibernate Search for details and supported DI frameworks.

If you don’t use a dependency injection framework, here are details on how to migrate:

org.hibernate.search.exception.SearchException has moved to org.hibernate.search.util.common.SearchException.

Static sharding is still available in Hibernate Search 6, but it works differently, so the Hibernate Search 5 APIs are no longer available. To implement static sharding in Hibernate Search 6, refer to this section of the documentation.

Dynamic sharding is no longer available in Hibernate Search 6. If your application absolutely requires it, contact us so we can discuss how to best address your needs, or drop a comment here.

The mass indexing Batch (JSR-352) job mostly stays the same in Hibernate Search 6, but MassIndexingJob moved to a different package: org.hibernate.search.batch.jsr352.core.massindexing.MassIndexingJob.

See this section of the documentation for more information about the JSR-352 integration.

See the table below for the exact equivalent of parameters that changed.

There is no longer a builtin, default bridge for java.util.Class.

If you need to index a Class<?>, you will need to implement a custom bridge (probably from Class to String).

Optionally, you can also register your custom bridge as a default bridge so that it is applied automatically and transparently to all fields defined on properties of type Class.

Hibernate Search 5 used to create an index field for document IDs, which could then be queried using the query DSL in particular:

In Hibernate Search 6, this is no longer the case. The identifier "field" is internal, and is not named after the entity property it originates from.

If you want to use the identifier as a field:

In Hibernate Search 5, @Indexed was not inherited by subclasses; the following configuration would result in instances of MyEntity being indexed, but not instances of MySubClassEntity:

In Hibernate Search 6, @Indexed is inherited by subclasses; the configuration above would result in instances of both MyEntity and MySubClassEntity being indexed, though in different indexes. A search query on type MyEntity will return instances of both MyEntity and MySubClassEntity, in accordance with the Liskov substitution principle.

To prevent MySubClassEntity from being indexed, annotate it with @Indexed(enabled = false); this will restore the Hibernate Search 5 behavior:

In Hibernate Search 5, it used to be possible to store multiple entity types in the same index.

In Hibernate Search 6, each type must have its own dedicated index. Annotating two distinct types with @Indexed(index = "my-index") (the same index name) will lead to a bootstrap failure.

In Hibernate Search 5, the default name of the index for a given entity when @Indexed.index was not set was the fully-qualified class name, so the following mapping resulted in an index named com.mycompany.MyEntity1 and another named com.mycompany.MyEntity2:

In Hibernate Search 6, the default name of the index in that case is the JPA entity name, so the mapping above results in an index named simply MyEntity1 and another named MyEntityTwo.

In Hibernate Search 5, when a field was configured with indexNullAs:

In Hibernate Search 6, this is no longer the case:

If this behavior is not acceptable, consider dropping the indexNullAs option and relying on the exists predicate to search for documents that have or don’t have a value for a given field.

In Hibernate Search 5, a terms aggregation on a field with a normalizer used to return raw (non-normalized) values.

In Hibernate Search 6, the same aggregation on this normalized field will return normalized values.

In Hibernate Search 5, automatic reindexing was only triggered by changes to the indexed entity by default: if you were to add @IndexedEmbedded(includePaths = "name") to an association from entity A to another entity B, then calling a.setB(…​) would lead to reindexing of a, but calling a.getB().setName("a new name") would not. In order to make sure that changes to B.name automatically trigger reindexing of the associated A, you had to mark the inverse side of the association, B.a, with the @ContainedIn annotation.

This behavior changed in Hibernate Search 6: in the example above, Hibernate Search 6 would automatically trigger reindexing of B.a when B.name is modified, without the need of applying a @ContainedIn annotation.

This means that automatic indexing is "safe" by default: whenever you apply @IndexedEmbedded to an association, Hibernate Search will automatically resolve the inverse side of that association and will make sure that any change in "indexed-embedded" entities lead to reindexing of affected indexed entities.

This also means that Hibernate Search 6 needs to know the inverse side of associations annotated with @IndexedEmbedded. If it can’t resolve it (for example when an @IndexedEmbedded association has no inverse side), Hibernate Search 6 will raise errors at bootstrap, looking like this:

The error message already explains the potential solutions, but here is a perhaps clearer explanation of each solution in the context of migrating Hibernate Search 5 applications:

For more information, refer to Tuning automatic reindexing, in particular this section for shallow reindexing and this section for specifying the inverse side of an association.

In Hibernate Search 5, when a @Transient property was mapped to an index field, Hibernate Search would switch to a "non-optimized" mode where reindexing was triggered for any change in the same entity, assuming that the transient property value was computed from other properties of the same entity. This would work fine in some cases, but could lead to unnecessary reindexing when unrelated properties were modified and to out-of-sync indexes when the transient property was computed from data extracted from associated entities.

This behavior changed in Hibernate Search 6: if a @Transient property is mapped to an index field, Hibernate Search will trigger a bootstrap failure asking for additionnal configuration.

The "right" solution in that case is to put an annotation on the transient property, to explain which properties are used to derive the value of the transient property: @IndexingDependency(derivedFrom = …​). You can find more information in this section of the documentation.

Alternatively, if you do not care about automatic reindexing when the transient property changes, then you can just disable automatic reindexing for this property with @IndexingDependency(reindexOnUpdate = ReindexOnUpdate.NO). See this section of the documentation.

In Hibernate Search 6, when a @*Field annotation is applied on a property of a container type, the field will work on container elements by default, not on the container itself.

For example, the following mapping will create a String field, and Hibernate Search will index each element of the List in the notes index field:

This should be kept in mind when migrating custom bridges that work on container types. For example, the following mapping likely won’t work, because MyListBridge expects values of type List, not String:

To disable the automatic extraction of container element (and get back to the Hibernate Search 5 behavior), use extraction = @ContainerExtraction(extract = ContainerExtract.NO):

See this section of the documentation for more information.

Fields of type Boolean, boolean, Short, short, Byte and byte used to be indexed as string values by default in Hibernate Search 5, but are indexed as numeric values by default in Hibernate Search 6.

Similarly, fields created to represent the embedded identifier when using @IndexedEmbedded.includeEmbeddedObjectId used to be string fields, unless annotated with @NumericField. The behavior changed in Hibernate Search 6:

When using a Query that is an adapter to a Hibernate Search query, the ScrollableResults returned by Query.scroll()/Query.scroll(ScrollMode) is now always forward-only; trying to move the cursor backward will lead to an exception being thrown.

When using a Query that is an adapter to a Hibernate Search query, the ScrollableResults returned by Query.scroll()/Query.scroll(ScrollMode), as well as the iterate() method, no longer load entities lazily as late as possible: instead, entities are loaded in batches under the hood.

This is important in particular if you clear the session, as you might clear an entity that was already loaded as part of the current batch, which could result in a LazyInitializationException being thrown upon accessing that entity.

You can control the size of batches by configuring the loading fetch size or scrolling through Hibernate Search’s own APIs.

In Hibernate Search 5, sorts involving missing values used to assume a default value depending on the field type, e.g. 0 for numeric types. As a result, a document whose field does not have a value could end up first, or right in the middle of other documents after a sort.

In Hibernate Search 6, a document whose field does not have a value always ends up at the very end by default. This behavior can be customized when defining the sort.

Hibernate Search logs all executed search queries to logger org.hibernate.search.query.

In Hibernate Search 5, these logs were at the DEBUG level. In Hibernate Search 5, they are at the TRACE level.

The default similarity for the Lucene backend is now BM25Similarity, instead of ClassicSimilarity in Hibernate Search 5.

If necessary, you can force the ClassicSimilarity through an analysis definition provider.