Metrics and buckets

Calculation scope

Aggregations operate on query-matching documents independently of returned hit count. size=0 suppresses hits, not calculations. Bucket aggregations group documents and metric aggregations calculate values. Sub-aggregations see their parent bucket’s documents, so a brand’s average price differs from the catalog average.

Metrics and intervals

sum, avg, min, max and stats operate on numeric values; missing and multivalued fields need care. Range uses explicit boundaries; histogram uses numeric intervals. date_histogram distinguishes calendar_interval from fixed_interval: a calendar day is not always 24 hours across clock changes. Time zone is part of the analytical definition, not a display detail.

Names and nesting

Aggregation names become response contract keys. Sorting hits by price does not sort buckets by average price. terms on brand creates groups and avg computes a metric within each. A nested aggregation specifically addresses nested documents; ordinary sub-aggregation nesting does not require nested mapping.

{
  "size": 0,
  "aggs": {
    "brands": {
      "terms": {
        "field": "brand",
        "size": 10
      },
      "aggs": {
        "average_price": {
          "avg": {
            "field": "price"
          }
        }
      }
    }
  }
}

Catalog reasoning example

For Sony/100, Sony/200 and Bose/50, terms on brand yields two groups. avg(price) gives Sony 150 and Bose 50. If query first restricts price<150, Sony’s average becomes 100. Setting size=1 changes hits, not those averages. Read analytical trees by identifying the document scope, grouping and metric in that order.

Count products by brand

A terms aggregation creates buckets for exact indexed values. Here we group by category instead of brand. Each bucket has a key and doc_count. The terms size controls the number of returned buckets; the root size controls returned documents. These are unrelated parameters with the same name.

Use keyword fields for whole-value groups, such as category or brand.keyword. Default terms ordering favors larger counts, with deterministic tie handling by key. On multi-shard production data, top terms can have approximation considerations; this trainer uses one primary shard and a size large enough to include every value in these examples.

{
  "size": 0,
  "aggs": {
    "categories": {
      "terms": {
        "field": "category",
        "size": 10
      }
    }
  }
}

{
  "hits": {
    "total": {
      "value": 300,
      "relation": "eq"
    },
    "hits": []
  },
  "aggregations": {
    "categories": {
      "doc_count_error_upper_bound": 0,
      "sum_other_doc_count": 0,
      "buckets": [
        {
          "key": "Accessories",
          "doc_count": 75
        },
        {
          "key": "Audio",
          "doc_count": 75
        },
        {
          "key": "Computers",
          "doc_count": 75
        },
        {
          "key": "Smartphones",
          "doc_count": 75
        }
      ]
    }
  }
}

Average price

avg computes the mean of indexed numeric values in its current scope. The example calculates average price only for category Audio using a top-level query. The metric response contains value, not a list of products or a bucket count. Without a query it would describe the whole index.

Documents missing the metric field do not contribute a value to a standard average. If there are no usable numeric values, value is null rather than zero. Treat decimal results as numeric calculations: insignificant floating-point differences are not a change in meaning.

{
  "size": 0,
  "query": {
    "term": {
      "category": "Audio"
    }
  },
  "aggs": {
    "audio_average": {
      "avg": {
        "field": "price"
      }
    }
  }
}

{
  "hits": {
    "total": {
      "value": 75,
      "relation": "eq"
    },
    "hits": []
  },
  "aggregations": {
    "audio_average": {
      "value": 859.4133333333333
    }
  }
}

Price boundaries

min and max are independent metric aggregations, so place them as siblings in aggs. The example limits the population to Accessories and asks for both price endpoints. A metric always inherits the current scope: neither sibling changes the document set of the other.

These endpoints are observed values, not the boundaries of a range filter. If a query allows price below 800, the maximum observed price can be lower than 800. Empty populations produce null metric values, so do not invent an extreme zero for an empty group.

{
  "size": 0,
  "query": {
    "term": {
      "category": "Accessories"
    }
  },
  "aggs": {
    "lowest": {
      "min": {
        "field": "price"
      }
    },
    "highest": {
      "max": {
        "field": "price"
      }
    }
  }
}

{
  "hits": {
    "total": {
      "value": 75,
      "relation": "eq"
    },
    "hits": []
  },
  "aggregations": {
    "lowest": {
      "value": 99
    },
    "highest": {
      "value": 2499
    }
  }
}

Metrics per brand

A bucket can contain child aggs. Group categories, then calculate average_price for each category. This computes several separate averages rather than one global average copied next to every bucket. The response shape mirrors the request tree, so read it from the parent key toward its descendants.

