Compatibility
Java | 11, 17 or 21 |
Hibernate ORM | 6.4/6.5 |
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:
You can find more documentation for all series on the documentation page.
How to get it
Hibernate Search 7.1 has reached its end-of-life: we recommend that you upgrade to a newer series if possible. See also the Maintenance policy. |
More information about specific releases (announcements, download links) can be found here.
Getting started
Hibernate Search 7.1 has reached its end-of-life: we recommend that you upgrade to a newer series if possible. See also the Maintenance policy. |
If you want to start using Hibernate Search 7.1, please refer to the getting started guide:
Migrating
If you need to upgrade from a previous series, please refer to the migration guide:
What's new
Latest release announcement (2024-08-30): 7.1.2.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.
Vector search for Lucene and Elasticsearch Backends
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 of10
-
a query matching the phrase
investigation help
with the phrase slop equals to2
-
-
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 |
2 | Set additional configuration properties. |
3 | Build the SearchMapping . |
See this section of the reference documentation on the entity definition for more information.
Releases in this series
Hibernate Search 7.1 has reached its end-of-life: we recommend that you upgrade to a newer series if possible. See also the Maintenance policy. |
A few fixes, dependency and documentation updates.
Maven artifacts Download Resolved issues Release announcement
Compatibility with OpenSearch 2.13 and Elasticsearch 8.13, a few fixes and documentation updates.
Maven artifacts Download Resolved issues Release announcement
Compatibility with OpenSearch 2.12, a few bug fixes and dependency upgrades
Maven artifacts Download Resolved issues Release announcement
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
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
Vector search in the Lucene backend, other bugfixes and improvements
Maven artifacts Download Resolved issues Release announcement