Hibernate Search

6.1 series stable

Asynchronous, distributed automatic indexing, OpenSearch compatibility, search DSL improvements, conditional mass indexing, ORM 5.6, Lucene 8.11, Elasticsearch 7.16, Jakarta EE artifacts, ORM 6 artifacts.

Compatibility

Java 8, 11, 17 or 18
Hibernate ORM 5.6
Hibernate ORM 6 (through *-orm6 artifacts) 6.0 - 6.1
Elasticsearch server 5.6 - 7.16
OpenSearch server 1.0 - 1.2
Apache Lucene 8.11

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

See also the Compatibility policy.

Documentation

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

HTML PDF API (JavaDoc)

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

How to get it

Maven, Gradle...

Maven artifacts of Hibernate Search are published to Maven Central and to the JBoss Maven repository. Refer to the Maven Getting Started guide on the JBoss Wiki for more information on how to configure the JBoss Maven repository.

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

Maven artifacts

Below are the Maven coordinates of the main artifacts.

org.hibernate.search:hibernate-search-mapper-orm:6.1.5.Final
Hibernate ORM mapper
org.hibernate.search:hibernate-search-mapper-orm-coordination-outbox-polling:6.1.5.Final
"outbox-polling" coordination strategy for the Hibernate ORM mapper
org.hibernate.search:hibernate-search-backend-lucene:6.1.5.Final
Lucene backend
org.hibernate.search:hibernate-search-backend-elasticsearch:6.1.5.Final
Elasticsearch/OpenSearch backend
org.hibernate.search:hibernate-search-backend-elasticsearch-aws:6.1.5.Final
Amazon IAM authentication for Elasticsearch/OpenSearch
org.hibernate.search:hibernate-search-mapper-orm-batch-jsr352-core:6.1.5.Final
Batch for Java (JSR-352) mass indexing job for the Hibernate ORM mapper - Core
org.hibernate.search:hibernate-search-mapper-orm-batch-jsr352-jberet:6.1.5.Final
Batch for Java (JSR-352) mass indexing job for the Hibernate ORM mapper - JBeret specifics
org.hibernate.search:hibernate-search-v5migrationhelper-orm:6.1.5.Final
Helper for migrating from Hibernate Search 5 to Hibernate Search 6 (Hibernate ORM mapper + Lucene backend)

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

To verify signed Maven artifacts, head to this page.

Zip archive

Direct download is available from SourceForge:

Download Zip archive

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

Getting started

If you want to start using Hibernate Search 6.1, please refer to the getting started guide:

HTML PDF

Migrating

If you need to upgrade from a previous series, please refer to the migration guide:

HTML PDF

What's new

Latest release announcement (2022-05-11): 6.1.5.Final.

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 6.1 is compatible with Hibernate ORM 5.6, but also 6.0 through separate Maven artifacts.

Lucene

The Lucene backend now uses Lucene 8.11.

Elasticsearch

The Elasticsearch backend now works with Elasticsearch 5.6, 6.8, 7.10 or 7.16.

Asynchronous, distributed automatic indexing

While it’s technically possible to use Hibernate Search 6.0 and Elasticsearch in distributed applications, it suffers from a few limitations.

The main goal of Hibernate Search 6.1 is to eliminate these limitations by introducing coordination between application nodes to implement asynchronous, distributed automatic indexing.

Hibernate Search 6.1 introduces the very first coordination strategy: outbox-polling. This strategy creates an outbox table in the database to push entity change events to, and relies on a background processor to consume these events and perform automatic indexing.

Clustered architecture with outbox polling and Elasticsearch backend

Beside eliminating the limitations mentioned above, another advantage of this strategy is that Hibernate Search will no longer trigger lazy-loading or build documents in application threads, which can improve the responsiveness of applications (less work to do on commit).

To learn more about an architecture based on outbox-polling coordination, head to this section of the documentation. You can also get a quick overview of several architectures here.

To jump right in and try the strategy, just set the following property (you will also need to add tables to your database schema):

hibernate.search.coordination.strategy = outbox-polling

Head to this section of the documentation for more information on how to configure coordination.

The outbox-polling coordination strategy can perfectly well be used with a Lucene backend.

You will still be limited to a single application node, but you will benefit from all the other advantages (data safety, increased application responsiveness, …​).

OpenSearch compatibility

Starting with version 6.1, Hibernate Search is also compatible with OpenSearch, the Apache 2.0 licensed fork of Elasticsearch, and regularly tested against versions 1.0 and 1.2.

