8.1 series - Hibernate Search

Hibernate Search 8.1 is still in development:

some features may be incomplete;
newly introduced features may change in a backward-incompatible way before the stable release.

We encourage you to give it a try and to let us know of any bugs or problems you encounter.

Compatibility

Java	17, 21, or 23
Hibernate ORM	7.0
Elasticsearch server	7.10 - 9.0
OpenSearch server	1.3 - 3.1
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.1 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: development

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 Search Platform BOM

Hibernate Search Platform (for the lucene-next backend) 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-07-29): 8.1.0.Alpha1.

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

Dependency upgrades

Hibernate ORM: Hibernate Search still targets the Hibernate ORM 7.0 series, with the plan, in the following beta releases to target 7.1 once it is out.

Lucene: The Lucene backend now uses Lucene 9.12.2, while the lucene-next backend relies on Lucene 10.2.2

Elasticsearch: The Elasticsearch backend is still compatible with all already compatible versions.

OpenSearch: The Elasticsearch backend works with OpenSearch 3.1, as well as other already compatible versions.

Aggregation improvements

With this version of Hibernate Search it is now possible to request terms and range aggregations for more than counts, i.e. such that would return other aggregations provided by the DSL.

AggregationKey<Map<Range<Double>, Double>> avgRatingByPriceKey = AggregationKey.of( "avgRatingByPrice" ); (1)
SearchResult<Book> result = searchSession.search( Book.class )
    .where( f -> f.matchAll() )
    .aggregation(
        avgRatingByPriceKey, f -> f.range()
            .field( "price", Double.class ) (2)
            .range( 0.0, 10.0 )
            .range( 10.0, 20.0 )
            .range( 20.0, null )
            .value( f.avg().field( "ratings", Double.class, ValueModel.RAW ) ) (3)
    )
    .fetch( 20 );
Map<Range<Double>, Double> countsByPrice = result.aggregation( avgRatingByPriceKey ); (4)

1	Create an aggregation key for an average rating by book price aggregation.
2	Start building range aggregation as usual, by specifying the field and ranges.
3	Request an `.avg()` aggregation on the ratings field. Specifying `Double` and using `ValueModel.RAW` here defines the expected return type of the computed aggregation.
4	Extract the aggregated value from the results.

The value of the range()/terms() aggregation can be any of the aggregations provided by the Search DSL, e.g. one of the metric aggregations: min()/max()/avg()/count()/sum(), a range()/terms() aggregation or a composite aggregation combining a number of other aggregations.

See the corresponding section on range aggregations to learn more. This also is applicable to the terms aggregations.

If multiple aggregations are of interest be it at the root level or per aggregation (terms/range) bucket, it is now possible to request a composite aggregation:

record PriceAggregation(Double avg, Double min, Double max) { (1)
}
AggregationKey<Map<Range<Double>, PriceAggregation>> priceAggregationsKey = AggregationKey.of( "priceAggregationsKey" ); (2)
SearchResult<Book> result = searchSession.search( Book.class )
    .where( f -> f.matchAll() )
    .aggregation(
        countsByPriceKey, f -> f.range()
            .field( "price", Double.class ) (3)
            .range( 0.0, 10.0 ) (3)
            .range( 10.0, 20.0 )
            .range( 20.0, null )
            .value( f.composite() (4)
                .from(
                    f.avg().field( "price", Double.class ), (5)
                    f.min().field( "price", Double.class ),
                    f.max().field( "price", Double.class )
                ).as( PriceAggregation::new ) ) (6)
    )
    .fetch( 20 );
Map<Range<Double>, PriceAggregation> countsByPrice = result.aggregation( priceAggregationsKey ); (7)

1	Define a structure to hold composite aggregation results.
2	Create an aggregation key for the composite range aggregation.
3	Start building range aggregation as usual, by specifying the field and ranges.
4	Request a `.composite()` aggregation.
5	Add any required aggregations to build up a composite one.
6	Specify how to transform the composite aggregation. By default, you would need to request the composite aggregation as a `List` or an array of aggregated values, but then it is possible to transform it to something else.
7	Extract the aggregated value from the results.

See the corresponding section on composite aggregations to learn more.

Hibernate Search Platform BOM

Besides the lean BOM file, Hibernate Search now also provides several platform POM files that manage the versions of Hibernate Search artifacts, and their transitive dependencies, and related artifacts that must be aligned. For example, it brings the management of all other org.hibernate.orm artifacts, beyond the ones required by the ORM mapper, or extra Lucene artifacts like lucene-suggest or lucene-analysis-icu and others, that can be helpful for more advanced applications. These platform files will help keep the versions of extra Hibernate ORM/Lucene/Elasticsearch client dependencies aligned with the versions of artifacts from the same groups that are used by Hibernate Search itself.

Currently, there are two platform POM files for Hibernate Search:

hibernate-search-platform-bom: use this when in doubt.
hibernate-search-platform-next-bom: use this if you want to use the lucene-next backend.

To leverage the dependency management provided by these platform files, use the same approach of importing as for the regular BOM file:

<dependencyManagement>
    <dependencies>
        <!--
            Import Hibernate Search platform
            to get all of its artifact versions aligned:
        -->
        <dependency>
            <groupId>org.hibernate.search</groupId>
            <artifactId>hibernate-search-platform-bom</artifactId>
            <version>8.1.0.Alpha1</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
        <!-- Any other dependency management entries -->
    </dependencies>
</dependencyManagement>

<dependencies>
    <!-- Any other dependency management entries -->
    <!--
         For example, add an extra Lucene dependency without specifying the version
         as it is managed by the platform POM:
    -->
    <dependency>
        <groupId>org.apache.lucene</groupId>
        <artifactId>lucene-suggest</artifactId>
    </dependency>
    <!-- Any other dependency management entries -->
</dependencies>

See the corresponding section on Hibernate Search Platform to find out more.

Development versions (SNAPSHOTS)

The latest development versions of Maven artifacts for Hibernate Search are published to the Sonatype Maven Central snapshots repository.

Sonatype Maven Central snapshots subdirectory

You should only need those (unstable) versions for testing recently merged patches, and should never use them in production.

To consume these artifacts, you may need to configure your build tool to fetch artifacts from https://central.sonatype.com/repository/maven-snapshots and to enable snapshots:

Maven Gradle

Releases in this series

8.1.0.Alpha1

2025-07-29

ASL v2

Aggregation DSL improvements, platform BOMs, compatibility with new versions of Elasticsearch/OpenSearch, other bugfixes, improvements and upgrades

How to get it

Maven artifacts Download Resolved issues Release announcement

Hibernate Search

8.1 series development

Aggregation DSL improvements, platform BOMs, compatibility with new versions of Elasticsearch/OpenSearch, other bugfixes, improvements and upgrades

Compatibility

Documentation

How to get it

Direct download

What's new

Dependency upgrades

Aggregation improvements

Hibernate Search Platform BOM

Development versions (SNAPSHOTS)

Releases in this series

Projects

Follow us

Contribute and community