HSEARCH-3661 Document range/terms .values(..)

Author: marko-bekhta

documentation/src/main/asciidoc/public/reference/_search-dsl-aggregation.adoc

@@ -220,6 +220,23 @@ When ordering entries by ascending count in a `terms` aggregation,
 link:{elasticsearchDocUrl}/search-aggregations-bucket-terms-aggregation.html#search-aggregations-bucket-terms-aggregation-order[hit counts are approximate].
 ====
 
+[[search-dsl-aggregation-terms-value]]
+=== Aggregated value
+
+By default, the aggregated value represents the number of documents that fall into the group of a particular term.
+With the `.value(..)` step in aggregation definition, it is now possible to set the aggregated value to something other than the document count.
+The `.value(..)` accepts any other aggregation, which will be applied to the documents within the aggregated group.
+
+.Total price of books per category
+====
+[source, JAVA, indent=0, subs="+callouts"]
+----
+include::{sourcedir}/org/hibernate/search/documentation/search/aggregation/AggregationDslIT.java[tags=terms-sum]
+----
+<1> Define the path and type of the field whose values should be considered as terms for the aggregation.
+<2> Define what the aggregated value should represent, e.g. the sum of all book prices within the genre.
+====
+
 [[search-dsl-aggregation-terms-other]]
 === Other options
 
@@ -318,6 +335,23 @@ include::{sourcedir}/org/hibernate/search/documentation/search/aggregation/Aggre
 
 See <<search-dsl-argument-type>> for more information.
 
+[[search-dsl-aggregation-range-value]]
+=== Aggregated value
+
+By default, the aggregated value represents the number of documents that fall into particular, defined range .
+With the `.value(..)` step in aggregation definition, it is now possible to set the aggregated value to something other than the document count.
+The `.value(..)` accepts any other aggregation, which will be applied to the documents within the aggregated group.
+
+.Total price of books per category
+====
+[source, JAVA, indent=0, subs="+callouts"]
+----
+include::{sourcedir}/org/hibernate/search/documentation/search/aggregation/AggregationDslIT.java[tags=range-avg]
+----
+<1> Define the path and type of the field whose value ranges for the aggregation.
+<2> Define what the aggregated value should represent, e.g. the average rating of all books within the price range.
+====
+
 [[search-dsl-aggregation-range-other]]
 === Other options
 
@@ -329,14 +363,8 @@ but that can be <<search-dsl-aggregation-common-filter,controlled explicitly wit
 
 include::../components/_incubating-warning.adoc[]
 
-Hibernate Search provides a set of most common metric aggregations such as `sum`, `min`, `max`, `count`,
-`count distinct` and `avg`. These aggregations can be requested for fields of numerical or temporal type.
-
-[NOTE]
-====
-At the moment, it is only possible to request metric aggregations at the root level;
-that is, the aggregation will be applied to the entire hit set.
-====
+Hibernate Search provides a set of most common metric aggregations such as `sum`, `min`, `max`, `count documents`, `count values`,
+`count values distinct` and `avg`. These aggregations can be requested for fields of numerical or temporal types.
 
 [IMPORTANT]
 ====
@@ -390,9 +418,28 @@ include::{sourcedir}/org/hibernate/search/documentation/search/aggregation/Aggre
 <1> Define the target field path to which you want to apply the aggregation function and the expected returned type.
 ====
 
+=== Count documents  metric aggregation
+
+The `count documents` aggregation counts the number of documents.
+While it is usually discouraged to use this aggregation at the root level,
+as the result would be equivalent to the count returned by the search results in `SearchResultTotal`,
+this aggregation can still be useful in defining aggregation values in other, more complex aggregations like
+<<search-dsl-aggregation-range-value,`range`>> or <<search-dsl-aggregation-terms-value,`terms`>>.
+
+.Count the number of the science fiction books
+====
+[source, JAVA, indent=0, subs="+callouts"]
+----
+include::{sourcedir}/org/hibernate/search/documentation/search/aggregation/AggregationDslIT.java[tags=count-documents]
+----
+<1> Apply the document count aggregation. For this function a `Long.class` value is always returned.
+====
+
 === Count values metric aggregation
 
 The `count values` aggregation counts the number of non-empty field values.
+This aggregation mostly make sense when the aggregated field is multivalued.
+For single-valued fields this aggregation would result in the number of documents where the aggregated field is present.
 
 .Count the number of the science fiction books with prices
 ====
