Part 12 of 1867% complete

2026-05-22•9 min read

Aggregations and facet counts

A search box rarely returns only hits. Next to the results sit counts: how many matches per state, per city, per gender. This chapter builds those facet counts. You run the aggregations a profile search needs in Kibana Dev Tools and check every number against PostgreSQL, reproduce the case where a top-N count is simply wrong, and add a /api/users/facets endpoint to the Search API whose counts stay useful after the user has already picked a filter.

You need the lab over TLS and the search-api module from chapter 11. The chapter takes about 45 minutes.

How aggregations work, and what they need from the mapping

What it is. An aggregation computes a summary over every document that matches the query: bucket aggregations group documents (per state, per month), and metric aggregations compute numbers (a count, a distinct count). They run in the same request as the search, over the same matching set. The aggregations reference lists every type.

Why it matters at 300 million profiles. A facet over a broad query touches millions of documents. It must read each document’s value quickly, which is what doc values provide: the per-document, column-oriented storage that keyword, numeric, and date fields have by default. Chapter 05’s capability matrix marked state, city, gender, accountStatus, and the date fields as aggregatable for exactly this reason, and chapter 06 showed what happens with a text field instead.

Example. Active profiles per state, top three, with size: 0 because only the counts are needed:

1
GET user-profile-read/_search?filter_path=aggregations
2
{
3
  "size": 0,
4
  "query": { "bool": { "filter": [ { "term": { "accountStatus": "ACTIVE" } } ] } },
5
  "aggs": { "by_state": { "terms": { "field": "state", "size": 3 } } }
6
}

1
{"aggregations":{"by_state":{"doc_count_error_upper_bound":0,"sum_other_doc_count":350174,
2
 "buckets":[{"key":"maharashtra","doc_count":140008},{"key":"bihar","doc_count":139925},{"key":"karnataka","doc_count":70317}]}}}

PostgreSQL’s GROUP BY state over active profiles gives the same three counts. Two fields in the response matter. sum_other_doc_count is the number of matching documents in states outside the top three. doc_count_error_upper_bound is the worst-case error of the counts shown, and here it is 0.

Common mistake. Displaying bucket keys directly. The keys are the indexed values, and state has chapter 05’s lowercase_ascii normaliser, so the UI would show maharashtra. Either map keys to display names in the application, or aggregate on a sub-field without a normaliser. Chapter 14 adds such a sub-field in the next index version.

When top-N counts are wrong

What it is. A terms aggregation over several shards asks each shard for its own top terms, shard_size of them, and merges those lists. A term that is just outside the top of every shard never reaches the merge, and a term’s count is under-reported when it is missing from some shards’ lists. The terms aggregation reference documents both the default shard_size, larger than size, and the error bounds.

Why it matters at 300 million profiles. The production index has many shards (chapter 08). For fields with a few dominant values, such as state or status, the merge is reliable. For long-tail fields, such as names or pincodes, where many values have similar counts, a “top 10” can contain wrong values with wrong counts.

Example. The lab index has one shard, so its counts are always exact. Copy the Bihar profiles into a five-shard scratch index and ask for the three most common full names:

1
PUT ch12-sharded
2
{
3
  "settings": { "number_of_shards": 5, "number_of_replicas": 0 },
4
  "mappings": { "properties": { "fullName": { "type": "keyword" }, "state": { "type": "keyword" } } }
5
}
6

7
POST _reindex?refresh=true&filter_path=created,failures
8
{
9
  "source": { "index": "user-profile-read", "_source": ["fullName", "state"], "query": { "term": { "state": "bihar" } } },
10
  "dest":   { "index": "ch12-sharded" }
11
}

1
{"created":199755,"failures":[]}

1
GET ch12-sharded/_search?filter_path=aggregations
2
{ "size": 0, "aggs": { "names": { "terms": { "field": "fullName", "size": 3, "show_term_doc_count_error": true } } } }

1
{"aggregations":{"names":{"doc_count_error_upper_bound":415,"sum_other_doc_count":199320,
2
 "buckets":[{"key":"Fatima Nair","doc_count":172,"doc_count_error_upper_bound":247},
3
            {"key":"Neha Iyer","doc_count":169,"doc_count_error_upper_bound":250},
4
            {"key":"Mohammed Menon","doc_count":94,"doc_count_error_upper_bound":332}]}}}

The true top three in PostgreSQL are Aditi Joshi and Harpreet Reddy with 381 profiles each, and Sneha Das with 375. None of them appears, and the counts shown are less than half the real ones. The response does warn you: an overall error bound of 415 on counts below 200 means the result is unreliable. Raise shard_size so that each shard reports enough terms to cover the long tail:

