Top metrics aggregation #

A metrics aggregation that returns metric values from the leading matching documents — a cheaper alternative to top_hits when you only need field values, not whole documents.

Engine note: sort is accepted for compatibility; the current implementation returns the metrics of the first size matching documents.

How it works #

top_metrics walks the bucket’s documents and emits one entry per document for the first size of them, in index order. Each entry maps every configured metric field to its value in that document. The response is the flat form {"top": [{"price": 15.0}, …]}.

• Metric fields must be numeric — a field that is missing, or not a number (strings included), comes back as null in the entry.

• The sort clause is parsed but does not steer the pick yet — the “top” documents are simply the first size matching documents.

• The column-store fast path reads each metric straight from the segment columns; the executor path reads per-document column values.

• Under distributed fan-out the coordinator keeps its own shard’s entries — there is no re-pick step in the merge.

Examples #

Over the 120 sales this returns the first sale’s price (15.0); with "size": 3 you get the first three sales’ prices.

One exemplar value per merchant — the usual nesting:

POST /sales/_search
{
  "size": 0,
  "aggs": {
    "merchants": {
      "terms": { "field": "merchant" },
      "aggs": {
        "sample_price": {
          "top_metrics": {
            "metrics": [{ "field": "price" }, { "field": "qty" }]
          }
        }
      }
    }
  }
}

Each of the four merchant buckets (30 sales each) gets a sample_price.top entry mapping price and qty to the bucket’s first sale.

Use cases #

• One number per bucket — dashboards that show each group’s exemplar value (a price, a status) without paying for full document sources.
• Cheaper top_hits — when only a field or two from the leading documents matter, skip source assembly entirely.
• Per-category representative — terms(category) with top_metrics inside surfaces a sample value per category, ready for a table column.

Parameters for top_metrics #

• metrics
  (Required, object array) field entries whose values are returned.
• sort
  (Optional, array) Sort clause selecting the “top” documents.
• size
  (Optional, integer, default: 1) How many top entries to return.

Related #

• top_hits — full documents, nested element hits, and a sort that ranks.
• terms — the bucket aggregation it usually nests in.