Elasticsearch aggregations enable powerful data summarization over search results. Among the four main aggregation types—metric, bucket, matrix, and pipeline—metric aggregations compute numeric statistics from document fields.

Average Aggregation

Computes the arithmetic mean of a numeric field. For example, to calculate the average student grade:

POST /student/_search?size=0
{
  "aggs": {
    "average_score": {
      "avg": {
        "field": "grade"
      }
    }
  }
}

For weighted averages (e.g., when each grade has an asociated weight), use weighted_avg:

POST /student/_search?size=0
{
  "aggs": {
    "weighted_average": {
      "weighted_avg": {
        "value": { "field": "grade" },
        "weight": { "field": "weight" }
      }
    }
  }
}

Min/Max Aggregations

Retrieve the minimum or maximum value in a field:

POST /student/_search?size=0
{
  "aggs": {
    "highest_score": { "max": { "field": "grade" } }
  }
}

POST /student/_search?size=0
{
  "aggs": {
    "lowest_score": { "min": { "field": "grade" } }
  }
}

Sum Aggregation

Caclulates the total sum of a numeric field:

POST /student/_search?size=0
{
  "aggs": {
    "total_points": { "sum": { "field": "grade" } }
  }
}

Top Hits Aggregation

Returns actual document hits from with in buckets, useful for retrieving representative records. The following example groups by grade and fetches the top document per group, sorted by grade in descending order:

POST /student/_search?size=0
{
  "aggs": {
    "by_grade": {
      "terms": {
        "field": "grade",
        "size": 2
      },
      "aggs": {
        "sample_docs": {
          "top_hits": {
            "sort": [{ "grade": { "order": "desc" } }],
            "_source": ["name", "grade"],
            "size": 1
          }
        }
      }
    }
  }
}

Java API Implementation

Using the Elasticsearch Java High Level REST Client:

private static void executeAvgAggregation() throws IOException {
    AggregationBuilder avgAgg = AggregationBuilders.avg("avg_score").field("grade");
    processAggregation(avgAgg, "avg_score");
}

private static void executeMaxAggregation() throws IOException {
    AggregationBuilder maxAgg = AggregationBuilders.max("max_score").field("grade");
    processAggregation(maxAgg, "max_score");
}

private static void executeSumAggregation() throws IOException {
    AggregationBuilder sumAgg = AggregationBuilders.sum("total_score").field("grade");
    processAggregation(sumAgg, "total_score");
}

private static SearchResponse runSearch(AggregationBuilder agg) throws IOException {
    SearchRequest request = new SearchRequest("student");
    SearchSourceBuilder sourceBuilder = new SearchSourceBuilder();
    sourceBuilder.fetchSource(false);
    sourceBuilder.aggregation(agg);
    request.source(sourceBuilder);
    return client.search(request, RequestOptions.DEFAULT);
}

private static void processAggregation(AggregationBuilder builder, String key) throws IOException {
    SearchResponse response = runSearch(builder);
    Aggregations aggs = response.getAggregations();
    
    if (key.contains("avg")) {
        Avg result = aggs.get(key);
        System.out.println(key + ": " + result.getValue());
    } else if (key.contains("max")) {
        Max result = aggs.get(key);
        System.out.println(key + ": " + result.getValue());
    } else if (key.contains("sum")) {
        Sum result = aggs.get(key);
        System.out.println(key + ": " + result.getValue());
    }
}