Introduction

The aim of this guide is to assist you migrating an existing application using any version 8.1.x of Hibernate Search to the latest of the 8.2.x series.

If you think something is missing or something does not work, please contact us.

If you’re looking to migrate from an earlier version, you should migrate step-by-step, from one minor version to the next, following the migration guide of each version.

To Hibernate Search 5 users

Be aware that a lot of APIs have changed since Hibernate Search 5, some only because of a package change, others because of more fundamental changes (like moving away from using Lucene types in Hibernate Search APIs).

When migrating from Hibernate Search 5, you are encouraged to migrate first to Hibernate Search 6.0 using the 6.0 migration guide, and only then to later versions (which will be significantly easier).

Requirements

The requirements of Hibernate Search 8.2.0.CR1 are the same as those of Hibernate Search 8.1.

Artifacts

The coordinates of Maven artifacts in Hibernate Search 8.2.0.CR1 are the same as in Hibernate Search 8.1.

A few new artifacts are introduced with this version. They are for the pluggable Elasticsearch backend REST clients. While for now, the Elasticsearch backend brings the default (Elasticsearch low level client (based on Apache HTTP client 4)) dependency automatically, it is recommended to explicitly specify the client dependency you want to use moving forward. Currently available options are:

  • org.hibernate.search:hibernate-search-backend-elasticsearch-client-rest4 backed by org.elasticsearch.client:elasticsearch-rest-client

  • org.hibernate.search:hibernate-search-backend-elasticsearch-client-rest5 backed by co.elastic.clients:elasticsearch-rest5-client

  • org.hibernate.search:hibernate-search-backend-elasticsearch-client-opensearch-rest backed by org.opensearch.client:opensearch-rest-client

  • The backend itself org.hibernate.search:hibernate-search-backend-elasticsearch contains a JDK-based REST client backed by java.net.http.HttpClient

Using the non-default client also requires setting the hibernate.search.backend.client_factory configuration property. See the user guide for more details on which values are acceptable.

Data format and schema

Indexes

The index format and schema in Hibernate Search 8.2.0.CR1 is backward-compatible with Hibernate Search 8.1: older indexes can be read from and written to without reindexing.

Outbox polling database tables

The event and agent database tables used for outbox-polling in Hibernate Search 8.2.0.CR1 are backward-compatible with Hibernate Search 8.1: no database schema update is necessary for these tables.

Configuration

The configuration properties in Hibernate Search 8.2.0.CR1, in general, are backward-compatible with Hibernate Search 8.1.

API

The API in Hibernate Search 8.2.0.CR1 is, in general, backward-compatible with Hibernate Search 8.1. However, some elements are now deprecated:

  • org.hibernate.search.backend.elasticsearch.client.ElasticsearchHttpClientConfigurer is deprecated for removal. With introduction of the pluggable Elasticsearch backend clients, configurers are a part of the particular client and expose client-specific configuration knobs. To keep using the Elasticsearch low level based REST client (Apache HTTP Client 4) switch to org.hibernate.search.backend.elasticsearch.client.rest4.ElasticsearchHttpClientConfigurer

  • org.hibernate.search.backend.elasticsearch.client.ElasticsearchHttpClientConfigurationContext is also up for removal, as it’s a part of the configurer API.

SPI

The SPI in Hibernate Search 8.2.0.CR1 is, in general, backward-compatible with Hibernate Search 8.1.

Behavior

The behavior of Hibernate Search 8.2.0.CR1 is, in general, backward-compatible with Hibernate Search 8.1.