Hibernate Search

Migration Guide from Hibernate Search 5.9 to 5.10

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

Upgrade to Hibernate Search 5.10.x from 5.9.x

The aim of this guide is to assist you migrating an existing application using any version 5.9.x of Hibernate Search to the latest of the 5.10.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.10.10.Final. If you think something is missing or something does not work, please contact us.


This version of Hibernate Search now requires using Hibernate ORM versions from the 5.3.x family.

This implies it now requires JPA 2.2, as that’s the version of JPA implemented by Hibernate ORM 5.3.

Configuration changes

  • We added Java module names to our JARs. The JVM was previously deriving the names from the JAR file names, as it does with all JARs where no module name is defined. If you have dependencies to Hibernate Search in your module-info, you might need to update these dependencies.

API changes

  • ElasticsearchEnvironment.ANALYSIS_DEFINITION_PROVIDER now contains elasticsearch.analysis_definition_provider, without the hibernate.search. prefix, consistently with other constants in the same class.

  • Binary compatibility with Hibernate Search 5.5 has been restored in the few places of our API that had changed in incompatible way. This is mainly of interest to Hibernate Search integrators.

SPI changes

  • Two methods have been removed from org.hibernate.search.indexes.spi.IndexManagerType: createAnalyzerStrategy and createMissingValueStrategy. To replace them, we added IndexFamilyImplementor createIndexFamily(ServiceManager, SearchConfiguration), which creates an intermediary "index family" which in turns provides the analyzer strategy and missing value strategy. See the javadoc for org.hibernate.search.indexes.spi.IndexFamilyImplementor for more information.

  • org.hibernate.search.hcore.spi.EnvironmentSynchronizer now exposes a org.hibernate.search.hcore.spi.EnvironmentSynchronizer#whenEnvironmentDestroying method.

Behavior changes

  • As of HSEARCH-3039, Embedded IDs are no longer analyzed. Embedded IDs are properties defined as @DocumentId (or, lacking that, JPA’s @Id), then embedded in another document using @IndexedEmbedded(includeEmbeddedObjectId = true) or @IndexedEmbedded(includePaths = { …​, "<the ID property name>", …​ }).

Back to top