Cardinality aggregation
/ Cardinality, / AggregationCardinality 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
missingis set, they all count as one additional distinct value; withoutmissingthey 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.)
...