Multi terms aggregation #

A multi-bucket aggregation like terms, but the bucket key is a TUPLE of values from several fields — e.g. every (merchant, status) combination. It answers cross-tab questions — “rows by column” tables — that a single-field terms aggregation cannot express without chaining requests.

How it works #

Each entry in the terms array contributes one component of the composite key. A document is placed in the bucket keyed by the tuple of its values, and the response reports each bucket’s key as an array — ["infini-store", "pending"].

A document contributes only when EVERY listed field has a value: a document missing any component field is skipped entirely (there is no missing fallback here, unlike terms). Multi-valued fields are not expanded per element on this aggregation — a document whose field holds an array is skipped as well.

Buckets are ordered by doc_count descending (ties in arbitrary order) and truncated to size (default 10). Nested sub-aggregations run per composite bucket exactly as they do under terms.

Over the teaching data, merchant × status produces twelve buckets of 10 sales each; the response reports each key as an array:

"pairs": {
  "buckets": [
    { "key": [ "infini-store", "delivered" ], "doc_count": 10 },
    { "key": [ "infini-store", "pending" ],  "doc_count": 10 },
    { "key": [ "infini-store", "shipped" ],  "doc_count": 10 },
    ...
  ]
}

Example #

Each bucket’s key is an array [merchant, status].

Use cases #

• Cross-tab grids. merchant × status over the teaching sales covers 12 combinations of 10 documents each — the skeleton of a pivot table, in one request.
• Revenue per cell. Nest a sum on amount to turn the count grid into a revenue matrix (type × status, merchant × type, …).
• Compound dimension drill-down. When a report needs “per (category, tier)” figures, one multi_terms replaces two chained terms aggregations and a client-side join.
• Slice matrices for reporting. type × status with a nested avg on price fills a spreadsheet-shaped result directly — each cell self-describing via its array key.

Parameters for multi_terms #

• terms
  (Required, object array) Two or more field entries forming the composite key.
• size
  (Optional, integer, default: 10) Maximum number of buckets.
• aggs
  (Optional, object) Nested sub-aggregations, computed per bucket.

Buckets always sort by doc_count descending; the order and min_doc_count parameters are not accepted.

Related #

• terms — single-field version
• rare_terms, significant_terms — filtered views of the value space
• composite — paginates large key sets (also multi-field)