AWS Builder Center
Aggregations and facets in OpenSearch

Aggregations and facets in OpenSearch

In this article, you build a genre facet with the terms aggregation, and learn the one parameter that keeps facet counts accurate when your index has more than one shard.

Series: Search on OpenSearch (8 articles)

  1. …
  2. 4
    Aggregations and facets in OpenSearch This article
OpenSearch Specialist Solutions Architect at AWS
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.

Series: Search on OpenSearch (8 articles)

  1. …
  2. 4
    Aggregations and facets in OpenSearch This article
Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.
Enjoyed reading this content? Let the author know!

Your likes, comments, shares, and saves help creators reach more builders.

Loading recommendations

Loading article