Hibernate Search

Migration Guide from Hibernate Search 5.11 to 6.0

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

Upgrade to Hibernate Search 6.0.x from 5.11.x

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

Search 6 breaks many APIs, so migrating older projects will be more work than usual. This migration guide will be completed as we release new versions and the APIs get more and more stable, but for now we recommend to only test Search 6 on small projects.

Ultimately, we intend to provide additional "compatibility" modules that will allow you to use the Search 5 APIs with Search 6 under the hood. However, our goal is not full backward compatibility: for some features that changed dramatically, it may not be possible to use the Search 5 APIs anymore. The main purpose of this compatibility layer will be to spread the migration effort: you will have to change your Maven dependencies, configuration and more complex mappings/queries immediately, but you will be able to delay the more repetitive parts of the migration work (simple queries, simple entity mappings) to later.

Finally, for those who cannot afford to, or do not want to, spend the time required to migrate, we intend to continue maintenance releases (= bugfixes) of Hibernate Search 5.x: no end-of-life date has been set at the moment.

Requirements

This section is still incomplete. To be completed upon the CR or release.
  • The Elasticsearch backend now requires Elasticsearch 5.6 or 6.6.

  • The Lucene backend now requires Lucene 8.0.

Maven coordinates changes

If you pull our artifacts from a Maven repository and you come from Hibernate Search 5, be aware that just bumping the version number will not be enough.
  • the group IDs changed from org.hibernate to org.hibernate.search

  • most of the artifact IDs changed to reflect the new mapper/backend design

  • the Lucene integration now requires an explicit dependency instead of being pulled by the engine by default.

Read the getting started guide, section "dependencies" for more information.

Configuration changes

This section is still incomplete. To be completed upon the CR or release.

One of the main changes is the addition of the concept of "backend" to the configuration. The "backend" represents a common set of resources shared between multiple index managers: thread pools if necessary, a filesystem directory where index files are stored (Lucene), a HTTP client to reach a remote indexing service (Elasticsearch), …​

You will have to define a named "backend" in your configuration, and set various backend-scoped properties such as the root index path (for local Lucene indexes) or the hosts (for Elasticsearch) instead of configuring these at the index level like in Search 5.

Read the getting started guide, section "configuration" for a quick introduction, or the main "configuration" section of the reference documentation for more in-depth information.

API changes

This section is still incomplete. To be completed upon the CR or release.

A lot of APIs changed. We recommend to have a look at the getting started guide before migrating.

SPI changes

This section is still incomplete. To be completed upon the CR or release.

Behavior changes

This section is still incomplete. To be completed upon the CR or release.
  • It is no longer possible to map multiple entity types to the same index. Each index must be mapped to exactly one entity type.

  • There is no longer a builtin, default bridge for java.util.Class. If you need to index a Class<?>, you will need to write a custom bridge (probably from Class to String).

Back to top