Nesting aggregations is not the same feature as a nested query on a nested-mapped field. Our products contain ordinary scalar fields; no nested field mapping is needed for a category-to-metric tree. Keep the hierarchy within the trainer limits and estimate bucket multiplication before adding another grouping.

{
  "size": 0,
  "aggs": {
    "categories": {
      "terms": {
        "field": "category",
        "size": 10
      },
      "aggs": {
        "average_price": {
          "avg": {
            "field": "price"
          }
        }
      }
    }
  }
}

{
  "hits": {
    "total": {
      "value": 300,
      "relation": "eq"
    },
    "hits": []
  },
  "aggregations": {
    "categories": {
      "doc_count_error_upper_bound": 0,
      "sum_other_doc_count": 0,
      "buckets": [
        {
          "key": "Accessories",
          "doc_count": 75,
          "average_price": {
            "value": 859.4
          }
        },
        {
          "key": "Audio",
          "doc_count": 75,
          "average_price": {
            "value": 859.4133333333333
          }
        },
        {
          "key": "Computers",
          "doc_count": 75,
          "average_price": {
            "value": 589.2
          }
        },
        {
          "key": "Smartphones",
          "doc_count": 75,
          "average_price": {
            "value": 589.88
          }
        }
      ]
    }
  }
}

Category and brand analytics

Use three levels: category buckets, then brand buckets, then numeric metric leaves. Our example analyzes active products, groups them by category and brand.keyword and computes three price metrics per pair. All metrics under a brand inherit both the category restriction and the brand restriction.

The query is outside aggs and restricts all groups. Each terms size is local to that level. At sizes 10 and 20, the conservative bucket estimate is 10 + 10 × 20 = 210, within the trainer budget of 1000. The metric leaves occupy the third level but do not multiply the number of buckets.

Read the response as categories.buckets → brands.buckets → metric.value. Never combine the metrics of different category-brand pairs unless the business question explicitly asks for a new calculation. A mean of group means is generally not the same as the overall document mean.

{
  "size": 0,
  "query": {
    "term": {
      "status": "active"
    }
  },
  "aggs": {
    "categories": {
      "terms": {
        "field": "category",
        "size": 10
      },
      "aggs": {
        "brands": {
          "terms": {
            "field": "brand.keyword",
            "size": 20
          },
          "aggs": {
            "average_price": {
              "avg": {
                "field": "price"
              }
            },
            "min_price": {
              "min": {
                "field": "price"
              }
            },
            "max_price": {
              "max": {
                "field": "price"
              }
            }
          }
        }
      }
    }
  }
}

{
  "hits": {
    "total": {
      "value": 100,
      "relation": "eq"
    },
    "hits": []
  },
  "aggregations": {
    "categories": {
      "doc_count_error_upper_bound": 0,
      "sum_other_doc_count": 0,
      "buckets": [
        {
          "key": "Accessories",
          "doc_count": 25,
          "brands": {
            "doc_count_error_upper_bound": 0,
            "sum_other_doc_count": 0,
            "buckets": [
              {
                "key": "apple",
                "doc_count": 25,
                "average_price": {
                  "value": 859.4
                },
                "min_price": {
                  "value": 99
                },
                "max_price": {
                  "value": 2499
                }
              }
            ]
          }
        },
        {
          "key": "Audio",
          "doc_count": 25,
          "brands": {
            "doc_count_error_upper_bound": 0,
            "sum_other_doc_count": 0,
            "buckets": [
              {
                "key": "apple",
                "doc_count": 25,
                "average_price": {
                  "value": 859.4
                },
                "min_price": {
                  "value": 99
                },
                "max_price": {
                  "value": 2499
                }
              }
            ]
          }
        },
        {
          "key": "Computers",
          "doc_count": 25,
          "brands": {
            "doc_count_error_upper_bound": 0,
            "sum_other_doc_count": 0,
            "buckets": [
              {
                "key": "Sony",
                "doc_count": 25,
                "average_price": {
                  "value": 589.2
                },
                "min_price": {
                  "value": 49
                },
                "max_price": {
                  "value": 1299
                }
              }
            ]
          }
        },
        {
          "key": "Smartphones",
          "doc_count": 25,
          "brands": {
            "doc_count_error_upper_bound": 0,
            "sum_other_doc_count": 0,
            "buckets": [
              {
                "key": "Sony",
                "doc_count": 25,
                "average_price": {
                  "value": 589.2
                },
                "min_price": {
                  "value": 49
                },
                "max_price": {
                  "value": 1299
                }
              }
            ]
          }
        }
      ]
    }
  }
}