Hibernate Search

7.1 series latest stable

Vector search in both Lucene and Elasticsearch backends, allow looking up the capabilities of each field in the metamodel, new query string predicate, simplify entity registration in the Standalone POJO mapper, compatibility with Elasticsearch 8.12/8.13 and OpenSearch 2.12/2.13, upgrade to Lucene 9.9, other bugfixes, improvements and upgrades

Compatibility

Java 11, 17 or 21
Hibernate ORM 6.4
Elasticsearch server 7.10 - 8.13
OpenSearch server 1.3 - 2.13
Apache Lucene 9.9

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 7.1 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

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.

org.hibernate.search:hibernate-search-bom:7.1.1.Final
Hibernate Search BOM
org.hibernate.search:hibernate-search-mapper-orm:7.1.1.Final
Hibernate ORM mapper
org.hibernate.search:hibernate-search-mapper-orm-outbox-polling:7.1.1.Final
"outbox-polling" coordination strategy for the Hibernate ORM mapper
org.hibernate.search:hibernate-search-mapper-pojo-standalone:7.1.1.Final
Standalone POJO mapper
org.hibernate.search:hibernate-search-backend-lucene:7.1.1.Final
Lucene backend
org.hibernate.search:hibernate-search-backend-elasticsearch:7.1.1.Final
Elasticsearch/OpenSearch backend
org.hibernate.search:hibernate-search-backend-elasticsearch-aws:7.1.1.Final
Amazon IAM authentication for Elasticsearch/OpenSearch
org.hibernate.search:hibernate-search-mapper-orm-jakarta-batch-core:7.1.1.Final
Jakarta Batch mass indexing job for the Hibernate ORM mapper - Core
org.hibernate.search:hibernate-search-mapper-orm-jakarta-batch-jberet:7.1.1.Final
Jakarta Batch mass indexing job for the Hibernate ORM mapper - JBeret specifics
org.hibernate.search:hibernate-search-v5migrationhelper-orm:7.1.1.Final
Helper for migrating from Hibernate Search 5 to Hibernate Search 6/7 (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

If you want to start using Hibernate Search 7.1, please refer to the getting started guide:

HTML PDF

Migrating

If you need to upgrade from a previous series, please refer to the migration guide:

HTML PDF

What's new

Latest release announcement (2024-04-10): 7.1.1.Final.

A detailed list of new features, improvements and fixes in this series can be found on our issue tracker.

Dependency upgrades

Lucene

The Lucene backend now uses Lucene 9.9. Besides other improvements it brings better vector search performance.

Elasticsearch

The Elasticsearch backend works with Elasticsearch 8.12/8.13 as well as other versions that were already compatible.

OpenSearch

The Elasticsearch backend works with OpenSearch 2.12/2.13 as well as other versions that were already compatible.

Hibernate Search now allows vector search in Lucene and Elasticsearch backends as an incubating feature. Vector search provides the tools to search over binary (images, audio or video) or text data: external tools convert that data to vectors (arrays of bytes or floats, also called "embeddings"), which are then used for indexing and queries in Hibernate Search. Hibernate Search introduces a new field type — @VectorField and a new predicate knn, so that the vectors can be indexed and then searched upon.

Vector fields can work with vector data represented as byte or float arrays in the documents. Out of the box byte[] and float[] property types will work with the new field type. For any other entity property types, a custom value bridge or value binder should be implemented. Keep in mind that indexed vectors must be of the same length and that this length should be specified upfront for the schema to be created:

@Entity
@Indexed
public class Book {

        @Id
        private Integer id;

        @VectorField(dimension = 512)
        private float[] coverImageEmbeddings;

        // Other properties ...
}

Searching for vector similarities is performed via a knn predicate:

float[] coverImageEmbeddingsVector = /*...*/

List<Book> hits = searchSession.search( Book.class )
.where( f ->
    // provide the number of similar documents to look for:
    f.knn( 5 )
        // the name of the vector field:
        .field( "coverImageEmbeddings" )
         // matched documents will be the ones whose indexed vector
         // is "most similar" to this vector
        .matching( coverImageEmbeddingsVector )
    // additionally an optional filter can be supplied
    // to provide a regular fulltext search predicate
    .filter( f.match().field( "authors.firstName" ).matching( "arthur" ) )
).fetchHits( 20 );

Note that each backend may have its own specifics and limitations with regard to the vector search. For more details look at the related documentation.

Looking up the capabilities of each field in the metamodel

It is now possible to see which capabilities (predicates/sorts/projections/etc.) are available for a field when inspecting the metamodel:

SearchMapping mapping = /*...*/ ;
// Retrieve a SearchIndexedEntity:
SearchIndexedEntity<Book> bookEntity = mapping.indexedEntity( Book.class );
// Get the descriptor for that index.
// The descriptor exposes the index metamodel:
IndexDescriptor indexDescriptor = bookEntity.indexManager().descriptor();

// Retrieve a field by name
// and inspect its capabilities if such field is present:
indexDescriptor.field( "releaseDate" ).ifPresent( field -> {
        if ( field.isValueField() ) {
                // Get the descriptor for the field type:
                IndexValueFieldTypeDescriptor type = field.toValueField().type();
                // Inspect the "traits" of a field type:
                // each trait represents a predicate/sort/projection/aggregation
                // that can be used on fields of that type.
                Set<String> traits = type.traits();
                if ( traits.contains( IndexFieldTraits.Aggregations.RANGE ) ) {
                        // ...
                }
                if ( traits.contains( IndexFieldTraits.Predicates.EXISTS ) ) {
                        // ...
                }
                // ...
        }
} );

Query string predicate

The queryString predicate matches documents according to a structured query given as a string. It allows building more advanced query strings (using Lucene’s query language) and has more configuration options than a simpleQueryString predicate.

List<Book> hits = searchSession.search( Book.class )
    .where( f -> f.queryString().field( "description" )
        .matching( "robots +(crime investigation disappearance)^10 +\"investigation help\"~2 -/(dis)?a[p]+ea?ance/" ) )
    .fetchHits( 20 );

The query string, in this predicate, will result in a boolean query with 4 clauses:

  • a should clause matching robots;

  • two must clauses

    • another boolean query constructed from (crime || investigation || disappearance) string with a boost of 10

    • a query matching the phrase investigation help with the phrase slop equals to 2

  • a must not clause matching a regular expression (dis)?a[p]+ea?ance

    Note that each of the mentioned clauses may itself end up being translated into other types of queries.

See this section of the reference documentation on the queryString predicate for more information.

Simpler entity registration in the Standalone POJO mapper

Hibernate Search simplifies how entities can be defined. For standalone mapper now it is enough to annotate your entities with the @SearchEntity annotation.

@SearchEntity (1)
// ... Other annotations, e.g. @Indexed if this entity needs to be mapped to an index.
public class Book {

    @Id
    private Integer id;

    // Other properties ...
}
1 Annotate the type with @SearchEntity so it is treated as an entity.

Another update related to this is a way the SearchMappingBuilder builder is created. Now it requires an annotated type source to be provided.

CloseableSearchMapping searchMapping =
SearchMapping.builder( AnnotatedTypeSource.fromClasses( (1)
        Book.class, Associate.class, Manager.class ))
    .property( "hibernate.search.backend.hosts", "elasticsearch.mycompany.com" ) (2)
// ...
    .build(); (3)
1 Create a builder, passing an AnnotatedTypeSource to let Hibernate Search know where to look for annotations.

Thanks to classpath scanning, your AnnotatedTypeSource only needs to include one class from each JAR containing annotated types. Other types should be automatically discovered.

2 Set additional configuration properties.
3 Build the SearchMapping.

See this section of the reference documentation on the entity definition for more information.

Development versions (SNAPSHOTS)

The latest development versions of Maven artifacts for Hibernate Search are published to the OSSRH snapshots repository.

OSSRH snapshots subdirectory

You should only need those (unstable) versions for testing recently merged patches, and should never use them in production.

To consume these artifacts, you may need to configure your build tool to fetch artifacts from and to enable snapshots:

Maven Gradle

Releases in this series

7.1.1.Final

2024-04-10

Compatibility with OpenSearch 2.13 and Elasticsearch 8.13, a few fixes and documentation updates.

How to get it Getting started

Maven artifacts Download Resolved issues Release announcement

7.1.0.Final

2024-02-28

Compatibility with OpenSearch 2.12, a few bug fixes and dependency upgrades

Maven artifacts Download Resolved issues Release announcement

7.1.0.CR1

2024-02-12

Better aligning of the knn predicate between backends and removing previous limitations, new query string predicate, simplify entity registration in the Standalone POJO mapper, allow targeting entities by name in the Standalone POJO Mapper, other improvements and dependency upgrades

Maven artifacts Download Resolved issues Release announcement

7.1.0.Alpha2

2024-01-24

Vector search in the Elasticsearch backend and various vector search improvements, allow looking up the capabilities of each field in the metamodel, compatibility with Elasticsearch 8.12, upgrade to Lucene 9.9, other bugfixes, improvements and upgrades

Maven artifacts Download Resolved issues Release announcement

7.1.0.Alpha1

2023-11-30

Vector search in the Lucene backend, other bugfixes and improvements

Maven artifacts Download Resolved issues Release announcement

Back to top