To use Hibernate Search with OpenSearch, use the same Maven artifacts, configuration and API that you would have used with Elasticsearch.

The only (minor) difference between using Elasticsearch and OpenSearch is if you configure the Elasticsearch version explicitly: with OpenSearch, you need to prefix the version with opensearch:, e.g. opensearch:1.0.

Search DSL improvements

New terms predicate

Matches documents for which a given field contains some terms, any or all of them.

Useful for enum-typed fields, in particular.

List<Book> hits = searchSession.search( Book.class )
        .where( f -> f.terms().field( "genre" )
                .matchingAny( Genre.CRIME_FICTION, Genre.SCIENCE_FICTION ) )
        .fetchHits( 20 );
New regexp predicate

Matches documents for which a given field contains a word matching the given regular expression.

List<Book> hits = searchSession.search( Book.class )
        .where( f -> f.regexp().field( "description" )
                .matching( "r.*t" ) )
        .fetchHits( 20 );
New id projection

Returns the identifier of the matched entity.

List<Integer> hits = searchSession.search( Book.class )
        .select( f -> f.id( Integer.class ) )
        .where( f -> f.matchAll() )
        .fetchHits( 20 );
Configurable .missing() behavior for distance sort

Distance sorts now allow specifying the behavior when encountering documents with missing values (though only .missing().first()/.missing().last() are supported with Elasticsearch).

GeoPoint center = GeoPoint.of( 47.506060, 2.473916 );
List<Author> hits = searchSession.search( Author.class )
        .where( f -> f.matchAll() )
        .sort( f -> f.distance( "placeOfBirth", center )
                .missing().first() )
        .fetchHits( 20 );
Relative field paths

The Search DSL now allows creating factories (SearchPredicateFactory, etc.) that accept relative field paths.

This is mostly useful if you pass factories to reusable methods.

List<Book> hits = searchSession.search( Book.class )
        .where( f -> f.bool()
                .should( f.nested().objectField( "writers" )
                        .nest( matchFirstAndLastName(
                                f.withRoot( "writers" ),
                                "bob", "kane" ) ) )
                .should( f.nested().objectField( "artists" )
                        .nest( matchFirstAndLastName(
                                f.withRoot( "artists" ),
                                "bill", "finger" ) ) ) )
        .fetchHits( 20 );

private SearchPredicate matchFirstAndLastName(SearchPredicateFactory f,
        String firstName, String lastName) {
    return f.bool()
            .must( f.match().field( "firstName" )
                    .matching( firstName ) )
            .must( f.match().field( "lastName" )
                    .matching( lastName ) )
            .toPredicate();
}

Conditional mass indexing

Hibernate Search 6.1 introduces the ability to apply the mass indexer to a subset of your entities, based on an HQL/JPQL "where" clause.

SearchSession searchSession = Search.session( entityManager );
MassIndexer massIndexer = searchSession.massIndexer();
massIndexer.type( Book.class ).reindexOnly( "e.publicationYear <= 2100" );
massIndexer.type( Author.class ).reindexOnly( "e.birthDate < :birthDate" )
        .param( "birthDate", LocalDate.ofYearDay( 2100, 77 ) );
massIndexer.startAndWait();

Named predicates

Hibernate Search 6.1 adds named predicates, a way to define the search logic as part of a custom binder/bridge.

This is, in a way, the comeback of the "full-text filters" of Hibernate Search 5.

Custom ES index settings

Starting with Hibernate Search 6.1, you can provide Hibernate Search with JSON files containing the desired settings of your indexes, and Hibernate Search will automatically push these settings when it creates/updates the indexes.

Custom ES index mapping

Starting with Hibernate Search 6.1, you can provide Hibernate Search with JSON files containing part of the desired mapping of your indexes, and Hibernate Search will automatically merge this mapping with the one it generated, so that it gets pushed to Elasticsearch when it creates/updates the indexes.

This is especially useful to set top-level mapping attributes, for example disabling the _source field.

Access to Lucene’s IndexReader

Starting with Hibernate Search 6.1, you can now retrieve an IndexReader when using the Lucene backend:

SearchMapping mapping = Search.mapping( entityManagerFactory );
LuceneIndexScope indexScope = mapping
        .scope( Book.class ).extension( LuceneExtension.get() );
try ( IndexReader indexReader = indexScope.openIndexReader() ) {
    // work with the low-level index reader:
    numDocs = indexReader.numDocs();
}

