8.0 series - Hibernate Search

Compatibility

Java	17, 21, or 23
Hibernate ORM	7.0
Elasticsearch server	7.10 - 9.0
OpenSearch server	1.3 - 3.0
Apache Lucene	9.12 / 10.2

Not compatible with your requirements? Have a look at the other series.

See also the Compatibility policy and Maintenance policy.

Documentation

Documentation for Hibernate Search 8.0 can be accessed through the links below:

Getting started guide (ORM) HTML PDF

Getting started guide (Standalone) HTML PDF

What's new HTML

Migration guide HTML PDF

Reference HTML PDF API (Javadoc)

You can find more documentation for all series on the documentation page.

How to get it

Current series status: end-of-life

Maven artifacts of Hibernate Search are published to Maven Central. Most build tools fetch artifacts from Maven Central by default, but if that's not the case for you, see this page to configure your build tool.

You can find the Maven coordinates of all artifacts through the link below:

Maven artifacts

Below are the Maven coordinates of the main artifacts.

Hibernate Search BOM

Hibernate ORM mapper

"outbox-polling" coordination strategy for the Hibernate ORM mapper

Standalone POJO mapper

Lucene backend backed by Lucene 9.12

Lucene backend backed by Lucene 10

Elasticsearch/OpenSearch backend

Amazon IAM authentication for Elasticsearch/OpenSearch

Jakarta Batch mass indexing job for the Hibernate ORM mapper - Core

Jakarta Batch mass indexing job for the Hibernate ORM mapper - JBeret specifics

Helper for migrating from Hibernate Search 5 to Hibernate Search 6/7/8 (Hibernate ORM mapper + Lucene backend)

Hibernate Search annotation processor capable of generating the static metamodel

All Maven artifacts of this project released after 2022-01-26 are signed.

To verify signed Maven artifacts, head to this page.

Direct download

A ZIP archive containing all JAR files, documentation and source is available from SourceForge:

Download ZIP archive

Individual Maven artifacts may be downloaded directly from the Maven repository:

Maven Central subdirectory

See here for how to download all dependencies of your Maven project to a local directory on your filesystem.

See here for how to download an explicitly listed set of artifacts to a local directory on your filesystem.

More information about specific releases (announcements, download links) can be found here.

What's new

Latest release announcement (2025-06-06): 8.0.0.Final.

A detailed list of new features, improvements and fixes in this series can be found on our issue tracker.

Dependency upgrades

JDK: Hibernate Search upgrades to JDK 17 as the baseline and drops JDK 11 compatibility.

Hibernate ORM: Hibernate Search now targets the Hibernate ORM 7.0 series, which implements Jakarta Persistence 3.2.0. In particular, it is currently based on Hibernate ORM 7.0.0.CR1.

Lucene: The Lucene backend now uses Lucene 9.12.1, while the lucene-next relies on Lucene 10.2.1

Elasticsearch: The Elasticsearch backend is compatible with Elasticsearch 8.16, 8.17, 8.18 and 9.0, as well as other already compatible versions.

OpenSearch: The Elasticsearch backend works with OpenSearch 2.17, 2.18, 2.19 and 3.0, as well as other already compatible versions.

Metric aggregations

The Hibernate Search DSL now allows requesting metric aggregations:

AggregationKey<Double> avgPriceKey = AggregationKey.of( "avgPrice" ); (1)
AggregationKey<LocalDate> oldestReleaseKey = AggregationKey.of( "oldestRelease" ); (2)

SearchResult<Book> result = searchSession.search( Book.class )
    .where( f -> f.matchAll() )
    .aggregation( avgPriceKey, f -> f.avg().field( "price", Double.class ) ) (3)
    .aggregation( oldestReleaseKey, f -> f.min().field( "releaseDate", LocalDate.class ) ) (4)
    .fetch( 20 );

Double avgPrice = result.aggregation( avgPriceKey ); (5)
LocalDate oldestRelease = result.aggregation( oldestReleaseKey );

1	Create an aggregation key for an average price aggregation.
2	Create an aggregation key for a minimum date aggregation.
3	Request an `.avg()` aggregation on the price field. Specifying `Double` here defines the expected return type of the computed aggregation.
4	Request a `.min()` aggregation on the release date field. Specifying `LocalDate` here defines the expected return type of the computed aggregation.
5	Extract the aggregated value from the results.

See the corresponding section on metric aggregations to learn which aggregations are available.

New Lucene backend

