Hibernate Search 6.2.0.Final is out!

We are pleased to announce the release of Hibernate Search 6.2.0.Final.

This release brings in particular a new standalone POJO Mapper, mapping of classes/records to projections using @ProjectionConstructor, highlighting, Elasticsearch schema export, and more bugfixes and improvements.

6.2.0.Final also includes compatibility with Elasticsearch 8.8 and OpenSearch 2.8, as well as an upgrade of -orm6 artifacts to Hibernate ORM 6.2.

What’s new compared to Hibernate Search 6.1

Dependency upgrades

Hibernate ORM: Hibernate Search still depends on Hibernate ORM 5.6 by default. -orm6 artifacts depend on Hibernate ORM 6.2.

Lucene: The Lucene backend still uses Lucene 8.11.

Elasticsearch: The Elasticsearch backend now works with Elasticsearch 8.8 and 7.17 as well as other versions that were already compatible.

OpenSearch: The Elasticsearch backend now works with OpenSearch 1.3 and 2.8 as well as other versions that were already compatible.

Standalone POJO Mapper

The Standalone POJO Mapper enables mapping arbitrary POJOs to indexes.

Its key feature compared to the Hibernate ORM integration is its ability to run without Hibernate ORM or a relational database. It can be used to index entities coming from an arbitrary datastore or even (though that’s not recommended in general) to use Lucene or Elasticsearch as a primary datastore.

For more information about the Standalone POJO Mapper, see this section of the reference documentation.

To get started with the Standalone POJO Mapper, see this getting started guide.

Mapping index content to custom types (projection constructors)

Hibernate Search now offers the ability to define projections through the mapping of custom types (typically records), by applying the @ProjectionConstructor annotation to those types or their constructor:

@ProjectionConstructor
public record MyBookProjection(String title, List<Author> authors) {
    @ProjectionConstructor
    public record Author(String firstName, String lastName) {
    }
}

Executing such a projection then becomes as easy as referencing the custom type:

List<MyBookProjection> hits = searchSession.search( Book.class )
        .select( MyBookProjection.class )
        .where( f -> f.matchAll() )
        .fetchHits( 20 );

More advanced projections can be configured through explicit annotations, for example a projection to the entity identifier:

@ProjectionConstructor
public record MyBookIdAndTitleProjection(
        @IdProjection (1)
        Integer id,
        String title (2)
) {
}

1	Projects to the entity identifier (explicit projection through an explicit annotation)
2	Projects to field `title` (implicit projection)

Explicit annotations also allow configuring field projections more precisely, for example setting the path of a field projection to something else than just the name of the constructor parameter:

@ProjectionConstructor
public record MyBookTitleAndAuthorNamesProjection(
        @FieldProjection (1)
        String title,
        @FieldProjection(path = "authors.lastName") (2)
        List<String> authorLastNames
) {
}

1	Projects to field `title` (path derived from the name of the constructor parameter)
2	Projects to field `authors.lastName` (explicit path)

See this section of the reference documentation for more information.

Highlighting

Hibernate Search now offers a new feature in the Search DSL: highlighting.

Highlighting is a projection that returns fragments from full-text fields of matched documents that caused a query match. Specific terms that caused the match are "highlighted" with a pair of opening and closing tags. It can help a user to quickly identify the information they were searching for on a results page.

For example, one can enable highlighting on a full-text field like this:

@Entity
@Indexed
public class Book {
    @Id
    private Integer id;

    @FullTextField(analyzer = "english")
    private String title;

    @FullTextField(analyzer = "english", projectable = Projectable.YES)
    private String description;
}

And then retrieve highlights like this:

SearchSession searchSession = /* ... */

List<List<String>> result = searchSession.search( Book.class )
        .select( f -> f.highlight( "description" ) )
        .where( f -> f.match().field( "description" ).matching( "robot" ) )
        .fetchHits( 20 );

Which can for example return the following highlights:

# Hit #0
["A <em>robot</em> becomes self-aware."]
# Hit #1
["A <em>robot</em> helps investigate a murder on an extrasolar colony.",
 "On this planet, <em>robots</em> are used extensively."]
# etc.

This is a simple example, but highligting can be configured extensively. See this section of the reference documentation for more information.

Indexing plan filters

Hibernate Search now allows enabling/disabling indexing in indexing plans (which includes in particular listener-triggered indexing), both fully (for all types) or on a per-type basis.

For example, the following will disable automatic indexing for future changes on all instances of the class Company, except for instances of its subclass Customer:

SearchMapping searchMapping = /* ... */
searchMapping.indexingPlanFilter(
        ctx -> ctx.exclude( Company.class )
                .include( Customer.class )
);

Indexing plan filters can also be configured per-session (though limitations apply when using the outbox-polling coordination strategy):