While generally not necessary, this can be useful for advanced, low-level operations.

Lucene low-level hit caching

Starting with version 6.1, Hibernate Search allows configuring the QueryCache and QueryCachingPolicy in the Lucene backend, adding one more performance tweak for advanced Lucene users.

Lucene analyzer definition using tokenizer/filter names

Starting with Hibernate Search 6.1, a LuceneAnalysisConfigurer can be implemented without referring to Lucene classes at all, referring to tokenizers and filters using their name instead.

This is useful in some modular environments where the application might have access to Hibernate Search classes, but not to Lucene classes.

Jakarta EE

Starting with Hibernate Search 6.1, beside the traditional artifacts targeting Java EE (JPA, CDI, …​), Hibernate Search now provides alternative, experimental artifacts that target Jakarta EE 9.1 (Jakarta Persistence 3, Jakarta CDI 3).

These artifacts have their artifact ID suffixed with "-jakarta", similarly to the equivalent artifacts for Hibernate ORM (which you should use together).

The main artifacts (e.g. org.hibernate.search:hibernate-search-mapper-orm) still target Java EE.

Hibernate ORM 6

Starting with Hibernate Search 6.1, beside the traditional artifacts targeting Hibernate ORM 5.x, Hibernate Search now provides alternative, experimental artifacts that target Hibernate ORM 6 and Jakarta EE 9.1 (Jakarta Persistence 3, Jakarta CDI 3).

These artifacts have their artifact ID suffixed with "-orm6".

The main artifacts (e.g. org.hibernate.search:hibernate-search-mapper-orm) still target Hibernate ORM 5.x and Java EE.

Java modules

Starting with version 6.1, where possible, Hibernate Search now provides multi-release JARs with a full Java module definition that includes all the dependencies.

This excludes the Lucene backend in particular, because Lucene 8 has split packages.

Releases in this series

6.1.5.Final

2022-05-11

Upgrade to Hibernate ORM 5.6.8.Final, Upgrade to Hibernate ORM 6.0.1.Final for -orm6 artifacts, upgrade to latest version of Jakarta dependencies for -orm6/-jakarta artifacts, bugfixes.

How to get it Getting started

Maven artifacts Download Resolved issues Release announcement

6.1.4.Final

2022-04-07

Upgrade to Hibernate ORM 6.0.0.Final for -orm6 artifacts, upgrade to latest version of Jakarta dependencies for -orm6/-jakarta artifacts, bugfixes.

Maven artifacts Download Resolved issues Release announcement

6.1.3.Final

2022-03-18

6.1.2.Final

2022-03-17

Upgrade to Hibernate ORM 6.0.0.CR2 for '-orm6' artifacts, documentation fixes.

Maven artifacts Download Resolved issues Release announcement

6.1.1.Final

2022-02-07

Upgrade to Hibernate ORM 5.6.5.Final (and 6.0.0.CR1 for '-orm6' artifacts), documentation fixes.

Maven artifacts Download Resolved issues Release announcement

6.1.0.Final

2022-01-25

Upgrade to Hibernate ORM 5.6.4.Final, small Jakarta EE compatibility improvements.

Maven artifacts Download Resolved issues Release announcement

6.1.0.CR1

2022-01-18

Better defaults and optional operators for the regexp predicate, additional Maven artifacts compatible with Hibernate ORM 6, bugfixes.

Maven artifacts Download Resolved issues Release announcement

6.1.0.Beta2

2022-01-05

Persistence and management of aborted events with the "outbox-polling" coordination, definition of Lucene analyzers without referring to Lucene classes, Elasticsearch 7.16 compatibility, OpenSearch 1.2 compatibility, bugfixes.

Maven artifacts Download Resolved issues Release announcement

6.1.0.Beta1

2021-12-03

"outbox-polling" coordination strategy scales dynamically, supports multi-tenancy, and pauses during mass indexing; new Jakarta EE artifacts, custom JSON mapping for the Elasticsearch backend, upgrade to Hibernate ORM 5.5.6.Final and Lucene 8.8.

Maven artifacts Download Resolved issues Release announcement

6.1.0.Alpha1

2021-09-09

Database-polling coordination with static sharding only, OpenSearch compatibility, terms/regexp predicates, id projection, conditional mass indexing, upgrade to Hibernate ORM 5.5.6.Final and Lucene 8.8, compatibility with Elasticsearch 7.13.

Maven artifacts Download Resolved issues Release announcement

Back to top