@@ -407,7 +454,7 @@ include::{sourcedir}/org/hibernate/search/documentation/search/aggregation/Aggre
 
 The `count distinct values` aggregation counts the number of unique field values.
 
-.Count anytime the price field has a different value among all the science fiction books
+.Count the number of all different price value among all the science fiction books
 ====
 [source, JAVA, indent=0, subs="+callouts"]
 ----

documentation/src/test/java/org/hibernate/search/documentation/search/aggregation/AggregationDslIT.java

@@ -272,23 +272,21 @@ void terms() {
 	void terms_value() {
 		withinSearchSession( searchSession -> {
 			// tag::terms-sum[]
-			AggregationKey<Map<Double, Double>> sumByPriceKey = AggregationKey.of( "sumByPrice" );
+			AggregationKey<Map<Genre, Double>> sumByCategoryKey = AggregationKey.of( "sumByCategory" );
 			SearchResult<Book> result = searchSession.search( Book.class )
 					.where( f -> f.matchAll() )
 					.aggregation(
-							sumByPriceKey, f -> f.terms()
-									.field( "price", Double.class ) // <1>
-									.value( f.sum().field( "price", Double.class ) )
+							sumByCategoryKey, f -> f.terms()
+									.field( "genre", Genre.class ) // <1>
+									.value( f.sum().field( "price", Double.class ) ) // <2>
 					)
 					.fetch( 20 );
-			Map<Double, Double> sumByPrice = result.aggregation( sumByPriceKey );
+			Map<Genre, Double> sumByPrice = result.aggregation( sumByCategoryKey );
 			// end::terms-sum[]
 			assertThat( sumByPrice )
 					.containsExactly(
-							entry( 7.99, 7.99 ),
-							entry( 15.99, 15.99 ),
-							entry( 19.99, 19.99 ),
-							entry( 24.99, 24.99 )
+							entry( Genre.SCIENCE_FICTION, 60.97 ),
+							entry( Genre.CRIME_FICTION, 7.99 )
 					);
 		} );
 
@@ -339,26 +337,26 @@ void terms_value() {
 	@Test
 	void range_value() {
 		withinSearchSession( searchSession -> {
-			// tag::range-sum[]
-			AggregationKey<Map<Range<Double>, Double>> countsByPriceKey = AggregationKey.of( "countsByPrice" );
+			// tag::range-avg[]
+			AggregationKey<Map<Range<Double>, Double>> avgRatingByPriceKey = AggregationKey.of( "avgRatingByPrice" );
 			SearchResult<Book> result = searchSession.search( Book.class )
 					.where( f -> f.matchAll() )
 					.aggregation(
-							countsByPriceKey, f -> f.range()
+							avgRatingByPriceKey, f -> f.range()
 									.field( "price", Double.class ) // <1>
-									.range( 0.0, 10.0 ) // <2>
+									.range( 0.0, 10.0 )
 									.range( 10.0, 20.0 )
-									.range( 20.0, null ) // <3>
-									.value( f.sum().field( "price", Double.class ) )
+									.range( 20.0, null )
+									.value( f.avg().field( "ratings", Double.class, ValueModel.RAW ) ) // <2>
 					)
 					.fetch( 20 );
-			Map<Range<Double>, Double> countsByPrice = result.aggregation( countsByPriceKey );
-			// end::range-sum[]
+			Map<Range<Double>, Double> countsByPrice = result.aggregation( avgRatingByPriceKey );
+			// end::range-avg[]
 			assertThat( countsByPrice )
 					.containsExactly(
-							entry( Range.canonical( 0.0, 10.0 ), 7.99 ),
-							entry( Range.canonical( 10.0, 20.0 ), 35.98 ),
-							entry( Range.canonical( 20.0, null ), 24.99 )
+							entry( Range.canonical( 0.0, 10.0 ), 4.0 ),
+							entry( Range.canonical( 10.0, 20.0 ), 3.6 ),
+							entry( Range.canonical( 20.0, null ), 3.2 )
 					);
 		} );
 
@@ -584,8 +582,8 @@ void sum() {
 					.aggregation( sumPricesKey, f -> f.sum().field( "price", Double.class ) ) // <1>
 					.fetch( 20 );
 			Double sumPrices = result.aggregation( sumPricesKey );
-			assertThat( sumPrices ).isEqualTo( 60.97 );
 			// end::sums[]
+			assertThat( sumPrices ).isEqualTo( 60.97 );
 		} );
 	}
 
@@ -599,8 +597,8 @@ void min() {
 					.aggregation( oldestReleaseKey, f -> f.min().field( "releaseDate", Date.class ) ) // <1>
 					.fetch( 20 );
 			Date oldestRelease = result.aggregation( oldestReleaseKey );
-			assertThat( oldestRelease ).isEqualTo( Date.valueOf( "1950-12-02" ) );
 			// end::min[]
+			assertThat( oldestRelease ).isEqualTo( Date.valueOf( "1950-12-02" ) );
 		} );
 	}
 
