In Relation To

Back to home

Hibernate Search 6.0.0.Beta3 released

Posted by    |       Hibernate Search Lucene Elasticsearch Releases

Hibernate Search is a library that integrates Hibernate ORM with Apache Lucene or Elasticsearch by automatically indexing entities, enabling advanced search functionality: full-text, geospatial, aggregations and more. For more information, see Hibernate Search on hibernate.org.

We just published Hibernate Search 6.0.0.Beta3. This release mainly brings schema improvements, deep customization of Elasticsearch search requests, more powerful bridge definitions, and restores features such as the search query timeouts. It also includes upgrades to Lucene 8.3.0, Elasticsearch 7.5 and Hibernate ORM 5.4.10.Final.

Getting started with Hibernate Search 6

If you want to dive right into the new, shiny Hibernate Search 6, a good starting point is the getting started guide included in the reference documentation.

Hibernate Search 6 APIs differ significantly from Search 5.

For more information about migration and what we intend to do to help you, see the migration guide.

What’s new

Schema improvements

We made several improvements to the metadata fields stored in each document (identifier, type, …​), in order to only store what is strictly necessary and to rely on doc-values rather than stored fields (HSEARCH-3657).

Also, in the Elasticsearch backend, we added a new _entity_type field to better handle multi-index search queries targeting index aliases (HSEARCH-3765) and changed the name of fields used for discriminator-based multi-tenancy (now _tenant_id and _tenant_doc_id, see HSEARCH-3788).

These improvements come at a cost: when upgrading from Beta2 to Beta3, existing data will need to be reindexed.

Deep customization of Elasticsearch search requests

In HSEARCH-3496, new APIs were introduced to allow the manipulation of the JSON of Elasticsearch search requests and the retrieval of the response as raw JSON. This will allow leveraging Elasticsearch features that are not (yet) available in the Search DSL, such as suggesters, while still taking advantage of the DSL where possible (match predicate, sorts, projections, …​). See this section of the documentation for more information.

Also, since HSEARCH-3662, Elasticsearch aggregations can now be defined directly as JSON, in order to access aggregation types that are not yet exposed through the DSL. See this section of the documentation for examples.

More powerful bridge definitions

Bridges gained several improvements:

  • HSEARCH-3135: The concept of custom mapping annotations was streamlined: it is no longer limited to the type bridge and property bridge, and can now also be used for value bridges too. In fact, custom annotations can now apply pretty much every mapping feature: bridges, indexed-embedded, marking a type as indexed, …​

  • HSEARCH-3717: ValueBinder is no longer limited to standard field types: it can now bind a value to more exotic field types, such as a "native" Elasticsearch field whose content is defined as JSON directly.

  • HSEARCH-3766: Custom annotations are now optional for type and property bridges. To apply a bridge that does not define a dedicated annotation, just apply the built-in @TypeBinding(…​)/@PropertyBinding(…​) annotations to the type/property, setting its attribute to a reference to your binder. Bridges applied this way cannot be parameterized.

For up-to-date information about bridges and how to use them, see the dedicated section in the reference documentation.

exists predicate can now target object fields

The exists predicate introduced in Search 6 can now target object fields (HSEARCH-2389). An object field will be considered as existing in a given document when it has at least one existing (non-null) sub-field in that document.

In the example below, all clients that have an order with at least one non-null indexed field will be present in the result:

List<Client> clientsWithAtLeastOneOrder = searchSession.search(Client.class)
    .predicate(f -> f.exists().field("orders"))
    .fetch( 20 );

Search query timeouts are back

As of HSEARCH-3352, it is once again possible to set timeouts on search queries, similarly to what was possible in Search 5.

Two kinds of timeouts are available:

  • failAfter(long, TimeUnit): a "hard" timeout that will abort the search query and throw an exception;

  • truncateAfter(long, TimeUnit): a "soft" timeout that will stop the result collection and return a truncated result.

These timeouts are available for both the Lucene backend and the Elasticsearch backend.

Additionally, as of HSEARCH-3456, the SearchResult interface now exposes information about the query execution time (getTook()) and a flag indicating whether the query timed out (isTimedOut()).

See the dedicated section in the reference documentation for more information.

Version upgrades

Hibernate Search 6 requires ORM 5.4.4.Final or later to work correctly. Earlier 5.4.x versions will not work correctly.

Backward-incompatible API changes

  • Configuration:

    • HSEARCH-3756: Multi-valued configuration properties now must be specified using commas as a separator, instead of blanks. This affects in particular the configuration of Elasticsearch hosts.

    • HSEARCH-3757: The protocol used to contact Elasticsearch (http or https) must now be specified separately in the dedicated hibernate.search.backends.<backend name>.protocol property. It can no longer be specified as part of the hibernate.search.backends.<backend name>.hosts property.

  • Bridges:

    • HSEARCH-3135: The *Binder interfaces no longer have a generic type parameter nor an initialize() method. Processing of custom annotations, for bridges or otherwise, are now implemented by meta-annotating the custom annotation with @TypeMapping or @PropertyMapping and implementing the dedicated interface TypeMappingAnnotationProcessor or PropertyMappingAnnotationProcessor. Binders that do not need to accept parameters can be applied directly to a type/property using the built-in @TypeBinding or @PropertyBinding annotation.

    • HSEARCH-3748: Some methods related to bridges in the programmatic API that couldn’t possibly work were removed.

  • Miscellaneous:

    • HSEARCH-3712: The API for defining DSL converters and projection converters on field types now uses different, simpler interfaces.

    • HSEARCH-3761: Elasticsearch APIs that produce or accept JSON now use GSON types (JsonObject, JsonElement, …​) rather than Strings.

Documentation

Other improvements and bug fixes

  • HSEARCH-1401: Allow integrators to declare entities whose structure is defined programmatically ("free-form").

  • HSEARCH-3634: Clarify the error message when a @javax.persistence.Transient property is missing a @IndexingDependency annotation.

  • HSEARCH-3764: It is now possible to disable value conversion in the id() predicate, so as to pass the document ID (a string) directly.

  • HSEARCH-3783: query.explain() with the Elasticsearch backend no longer fails when using projections or multi-tenancy.

  • HSEARCH-3693: Some missing log messages from Search 5, in particular the Hibernate Search version displayed on startup, were restored.

And more. For a full list of changes since the previous releases, please see the release notes.

How to get this release

All details are available and up to date on the dedicated page on hibernate.org.

Feedback, issues, ideas?

To get in touch, use the following channels:

Back to top