6.0 series - Hibernate Search

Compatibility

Java	8, 11 or 17
Hibernate ORM	5.4 (>= 5.4.4.Final), 5.5 or 5.6
Elasticsearch server	5.6 - 7.10
Apache Lucene	8.7

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.0 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.0 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

Lucene backend

Elasticsearch backend

Amazon IAM authentication for Elasticsearch

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

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

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.

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.0 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

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 relies on Hibernate ORM 5.4.

Note that only Hibernate ORM 5.4.4.Final or later will work correctly; 5.4.3.Final and earlier will not.

Lucene 8: The Lucene backend now uses Lucene 8.7.

Elasticsearch 7: The Elasticsearch backend now works with Elasticsearch 5.6, 6.8 or 7.10. Support for older versions of Elasticsearch was dropped.

API overhaul

This is perhaps the most important aspect of Hibernate Search 6: most APIs have changed. We didn’t take this decision lightly, and we don’t intend to do this again anytime soon: at this point, breaking APIs was necessary for Hibernate Search to keep improving.

The primary goal of this overhaul was to abstract away Lucene APIs, so that the Elasticsearch backend can become a first-class citizen, implemented without any hacks or unnecessary dependencies.

It goes without saying, but the Lucene backend will remain as important as ever. In fact, abstracting away Lucene APIs is good for the Lucene backend too: it will give the Hibernate Search project the ability to upgrade Lucene as soon as new versions are released.

Another benefit of the overhaul: since APIs had to change anyway, we took that opportunity to implement long-overdue improvements that also required API changes. See the following sections to know more about these improvements.

Safer, more concise, backend-agnostic Search DSL

The Search DSL is brand new, with several improvements:

Safer

Search hits now have a type, even when projecting thanks to the brand-new projection DSL.
The implementation for numeric predicates (e.g. int-based, long-based, double-based) is now determined from the type of the targeted field, instead of the type of arguments. This is safer when passing arguments with the wrong type: where Hibernate Search 5 would have generated a predicate that doesn’t match anything, Hibernate Search 6 will detect the type mismatch and will throw an exception.

More concise

Ability to use lambdas for more concise query definition, even when queries are complex.
Simpler syntax for predicates when targeting multiple types in a single query: instantiating multiple QueryBuilders is no longer needed, Hibernate Search takes into account that multiple types are targeted and automatically checks that targeted fields are compatible across all targeted indexes.

More consistent

The API types consistently use the Search prefix: no more mixing FullText with Search or simply no prefix.
The SearchQuery type (previously FullTextQuery) now defines its own methods instead of extending JPA’s TypeQuery, highlighting the fact that it targets an index and not a database, and making it a friendlier API. When necessary, it is still possible to retrieve an adapter that implements JPA’s TypeQuery.

Backend-agnostic by default, with backend-specific extensions

As explained in API overhaul, the Search DSL no longer exposes Lucene-specific types by default. When necessary, native Lucene queries can still be used (see below).
Injection of native predicates (org.apache.lucene.search.Query for Lucene, JSON for Elasticsearch) within DSL-created predicates. This is not new for the Lucene integration, but it is for the Elasticsearch integration. See predicate extensions.
Injection of native sorts and aggregations within DSL-created Hibernate Search queries.
Ability to directly manipulate the JSON of Elasticsearch requests/responses.

More features

A new id predicate.
A new exists predicate.
Ability to override analyzers on a per-predicate basis.
Better support for multi-valued fields for sorts, projections and aggregations (faceting).

Easier mapping

Specialized @*Field annotations

Hibernate Search 6 offers separate @*Field annotations for each major field type: @GenericField works in most cases, but you can access more options (analysis, …) with @FullTextField, @KeywordField, …

This way, each annotation offers the options that make sense for the selected field types, and only those options. No longer will you end up disabling analysis on a numeric field!

Simpler mapping of container types

@*Field annotations can be applied directly to List<String> or OptionalInt in order to index the "contained" elements, thanks to container extractors.
For more complex types (e.g. Map<String, Integer>), the container extractor can be selected explicitly.

More features

Ability to define a searchAnalyzer, to analyze search queries differently from indexed text (useful for auto-complete in particular).
Ability to map scaled numbers (BigDecimal/BigInteger) with @ScaledNumberField.

