Value count aggregation #

A single-value metrics aggregation that counts the number of values that are extracted from the aggregated documents. Typically, this aggregator will be used in conjunction with other single-value aggregations. For example, when computing the avg one might be interested in the number of values the average is computed over.

value_count does not de-duplicate values, so even if a field has duplicates each value will be counted individually.

How it works #

The engine counts the values a field actually holds across the matching documents — not the documents themselves. A document without the field contributes nothing; a field with a value in every document counts one per document, and a document whose field holds an array also counts once (per element spreading is bucket-aggregation behavior). No numeric coercion is involved: any present value counts, whatever its type.

With missing set, documents that lack the field are treated as carrying the default — one contribution each — so the count then equals the number of matching documents.

On the column-store fast path (the production executor) each segment’s column is decoded once and count_present supplies the per-segment count in a single batch; per-shard counts combine by plain addition, so the result is exact and identical on single-node and distributed requests. Like sum, it never returns null — an empty match is a count of zero.

Examples #

Counting the values of type — one number per value present, no de-duplication; COUNT(*) on the SQL side:

POST /sales/_search
{
  "aggs" : {
    "types_count" : {
      "value_count" : {
        "field" : "type"
      }
    }
  }
}

Response:

{
  ...
  "aggregations": {
    "types_count": {
      "value": 120
    }
  }
}

The name of the aggregation (types_count above) also serves as the key by which the aggregation result can be retrieved from the returned response.

Use cases #

• Denominators. sales.value_count(price) = 120 is the N behind avg(price) = 27.5 — display both and a mean never masquerades as a median built on three points.
• Field completeness audits. Only 20 of the 44 articles docs carry title (the rest are relation edges): value_count(title) = 20 next to places.total-style totals exposes sparse fields at a glance.
• Coverage rates. Divide the count by the match count to get “share of documents that have this field” — data-quality dashboards in one request.
• Sparse-field discovery. Run one value_count per field over the same query and sort by the result: fields that come back well below the match count are the ones client code cannot rely on.
• Distinctness checks. Pair with cardinality: type has 120 values but only 4 distinct ones — high duplication, a candidate for terms instead.

Parameters for value_count #

• field
  (Required, string) Field you wish to aggregate.
• script
  (Optional, object) Script evaluated per document as the value source — mutually exclusive with field.
• missing
  (Optional, value) Value used for documents missing the field; each such document then counts as one contribution.

Related #

• cardinality — the de-duplicating count
• stats — count plus min/max/avg/sum in one request
• terms — count per distinct value