1
GET ch12-sharded/_search?filter_path=aggregations
2
{ "size": 0, "aggs": { "names": { "terms": { "field": "fullName", "size": 3, "shard_size": 1000, "show_term_doc_count_error": true } } } }

1
{"aggregations":{"names":{"doc_count_error_upper_bound":0,"sum_other_doc_count":198618,
2
 "buckets":[{"key":"Aditi Joshi","doc_count":381,"doc_count_error_upper_bound":0},
3
            {"key":"Harpreet Reddy","doc_count":381,"doc_count_error_upper_bound":0},
4
            {"key":"Sneha Das","doc_count":375,"doc_count_error_upper_bound":0}]}}}

Exact, because the field has only 600 distinct values and 1,000 per shard covers them all. On a field with millions of distinct values, no shard_size covers everything, and the cost of each shard’s list grows with it.

Trade-off. Large shard_size values buy accuracy with memory and time on every shard. For facets over low-cardinality fields, the default is fine. For “top N” questions over high-cardinality fields, either accept and display the error bound, or answer the question with an exhaustive composite aggregation offline. Delete the scratch index:

1
DELETE ch12-sharded

Common mistake. Ignoring doc_count_error_upper_bound. When it is large compared with the counts, the list is not a ranking.

Distinct counts are approximate by design

What it is. The cardinality aggregation estimates the number of distinct values with the HyperLogLog++ algorithm, in bounded memory. precision_threshold trades memory for accuracy: the reference gives the memory as about precision_threshold × 8 bytes and says counts are likely accurate up to the threshold.

Why it matters at 300 million profiles. An exact distinct count over hundreds of millions of values needs memory proportional to the values. An estimate with a known, small error needs a few hundred kilobytes.

Example. Every email address in the lab is unique, so the exact answer is 1,000,000:

1
GET user-profile-read/_search?filter_path=aggregations
2
{
3
  "size": 0,
4
  "aggs": {
5
    "distinct_emails":         { "cardinality": { "field": "email" } },
6
    "distinct_emails_precise": { "cardinality": { "field": "email", "precision_threshold": 40000 } },
7
    "distinct_cities":         { "cardinality": { "field": "city" } }
8
  }
9
}

1
{"aggregations":{"distinct_cities":{"value":10},"distinct_emails":{"value":994297},"distinct_emails_precise":{"value":1000182}}}

The default estimate is 0.57% low; with precision_threshold: 40000, about 320 KB per shard by the formula, it is 0.018% high. The ten distinct cities are counted exactly, because they are far below either threshold.

Common mistake. Presenting a cardinality result as an exact figure in a report or a reconciliation. Use cardinality for dashboards and trends; use PostgreSQL for numbers that must be exact.

Every bucket, page by page, with composite

What it is. A composite aggregation returns buckets for combinations of sources in a stable order, a page at a time, with an after_key to request the next page. Unlike terms, it is exhaustive and exact.

Why it matters at 300 million profiles. Some questions need every bucket, not the top ones: a nightly count per state and city, or a reconciliation that compares Elasticsearch with PostgreSQL group by group. composite answers them without the top-N error and without loading every bucket into memory at once.

Example. State and city combinations, three per page:

1
GET user-profile-read/_search?filter_path=aggregations
2
{
3
  "size": 0,
4
  "aggs": { "places": { "composite": {
5
    "size": 3,
6
    "sources": [ { "state": { "terms": { "field": "state" } } }, { "city": { "terms": { "field": "city" } } } ]
7
  } } }
8
}

1
{"aggregations":{"places":{"after_key":{"state":"karnataka","city":"bengaluru"},
2
 "buckets":[{"key":{"state":"bihar","city":"gaya"},"doc_count":99646},
3
            {"key":{"state":"bihar","city":"patna"},"doc_count":100109},
4
            {"key":{"state":"karnataka","city":"bengaluru"},"doc_count":100159}]}}}

Pass the after_key back as "after": {"state": "karnataka", "city": "bengaluru"} in the same request to get the next page, which starts at kerala / kochi. Stop when a response has no after_key.

Counts over time with date_histogram

A date_histogram buckets documents by calendar interval. Profile updates per month since May 2026:

1
GET user-profile-read/_search?filter_path=aggregations
2
{
3
  "size": 0,
4
  "query": { "range": { "updatedAt": { "gte": "2026-05-01" } } },
5
  "aggs": { "per_month": { "date_histogram": { "field": "updatedAt", "calendar_interval": "month" } } }
6
}

1
2026-05  3866
2
2026-06  2716
3
2026-07  1723
4
2026-08   579
5
2026-09     4

