Compatibility
| Java | 11, 17, 21 or 22 |
| Hibernate ORM | 6.6 |
| Elasticsearch server | 7.10 - 8.15 |
| OpenSearch server | 1.3 - 2.16 |
| Apache Lucene | 9.11 |
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.2 can be accessed through the links below:
You can find more documentation for all series on the documentation page.
How to get it
More information about specific releases (announcements, download links) can be found here.
Getting started
If you want to start using Hibernate Search 7.2, 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.2.1.Final.
A detailed list of new features, improvements and fixes in this series can be found on our issue tracker.
Dependency upgrades
- Hibernate ORM
-
Hibernate Search now depends on Hibernate ORM 6.6.0.Final.
- Lucene
-
The Lucene backend now uses Lucene 9.11.1.
- Elasticsearch
-
The Elasticsearch backend works with Elasticsearch 8.14 and 8.15, as well as other versions that were already compatible.
- OpenSearch
-
The Elasticsearch backend works with OpenSearch 2.14, 2.15 and 2.16, as well as other versions that were already compatible.
- JBoss Logging
-
Hibernate Search now depends on JBoss Logging 3.6.
If you are using Hibernate Search with Hibernate ORM integration, or if your application has a dependency on JBoss Logging for any other reasons, make sure to enforce the resolution of JBoss Logging dependency to 3.6, as otherwise you may experience errors on startup.
queryString/simpleQueryString predicates for numeric/date fields
simpleQueryString and
queryString
can now be applied to numeric and date fields.
List<Book> hits = searchSession.search( Book.class )
.where( f -> f.queryString()
.field( "numberOfPages" )
.matching( "[350 TO 800]" )
)
.fetchHits( 20 );See corresponding sections in simpleQueryString
queryString documentation
for details.
match predicate and minimum number of terms that should match
With the introduction of the minimumShouldMatch option,
similar to the ones already available for the
bool,
queryString,
simpleQueryString predicates,
it is now possible to require that
an arbitrary number of terms from the match string are present in the document
in order for the match predicate to match.
List<Book> hits = searchSession.search( Book.class )
.where( f -> f.match()
.field( "title" )
.matching( "investigation detective automatic" )
.minimumShouldMatchNumber( 2 ) ) (1)
.fetchHits( 20 ); (2)| 1 | At least two terms must match for this predicate to match. |
| 2 | All returned hits will match at least two of the terms:
their titles will match either investigation and detective,
investigation and automatic, detective and automatic, or all three of these terms. |
Basic support for parameters at the query level
A number of withParameters(..) methods were introduced to the Search DSL.
Through them, it is now possible to construct
aggregations,
predicates,
projections,
and sorts
using query parameters.
These can be helpful when there is a need to use the same parameter in multiple parts of the query
or when the same query has to be executed for various parameter values.
SearchScope<Book> scope = searchSession.scope( Book.class );
SearchPredicateFactory factory = scope.predicate();
SearchPredicate predefinedPredicate = factory.withParameters(
params -> factory.bool() (1)
.should( factory.match().field( "title" )
.matching( params.get( "title-param", String.class ) ) ) (2)
.filter( factory.match().field( "genre" )
.matching( params.get( "genre-param", Genre.class ) ) ) (3)
).toPredicate();
List<Book> crimeBooks = searchSession.search( Book.class )
.where( predefinedPredicate ) (4)
.param( "title-param", "robot" ) (5)
.param( "genre-param", Genre.CRIME_FICTION )
.fetchHits( 20 );
List<Book> scienceFictionBooks = searchSession.search( Book.class )
.where( predefinedPredicate ) (6)
.param( "title-param", "spaceship" ) (7)
.param( "genre-param", Genre.SCIENCE_FICTION )
.fetchHits( 20 );| 1 | Start creating the .withParameters() predicate. |
| 2 | Access the query parameter title-param of String type when constructing the predicate. |
| 3 | Access the query parameter genre-param of Genre enum type when constructing the predicate. |
| 4 | Use the predefined, parameterized predicate in a query. |
| 5 | Set parameters required by the predicate at the query level. |
| 6 | Reuse the predefined, parameterized predicate in a query. |
| 7 | Set a different pair of parameters required by the predicate at the query level. |
@DistanceProjection to map a constructor parameter to a distance projection
With the introduction of the query parameters, it is now possible to define a
@DistanceProjection
that can be used in the projection constructors.
@ProjectionConstructor
public record MyAuthorPlaceProjection(
@DistanceProjection( (1)
fromParam = "point-param", (2)
path = "placeOfBirth") (3)
Double distance ) {
}| 1 | Annotate the parameter that should receive the distance value with @DistanceProjection. |
| 2 | Specify the query parameter that will be used to calculate the distance from. |
| 3 | Optionally, customize the path, since most likely the GeoPoint property of the entity will have a different name from the
distance property in a projection. |
List<MyAuthorPlaceProjection> hits = searchSession.search( Author.class )
.select( MyAuthorPlaceProjection.class )
.where( f -> f.matchAll() )
.param( "point-param", GeoPoint.of( latitude, longitude ) ) (1)
.fetchHits( 20 );| 1 | Pass a query parameter value, with the same name point-param as in the @DistanceProjection fromParam of a projection constructor. |
Document tree projection
With the Lucene backend, requesting a document tree projection is now possible.
This new .documentTree()
projection returns the matched document as a tree containing native Lucene Document and corresponding nested tree nodes.
List<DocumentTree> hits = searchSession.search( Book.class )
.extension( LuceneExtension.get() )
.select( f -> f.documentTree() )
.where( f -> f.matchAll() )
.fetchHits( 20 );
DocumentTree documentTree = hits.get( 0 );
Document rootDocument = documentTree.document();
Map<String, Collection<DocumentTree>> nestedDocuments = documentTree.nested();
// ...within/withinAny for the range predicate
The range predicate can now accept multiple ranges,
matching the document when the value is within at least one of the provided ranges.
List<Book> hits = searchSession.search( Book.class )
.where( f -> f.range().field( "pageCount" )
.withinAny(
Range.between( 200, 250 ),
Range.between( 500, 800 )
) )
.fetchHits( 20 );knn predicate updates
The knn predicate, besides the existing .requiredMinimumSimilarity(..) filter,
now also has a score-based alternative: requiredMinimumScore(..).
With knn search, similarity and score are derived one from the other, and in some scenarios, it may be simpler to use score,
while in others — similarity.
Starting with OpenSearch 2.14, these filters are now also available for the OpenSearch distribution of the Elasticsearch backend.
To remind you how the vector search works: for vector fields to be indexed, they should be annotated with a @VectorField annotation:
@Entity
@Indexed
public class Book {
@Id
private Integer id;
@VectorField(dimension = 512)
private float[] coverImageEmbeddings;
// Other properties ...
}Then, searching for vector similarities is performed via a knn predicate:
float[] coverImageEmbeddingsVector = /*...*/
List<Book> hits = searchSession.search( Book.class )
.where( f ->
f.knn( 5 ) (1)
.field( "coverImageEmbeddings" ) (2)
.matching( coverImageEmbeddingsVector ) (3)
.requiredMinimumSimilarity( similarity ) (4)
).fetchHits( 20 );| 1 | Provide the number of similar documents to look for. |
| 2 | Specify the name of the vector field. |
| 3 | Provide a reference vector; matched documents will be the ones whose indexed vector is "most similar" to this vector. |
| 4 | Specify the minimum required similarity between the reference and indexed vectors;
documents where indexed vector similarity is less than the specified similarity value will be filtered out.
Alternatively, the requiredMinimumScore( score ) filter can be applied instead of the requiredMinimumSimilarity( similarity ). |
Prefix predicate
The prefix predicate matches documents for which a given field has a value starting with a given string.
List<Book> hits = searchSession.search( Book.class )
.where( f -> f.prefix().field( "description" )
.matching( "rob" ) )
.fetchHits( 20 );Switch project license to Apache License 2.0
We are also pleased to announce that Hibernate Search 7.2.0.Alpha2 is licensed under Apache License 2.0. This change is a part of a broader initiative to re-license Hibernate projects with the Apache License 2.0.
Development versions (SNAPSHOTS)
The latest development versions of Maven artifacts for Hibernate Search are published to the OSSRH snapshots repository.
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
https://oss.sonatype.org/content/repositories/snapshots
and to enable snapshots:
Releases in this series
A few fixes and documentation updates.
Maven artifacts Download Resolved issues Release announcement
compatibility with Elasticsearch 8.15 and OpenSearch 2.16, Hibernate ORM 6.6 upgrade.
Maven artifacts Download Resolved issues Release announcement
New prefix predicate, knn predicate improvements, upgrade to Hibernate ORM 6.6, compatibility with OpenSearch 2.15, other bugfixes, improvements and upgrades
Maven artifacts Download Resolved issues Release announcement
Switch project license to Apache License 2.0, accept multiple ranges in a range predicate, compatibility with Elasticsearch 8.14, upgrade to Lucene 9.11, other bugfixes, improvements and upgrades
Maven artifacts Download Resolved issues Release announcement
Enable query string predicates on numeric/date fields, query parameters, document tree projection for the Lucene backend, new APIs to work with analyzers, compatibility with OpenSearch 2.14, upgrade to Lucene 9.10, upgrade to Hibernate ORM 6.5, other bugfixes, improvements and upgrades
Maven artifacts Download Resolved issues Release announcement
