Cardinality aggregation #

A single-value metrics aggregation that counts the number of distinct values of a field — how many different types were sold, how many different hosts logged, how many different authors wrote.

How it works #

The engine counts with a HyperLogLog++ sketch — tuned so that small counts stay exact:

• Values are hashed (MurmurHash3, 64-bit) into a sketch that keeps an exact set while the number of distinct values stays at or below precision_threshold; those counts are returned verbatim.
• Above the threshold the sketch promotes to dense HyperLogLog registers, so memory stops growing with the data: roughly 1.6% relative error at the default threshold of 3000, tightening to about 0.4% at the maximum of 40000. The returned value is always a rounded whole number.
• When documents lack the field and missing is set, they all count as one additional distinct value; without missing they are simply not counted.

Distributed queries ship the sketch itself with each shard’s partial result and the coordinating node unions the sketches before estimating — the same number a single-node execution over all shards' documents would produce. (Cardinality nested inside bucket sub-aggregations still merges its per-shard finalized counts by maximum, a lower bound, when no sketch travels with them.)

Examples #

Distinct values — COUNT(DISTINCT …) on the SQL side (the pill beside the Run button):

POST /sales/_search
{
  "aggs": {
    "type_count": {
      "cardinality": {
        "field": "type"
      }
    }
  }
}

Response:

{
  ...
  "aggregations": {
    "type_count": {
      "value": 4
    }
  }
}

Four product types (t-shirt, hat, mug, sticker), and the same shape of question over the other teaching datasets gives 4 merchants in sales, 3 hosts and 3 log levels in logs, and 4 authors across the 44 articles.

Use cases #

• Unique counts. Distinct users, hosts, sessions or SKUs — the canonical cardinality question. Over logs, cardinality on host is “how many servers am I actually hearing from” (3: web-01 … web-03).
• Gauging dimensionality before faceting. Run cardinality on a field before you build a terms aggregation on it: 4 distinct types is a clean facet, 4 million is a dashboard that will not load.
• Data-quality checks. A field expected to be nearly unique (_id-like) should return cardinality ≈ value_count; a gap means duplicates. Compare with value_count, which counts values without de-duplicating.
• Funnel and coverage metrics. “In how many distinct days did each customer buy” is a cardinality nested per customer under terms.

Parameters for cardinality #

• field
  (Required, string) Field you wish to aggregate.
• precision_threshold
  (Optional, integer) Counts are exact at or below this many distinct values; above it, the HyperLogLog++ estimate takes over (default 3000, maximum 40000 — larger requests clamp to 40000). Higher thresholds cost more memory, not more time.
• missing
  (Optional, value) Value used for documents missing the field; all such documents count as one distinct value.

Related #

• value_count — total values, no de-duplication; the ratio cardinality / value_count measures repetition.
• terms — not just how many distinct values, but which ones, with per-value counts.
• cumulative_cardinality — the running distinct count across date_histogram buckets.