The response is condensed to month and count; each bucket also carries key in epoch milliseconds. It matches PostgreSQL’s date_trunc('month', updated_at) counts. The four profiles in September are the ones chapter 04 changed.

A facet panel has one behaviour users expect and a naive implementation breaks. When a user picks city = patna, the city facet must still show Gaya and its count, so the user can switch; only the other facets should narrow. If the city filter is applied to the city facet, it shows a single bucket, Patna.

Elasticsearch offers two ways to get that behaviour. The first is post_filter, which applies after aggregations are computed:

1
GET user-profile-read/_search?filter_path=hits.total,aggregations
2
{
3
  "size": 0,
4
  "track_total_hits": true,
5
  "query": { "bool": { "filter": [ { "term": { "accountStatus": "ACTIVE" } }, { "term": { "state": "bihar" } } ] } },
6
  "post_filter": { "term": { "city": "patna" } },
7
  "aggs": { "city_facet": { "terms": { "field": "city" } } }
8
}

1
{"hits":{"total":{"value":70214,"relation":"eq"}},
2
 "aggregations":{"city_facet":{"doc_count_error_upper_bound":0,"sum_other_doc_count":0,
3
 "buckets":[{"key":"patna","doc_count":70214},{"key":"gaya","doc_count":69711}]}}}

The hits are Patna only; the facet still shows Gaya. post_filter handles one selected facet. With several facet fields, each facet must ignore its own filter and apply all the others, which is what filter aggregations do, one per facet. The Search API uses that pattern.

Facet filters and the other filters must now be available separately. In UserQueryBuilder.kt, replace the filters function with these three:

1
    /** Exact constraints: filter context, no scoring, cacheable. */
2
    fun filters(request: UserSearchRequest): List<Query> = baseFilters(request) + facetFilters(request).values
3

4
    /** Constraints that are never faceted. */
5
    fun baseFilters(request: UserSearchRequest): List<Query> = buildList {
6
        add(term("accountStatus", request.accountStatus.name))
7
        request.pincode?.let { add(term("pincode", it)) }
8
        request.updatedSince?.let { add(updatedAtFrom(it.toString())) }
9
        // Rounded to the day, so the same filter is reused, and cached, for a whole day.
10
        request.updatedWithinDays?.let { add(updatedAtFrom("now-${it}d/d")) }
11
    }
12

13
    /** Constraints on faceted fields, keyed by field name (chapter 12). */
14
    fun facetFilters(request: UserSearchRequest): Map<String, Query> = buildMap {
15
        request.state?.let { put("state", term("state", it)) }
16
        request.city?.let { put("city", term("city", it)) }
17
        request.gender?.let { put("gender", term("gender", it.name)) }
18
    }

filters returns the same set of clauses as before, so /search is unchanged. Add the facets request builder:

1
package `in`.o612.eng.usersearch.api.search
2

3
import co.elastic.clients.elasticsearch._types.aggregations.Aggregation
4
import co.elastic.clients.elasticsearch._types.query_dsl.Query
5
import co.elastic.clients.elasticsearch.core.SearchRequest
6
import `in`.o612.eng.usersearch.api.web.UserSearchRequest
7
import `in`.o612.eng.usersearch.index.UserProfileIndex
8

9
/**
10
 * Facet counts for a search. Each facet ignores its own filter and applies all the others,
11
 * so a user who picked city=patna still sees how many matches Gaya would give ("disjunctive" facets).
12
 */
13
object UserFacetsBuilder {
14

15
    val FACET_FIELDS = listOf("state", "city", "gender")
16

17
    private const val BUCKETS_PER_FACET = 50
18

19
    fun build(request: UserSearchRequest): SearchRequest = SearchRequest.of { s ->
20
        s.index(UserProfileIndex.READ_ALIAS)
21
            .size(0)
22
            .query(baseQuery(request))
23
            .aggregations(FACET_FIELDS.associateWith { field -> facet(field, request) })
24
    }
25

26
    /** The name clause and the non-faceted filters: what every facet has in common. */
27
    private fun baseQuery(request: UserSearchRequest): Query = Query.of { q ->
28
        q.bool { b ->
29
            request.name?.let { b.must(UserQueryBuilder.nameQuery(it, request.nameMode)) }
30
            UserQueryBuilder.baseFilters(request).forEach { b.filter(it) }
31
            b
32
        }
33
    }
34

35
    /** A filter aggregation with every other facet's filter, wrapping a terms aggregation on [field]. */
36
    private fun facet(field: String, request: UserSearchRequest): Aggregation {
37
        val otherFilters = UserQueryBuilder.facetFilters(request).filterKeys { it != field }.values.toList()
38
        return Aggregation.of { a ->
39
            a.filter { f -> f.bool { b -> b.filter(otherFilters) } }
40
                .aggregations("values", Aggregation.of { t -> t.terms { tt -> tt.field(field).size(BUCKETS_PER_FACET) } })
41
        }
42
    }
43
}

