Rare terms aggregation #

A multi-bucket aggregation that keeps only RARE terms — bucket keys whose document count is at or below max_doc_count. The mirror image of terms for finding the long tail: instead of the top-N most frequent values, it returns every low-frequency value.

How it works #

Bucketing works exactly like terms: one bucket per unique value of field, multi-valued fields counted per element, and documents without the field either skipped or folded into a missing bucket. include/exclude filter candidate keys up front (exact-value arrays or a single wildcard string prefix* / *suffix).

The difference is the cut: after counting, buckets with doc_count <= max_doc_count (default 1) survive and the rest are dropped — the inverse of terms’ min_doc_count. Surviving buckets are ordered by doc_count ASCENDING (rarest first). There is no size truncation: every rare term is returned, because the interesting population is by definition small.

For the example below the response is a single bucket:

"rare_types": {
  "buckets": [
    { "key": "sticker", "doc_count": 10 }
  ]
}

terms could approximate this with a small size and luck, but it would still rank by descending count and truncate; rare_terms expresses “everything at or below this frequency” directly.

Example #

Every product type sells ≥10 times; raise the bar to 15 and only sticker (10 sales) survives:

Use cases #

• Long-tail tag inventory. Of the 30 distinct tags on the teaching articles, 25 appear on exactly one article — rare_terms on tags lists them all in one shot.
• Singleton detection for data quality. Values occurring once are often typos: rare terms on customers.city surfaces mis-entered cities for cleanup.
• One-off events. Hosts, URLs or error codes seen a single time in logs — the prefix of any anomaly hunt.
• Complement of a leaderboard. Pair a terms (top values) with a rare_terms (everything rare) to describe a field’s full shape in one request.
• Frequency-band filtering. max_doc_count: 2 on articles.tags widens the net to the handful of tags used twice (optimizer, search, sharding, storage, vector) while ignoring the workhorse tags entirely.

Parameters for rare_terms #

• field
  (Required, string) Keyword field you wish to aggregate.
• max_doc_count
  (Optional, integer, default: 1) Maximum document count for a term to be considered rare.
• missing
  (Optional, value) Value substituted for documents without the field; they land in one bucket keyed by it.
• include / exclude
  (Optional) Restrict candidate terms (exact values or wildcard patterns).
• aggs
  (Optional, object) Nested sub-aggregations, computed per bucket.

Related #

• terms — the frequent side of the same field
• significant_terms — rare AND unusually concentrated in a scope