In Relation To

Back to home

Hibernate Search 6.0.0.Beta1 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.

Hibernate Search 6 just reached Beta status with the release of version 6.0.0.Beta1. This release clears the last remaining major hurdles: it fixes the few remaining inconsistencies in APIs, and completes the documentation of the major features. This release also introduces aggregations, similar to Search 5’s faceting feature.

What the Beta status means

Essentially, reaching Beta status means Hibernate Search 6 will be more stable from now on:

  • The most commonly used APIs are not expected to change anymore.

  • The implementations are well-tested and work as expected.

  • The reference documentation covers all common use cases and most advanced use cases, and shouldn’t change much before the final release.

It’s still a Beta, not a Candidate Release, because a significant amount of work still remains before the final release:

  • Some of the less commonly used features such as scrolling or error handlers are still missing.

  • Some improvements over Search 5 such as search analyzers or zero-downtime mass indexing are still missing.

  • Performance is satisfying (no obvious bottlenecks), but needs more thorough testing.

  • Depending on the changes needed to solve the above, we may still change the index format in later Betas, which will require reindexing.

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

Aggregation DSL

As of HSEARCH-3649, Hibernate Search 6 now offers a DSL to build aggregations, i.e. aggregated results based on all hits for a given search query.

Supported aggregations are rather simple for now, but more will be added later:

  • Terms aggregations produce a count of the number of hits for each value of a given field:

    AggregationKey<Map<Genre, Long>> countsByGenreKey =
        AggregationKey.of( "countsByGenre" );
SearchResult<Book> result = searchSession.search( Book.class )
        .predicate( f -> f.matchAll() )
        .aggregation( countsByGenreKey, f -> f.terms()
                .field( "genre", Genre.class ) )
        .fetch( 20 );
Map<Genre, Long> countsByGenre = result.getAggregation( countsByGenreKey );

  • Given a set of ranges, range aggregations produce a count of the number of hits for each range of values of a given field:

    AggregationKey<Map<Range<Double>, Long>> countsByPriceKey =
        AggregationKey.of( "countsByPrice" );
SearchResult<Book> result = searchSession.search( Book.class )
        .predicate( f -> f.matchAll() )
        .aggregation( countsByPriceKey, f -> f.range()
                .field( "price", Double.class )
                .range( 0.0, 10.0 )
                .range( 10.0, 20.0 )
                .range( 20.0, null )
        )
        .fetch( 20 );
Map<Range<Double>, Long> countsByPrice = result.getAggregation( countsByPriceKey );

This provides all the features that were provided by Hibernate Search 5’s "faceting" feature, with the exception of "drill-down", which is straightforward to reproduce using the predicate DSL. In addition, the new aggregation feature solves several long-standing issues of faceting in Search 5:

  • HSEARCH-1372/HSEARCH-2111: The aggregation API uses clear, consistent naming.

  • HSEARCH-2472/HSEARCH-2954: Encoding is no longer limited to just numeric fields or text: fields with Java 8 date/time types can be aggregated too, for example LocalDate, and they use the dedicated date datatype in the Elasticsearch backend.

  • HSEARCH-1748: Attempts to create aggregations on unsupported fields will now trigger an exception during query building, instead of just returning empty results.

  • HSEARCH-2446: Aggregations (faceting) can now be used on fields declared by bridges.

  • Discrete aggregations no longer require to index numbers as text.

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.

Documentation

As of HSEARCH-3270, all major features of Hibernate Search 6 are documented.

Here are the sections we added or completed since the previous release:

Backward-incompatible API changes

