Elasticsearch Max Aggregation - Maximum Value of a Numeric Field

Q: Does max work on date fields?

Yes. Date fields are stored as epoch milliseconds ( date ) or nanoseconds ( date_nanos ), and max returns the largest stored number. Use the format parameter to render the result as a formatted date string.

Q: How does max handle missing values?

Documents without the field are skipped unless missing is set. With missing , the substitute value participates in the comparison.

Q: What does max return when no documents match?

value is null and value_as_string is absent. Client code should handle the null case explicitly.

Q: How do I get min, max, sum, avg, and count in one call?

Use the stats aggregation, which returns all five in a single response with one pass over doc values.

The Elasticsearch max aggregation is a single-value metric aggregation that returns the largest value extracted from the documents in a bucket. It works on numeric fields and on date/date_nanos fields (treated as milliseconds or nanoseconds since epoch). Use it to find peak observations: highest price per category, most recent timestamp per host, or maximum response time per endpoint.

Syntax

GET /products/_search
{
  "size": 0,
  "aggs": {
    "max_price": {
      "max": {
        "field": "price",
        "missing": 0
      }
    }
  }
}

Result is a double (or formatted date string for date fields) at aggregations.max_price.value.

Parameters

Parameter	Default	Description
`field`	required (or `script`)	Numeric or date field to scan.
`missing`	-	Substitute used when the field is missing. Without it, missing docs are ignored.
`script`	-	Use a Painless script. Slower than field access.
`format`	-	Numeric/date format applied to `value_as_string`.

Examples

Latest event timestamp per host:

"aggs": {
  "by_host": {
    "terms": { "field": "host.keyword", "size": 100 },
    "aggs": {
      "last_seen": {
        "max": { "field": "@timestamp", "format": "yyyy-MM-dd'T'HH:mm:ss" }
      }
    }
  }
}

Highest price overall, scoped by a query:

GET /products/_search
{
  "size": 0,
  "query": { "term": { "in_stock": true } },
  "aggs": {
    "ceiling": { "max": { "field": "price" } }
  }
}

Max of a computed value via script:

"max": {
  "script": {
    "source": "doc['price'].value * (1 - doc['discount'].value)"
  }
}

Performance Notes

max reads doc values for the target field and runs in linear time over the matched documents. On indexed numeric and date fields it is near-free; on text fields it requires fielddata and is best avoided - prefer a .keyword sub-field for ordering, or a numeric sub-field for true maxima.

Scripted max evaluates the script per document and disables doc-value range optimizations. For very large indices, prefer indexing the computed value than calculating it at query time. When max is nested deep inside high-cardinality buckets, each bucket maintains its own running maximum - cheap individually, but cumulative across millions of buckets it pushes coordinator memory. Pulse monitors aggregation latency and heap pressure on Elasticsearch and OpenSearch clusters and surfaces patterns where simple metrics like max are amplified by their bucket parents.

Common Mistakes

Running max on a text field without a numeric sub-field, triggering fielddata.
Using max to find "the most recent document" - it returns only the timestamp. To return the document, combine a terms agg with top_hits sorted desc by timestamp.
Ignoring missing when a field is sparse - documents without the field do not lower the max, but they may not be present in the dataset at all if the parent query filters them out.
Treating the returned date as a formatted string by default. value is a number (epoch millis); value_as_string carries the formatted form.
Using max where min, percentiles, or stats would answer the actual question.

Frequently Asked Questions

Q: Does max work on date fields?
A: Yes. Date fields are stored as epoch milliseconds (date) or nanoseconds (date_nanos), and max returns the largest stored number. Use the format parameter to render the result as a formatted date string.

Q: How does max handle missing values?
A: Documents without the field are skipped unless missing is set. With missing, the substitute value participates in the comparison.

Q: What does max return when no documents match?
A: value is null and value_as_string is absent. Client code should handle the null case explicitly.

Q: How do I get min, max, sum, avg, and count in one call?
A: Use the stats aggregation, which returns all five in a single response with one pass over doc values.

Q: Can I use max on a runtime field?
A: Yes, but the runtime script executes per document, which is much slower than doc-value reads. Index the value if you query it often.

Q: How is max different from max_bucket?
A: The max aggregation returns the highest field value across documents. The max_bucket pipeline aggregation returns the bucket with the highest metric value across sibling buckets - different stages of the pipeline.

Sum Aggregation: totals rather than peaks.
Top Hits Aggregation: return the actual document with the max value, not just the value.
Value Count Aggregation: exact value count, often paired with max in dashboards.
Date Histogram Aggregation: bucket time series before applying max.
Elasticsearch Query Language: the DSL max runs inside.

Elasticsearch Max Aggregation - Maximum Value of a Numeric Field - Syntax, Example, and Tips