SearchSession searchSession = /* ... */
searchSession.indexingPlanFilter(
        ctx -> ctx.exclude( Company.class )
                .include( Customer.class )
);

See this section of the reference documentation for more information.

Mapping improvements

@IndexedEmbedded(excludePaths = …): The @IndexedEmbedded annotation now exposes an excludePaths attribute, allowing the inclusion of all paths with only a few selectively excluded, as opposed to the pre-existing approach of selectively including paths with includePaths.

See this section of the reference documentation for more information.
Projectable fields: All fields are now projectable by default with the Elasticsearch backend.

This change was made because making a field projectable doesn’t incur any performance penalty with the Elasticsearch backend.

Since making a field projectable does have an impact on performance with the Lucene backend, the defaults with the Lucene backend didn’t change: Lucene fields still need to be made projectable explicitly.

Search DSL improvements

Simpler boolean operators with the and/or/not predicates

For simpler use cases, you can now avoid the rather complex bool predicate and use the new and/or/not predicates instead:

List<Book> hits = searchSession.search( Book.class )
        .where( f -> f.and(
                        f.match().field( "title" )
                                .matching( "robot" ),
                        f.match().field( "description" )
                                .matching( "crime" )
        ) )
        .fetchHits( 20 );

List<Book> hits = searchSession.search( Book.class )
        .where( f -> f.or(
                        f.match().field( "title" )
                                .matching( "robot" ),
                        f.match().field( "description" )
                                .matching( "investigation" )
        ) )
        .fetchHits( 20 );

List<Book> hits = searchSession.search( Book.class )
        .where( f -> f.not(
                f.match()
                        .field( "genre" )
                        .matching( Genre.SCIENCE_FICTION )
        ) )
        .fetchHits( 20 );

Shorter syntax for complex, root boolean predicates

Instead of .where( f → f.bool( b → … ) ), you can now use .where( (f, b) → … ):

MySearchParameters searchParameters = getSearchParameters();
List<Book> hits = searchSession.search( Book.class )
        .where( (f, root) -> {
            root.add( f.matchAll() );
            if ( searchParameters.getGenreFilter() != null ) {
                root.add( f.match().field( "genre" )
                        .matching( searchParameters.getGenreFilter() ) );
            }
            if ( searchParameters.getFullTextFilter() != null ) {
                root.add( f.match().fields( "title", "description" )
                        .matching( searchParameters.getFullTextFilter() ) );
            }
            if ( searchParameters.getPageCountMaxFilter() != null ) {
                root.add( f.range().field( "pageCount" )
                        .atMost( searchParameters.getPageCountMaxFilter() ) );
            }
        } )
        .fetchHits( 20 );

The older syntax has been deprecated in favor of the new one.

Clearer syntax for complex, non-root boolean predicates

Instead of f.bool( b → … ), you can now use f.bool().with( b → … ):

MySearchParameters searchParameters = getSearchParameters();
List<Book> hits = searchSession.search( Book.class )
        .where( (f, b) -> {
            b.must( f.matchAll() );
            if ( searchParameters.getGenreFilter() != null ) {
                b.must( f.match().field( "genre" )
                        .matching( searchParameters.getGenreFilter() ) );
            }
            if ( !searchParameters.getAuthorFilters().isEmpty() ) {
                b.must( f.bool().with( b2 -> {
                    for ( String authorFilter : searchParameters.getAuthorFilters() ) {
                        b2.should( f.match().fields( "authors.firstName", "authors.lastName" )
                                .matching( authorFilter ) );
                    }
                } ) );
            }
        } )
        .fetchHits( 20 );

The older syntax has been deprecated in favor of the new one.

Clearer syntax for the nested predicate

Instead of f.nested().objectField( … ).nest( f.bool().must( … ) ), you can now use f.nested( … ).add( … ):

List<Book> hits = searchSession.search( Book.class )
        .where( f -> f.nested( "authors" )
                .add( f.match().field( "authors.firstName" )
                        .matching( "isaac" ) )
                .add( f.match().field( "authors.lastName" )
                        .matching( "asimov" ) ) )
        .fetchHits( 20 );

The older syntax has been deprecated in favor of the new one.

New matchNone predicate

The matchNone predicate matches no documents.

List<Book> hits = searchSession.search( Book.class )
        .where( f -> f.matchNone() )
        .fetchHits( 20 );

New syntax for composite projections

The definition of composite projections is now possible with a fluent syntax:

List<MyPair<String, Genre>> hits = searchSession.search( Book.class )
        .select( f -> f.composite()
                .from( f.field( "title", String.class ),
                        f.field( "genre", Genre.class ) )
                .as( MyPair::new ) )
        .where( f -> f.matchAll() )
        .fetchHits( 20 );

Most older syntaxes have been deprecated in favor of the new one.

New object projection

The object projection yields one projected value for each object in a given object field.

