Why is Elasticsearch's cardinality aggregation approximate, and what does precision_threshold trade off?

## Why exact distinct counting is expensive To count distinct values exactly you must remember which values you already saw — a hash set whose size grows with the cardinality, not with the data volume. On a distributed index that is worse than it sounds: each shard would have to ship its full set of values to the coordinating node, because two shards seeing the same value must not count it twice. Summing per-shard distinct counts is simply wrong. So an exact distinct count across shards means moving the values themselves, with memory and network cost proportional to cardinality. ## What HyperLogLog++ does instead The `cardinality` aggregation hashes each value and keeps a fixed-size array of small registers, each recording the maximum number of leading zero bits seen in the hashes that mapped to it. Long runs of leading zeros are rare, so seeing one is evidence that many distinct hashes passed through. From the distribution of register values the algorithm estimates the number of distinct inputs. HyperLogLog++ is Google's refinement of HyperLogLog, adding bias correction and a sparse representation that is near-exact for small cardinalities. Three properties matter for interviews: 1. **Fixed memory.** The sketch's size depends on the configured precision, never on how many distinct values arrive. 2. **Mergeable.** Two sketches combine by taking the element-wise maximum of their registers, which is exactly the sketch you would have built from the union. That is what makes distributed counting cheap: each shard builds a sketch, the coordinating node merges them, and duplicates across shards collapse naturally. 3. **Deterministic.** The estimate is a function of the set of hashed values. The same documents produce the same estimate on every run — the error is a stable bias, not run-to-run noise. A user who checks a number twice will see the same wrong answer, which is why "just retry it" is not a diagnosis. ## precision_threshold ```json { "aggs": { "unique_users": { "cardinality": { "field": "user_id", "precision_threshold": 40000 } } } } ``` `precision_threshold` is the unique count below which results are expected to be close to accurate. It defaults to 3000 and the maximum supported value is 40000; values above that are capped. Memory is roughly `precision_threshold × 8` bytes per counter, so the maximum setting costs on the order of a few hundred kilobytes — per aggregation, per shard. That last clause is where operators get hurt. If a `cardinality` aggregation is nested under a `terms` aggregation with ten thousand buckets, you are asking each shard for ten thousand sketches. Raising precision on a nested cardinality is how a harmless-looking dashboard query starts tripping circuit breakers. Raising the threshold does not buy exactness above it. With `precision_threshold: 40000` and 50,000 actual distinct users, the answer is still an estimate — the setting only moves where meaningful error starts. ## Where the error shows up Error is relative, so it looks small in percentage terms and large in absolute ones: a fraction of a percent on ten million uniques is still tens of thousands of users. There is no per-response error bound for `cardinality` — the response carries a single `value` with no confidence interval — so you cannot inspect a given result and tell how far off it is. The operational consequence is that approximate distinct counts are fine for trends, dashboards, anomaly spotting and relative comparison, and unsuitable as the number on an invoice, a compliance report, or anything a customer will reconcile against their own records. ## Practical notes - `cardinality` accepts `missing`, so documents lacking the field can be folded in under a substitute value. - It counts distinct values, and multi-valued fields contribute each of their values, so "distinct tags" across an array field behaves as you would expect. - It can run over a script or a runtime field rather than an indexed field, at the cost of evaluating the script per value. - It aggregates the *indexed* values, so if a `keyword` field was normalized at index time (lowercased, for instance), the distinct count is over the normalized forms, not the raw source strings. Counting distinct values of an analyzed `text` field is almost never what anyone means and requires fielddata, which you should not enable. ## The answer an interviewer wants Name the algorithm, explain the bounded-memory and mergeability motivation, state that `precision_threshold` trades memory for accuracy with a hard ceiling, and finish on judgment: know which consumers of the number can tolerate approximation and have a plan — exact enumeration, a precomputed entity-per-document index, or an offline pipeline — for the ones that cannot.