IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.
« Searching for documents Troubleshooting »
Elastic Docs ›Elasticsearch Java API Client [8.8] ›Using the Java API Client

Aggregations

edit

Aggregations

edit

An aggregation summarizes your data as metrics, statistics, or other analytics.

See the Elasticsearch documentation for a full explanation of aggregations.

A simple aggregation

edit

In the example below we run an aggregation that creates a price histogram from a product index, for the products whose name match a user-provided text. To achieve this, we use a search request that has a query (explained in Searching for documents) and an aggregation definition.

This example is an analytics-type aggregation where we do not want to use the matching documents. A general pattern for search requests used for analytics is to set the result size to zero and the target class for search results to Void.

If that same aggregation was used for to display products and the price histogram as drill-down facets, we would have set size to a non-zero value and used Product as the target class to process the results.

String searchText = "bike";

Query query = MatchQuery.of(m -> m
    .field("name")
    .query(searchText)
)._toQuery();

SearchResponse<Void> response = esClient.search(b -> b
    .index("products")
    .size(0) 
    .query(query) 
    .aggregations("price-histogram", a -> a 
        .histogram(h -> h 
            .field("price")
            .interval(50.0)
        )
    ),
    Void.class 
);

Set the number of matching documents to zero as we only use the price histogram.

Set the query that fill filter the products on which to run the aggregation

Create an aggregation named "price-histogram". You can add as many named aggregations as needed.

Select the histogram aggregation variant.

We do not care about matches (size is set to zero), using Void will ignore any document in the response.

The response contains an aggregation result for each aggregation in the request.

List<HistogramBucket> buckets = response.aggregations()
    .get("price-histogram") 
    .histogram() 
    .buckets().array(); 

for (HistogramBucket bucket: buckets) {
    logger.info("There are " + bucket.docCount() +
        " bikes under " + bucket.key());
}

Get the results for the "price-histogram" aggregation.

Cast it down to the histogram variant results. This has to be consistent with the aggregation definition.

Buckets can be expressed as arrays or maps. This casts down to the array variant (the default).

The source code for the examples above can be found in the Java API Client tests.

« Searching for documents Troubleshooting »