6.1 series - Hibernate Search

Compatibility

Java	8, 11, 17 or 18
Hibernate ORM	5.6 in the main artifacts, 6.0 - 6.2 through `*-orm6` artifacts
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 and Maintenance 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

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

Maven, Gradle...

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 ORM mapper (Hibernate ORM 6)

"outbox-polling" coordination strategy for the Hibernate ORM mapper (Hibernate ORM 6)

Lucene backend

Elasticsearch/OpenSearch backend

Amazon IAM authentication for Elasticsearch/OpenSearch

Batch for Java (JSR-352) mass indexing job for the Hibernate ORM mapper - Core (Hibernate ORM 6)

Batch for Java (JSR-352) mass indexing job for the Hibernate ORM mapper - JBeret specifics (Hibernate ORM 6)

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

Hibernate ORM mapper (Hibernate ORM 5)

"outbox-polling" coordination strategy for the Hibernate ORM mapper (Hibernate ORM 5)

Batch for Java (JSR-352) mass indexing job for the Hibernate ORM mapper - Core (Hibernate ORM 5)

Batch for Java (JSR-352) mass indexing job for the Hibernate ORM mapper - JBeret specifics (Hibernate ORM 5)

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

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.

Getting started

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

Migrating

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

HTML PDF

What's new

Latest release announcement (2023-01-31): 6.1.8.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 with Hibernate ORM 6.0 or 6.1 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

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

Hibernate Search

6.1 series end-of-life

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

Documentation

How to get it

Maven, Gradle...

Direct download

Getting started

Migrating

What's new

Dependency upgrades

Asynchronous, distributed automatic indexing

OpenSearch compatibility

Search DSL improvements

Conditional mass indexing

Named predicates

Custom ES index settings

Custom ES index mapping

Access to Lucene’s `IndexReader`

Lucene low-level hit caching

Lucene analyzer definition using tokenizer/filter names

Jakarta EE

Hibernate ORM 6

Java modules

Releases in this series

Projects

Follow us

Contribute and community

Hibernate Search

6.1 series end-of-life

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

Documentation

How to get it

Maven, Gradle...

Direct download

Getting started

Migrating

What's new

Dependency upgrades

Asynchronous, distributed automatic indexing

OpenSearch compatibility

Search DSL improvements

Conditional mass indexing

Named predicates

Custom ES index settings

Custom ES index mapping

Access to Lucene’s IndexReader

Lucene low-level hit caching

Lucene analyzer definition using tokenizer/filter names

Jakarta EE

Hibernate ORM 6

Java modules

Releases in this series

Projects

Follow us

Contribute and community

Access to Lucene’s `IndexReader`