In Relation To

Back to home

Hibernate Search 6.0.0.Beta11 released

Posted by    |      

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

This release mainly brings a default analyzer, a way to limit automatic reindexing to same-entity updates only, a new implementation for AWS IAM authentication, and a migration helper for applications moving from Search 5 to Search 6.

It also includes an upgrade to Lucene 8.6.2, and Hibernate ORM 5.4.22.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 Hibernate Search 5.

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

What’s new

Default analyzer

Both the Lucene backend and the Elasticsearch backend now have a default analyzer definition, which can be used even if you didn’t configure analysis.

Thanks to this new default analyzer, the analyzer attribute in @FullTextField(analyzer = …​) no longer needs to be set: for simple use cases, you can just use @FullTextField without any argument, which will create an index field using the default analyzer.

This should make experimenting with Hibernate Search easier, even if it’s unlikely that a single default analyzer will be enough for real-world applications.

For more information about the default analyzer, see here for Lucene and here for Elasticsearch.

ReindexOnUpdate.SHALLOW: limiting automatic reindexing to same-entity updates only

As of HSEARCH-4001, it is now possible to apply @IndexingDependency(reindexOnUpdate = ReindexOnUpdate.SHALLOW) to an association. If that association also has an @IndexedEmbedded, then:

  • When the @Indexed entity is indexed, the entities targeted by the association will be index-embedded as usual (no change here).

  • When the association changes (associated entities are added or removed), then the @Indexed entity will be automatically reindexed as usual (no change here.)

  • When the associated entities are modified (e.g. their name property change), the @Indexed entity will not be automatically reindexed.

This is especially useful for associations to "reference" entities (e.g. categories, types, cities, countries, …​) which are not expected to change and cannot possibly expose the inverse side of the association (e.g. city ⇒ address), which would be necessary for automatic reindexing.

For more information, head to this section of the documentation.

New implementation for AWS IAM authentication

The module org.hibernate.search:hibernate-search-backend-elasticsearch-aws provides AWS IAM authentication, so that applications can use AWS Elasticsearch Service as a backend, which is an alternative to an on-premises cluster or Elastic’s own cloud offering.

This module was re-implemented to rely on the AWS SDK instead of a third-party library. This fixed a known bug of request signing (HSEARCH-3655), and opened the way to other ways of providing credentials.

As of HSEARCH-3560, you can use all types of credentials supported by the AWS SDK, in particular EC2 instance roles. See this section of the documentation for more information.

As a result of re-implementing this module, configuration properties related to AWS authentication have changed. See Breaking changes for more details.

Migration helper for applications moving from Search 5 to Search 6

As of HSEARCH-3282, we publish two modules that provide partial compatibility with Hibernate Search 5 APIs backed by the Hibernate Search 6 implementations.

These modules should make migration easier by making sure that code relying on the most-used APIs (search DSL, …​) continues to compile and run. The idea is to use the migration helper temporarily to make most of the application code (search queries, …​) work, making it easier to focus on migrating configuration and to assess the effort required to migrate the remaining code.

These modules should not be used in production environments. They have limitations preventing full compatibility with Hibernate Search 5, and these limitations will never be addressed. All code in these modules is deprecated and will be removed in the next major version.

More information will come in the following weeks about how to use these modules when migrating, and what their limitations are. In particular, expect some updates to the migration guide soon.

Version upgrades

Hibernate Search 6 requires ORM 5.4.4.Final or later to work correctly. Earlier 5.4.x versions will lead to potentially cryptic runtime exceptions.

