Sampler aggregation #

A single-bucket aggregation that keeps only a sample of the matching documents before running its sub-aggregations — used to cut aggregation cost on very large result sets. If a terms aggregation over millions of documents is too slow or too memory-hungry, sampling trades exact counts for an order-of-magnitude answer at a fraction of the cost.

How it works #

The sampler keeps the first shard_size matching documents (default 100) and discards the rest; its sub-aggregations then run over that sample only. The result is a single bucket keyed sample, carrying the sample’s doc_count and the sub-aggregation results:

"sampled": { "doc_count": 60, "types": { "buckets": [ … ] } }

Because the cut is positional (candidates in doc-id order), the sample is deterministic for the same query and index state — replaying a request reproduces the same numbers. Anything nested under the sampler sees only the sampled documents; sibling aggregations outside it are unaffected.

shard_size bounds the sample on the executing node; in a distributed run each shard contributes up to shard_size documents and the partial results merge (single-bucket merge sums the doc counts).

One caveat follows from the positional cut: the sample is the leading block of the candidate set, not a random draw. When documents cluster — the oldest segment holding one product line, one day of one datacenter — whatever sits early is over-represented. Reach for diversified_sampler when the sample must stay balanced across a field’s values.

Example #

Sample 60 documents, then count types inside the sample:

Use cases #

• High-cardinality fields, bounded cost. Terms over a field with millions of distinct values: sample first, then aggregate, so the bucket count and the work stay proportional to shard_size.
• Exploratory dashboards. Get approximate distributions over huge time ranges instantly; drop the sampler when the numbers matter.
• Sample-then-signify. Feed a sampled scope to significant_terms instead of the full foreground set.
• Cost-capped exploration of logs. Terms over logs.message-style high-cardinality text with a sampler ceiling keeps the working set bounded no matter how wide the time filter is.

Parameters for sampler #

• shard_size
  (Optional, integer, default: 100) Sample size per shard.
• aggs
  (Optional, object) Sub-aggregations computed over the sample.

Related #

• diversified_sampler — same cap, but spread evenly across a field’s values
• significant_terms — the classic consumer of a sampled scope