More powerful, backend-agnostic bridges

The new Bridge APIs are different and vastly improved.

Full control over field definitions

Bridges can declare field types precisely, allowing in particular to pick an analyzer or to enable aggregation (faceting) on a bridge-declared field.
Bridges targeting non-String fields are now first-class citizens: when targeting bridge-declared, non-String fields in the Search DSL, you will no longer have to bypass bridges (.ignoreFieldBridge()) like you had to in Search 5.
Bridges can declare dynamic fields with a precise type which the Search DSL will be aware of.

Full control over automatic reindexing

Bridges can declare the properties they rely on, allowing Hibernate Search to reindex less frequently.

Custom bridge annotations

Bridges can be applied with custom annotations, allowing clearer mappings, especially when bridges are parameterized.

For more information about bridges, see this section of the documentation.

Backend-agnostic

Field declarations do not involve any Lucene API by default.
However, bridges can still declare native fields when necessary, be it with Lucene or Elasticsearch.

Easier to configure, smarter automatic indexing

Automatic resolution of reindexing requirements

@ContainedIn is no longer needed: when using @IndexedEmbedded on an association, Hibernate Search 6 infers the inverse side of the association from Hibernate ORM metadata, which allows it to automatically reindex the class hosting the @IndexedEmbedded annotation when the target of the association changes.
When the inverse side of an association cannot be resolved, Hibernate Search 6 will report a mapping error on bootstrap, allowing you to detect risks of out-of-sync indexes early.

Easy override of reindexing requirements

You can opt out of automatic reindexing locally using @IndexingDependency(reindexOnUpdate = …).
You can declare the dependencies of a @Transient, indexed property using @IndexingDependency(derivedFrom = …).

Easy configuration of indexing synchronization

Some want more performance with asynchronous automatic indexing, others prefer data safety and immediate visibility of indexed documents with synchronous automatic indexing. With Hibernate Search 6, this can all be configured with a single configuration property.

Smarter change processing

Hibernate Search 6 is smarter when processing changes on complex entity graphs.

When a property changes in an entity that is indexed-embedded in multiple other entities, Hibernate Search 6 will only traverse associations to entities that are actually affected by the change, based on @IndexedEmbedded(includePaths = …) and other metadata.

More flexible schema management

Manage the schema on startup: Just like Hibernate Search 5, Hibernate Search 6 can manage the schema for you on startup. Or not: if this gets in the way, it can be disabled.
Manage the schema on demand: Unlike Hibernate Search 5, Hibernate Search 6 offers dedicated APIs to trigger schema operations on demand.
Manage the schema when mass indexing: The mass indexer can drop and re-create the schema automatically: you only have to call .dropAndCreateSchemaOnStart(true). With the Elasticsearch backend, this can be significantly faster than removing all documents from an existing schema.

Runtime joins with nested documents

Hibernate Search 6.0 introduces "nested" fields and predicates, similar to the feature with the same name in Elasticsearch.

This means in particular that indexed-embedded entities can be searched much more finely, for example searching for that one book whose author has a given first name and last name. With the right mapping and the right query, no longer will Hibernate Search return a book co-authored by "John Smith" and "Jane Doe" when you were looking for "John Doe"!

For details, see Structuring embedded elements as nested documents in the reference documentation.

And more

Better support for traditional JPA batch processes involving a periodic flush/clear: Hibernate Search 6 will buffer the documents to index upon flush(), to avoid the dreaded LazyInitializationException that Hibernate Search 5 would trigger.
Better reporting of errors on bootstrap: Hibernate Search will provide more context for each error, and will collect as many errors as possible before stopping.
…

Releases in this series

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

Hibernate Search

6.0 series end-of-life

API overhaul. Safer and more concise Search DSL, more powerful bridges, smarter automatic indexing, nested documents. Upgrades to Lucene 8 and Elasticsearch 7.

Compatibility

Documentation

How to get it

Maven, Gradle...

Direct download

Getting started

Migrating

What's new

Dependency upgrades

API overhaul

Safer, more concise, backend-agnostic Search DSL

Easier mapping

More powerful, backend-agnostic bridges

Easier to configure, smarter automatic indexing

More flexible schema management

Runtime joins with nested documents

And more

Releases in this series

Projects

Follow us

Contribute and community