Breaking changes

  • HSEARCH-3560: the properties to configure AWS authentication have changed:

    • hibernate.search.backend.aws.signing.region is now hibernate.search.backend.aws.region.

    • In order to specify credentials statically in configuration properties, you must set hibernate.search.backend.aws.credentials.type to static and also set the following two properties.

    • hibernate.search.backend.aws.signing.access_key is now hibernate.search.backend.aws.credentials.access_key_id.

    • hibernate.search.backend.aws.signing.secret_key is now hibernate.search.backend.aws.credentials.secret_access_key.

    • hibernate.search.backend.aws.signing.enabled didn’t change.

  • HSEARCH-3994: org.hibernate.search.mapper.orm.mapping.SearchIndexedEntity is now deprecated and will be removed before the release of Hibernate Search 6.0.0.CR1. Use org.hibernate.search.mapper.orm.entity.SearchIndexedEntity instead.

  • The incubating interface org.hibernate.search.mapper.pojo.extractor.ContainerExtractor changed; see its javadoc for defails of the new interface.

  • The array container extractor was renamed to array-object. Variants were introduced for arrays of each primitive type (array-char, array-int, array-byte, …​). See org.hibernate.search.mapper.pojo.extractor.builtin.BuiltinContainerExtractors for a list of all available container extractors.

Documentation

Other improvements and bug fixes

  • HSEARCH-3071: Support for @IndexedEmbedded.includeEmbeddedObjectId has been restored.

  • HSEARCH-4025: Partial support for indexing entities with @IdClass if they have an explicit @DocumentId. Mass indexing doesn’t work at the moment (HSEARCH-4033).

  • HSEARCH-4002: MappingAnnotatedProperty (used in annotation processors) now exposes the type of the property for any given ContainerExtractorPath.

  • HSEARCH-4003: Repeatable annotations are now automatically expended when retrieved from MappingAnnotatedElement (used in annotation processors).

  • HSEARCH-3994: SearchScope now exposes metadata about the targeted types through SearchScope#includedTypes.

  • HSEARCH-3122: It is now possible to configure the default value of the dynamic attribute of Elasticsearch mappings. See this section of the documentation.

  • HSEARCH-3243: Hibernate Search will now reject identifier/value bridges whose compatibility with the bound property cannot be validated. As a rule of thumb, when implementing identifier/value bridges, the generic type parameter I or T should always be set to a raw class. For more advanced implementations, you should rely on an IdentifierBinder or ValueBinder.

  • HSEARCH-3864: A java.lang.Error thrown during mass indexing is no longer swallowed and are propagated to the caller.

  • HSEARCH-3997: Mapping arrays of primitive types (int[]/float[]/etc.) now works as expected: it no longer leads to a ClassCastException upon indexing.

  • HSEARCH-3998: Mass indexing a (non-abstract) parent class in a type hierarchy with a subclass annotated with @Indexed(enabled = false) will now correctly ignore that subclass.

  • HSEARCH-3999: Deleting an entity whose @ElementCollection is indexed-embedded in another entity no longer leads to LazyInitializationException.

  • HSEARCH-4009: Fixed a corner case where @IndexingDependency(derivedFrom = …​) would lead to bootstrap failure.

  • HSEARCH-4011: Hibernate Search ScrollableResults now throw a JPA QueryTimeoutException on timeout instead of SearchTimeoutException.

  • HSEARCH-4027: ScrollResult.timedOut() sometimes used to return false even though a timeout occurred with Lucene; this was fixed.

  • HSEARCH-4028: Elasticsearch’s SearchResultTotal now correctly reports an approximate total hit count after a timeout.

  • HSEARCH-3917: Performance improvement: Hibernate Search now uses TopScoreDocCollector instead of TopFieldDocCollector when a descending score sort is requested explicitly (not just when it’s the implicit default).

  • HSEARCH-3947: Performance improvement: Hibernate Search no longer creates huge arrays for collectors when a query does not set a limit to the amount of retrieved hits and there are fewer than 10,000 hits.

  • HSEARCH-4017: Performance improvement: the Lucene backend no longer scans index segments that don’t contain any returned hit when extracting projections.

  • HSEARCH-4018: Performance improvement: the Lucene backend now skips some filters when an index doesn’t have any nested documents.

  • HSEARCH-4019: Performance improvement: the Lucene backend now only uses a TotalHitCountCollector when absolutely necessary.

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