While Hibernate Search 8.0 still targets JDK 17, Lucene, starting with version 10, is leveraging new Java APIs, particularly to work with memory, that are available starting with JDK 21. To give users an option to work with the newer Lucene version, Hibernate Search introduces the hibernate-search-backend-lucene-next backend.

Currently, this backend is backed by Lucene 10 and requires JDK 21. In terms of functionality, both Lucene-based backends have the same search capabilities.

See this section of the reference documentation to learn more.

Projecting multivalued fields

It is now possible to use other collection types than List for multivalued projections:

Example 1. Using a Set to collect author names in a projection constructor

@ProjectionConstructor
public record MyBookProjection(
    @IdProjection Integer id,
    String title,
    Set<String> authors) {  (1)
}

1	Using `Set` as a collection for a multivalued projection.

Example 2. Using the set collector within projection DSL

List<Set<String>> hits = searchSession.search( Book.class )
    .select( f -> f.field( "authors.lastName", String.class ).set() ) (1)
    .where( f -> f.matchAll() )
    .fetchHits( 20 );

1	Using the set collector.

Hibernate Search comes with implementation for most popular collections, but it is also possible to extend it and use a custom collector for an unsupported collection:

List<MyCustomCollection<String>> hits = searchSession.search( Book.class )
    .select( f -> f.field( "authors.lastName", String.class ).collector( new MyCustomCollector() ) ) (1)
    .where( f -> f.matchAll() )
    .fetchHits( 20 );

1	Pass an instance of `ProjectionCollector.Provider` to the `.collector()` method.

Logging categories

Hibernate Search now utilizes logging categories instead of FQCNs. It is now easier to enable logging when debugging a particular area of Hibernate Search:

# Set logging level for massindexing events to `TRACE`:
org.hibernate.search.mapper.massindexing=TRACE

See the corresponding section on logging categories to find out which categories are available.

Static metamodel

Hibernate Search’s static metamodel is a set of generated classes that represents the structure of each entity’s index, thereby allowing type-safe references to index fields when creating search queries through the Search DSL.

The basic principles are very similar to the JPA static metamodel available in Hibernate ORM, but in the case of Search the metamodel is about indexes rather than entities.

To try out this new feature, add the annotation processor to the build configuration:

<plugin>
    <artifactId>maven-compiler-plugin</artifactId>
    <executions>
        <execution>
            <id>default-compile</id>
            <configuration>
                <annotationProcessors>
                    <annotationProcessor>org.hibernate.search.processor.HibernateSearchProcessor</annotationProcessor> (1)
                </annotationProcessors>
                <annotationProcessorPaths>
                    <path>
                        <groupId>org.hibernate.search</groupId>
                        <artifactId>hibernate-search-processor</artifactId> (2)
                    </path>
                    <path>
                        <groupId>org.hibernate.search</groupId>
                        <artifactId>hibernate-search-backend-lucene</artifactId> (3)
                    </path>
                </annotationProcessorPaths>
            </configuration>
        </execution>
    </executions>
</plugin>

1	Provide the fully qualified class name of the annotation processor that generates the metamodel.
2	Add the `org.hibernate.search:hibernate-search-processor` dependency to the annotation processor path (a superset of the compile path), so the Java compiler can find the processor.
3	Add the backend dependency, in this example, the Lucene backend, to the annotation processor path.

The version of both annotation processor and backend dependencies can be omitted in the definition of the annotation paths, because they are defined in the Hibernate Search BOM, which we recommend you import via dependency management. This way the generated metamodel classes will be based on the same backend that the application uses.

And then use the generated metamodel classes to create search queries, e.g.:

SearchSession searchSession = /* ... */; (1)
var scope = Book__.INDEX.scope( searchSession ); (2)

List<Book> hits = searchSession.search( scope )
    .where( f -> f.match()
        .field( Book__.INDEX.title ).field( Book__.INDEX.description ) (3)
        .matching( "robot" ) )
    .fetchHits( 20 );

1	Obtain the search session.
2	Create the search scope over the book index. Using such scope in the Search DSL will automatically limit acceptable field references to the ones obtained from the `Book__.INDEX`
3	Use the metamodel to reference the fields when creating the queries.

See the corresponding section on static metamodel to find out more.

Releases in this series

Hibernate Search 8.0 has reached its end-of-life: we recommend that you upgrade to a newer series if possible.

Hibernate Search

8.0 series end-of-life

Integration with Hibernate ORM 7.0, metric aggregations, new Lucene-based backend, logging categories and more.