|
| 1 | +:awestruct-layout: project-releases-series |
| 2 | +:awestruct-project: search |
| 3 | +:awestruct-series_version: "8.1" |
| 4 | +:page-interpolate: true |
| 5 | +:latest-release-version: #{series(page, page.series_version).releases.first.version} |
| 6 | +:hsearch-doc-url-prefix: #{reference_doc(site.projects[page.project], series(page, page.series_version)).html_url} |
| 7 | + |
| 8 | +**** |
| 9 | +[discrete] |
| 10 | +=== Dependency upgrades |
| 11 | +
|
| 12 | +[[orm-version]] |
| 13 | +Hibernate ORM:: |
| 14 | +Hibernate Search still targets the Hibernate ORM 7.0 series, with the plan, in the following beta releases to target 7.1 once it is out. |
| 15 | +[[lucene-version]] |
| 16 | +Lucene:: |
| 17 | +The Lucene backend now uses Lucene 9.12.2, while the `lucene-next` backend relies on Lucene 10.2.2 |
| 18 | +[[elasticsearch-version]] |
| 19 | +Elasticsearch:: |
| 20 | +The Elasticsearch backend is still compatible with all already compatible versions. |
| 21 | +[[opensearch-version]] |
| 22 | +OpenSearch:: |
| 23 | +The Elasticsearch backend works with OpenSearch 3.1, as well as other already compatible versions. |
| 24 | +
|
| 25 | +[[aggregations-improvements]] |
| 26 | +[discrete] |
| 27 | +=== Aggregation improvements |
| 28 | +
|
| 29 | +With this version of Hibernate Search it is now possible to request terms and range aggregations for more than counts, |
| 30 | +i.e. such that would return other aggregations provided by the DSL. |
| 31 | +
|
| 32 | +==== |
| 33 | +[source, Java, indent=0, subs="+attributes"] |
| 34 | +---- |
| 35 | +AggregationKey<Map<Range<Double>, Double>> avgRatingByPriceKey = AggregationKey.of( "avgRatingByPrice" ); // <1> |
| 36 | +SearchResult<Book> result = searchSession.search( Book.class ) |
| 37 | + .where( f -> f.matchAll() ) |
| 38 | + .aggregation( |
| 39 | + avgRatingByPriceKey, f -> f.range() |
| 40 | + .field( "price", Double.class ) // <2> |
| 41 | + .range( 0.0, 10.0 ) |
| 42 | + .range( 10.0, 20.0 ) |
| 43 | + .range( 20.0, null ) |
| 44 | + .value( f.avg().field( "ratings", Double.class, ValueModel.RAW ) ) // <3> |
| 45 | + ) |
| 46 | + .fetch( 20 ); |
| 47 | +Map<Range<Double>, Double> countsByPrice = result.aggregation( avgRatingByPriceKey ); // <4> |
| 48 | +---- |
| 49 | +<1> Create an aggregation key for an average rating by book price aggregation. |
| 50 | +<2> Start building range aggregation as usual, by specifying the field and ranges. |
| 51 | +<3> Request an `.avg()` aggregation on the ratings field. |
| 52 | +Specifying `Double` and using `ValueModel.RAW` here defines the expected return type of the computed aggregation. |
| 53 | +<4> Extract the aggregated value from the results. |
| 54 | +==== |
| 55 | +
|
| 56 | +[TIP] |
| 57 | +==== |
| 58 | +The value of the `range()`/`terms()` aggregation can be any of the aggregations provided by the Search DSL, e.g. |
| 59 | +one of the metric aggregations: `min()`/`max()`/`avg()`/`count()`/`sum()`, |
| 60 | +a `range()`/`terms()` aggregation or a composite aggregation combining a number of other aggregations. |
| 61 | +==== |
| 62 | +
|
| 63 | +See the corresponding section on link:{hsearch-doc-url-prefix}#search-dsl-aggregation-range-value[range aggregations] |
| 64 | +to learn more. This also is applicable to the link:{hsearch-doc-url-prefix}#search-dsl-aggregation-terms-value[terms aggregations]. |
| 65 | +
|
| 66 | +If multiple aggregations are of interest be it at the root level or per aggregation (terms/range) bucket, |
| 67 | +it is now possible to request a composite aggregation: |
| 68 | +
|
| 69 | +==== |
| 70 | +[source, Java, indent=0, subs="+attributes"] |
| 71 | +---- |
| 72 | +record PriceAggregation(Double avg, Double min, Double max) { // <1> |
| 73 | +} |
| 74 | +AggregationKey<Map<Range<Double>, PriceAggregation>> priceAggregationsKey = AggregationKey.of( "priceAggregationsKey" ); // <2> |
| 75 | +SearchResult<Book> result = searchSession.search( Book.class ) |
| 76 | + .where( f -> f.matchAll() ) |
| 77 | + .aggregation( |
| 78 | + countsByPriceKey, f -> f.range() |
| 79 | + .field( "price", Double.class ) // <3> |
| 80 | + .range( 0.0, 10.0 ) // <3> |
| 81 | + .range( 10.0, 20.0 ) |
| 82 | + .range( 20.0, null ) |
| 83 | + .value( f.composite() // <4> |
| 84 | + .from( |
| 85 | + f.avg().field( "price", Double.class ), // <5> |
| 86 | + f.min().field( "price", Double.class ), |
| 87 | + f.max().field( "price", Double.class ) |
| 88 | + ).as( PriceAggregation::new ) ) // <6> |
| 89 | + ) |
| 90 | + .fetch( 20 ); |
| 91 | +Map<Range<Double>, PriceAggregation> countsByPrice = result.aggregation( priceAggregationsKey ); // <7> |
| 92 | +---- |
| 93 | +<1> Define a structure to hold composite aggregation results. |
| 94 | +<2> Create an aggregation key for the composite range aggregation. |
| 95 | +<3> Start building range aggregation as usual, by specifying the field and ranges. |
| 96 | +<4> Request a `.composite()` aggregation. |
| 97 | +<5> Add any required aggregations to build up a composite one. |
| 98 | +<6> Specify how to transform the composite aggregation. By default, you would need to request the composite aggregation |
| 99 | +as a `List` or an array of aggregated values, but then it is possible to transform it to something else. |
| 100 | +<7> Extract the aggregated value from the results. |
| 101 | +==== |
| 102 | +
|
| 103 | +See the corresponding section on link:{hsearch-doc-url-prefix}#search-dsl-aggregation-composite[composite aggregations] |
| 104 | +to learn more. |
| 105 | +
|
| 106 | +[[platform-bom]] |
| 107 | +[discrete] |
| 108 | +=== Hibernate Search Platform BOM |
| 109 | +
|
| 110 | +Besides the lean BOM file, Hibernate Search now also provides several platform POM files that manage |
| 111 | +the versions of Hibernate Search artifacts, _and_ their transitive dependencies, _and_ related artifacts that must be aligned. |
| 112 | +For example, it brings the management of all other `org.hibernate.orm` artifacts, |
| 113 | +beyond the ones required by the ORM mapper, or extra Lucene artifacts like |
| 114 | +`lucene-suggest` or `lucene-analysis-icu` and others, that can be helpful for more advanced applications. |
| 115 | +These platform files will help keep the versions of extra Hibernate ORM/Lucene/Elasticsearch client dependencies |
| 116 | +aligned with the versions of artifacts from the same groups that are used by Hibernate Search itself. |
| 117 | +
|
| 118 | +Currently, there are two platform POM files for Hibernate Search: |
| 119 | +
|
| 120 | +* `hibernate-search-platform-bom`: use this when in doubt. |
| 121 | +* `hibernate-search-platform-next-bom`: use this if you want to use the `lucene-next` backend. |
| 122 | +
|
| 123 | +To leverage the dependency management provided by these platform files, use the same approach of importing as for |
| 124 | +the regular BOM file: |
| 125 | +
|
| 126 | +[source, XML, subs="+attributes"] |
| 127 | +---- |
| 128 | +<dependencyManagement> |
| 129 | + <dependencies> |
| 130 | + <!-- |
| 131 | + Import Hibernate Search platform |
| 132 | + to get all of its artifact versions aligned: |
| 133 | + --> |
| 134 | + <dependency> |
| 135 | + <groupId>org.hibernate.search</groupId> |
| 136 | + <artifactId>hibernate-search-platform-bom</artifactId> |
| 137 | + <version>{latest-release-version}</version> |
| 138 | + <type>pom</type> |
| 139 | + <scope>import</scope> |
| 140 | + </dependency> |
| 141 | + <!-- Any other dependency management entries --> |
| 142 | + </dependencies> |
| 143 | +</dependencyManagement> |
| 144 | +
|
| 145 | +<dependencies> |
| 146 | + <!-- Any other dependency management entries --> |
| 147 | + <!-- |
| 148 | + For example, add an extra Lucene dependency without specifying the version |
| 149 | + as it is managed by the platform POM: |
| 150 | + --> |
| 151 | + <dependency> |
| 152 | + <groupId>org.apache.lucene</groupId> |
| 153 | + <artifactId>lucene-suggest</artifactId> |
| 154 | + </dependency> |
| 155 | + <!-- Any other dependency management entries --> |
| 156 | +</dependencies> |
| 157 | +---- |
| 158 | +
|
| 159 | +See the corresponding section on link:{hsearch-doc-url-prefix}#compatibility-search-dependencies-platform[Hibernate Search Platform] |
| 160 | +to find out more. |
| 161 | +**** |
0 commit comments