Nested aggregation #

A single-bucket aggregation that scopes its sub-aggregations to a nested object path. Nested field values are addressable as dotted columns, so sub-aggregations read variants.color style fields directly — counting per array element where it matters, not per parent document.

reverse_nested (only valid inside a nested aggregation) jumps back out to the parent-document scope.

How it works #

The engine returns a single bucket shaped { "doc_count": <parents>, …sub-aggs }. Sub-aggregations run over the parent documents, but the nested path’s values live in multivalue dotted columns, so a terms on variants.color buckets every array ELEMENT: over the 30 teaching products with 60 variant elements, black / white / blue each collect 20. One exception is top_hits, which is element-level here: each hit is one stored element carrying _nested: {field, offset} identity, sorted per the requested sort.

reverse_nested returns one bucket keyed reverse_nested over the same parent set — the ladder back out after diving into a path.

Examples #

Products carry a variants array; aggregate one value per parent product inside the nested scope, then reverse back out:

colors counts elements (20 / 20 / 20 across 60 variants); back_out reports the 30 parent products:

{
  ...
  "aggregations": {
    "in_variants": {
      "doc_count": 30,
      "colors": {
        "buckets": [
          { "key": "black", "doc_count": 20 },
          { "key": "blue", "doc_count": 20 },
          { "key": "white", "doc_count": 20 }
        ]
      },
      "back_out": {
        "buckets": [
          { "key": "reverse_nested", "doc_count": 30 }
        ]
      }
    }
  }
}

Use cases #

• Per-variant inventory. Count sizes or colors across every variant element while the outer query stays at product grain.
• Element-level top lists. top_hits under nested returns individual variants (with _nested offsets), not whole products.
• Line-item analytics. Orders with nested line_items: sum per item field inside the path, then reverse_nested for order-level context in the same request.
• Inner-hit preview. Pair with the nested query to see which elements matched and which statistics they feed.

Parameters for nested #

• path
  (Required, string) Path of the nested object (dotted).
• aggs
  (Optional, object) Sub-aggregations in nested scope.

Parameters for reverse_nested #

• aggs
  (Optional, object) Sub-aggregations back in the parent scope.

Related #

• children — the relation-field counterpart
• Nested query — element-wise matching within one array element
• top_hits — element-level hits under nested
• terms — the workhorse inside a nested scope