There are quite a few backward-incompatible changes this time, as this was the last set of changes before the Betas.

  • HSEARCH-3705: The default index name for indexed entity types is now the entity name instead of the fully qualified class name.

  • HSEARCH-3707: The limit and offset parameters in SearchQuery.fetch(Integer, Integer) have been swapped.

  • HSEARCH-3669: The fetch()/fetchHits() methods are now deprecated: use fetchAll/fetchAllHits instead.

  • HSEARCH-3606: The SearchWriter was renamed to SearchWorkspace, and SearchSessionWritePlan was renamed to SearchIndexingPlan.

  • HSEARCH-3623: The syntax of analysis definition DSLs was updated:

    • It is no longer possible to chain analyzer/normalizer definition with the Lucene analysis definition DSL.

    • The methods prefixed with with in the Elasticsearch analysis definition DSL were deprecated in favor of new methods without this prefix (withTokenizer() ⇒ tokenizer()).

  • HSEARCH-3671: SearchScope is now session-independent. The main implication is you can no longer write scope.search(): use searchSession.search(scope) instead.

  • HSEARCH-3691: @GeoPointBinding can no longer be used on properties of type GeoPoint: use @GenericField instead.

  • HSEARCH-3687: Generic type parameters of DSL step interfaces have changed. This will only affect you if you store DSL steps in variables, which is not recommended (you should just chain calls).

  • HSEARCH-3708: The range predicate DSL now exposes a new syntax to define the range to match, leveraging the new Range class. The old syntax still works but it is deprecated.

  • HSEARCH-1347:

    • org.hibernate.search.mapper.pojo.dirtiness.ReindexOnUpdate was moved to org.hibernate.search.mapper.pojo.automaticindexing.ReindexOnUpdate

    • Package org.hibernate.search.engine.search.dsl.predicate was moved to org.hibernate.search.engine.search.predicate.dsl

    • Package org.hibernate.search.engine.search.dsl.sort was moved to org.hibernate.search.engine.search.sort.dsl

    • Package org.hibernate.search.engine.search.dsl.projection was moved to org.hibernate.search.engine.search.projection.dsl

    • Package org.hibernate.search.engine.search.dsl.aggregation was moved to org.hibernate.search.engine.search.aggregation.dsl

    • Package org.hibernate.search.backend.elasticsearch.search.dsl.predicate was moved to org.hibernate.search.backend.elasticsearch.search.predicate.dsl

    • Package org.hibernate.search.backend.elasticsearch.search.dsl.sort was moved to org.hibernate.search.backend.elasticsearch.search.sort.dsl

    • Package org.hibernate.search.backend.elasticsearch.search.dsl.projection was moved to org.hibernate.search.backend.elasticsearch.search.projection.dsl

    • Package org.hibernate.search.backend.elasticsearch.search.dsl.aggregation was moved to org.hibernate.search.backend.elasticsearch.search.aggregation.dsl

    • Package org.hibernate.search.backend.lucene.search.dsl.predicate was moved to org.hibernate.search.backend.lucene.search.predicate.dsl

    • Package org.hibernate.search.backend.lucene.search.dsl.sort was moved to org.hibernate.search.backend.lucene.search.sort.dsl

    • Package org.hibernate.search.backend.lucene.search.dsl.projection was moved to org.hibernate.search.backend.lucene.search.projection.dsl

    • Package org.hibernate.search.backend.lucene.search.dsl.aggregation was moved to org.hibernate.search.backend.lucene.search.aggregation.dsl

    • org.hibernate.search.engine.search.SearchPredicate was moved to org.hibernate.search.engine.search.predicate.SearchPredicate

    • org.hibernate.search.engine.search.SearchSort was moved to org.hibernate.search.engine.search.sort.SearchSort

    • org.hibernate.search.engine.search.SearchProjection was moved to org.hibernate.search.engine.search.projection.SearchProjection

    • org.hibernate.search.engine.search.DocumentReference was moved to org.hibernate.search.engine.backend.common.DocumentReference

  • HSEARCH-3441: DSL methods now use consistent wording.

    • In the programmatic mapping API:

      • withExtractor() was renamed to extractor()

      • withExtractors() was renamed to extractors()

      • withoutExtractors() was renamed to noExtractors()

    • In the predicate DSL:

      • onField()/orField()/onFields()/orFields() are now deprecated. Use the prefix-less versions instead (e.g. onField() ⇒ field()).

      • withConstantScore() is now deprecated: use constantScore() instead.

      • boostedTo() is now deprecated: use boost() instead.

      • withAndAsDefaultOperator() is now deprecated: use defaultOperator(BooleanOperator) instead.

      • withSlop() is now deprecated: use slop() instead.

    • In the sort DSL:

      • Methods prefixed with by are now deprecated. Use the prefix-less versions instead (e.g. byField() ⇒ field()).

      • onMissingValue() is now deprecated: use missing() instead.

      • sortLast() is now deprecated: use last() instead.

      • sortFirst() is now deprecated: use first() instead.

  • HSEARCH-859: Some configuration properties were changed for better consistency.

    • Configuration properties that were simply renamed:

      • hibernate.search.backends.myBackend.analysis_configurer → hibernate.search.backends.myBackend.analysis.configurer

      • hibernate.search.backends.myBackend.multi_tenancy_strategy → hibernate.search.backends.myBackend.multi_tenancy.strategy

      • hibernate.search.mapping_configurer → hibernate.search.mapping.configurer

      • hibernate.search.enable_annotation_mapping → hibernate.search.mapping.process_annotations

      • hibernate.search.autoregister_listeners → hibernate.search.enable

    • hibernate.search.enable_configuration_property_tracking was renamed to hibernate.search.configuration_property_checking.strategy and expected values also changed: default is warn, use ignore to disable checks.

    • Enums for configuration properties were relocated to appropriate packages.

    • Property keys listed in *Settings classes now include the hibernate.search. prefix where relevant. Use *Settings.Radicals for property keys without any prefix.

Other improvements and bug fixes

  • HSEARCH-3667: Hibernate Search 6 now works correctly when Hibernate Envers is enabled: it boots correctly and is able to index the latest version of versioned entities. Thanks to Damien Clement d’Huart for reporting this and providing a fix.

  • HSEARCH-2254: Single-valued sorts on fields within nested fields now work correctly.

  • HSEARCH-3715: It is once again possible to set a custom monitor when mass indexing.

  • HSEARCH-3670: java.util.Date properties holding a java.sql.Date value will now be correctly indexed.

  • HSEARCH-3690: Entity identifiers of type string are now correctly supported.

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