List<List<MyAuthorName>> hits = searchSession.search( Book.class )
        .select( f -> f.object( "authors" )
                .from( f.field( "authors.firstName", String.class ),
                        f.field( "authors.lastName", String.class ) )
                .as( MyAuthorName::new )
                .multi() )
        .where( f -> f.matchAll() )
        .fetchHits( 20 );

New constant projection

The constant projection returns the same value for every single document, the value being provided when defining the projection.

Instant searchRequestTimestamp = Instant.now();
List<MyPair<Integer, Instant>> hits = searchSession.search( Book.class )
        .select( f -> f.composite()
                .from( f.id( Integer.class ), f.constant( searchRequestTimestamp ) )
                .as( MyPair::new ) )
        .where( f -> f.matchAll() )
        .fetchHits( 20 );

.missing().lowest()/.missing().highest() options in sorts

When sorting on a field that may not have a value for some documents, it was already possible to use .missing().first()/.missing().last() to tell Hibernate Search to put such documents in first/last position (respectively), regardless of sorting order (ascending/descending).

It is now possible, as an alternative, to use .missing().lowest()/.missing().highest() to tell Hibernate Search to consider such documents as having the lowest/highest value (respectively), taking into account sorting order (ascending/descending):

.missing().lowest() puts documents with no value in the first position when using ascending order or in the last position when using descending order.
.missing().highest() puts documents with no value in the last position when using ascending order or in the first position when using descending order.

This is mostly useful when the position of missing values is hardcoded, but the sort order is given by the user:

SortOrder orderFromUser = /* ... */;
List<Book> hits = searchSession.search( Book.class )
        .where( f -> f.matchAll() )
        .sort( f -> f.field( "pageCount" ).missing().lowest().order( orderFromuser ) )
        .fetchHits( 20 );

Mass indexing improvements

Mass indexing multiple tenants: In multi-tenant applications, mass indexing can now handle multiple tenants at once, provided you don’t pass any tenant identifier when creating the mass indexer, and you provided a list of tenants in the Hibernate Search configuration. See this section of the reference documentation for more information.
Setting up thread locals during mass indexing: The mass indexer now has a concept of "mass indexing environment", allowing for instance to set up custom thread locals in mass indexing threads. See the environment parameter in this section of the reference documentation for more information.
Better exception handling: Exceptions thrown by Hibernate ORM during mass indexing are now passed to the failure handler as every other exception, instead of aborting the whole mass indexing.
Smarter defaults for parameters: purgeAllOnStart is now disabled by default in the mass indexer when dropAndCreateSchemaOnStart is enabled.

`outbox-polling` coordination improvements

Outbox events and agents now use UUIDs for their identifiers: The primary key of the relevant tables are now using UUIDs instead of longs, to avoid reliance on sequences that were slowing down event processing on some databases. The migration guide includes migration scripts for the necessary database schema changes.
Customizable database schema: Simple, straightforward configuration properties now allow customizing the database schema involved in Hibernate Search’s outbox-polling coordination strategy: table names, schema and catalog, type of UUID columns as well as UUID generation strategy (random vs. time). See this section of the reference documentation for more information.

Elasticsearch schema export

It is now possible to export the Elasticsearch schema that Hibernate Search expects to JSON files on the filesystem:

SearchSchemaManager schemaManager = searchSession.schemaManager();
schemaManager.exportExpectedSchema( Path.of( "mydirectory" ) );

The code above will result in a directory tree similar to this:

# For the default backend: backend/indexes/<index-name>/<file>
mydirectory/backend/indexes/customer/create-index.json
mydirectory/backend/indexes/customer/create-index-query-params.json
mydirectory/backend/indexes/order/create-index.json
mydirectory/backend/indexes/order/create-index-query-params.json
# For additional named backends: backend/<backend-name>/indexes/<index-name>/<file>
mydirectory/backends/auth/indexes/user/create-index.json
mydirectory/backends/auth/indexes/user/create-index-query-params.json
mydirectory/backends/auth/indexes/usergroup/create-index.json
mydirectory/backends/auth/indexes/usergroup/create-index-query-params.json

See this section of the reference documentation for more information.

What’s new compared to Hibernate Search 6.2.0.CR1

For a list of changes since 6.2.0.CR1 only, refer to the release notes.

How to get this release

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

Getting started, migrating

For new applications, refer to the getting started guide:

For existing applications, Hibernate Search 6.2 is a drop-in replacement for 6.1, assuming you also upgrade the dependencies. Information about deprecated configuration and API is included in the migration guide.

Feedback, issues, ideas?

To get in touch, use the following channels:

hibernate-search tag on Stackoverflow (usage questions)
User forum (usage questions, general feedback)
Issue tracker (bug reports, feature requests)
Mailing list (development-related discussions)

In Relation To