Global aggregation #

A single-bucket aggregation whose nested aggregations run over all documents in the search context, ignoring the query scope. It is the baseline column of every analytic table: “this slice” next to “the whole dataset”, computed in the same request instead of a second round-trip.

How it works #

Normally an aggregation sees only the documents the query matched. global detaches its sub-aggregations from that scope: the engine takes the exact set of live documents — visibility and tombstones honored, per segment — and aggregates over that instead. The result is one bucket shaped { "doc_count": <all live docs>, …sub-aggs }; the aggregation itself takes no parameters beyond its sub-aggregations.

Because the outer query is irrelevant to the bucket, a filtered search still returns truthful totals: with a t-shirt term query over the teaching sales, the query-scoped average price is 15.0, while the global bucket reports 27.5 across all 120 sales.

Examples #

Compare the query’s average price against the whole dataset’s:

POST /sales/_search
{
  "query": { "term": { "field": "type", "value": "t-shirt" } },
  "aggs": {
    "all_products": {
      "global": {},
      "aggs": {
        "avg_price": { "avg": { "field": "price" } }
      }
    }
  }
}

Even under the t-shirt query the bucket reports every document:

{
  ...
  "aggregations": {
    "all_products": {
      "doc_count": 120,
      "avg_price": { "value": 27.5 }
    }
  }
}

Use cases #

• Percent-of-total. Divide a query-scoped sum by the global sum to state “this segment is 34 % of revenue” in one request.
• Baseline comparisons. Put the query’s average next to the dataset’s average (15.0 vs 27.5 above) to say whether a slice skews high or low.
• Constant denominators. Dashboards that need the fixed total alongside every filtered view get it without a second query per filter.
• Sanity checks. A global value_count confirms how many documents the index really holds under the current visibility rules.

Parameters for global #

• aggs
  (Required, object) Nested sub-aggregations — the whole point of global: they run over every document, not just the query’s matches.

Related #

• filter — the mirror image: a bucket narrowed to one query, this one widened to all of them
• missing — another scope-carving single bucket