@@ -614,28 +612,43 @@ void max() {
 					.aggregation( mostRecentReleaseKey, f -> f.max().field( "releaseDate", Date.class ) ) // <1>
 					.fetch( 20 );
 			Date mostRecentRelease = result.aggregation( mostRecentReleaseKey );
-
 			// end::max[]
+			assertThat( mostRecentRelease ).isEqualTo( Date.valueOf( "1983-01-01" ) );
 		} );
 	}
 
 	@Test
-	void count() {
+	void countDocuments() {
 		withinSearchSession( searchSession -> {
-			// tag::count[]
-			AggregationKey<Long> countPricesKey = AggregationKey.of( "countPrices" );
+			// tag::count-documents[]
+			AggregationKey<Long> countBooksKey = AggregationKey.of( "countBooks" );
 			SearchResult<Book> result = searchSession.search( Book.class )
 					.where( f -> f.match().field( "genre" ).matching( Genre.SCIENCE_FICTION ) )
-					.aggregation( countPricesKey, f -> f.countValues().field( "price" ) ) // <1>
+					.aggregation( countBooksKey, f -> f.countDocuments() ) // <1>
 					.fetch( 20 );
-			Long countPrices = result.aggregation( countPricesKey );
+			Long countPrices = result.aggregation( countBooksKey );
+			// end::count-documents[]
 			assertThat( countPrices ).isEqualTo( 3L );
+		} );
+	}
+
+	@Test
+	void countValues() {
+		withinSearchSession( searchSession -> {
+			// tag::count[]
+			AggregationKey<Long> countRatingsKey = AggregationKey.of( "countRatings" );
+			SearchResult<Book> result = searchSession.search( Book.class )
+					.where( f -> f.match().field( "genre" ).matching( Genre.SCIENCE_FICTION ) )
+					.aggregation( countRatingsKey, f -> f.countValues().field( "ratings" ) ) // <1>
+					.fetch( 20 );
+			Long countPrices = result.aggregation( countRatingsKey );
 			// end::count[]
+			assertThat( countPrices ).isEqualTo( 15L );
 		} );
 	}
 
 	@Test
-	void countDistinct() {
+	void countDistinctValues() {
 		withinSearchSession( searchSession -> {
 			// tag::count-distinct[]
 			AggregationKey<Long> countDistinctPricesKey = AggregationKey.of( "countDistinctPrices" );
@@ -644,8 +657,8 @@ void countDistinct() {
 					.aggregation( countDistinctPricesKey, f -> f.countDistinctValues().field( "price" ) ) // <1>
 					.fetch( 20 );
 			Long countDistinctPrices = result.aggregation( countDistinctPricesKey );
-			assertThat( countDistinctPrices ).isEqualTo( 3L );
 			// end::count-distinct[]
+			assertThat( countDistinctPrices ).isEqualTo( 3L );
 		} );
 	}
 
@@ -679,6 +692,7 @@ private void initData() {
 			book1.setPrice( 24.99 );
 			book1.setGenre( Genre.SCIENCE_FICTION );
 			book1.setReleaseDate( Date.valueOf( "1950-12-02" ) );
+			book1.setRatings( List.of( 5, 5, 4, 2, 0 ) );
 			addEdition( book1, "Mass Market Paperback, 1st Edition", 9.99 );
 			addEdition( book1, "Kindle", 9.99 );
 
@@ -688,6 +702,7 @@ private void initData() {
 			book2.setPrice( 19.99 );
 			book2.setGenre( Genre.SCIENCE_FICTION );
 			book2.setReleaseDate( Date.valueOf( "1953-10-01" ) );
+			book2.setRatings( List.of( 5, 5, 3, 3, 5 ) );
 			addEdition( book2, "Mass Market Paperback, 12th Edition", 4.99 );
 			addEdition( book2, "Kindle", 19.99 );
 
@@ -697,6 +712,7 @@ private void initData() {
 			book3.setPrice( 15.99 );
 			book3.setGenre( Genre.SCIENCE_FICTION );
 			book3.setReleaseDate( Date.valueOf( "1983-01-01" ) );
+			book3.setRatings( List.of( 3, 3, 3, 3, 3 ) );
 			addEdition( book3, "Mass Market Paperback, 59th Edition", 3.99 );
 			addEdition( book3, "Kindle", 5.99 );
 
@@ -706,6 +722,7 @@ private void initData() {
 			book4.setPrice( 7.99 );
 			book4.setGenre( Genre.CRIME_FICTION );
 			book4.setReleaseDate( Date.valueOf( "2008-02-05" ) );
+			book4.setRatings( List.of( 4, 4, 4, 4, 4 ) );
 			addEdition( book4, "Mass Market Paperback, 2nd Edition", 10.99 );
 			addEdition( book4, "Kindle", 12.99 );
 

documentation/src/test/java/org/hibernate/search/documentation/search/aggregation/Book.java

@@ -9,6 +9,7 @@
 import java.util.List;
 
 import jakarta.persistence.CascadeType;
+import jakarta.persistence.ElementCollection;
 import jakarta.persistence.Entity;
 import jakarta.persistence.Id;
 import jakarta.persistence.OneToMany;
@@ -42,6 +43,10 @@ public class Book {
 	@GenericField(aggregable = Aggregable.YES)
 	private Date releaseDate;
 
+	@GenericField(aggregable = Aggregable.YES)
+	@ElementCollection
+	private List<Integer> ratings;
+
 	@OneToMany(mappedBy = "book", cascade = CascadeType.ALL)
 	@OrderColumn
 	@IndexedEmbedded(structure = ObjectStructure.NESTED)
@@ -97,4 +102,12 @@ public List<BookEdition> getEditions() {
 	public void setEditions(List<BookEdition> editions) {
 		this.editions = editions;
 	}
+
+	public List<Integer> getRatings() {
+		return ratings;
+	}
+
+	public void setRatings(List<Integer> ratings) {
+		this.ratings = ratings;
+	}
 }

engine/src/main/java/org/hibernate/search/engine/search/aggregation/dsl/RangeAggregationRangeValueStep.java

@@ -9,6 +9,7 @@
 
 import org.hibernate.search.engine.search.aggregation.SearchAggregation;
 import org.hibernate.search.engine.search.predicate.dsl.TypedSearchPredicateFactory;
+import org.hibernate.search.util.common.annotation.Incubating;
 import org.hibernate.search.util.common.data.Range;
 
 /**
@@ -18,13 +19,35 @@
  * @param <PDF> The type of factory used to create predicates in {@link RangeAggregationOptionsStep#filter(Function)}.
  * @param <F> The type of the targeted field.
  */
+@Incubating
 public interface RangeAggregationRangeValueStep<
 		SR,
 		PDF extends TypedSearchPredicateFactory<SR>,
 		F> {
-
+	/**
+	 * Specify which aggregation to apply to the documents within the range.
+	 * <p>
+	 * This allows to "group" the documents by "ranges" and then apply one of the aggregations from {@link SearchAggregationFactory}
+	 * to the documents in that group.
+	 *
+	 * @param aggregation The aggregation to apply to the documents within each range.
+	 * @return The next step in range aggregation definition.
+	 * @param <T> The type of the aggregated results within a range.
+	 */
+	@Incubating
 	<T> RangeAggregationOptionsStep<SR, ?, PDF, F, Map<Range<F>, T>> value(SearchAggregation<T> aggregation);
 
+	/**
+	 * Specify which aggregation to apply to the documents within the range.
+	 * <p>
+	 * This allows to "group" the documents by "ranges" and then apply one of the aggregations from {@link SearchAggregationFactory}
+	 * to the documents in that group.
+	 *
+	 * @param aggregation The aggregation to apply to the documents within each range.
+	 * @return The next step in range aggregation definition.
+	 * @param <T> The type of the aggregated results within a range.
+	 */
+	@Incubating
 	default <T> RangeAggregationOptionsStep<SR, ?, PDF, F, Map<Range<F>, T>> value(AggregationFinalStep<T> aggregation) {
 		return value( aggregation.toAggregation() );
 	}