Max aggregation #

A single-value metrics aggregation that keeps track and returns the maximum value among the numeric values extracted from the aggregated documents. It answers “how high does this field go” over any query — the top of a price range, the latest timestamp in a window, the biggest order that matches a filter.

How it works #

The engine walks the matching documents once, keeping the largest value seen; any smaller value costs one comparison. Values are coerced to doubles as they are read — integers, floats and booleans (true = 1, false = 0) qualify, non-numeric values such as keyword strings do not.

Documents that lack the field are skipped by default. With missing set, the default is folded into the comparison whenever at least one candidate document lacks the field — a missing document can therefore become the maximum.

On the column-store fast path (the production executor) each segment’s column is decoded once and reduced in a batch (max_f64), with count_present deciding whether the missing default applies; segments and shards combine by pairwise max, so distributed and single-node requests return the same number. Everything is exact — no approximation is involved.

When no document contributed a value, the result is null — an empty set has no meaningful maximum.

Examples #

Computing the max price value across all documents — the SQL pill beside the Run button answers the same question with MAX(price):

POST /sales/_search
{
  "aggs": {
    "max_price": {
      "max": {
        "field": "price"
      }
    }
  }
}

Response:

{
  ...
  "aggregations": {
    "max_price": {
      "value": 60.0
    }
  }
}

As can be seen, the name of the aggregation (max_price above) also serves as the key by which the aggregation result can be retrieved from the returned response.

Use cases #

• Price ceilings. sales.max(price) = 60.0 — the highest price in the 120 teaching sales; together with min it states the full 15..60 range in one response.
• Outlier spotting. Avg price is 27.5 and the max is more than twice that — the few expensive orders pull the mean, a first hint before reaching for percentiles.
• Capacity planning. On telemetry-style data, max over a time window gives the peak you must provision for, not the typical load.
• Per-group extremes. Nested under terms, max(price) per product type finds the premium item in each line.
• Freshness checks. The highest value of a monotonically increasing field (sequence numbers, timestamps) tells you how far ingestion has progressed for any slice of the data.

Parameters for max #

• field
  (Required, string) Field you wish to aggregate.
• script
  (Optional, object) Script evaluated per document as the value source — mutually exclusive with field.
• missing
  (Optional, number) Value used for documents missing the field; it takes part in the comparison, so it can become the maximum.

Related #

• min — the mirror image of this aggregation
• stats — min and max plus count/avg/sum in one request
• percentiles — the whole distribution, not just the ends
• max_bucket — max over another aggregation’s bucket values