Each facet is a filter aggregation that applies every other facet’s filter, wrapping a terms aggregation on the facet’s own field. The top-level query carries only what all facets share: the name clause and the non-faceted filters. The facet fields have a handful of values each, so 50 buckets per facet returns all of them.

Add the response types at the end of SearchDtos.kt:

1
/** Counts per value for each faceted field. Keys are the indexed, normalised values (chapter 12). */
2
data class FacetsResponse(val facets: Map<String, List<FacetBucket>>)
3

4
data class FacetBucket(val value: String, val count: Long)

In UserSearchService, add the facets method, and import FacetBucket and FacetsResponse:

1
    fun facets(request: UserSearchRequest): FacetsResponse {
2
        val response = client.search(UserFacetsBuilder.build(request), Void::class.java)
3
        val facets = UserFacetsBuilder.FACET_FIELDS.associateWith { field ->
4
            response.aggregations()[field]!!.filter().aggregations()["values"]!!.sterms().buckets().array()
5
                .map { FacetBucket(value = it.key().stringValue(), count = it.docCount()) }
6
        }
7
        return FacetsResponse(facets)
8
    }

The typed client exposes each aggregation result through a variant accessor: filter() for the filter aggregation, then sterms() for a terms aggregation on a string field. And in UserSearchController, add the endpoint before the /{userId} mapping:

1
    @GetMapping("/facets")
2
    fun facets(@Valid request: UserSearchRequest): FacetsResponse = service.facets(request)

The facets endpoint takes exactly the same parameters as /search, so a UI sends the same query string to both.

Restart search-api, then request facets with a state and a city selected:

1
curl -s 'localhost:8080/api/users/facets?state=bihar&city=patna'

1
{
2
  "facets": {
3
    "state":  [ { "value": "bihar", "count": 70214 } ],
4
    "city":   [ { "value": "patna", "count": 70214 }, { "value": "gaya", "count": 69711 } ],
5
    "gender": [ { "value": "FEMALE", "count": 34752 }, { "value": "MALE", "count": 34707 }, { "value": "OTHER", "count": 755 } ]
6
  }
7
}

The response is reformatted here. Each facet behaves as designed. city ignores the city selection, so Gaya stays visible with its count. state ignores the state selection but applies city=patna, so only Bihar remains. gender applies both. PostgreSQL agrees on every number, for example 34,752 active female profiles in Patna.

With a name, the facets describe the matches of the search. facets?name=prashant&state=bihar returns 4,715 for Bihar, 4,628 for Maharashtra, and 2,401 for Rajasthan in the state facet, the active Prashants per state, and 2,363 for Patna and 2,352 for Gaya in the city facet. All match PostgreSQL.

Checkpoint

/api/users/facets?state=bihar&city=patna returns two city buckets, not one. If it returns only Patna, the filterKeys { it != field } line in UserFacetsBuilder is missing.

Global ordinals: the hidden cost of terms on keywords

A terms aggregation on a keyword field works on global ordinals, a per-shard mapping from every distinct value to a number. Elasticsearch builds them lazily, on the first aggregation after a refresh that changed the shard, so on a busy index that first facet request after each refresh pays the build cost. For the low-cardinality facet fields here, the cost is small. For high-cardinality fields that are aggregated often, the eager_global_ordinals mapping option moves the build to refresh time, so indexing pays instead of the first search. Chapter 15 comes back to this trade-off with measurements.

Common mistakes with aggregations

Aggregating on text fields. Use keyword sub-fields; chapter 06 showed the alternative.
Treating terms results over many shards as exact. Read doc_count_error_upper_bound.
Treating cardinality as exact. It is an estimate with a tunable error.
Using terms with a huge size to “get everything”. Use composite and page through.
Applying a facet’s own filter to that facet. Users lose the ability to switch values.
Showing normalised keys as display names. maharashtra is an index value, not a label.

What you built, and what comes next

You ran the aggregations profile search needs, terms, cardinality, composite, and date_histogram, and checked every count against PostgreSQL. You reproduced a top-N aggregation that returned the wrong names across five shards, and fixed it with shard_size where the field’s cardinality allowed. The Search API now has a facets endpoint that keeps each facet’s alternatives visible after a selection.

The facet values are still normalised keys. Chapter 14’s next index version adds display sub-fields for them.

Chapter 13 adds cursor pagination: why deep from and size is expensive, search_after with a point in time for stable pages, when scroll still has a place, and a cursor-based contract for the Search API.

ElasticsearchSpring BootKotlin