Search finds documents. Aggregations summarize them. The "browse by genre (142)" sidebar on an online bookstore is a facet, and facets are built with aggregations. This article shows you the terms aggregation on the books index, then explains why its counts can be approximate on a multi-shard index and how to tighten them.
This is Part 4 of a beginner series on search with Amazon OpenSearch Service . Continue with the books index and Dev Tools from the earlier parts. Your first facet: the terms aggregation
A facet is a count of documents grouped by the distinct values of a field. The terms aggregation produces exactly that: one bucket per unique term, with a document count. Run it with size: 0 so you get the aggregation without the search hits.
GET books/_search
{
"size": 0,
"aggs": {
"by_genre": {
"terms": { "field": "genre.keyword", "size": 10 }
}
}
}
Two details matter. First, aggregate on genre.keyword , not genre : the terms aggregation requires a keyword , numeric, boolean, date, or IP field, and analyzed text fields are not valid targets. Second, size controls how many buckets come back, defaulting to 10, and buckets are sorted by document count descending by default.
Facets alongside a search
Facets are most useful next to results. Put a query and an aggregation in the same request, and the aggregation counts only the documents that match the query.
GET books/_search
{
"query": {
"match": { "title": "wizard" }
},
"aggs": {
"by_genre": {
"terms": { "field": "genre.keyword" }
}
}
}
Now the by_genre buckets describe the genres of the books that matched "wizard", which is the "narrow your results" experience readers expect.
Why the counts can be approximate
Here is the part that surprises people. When your index has more than one shard, the terms aggregation can return slightly inaccurate counts. The coordinating node asks each shard for its top terms, then merges the shard responses. If a term is just outside a shard's top list, that shard's contribution to the term is missed, and the merged count comes out low.
OpenSearch is honest about this in the response. Every terms aggregation returns two bookkeeping fields:
-
doc_count_error_upper_bound — the maximum number of documents that could be missing from any returned bucket's count. It is your margin of error.
-
sum_other_doc_count — the number of matching documents that fell outside the returned buckets entirely.
If doc_count_error_upper_bound is 0, your counts are exact.
The fix: shard_size
The shard_size parameter controls how many candidate terms each shard returns to the coordinating node. It is separate from size , and it exists specifically to improve count accuracy. Raising it makes each shard send a longer list, so terms near the boundary are less likely to be missed.
GET books/_search
{
"size": 0,
"aggs": {
"by_genre": {
"terms": {
"field": "genre.keyword",
"size": 10,
"shard_size": 200
}
}
}
}
By default, shard_size is size * 1.5 + 10 . Increasing it trades compute and memory for accuracy: higher values give more accurate counts but cost more per query. A value like 200 is a common choice when you need facet counts to match a source of truth. This is the same lever you reach for when facet totals in a migrated or sharded index do not line up with expectations.
A facet cheat-sheet
- Aggregate on a
keyword (or numeric/date/boolean) field, never analyzed text .
- Use
size: 0 at the request level when you only need the facet, not the hits.
- Check
doc_count_error_upper_bound . Zero means exact; nonzero means raise shard_size .
- Reach for
shard_size (for example, 200) when accuracy matters more than raw speed.
Where this series goes next
You can now summarize results, not just retrieve them, and you know how to keep those summaries accurate. In Part 5, you go back to the hits and control their order: how relevance scoring works, why OpenSearch uses BM25, and how field boosting and multi_match change the ranking.
If your facet counts look off, paste the aggregation and the two bookkeeping fields from your response and I will help you decide whether shard_size is the fix.
Loading article