Query design for profile search

This chapter designs the query behind the Search API and replaces chapter 10’s placeholder. By the end, UserQueryBuilder produces one request shape for every search: a single scored clause for the name, which tolerates typos and combines name, city, and state; every other constraint as a cached, unscored filter; a sort that is always total; highlighting; and a source filter. You build each piece in Kibana Dev Tools first, check its counts against PostgreSQL, and then write it in Kotlin.

The chapter’s centre is the request chapter 01 used as its example: find active users named Prashant in Bihar, updated recently. You write it as JSON and as Kotlin, and confirm that both produce the same request and the same seven profiles.

You need the lab over TLS and the search-api module from chapter 10. Requests use Kibana Dev Tools syntax. The chapter takes about 60 minutes.

Query context and filter context

What it is. Every clause in a search runs in one of two contexts. In query context, a clause answers “how well does this document match?” and contributes to the relevance score. In filter context, it answers only “does it match?”, yes or no. Filter context is used by filter and must_not clauses in a bool query. Elastic’s query and filter context guide states that frequently used filters are cached automatically.

Why it matters at 300 million profiles. Most constraints in profile search are exact: status, state, city, gender, pincode, a date range. Scoring them is wasted work on every matching document, and scored clauses cannot use the filter cache. Keeping exact constraints in filter context makes them cheaper and reusable across requests.

Example. The same term on state, first in must, then in filter:

1
GET user-profile-read/_search?filter_path=hits.total,hits.hits._score&size=2
2
{ "query": { "bool": { "must": [ { "term": { "state": "bihar" } } ] } } }

1
{"hits":{"total":{"value":10000,"relation":"gte"},"hits":[{"_score":1.6106621},{"_score":1.6106621}]}}

1
GET user-profile-read/_search?filter_path=hits.total,hits.hits._score&size=2
2
{ "query": { "bool": { "filter": [ { "term": { "state": "bihar" } } ] } } }

1
{"hits":{"total":{"value":10000,"relation":"gte"},"hits":[{"_score":0.0},{"_score":0.0}]}}

Same documents; in must every one received the same computed score of 1.61, which carries no information, because every match has the same state.

Common mistake. Putting every clause in must because “they all have to match”. They do, and filter also means “has to match”. Use must only for the clauses whose degree of match should order the results.

The bool query, clause by clause

A bool query combines clauses with four occurrence types:

minimum_should_match is where should becomes subtle. The bool query reference is precise: when a bool has at least one should clause and no must or filter clauses, the default is 1; otherwise it is 0, and should clauses only add score. The name clause in this chapter sets it explicitly, so its meaning does not change when someone adds a filter next to it.

must_not is filter context too. Excluding two statuses in Bihar:

1
GET user-profile-read/_count?filter_path=count
2
{ "query": { "bool": {
3
  "filter":   [ { "term": { "state": "bihar" } } ],
4
  "must_not": [ { "terms": { "accountStatus": ["DELETED", "SUSPENDED"] } } ]
5
} } }

1
{"count":159861}

PostgreSQL’s state = 'Bihar' AND account_status NOT IN ('DELETED', 'SUSPENDED') agrees. The Search API expresses the same intent positively, with accountStatus as a filter, which is easier to read and to cache.

Exact lookups use term queries

What it is. A term query matches one exact value in a keyword field, after the field’s normaliser. Chapter 10’s lookups by email and mobile number use it, and a lookup by userId uses get.

Why it matters at 300 million profiles. An exact lookup should cost the same at 300 million profiles as at one million: a direct term lookup, not a scan. It also must never match a different profile, which rules out analysed fields.

Example. The prefix query is the exact-value relative of term for keyword fields. All profiles in pincodes starting 8000:

1
GET user-profile-read/_count?filter_path=count
2
{ "query": { "prefix": { "pincode": "8000" } } }

1
{"count":100109}

That matches PostgreSQL’s pincode LIKE '8000%' exactly.

Common mistake. Sending exact lookups through the full-text search endpoint. A match query for an email address analyses it, and a mistyped address may still match something. Exact lookups get their own endpoints and term queries, as chapter 10 built.

Name search across name, city, and state

What it is. A multi_match query runs one text against several fields. Its cross_fields type treats those fields as if they were one big field, so each word may match in a different field. That is what a search box needs for input like prashant patna: prashant is in the name, patna is in the city.

Why it matters at 300 million profiles. Users do not say which field a word belongs to. Requiring every word in one field finds nothing for prashant patna; matching any word in any field returns every Prashant and everyone in Patna.

Example. Search the name, city, and state, with the name weighted three times higher:

1
GET user-profile-read/_count?filter_path=count
2
{ "query": { "multi_match": {
3
  "query": "prashant patna", "type": "cross_fields", "operator": "and",
4
  "fields": ["fullName^3", "city.text", "state.text"]
5
} } }

1
{"count":0}

Zero, although PostgreSQL has 3,343 Prashants in Patna. The validate API with explain=true shows the query Elasticsearch actually built:

1
GET user-profile-read/_validate/query?explain=true&filter_path=explanations.explanation
2
{ "query": { "multi_match": {
3
  "query": "prashant patna", "type": "cross_fields", "operator": "and",
4
  "fields": ["fullName^3", "city.text", "state.text"]
5
} } }

1
{"explanations":[{"explanation":"((+blended(terms:[state.text:prashant, city.text:prashant]) +blended(terms:[state.text:patna, city.text:patna])) | (+fullName:prashant +fullName:patna)^3.0)"}]}

cross_fields blends only fields that share a search analyser. fullName uses name_search, with synonyms, and city.text and state.text use name_index, so Elasticsearch built two groups and applied operator: and inside each: all words in the name, or all words in the place. Neither group can contain both words.

Force one analyser for the whole query:

1
GET user-profile-read/_validate/query?explain=true&filter_path=explanations.explanation
2
{ "query": { "multi_match": {
3
  "query": "prashant patna", "type": "cross_fields", "operator": "and",
4
  "analyzer": "name_search",
5
  "fields": ["fullName^3", "city.text", "state.text"]
6
} } }

1
{"explanations":[{"explanation":"+blended(terms:[state.text:prashant, fullName:prashant^3.0, city.text:prashant]) +blended(terms:[state.text:patna, fullName:patna^3.0, city.text:patna])"}]}

Now each word must appear in some field, and the count is 3,343. Because the forced analyser is name_search, synonyms apply across all three fields: mohd patna counts 3,347, exactly PostgreSQL’s Mohammeds in Patna.

Common mistake. Trusting cross_fields without checking the groups. When fields have different analysers, the query silently becomes something else. _validate/query?explain=true is the fastest way to see what a text query really is.

Tolerating typos without letting them win

cross_fields does not support fuzziness, and a support agent will type prashnat kumr. The name clause therefore offers two ways to match, and a profile needs only one:

1
{ "bool": {
2
  "should": [
3
    { "multi_match": { "query": "prashnat kumr", "type": "cross_fields", "operator": "and",
4
                       "analyzer": "name_search", "fields": ["fullName^3", "city.text", "state.text"] } },
5
    { "match": { "fullName": { "query": "prashnat kumr", "operator": "and",
6
                               "fuzziness": "AUTO", "prefix_length": 1 } } }
7
  ],
8
  "minimum_should_match": 1
9
} }

Run as a search, it finds the 1,666 Prashant Kumars through the fuzzy clause alone, each scoring 5.22. The correctly spelled prashant kumar matches both clauses and scores 25.59. Exact spellings rank above typo matches without any extra rule, because a document that satisfies both alternatives earns both scores. prefix_length: 1 requires the first letter to be right, which keeps fuzzy expansion cheap and avoids matching names that differ in their first letter.

Autocomplete is a separate mode

Chapter 07 chose an edge n-gram sub-field for autocomplete. It gets its own mode rather than being mixed into the full search, because its semantics differ: every word is a prefix, and there is no typo tolerance.

1
{ "match": { "fullName.prefix": { "query": "pras", "operator": "and" } } }

Scores, sorting, and when to ignore relevance

What it is. Results are sorted by _score unless you say otherwise. Sorting by a field, such as updatedAt, skips score computation for that ordering. In chapter 10’s filter-only search sorted by UPDATED_AT, every hit had "score": null. The sort reference describes the options.

Why it matters at 300 million profiles. Relevance is meaningful only when there is text to match. An admin list of “profiles in Kochi, newest first” should not pay for scoring, and its order should not depend on BM25 statistics that shift as the index changes.

Example. The Search API’s sort is always one of two, and both end with tiebreakers:

Chapter 07 showed that all 1,666 Prashant Kumars score exactly the same. Without updatedAt and userId after the score, their order would be whatever the shards returned, and it could change between requests. The final userId makes the order total, because it is unique, which chapter 13’s cursor pagination requires.

Common mistake. Adding track_scores or scripting a custom score to rescue a sort that should simply not use relevance. Decide per use case: text search sorts by relevance; lists and exports sort by fields.

Highlighting and source filtering

Highlighting returns the matched parts of each field with markers. Request it for the fields the name clause searches; Elasticsearch returns fragments only for fields that actually matched. See the highlighting reference.

Source filtering limits _source to the listed fields. Chapter 10’s RESULT_FIELDS keeps email, mobile number, and date of birth out of every result list. That is a privacy control, not only an optimisation. See retrieving selected fields.

Security note — Highlighting reads the stored source of the fields it highlights. Highlight only fields that are safe to return. A highlight on email would return the address inside the highlight section even with email excluded from _source.

The composed request: active users named Prashant in Bihar, updated recently

Everything in this chapter combines into one request. “Recently” here means within 90 days. now-90d/d rounds to the start of the day, so the filter value is identical for every request on the same day, and can be cached, instead of changing every millisecond.

1
GET user-profile-read/_search
2
{
3
  "size": 3,
4
  "track_total_hits": true,
5
  "_source": ["userId", "fullName", "city", "state", "accountStatus", "updatedAt"],
6
  "query": {
7
    "bool": {
8
      "must": [
9
        {
10
          "bool": {
11
            "should": [
12
              {
13
                "multi_match": {
14
                  "query": "prashant",
15
                  "type": "cross_fields",
16
                  "operator": "and",
17
                  "analyzer": "name_search",
18
                  "fields": ["fullName^3", "city.text", "state.text"]
19
                }
20
              },
21
              {
22
                "match": {
23
                  "fullName": { "query": "prashant", "operator": "and", "fuzziness": "AUTO", "prefix_length": 1 }
24
                }
25
              }
26
            ],
27
            "minimum_should_match": 1
28
          }
29
        }
30
      ],
31
      "filter": [
32
        { "term": { "accountStatus": "ACTIVE" } },
33
        { "term": { "state": "bihar" } },
34
        { "range": { "updatedAt": { "gte": "now-90d/d" } } }
35
      ]
36
    }
37
  },
38
  "sort": [
39
    { "_score": "desc" },
40
    { "updatedAt": "desc" },
41
    { "userId": "asc" }
42
  ],
43
  "highlight": {
44
    "fields": { "fullName": {}, "city.text": {}, "state.text": {} }
45
  }
46
}

The response, condensed to the first hit:

1
{
2
  "hits": {
3
    "total": { "value": 7, "relation": "eq" },
4
    "hits": [
5
      {
6
        "_id": "857970",
7
        "_score": 13.604773,
8
        "_source": { "userId": "857970", "fullName": "Prashant Jha", "city": "Patna", "state": "Bihar",
9
                     "accountStatus": "ACTIVE", "updatedAt": "2026-08-01T00:00:00+00:00" },
10
        "highlight": { "fullName": ["<em>Prashant</em> Jha"] },
11
        "sort": [13.604773, 1785542400000, "857970"]
12
      },
13
      ...
14
    ]
15
  }
16
}

Seven profiles, on the day this was run. Because the date window is relative, your count depends on the day you run it. Check it against the source of truth:

1
SELECT count(*) FROM user_profile
2
WHERE first_name = 'Prashant' AND state = 'Bihar' AND account_status = 'ACTIVE'
3
  AND updated_at >= date_trunc('day', now() - interval '90 days');

Each hit’s sort array holds its values for the three sort keys. Chapter 13 passes the last hit’s array back as a cursor.

Stage 1 — The query in Kotlin

The request contract gains two fields: a nameMode that selects full search or autocomplete, and updatedWithinDays for relative date windows. Replace SearchDtos.kt:

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

3
import jakarta.validation.constraints.Max
4
import jakarta.validation.constraints.Min
5
import jakarta.validation.constraints.Pattern
6
import jakarta.validation.constraints.Size
7
import java.time.Instant
8
import java.time.LocalDate
9

10
enum class Gender { MALE, FEMALE, OTHER }
11

12
enum class AccountStatus { ACTIVE, INACTIVE, SUSPENDED, DELETED }
13

14
enum class SortOrder { RELEVANCE, UPDATED_AT }
15

16
/** FULL: whole words, typo-tolerant, across name, city, and state. PREFIX: autocomplete on the name. */
17
enum class NameMode { FULL, PREFIX }
18

19
/** Query parameters of GET /api/users/search. Only the filters chapter 05's capability matrix allows exist. */
20
data class UserSearchRequest(
21
    @field:Size(min = 2, max = 100) val name: String? = null,
22
    val nameMode: NameMode = NameMode.FULL,
23
    @field:Size(max = 60) val city: String? = null,
24
    @field:Size(max = 60) val state: String? = null,
25
    @field:Pattern(regexp = "\\d{6}") val pincode: String? = null,
26
    val gender: Gender? = null,
27
    val accountStatus: AccountStatus = AccountStatus.ACTIVE,
28
    val updatedSince: Instant? = null,
29
    @field:Min(1) @field:Max(3650) val updatedWithinDays: Int? = null,
30
    val sort: SortOrder = SortOrder.RELEVANCE,
31
    @field:Min(1) @field:Max(50) val size: Int = 20,
32
)
33

34
data class UserSearchResponse(
35
    val total: TotalHits,
36
    val hits: List<UserSearchHit>,
37
)
38

39
/** `exact = false` means "at least [value]": Elasticsearch stopped counting (chapter 09). */
40
data class TotalHits(val value: Long, val exact: Boolean)
41

42
/** A search result. Deliberately without email, mobile number, or date of birth. */
43
data class UserSearchHit(
44
    val userId: String,
45
    val fullName: String,
46
    val city: String,
47
    val state: String,
48
    val accountStatus: String,
49
    val updatedAt: Instant,
50
    val score: Double?,
51
    val highlights: Map<String, List<String>>,
52
)
53

54
/** A single profile, returned only by exact lookups. */
55
data class ProfileDetail(
56
    val userId: String,
57
    val fullName: String,
58
    val email: String,
59
    val mobileNumber: String,
60
    val city: String,
61
    val state: String,
62
    val pincode: String,
63
    val dateOfBirth: LocalDate?,
64
    val gender: String,
65
    val accountStatus: String,
66
    val updatedAt: Instant,
67
)

Replace UserQueryBuilder.kt with the full design:

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

3
import co.elastic.clients.elasticsearch._types.FieldValue
4
import co.elastic.clients.elasticsearch._types.SortOptions
5
import co.elastic.clients.elasticsearch._types.SortOrder as EsSortOrder
6
import co.elastic.clients.elasticsearch._types.query_dsl.Operator
7
import co.elastic.clients.elasticsearch._types.query_dsl.Query
8
import co.elastic.clients.elasticsearch._types.query_dsl.TextQueryType
9
import co.elastic.clients.elasticsearch.core.SearchRequest
10
import co.elastic.clients.elasticsearch.core.search.Highlight
11
import co.elastic.clients.elasticsearch.core.search.HighlightField
12
import co.elastic.clients.json.JsonData
13
import co.elastic.clients.util.NamedValue
14
import `in`.o612.eng.usersearch.api.web.NameMode
15
import `in`.o612.eng.usersearch.api.web.SortOrder
16
import `in`.o612.eng.usersearch.api.web.UserSearchRequest
17
import `in`.o612.eng.usersearch.index.UserProfileIndex
18

19
/**
20
 * Turns a validated search request into an Elasticsearch request. Pure: no I/O, so it is unit-tested directly.
21
 *
22
 * Scoring happens only in the name clause. Every other constraint is a filter.
23
 */
24
object UserQueryBuilder {
25

26
    /** The only fields a result list may return. */
27
    val RESULT_FIELDS = listOf("userId", "fullName", "city", "state", "accountStatus", "updatedAt")
28

29
    /** Fields a free-text name search covers; the name counts three times as much as the place. */
30
    private val TEXT_FIELDS = listOf("fullName^3", "city.text", "state.text")
31

32
    fun build(request: UserSearchRequest): SearchRequest = SearchRequest.of { s ->
33
        s.index(UserProfileIndex.READ_ALIAS)
34
            .size(request.size)
35
            .source { src -> src.filter { f -> f.includes(RESULT_FIELDS) } }
36
            .query(query(request))
37
            .sort(sort(request.sort))
38
        request.name?.let { s.highlight(highlight(request.nameMode)) }
39
        s
40
    }
41

42
    fun query(request: UserSearchRequest): Query = Query.of { q ->
43
        q.bool { b ->
44
            request.name?.let { b.must(nameQuery(it, request.nameMode)) }
45
            filters(request).forEach { b.filter(it) }
46
            b
47
        }
48
    }
49

50
    /** The only scored clause. */
51
    fun nameQuery(name: String, mode: NameMode): Query = when (mode) {
52
        NameMode.FULL -> Query.of { q ->
53
            q.bool { b ->
54
                b.should(crossFields(name))
55
                    .should(fuzzyName(name))
56
                    .minimumShouldMatch("1")
57
            }
58
        }
59
        NameMode.PREFIX -> Query.of { q ->
60
            q.match { m -> m.field("fullName.prefix").query(name).operator(Operator.And) }
61
        }
62
    }
63

64
    /**
65
     * Every word must appear in the name, city, or state, in any combination: "prashant patna".
66
     * One analyser for all fields keeps them in one blended group; without it, operator AND applies per field group.
67
     */
68
    private fun crossFields(text: String): Query = Query.of { q ->
69
        q.multiMatch { mm ->
70
            mm.query(text)
71
                .type(TextQueryType.CrossFields)
72
                .operator(Operator.And)
73
                .analyzer("name_search")
74
                .fields(TEXT_FIELDS)
75
        }
76
    }
77

78
    /** Typo tolerance on the name alone. Scores below exact matches, so exact spellings rank first. */
79
    private fun fuzzyName(text: String): Query = Query.of { q ->
80
        q.match { m ->
81
            m.field("fullName").query(text).operator(Operator.And).fuzziness("AUTO").prefixLength(1)
82
        }
83
    }
84

85
    /** Exact constraints: filter context, no scoring, cacheable. */
86
    fun filters(request: UserSearchRequest): List<Query> = buildList {
87
        add(term("accountStatus", request.accountStatus.name))
88
        request.city?.let { add(term("city", it)) }
89
        request.state?.let { add(term("state", it)) }
90
        request.pincode?.let { add(term("pincode", it)) }
91
        request.gender?.let { add(term("gender", it.name)) }
92
        request.updatedSince?.let { add(updatedAtFrom(it.toString())) }
93
        // Rounded to the day, so the same filter is reused, and cached, for a whole day.
94
        request.updatedWithinDays?.let { add(updatedAtFrom("now-${it}d/d")) }
95
    }
96

97
    /** Relevance first when requested, then newest, then userId so every order is total. */
98
    fun sort(order: SortOrder): List<SortOptions> = buildList {
99
        if (order == SortOrder.RELEVANCE) add(SortOptions.of { it.score { sc -> sc.order(EsSortOrder.Desc) } })
100
        add(SortOptions.of { it.field { f -> f.field("updatedAt").order(EsSortOrder.Desc) } })
101
        add(SortOptions.of { it.field { f -> f.field("userId").order(EsSortOrder.Asc) } })
102
    }
103

104
    fun highlight(mode: NameMode): Highlight {
105
        val fields = when (mode) {
106
            NameMode.FULL -> listOf("fullName", "city.text", "state.text")
107
            NameMode.PREFIX -> listOf("fullName.prefix")
108
        }
109
        return Highlight.of { h -> h.fields(fields.map { NamedValue.of(it, HighlightField.of { f -> f }) }) }
110
    }
111

112
    private fun term(field: String, value: String): Query =
113
        Query.of { q -> q.term { t -> t.field(field).value(FieldValue.of(value)) } }
114

115
    private fun updatedAtFrom(from: String): Query =
116
        Query.of { q -> q.range { r -> r.untyped { u -> u.field("updatedAt").gte(JsonData.of(from)) } } }
117
}

Three details map directly to the JSON. nameQuery builds the same two-way should with minimumShouldMatch("1") for the FULL mode, and the edge n-gram match for PREFIX. filters puts every exact constraint in filter context, including the rounded now-Nd/d range. And highlight passes its fields as NamedValue entries: in client 9.x, highlight fields are an ordered list, not a map.

In UserSearchService.kt, replace the highlights = hit.highlight(), line in search so that callers see field names from the contract, not index internals such as fullName.prefix or city.text:

1
                        // "fullName.prefix" and "city.text" are index details; callers see "fullName" and "city".
2
                        highlights = hit.highlight().mapKeys { (field, _) -> field.substringBefore('.') },

Check that Kotlin and JSON agree

The Java API Client’s request objects print their JSON body with toString(). For UserSearchRequest(name = "prashant", state = "bihar", updatedWithinDays = 90, size = 3), UserQueryBuilder.build(request).toString() produces, reformatted:

1
{
2
  "_source": { "includes": ["userId", "fullName", "city", "state", "accountStatus", "updatedAt"] },
3
  "highlight": { "fields": [ { "fullName": {} }, { "city.text": {} }, { "state.text": {} } ] },
4
  "query": { "bool": {
5
    "filter": [
6
      { "term": { "accountStatus": { "value": "ACTIVE" } } },
7
      { "term": { "state": { "value": "bihar" } } },
8
      { "range": { "updatedAt": { "gte": "now-90d/d" } } }
9
    ],
10
    "must": [ { "bool": {
11
      "minimum_should_match": "1",
12
      "should": [
13
        { "multi_match": { "analyzer": "name_search", "fields": ["fullName^3", "city.text", "state.text"],
14
                           "operator": "and", "query": "prashant", "type": "cross_fields" } },
15
        { "match": { "fullName": { "fuzziness": "AUTO", "operator": "and", "prefix_length": 1, "query": "prashant" } } }
16
      ]
17
    } } ]
18
  } },
19
  "size": 3,
20
  "sort": [ { "_score": { "order": "desc" } }, { "updatedAt": { "order": "desc" } }, { "userId": { "order": "asc" } } ]
21
}

It is the Dev Tools request, with the long form of term and sort, and highlight fields as a list. The only intended difference is track_total_hits: the API keeps the default and reports exact: false above 10,000. Chapter 17 turns this comparison into a unit test.

Stage 2 — Run it through the API

Restart search-api with chapter 10’s environment variables, and run the composed search:

1
curl -s 'localhost:8080/api/users/search?name=prashant&state=bihar&updatedWithinDays=90&size=3'

1
total {value: 7, exact: true}
2
857970  Prashant Jha     Patna  2026-08-01T00:00:00Z  13.604773  {fullName: [<em>Prashant</em> Jha]}
3
518970  Prashant Jha     Patna  2026-07-24T00:00:00Z  13.604773  {fullName: [<em>Prashant</em> Jha]}
4
598470  Prashant Mishra  Patna  2026-07-23T00:00:00Z  13.604773  {fullName: [<em>Prashant</em> Mishra]}

The JSON response is condensed here to one line per hit. The same seven profiles, in the same order, as the Dev Tools request. The other modes, each checked against PostgreSQL for active profiles:

An unknown nameMode value is rejected with 400 before any request reaches Elasticsearch.

Checkpoint

The composed search returns the same total as the PostgreSQL query from the previous section, for the day you run it, and its first hit carries a highlights.fullName fragment. If name=prashant%20patna returns 0, the analyzer("name_search") line is missing from crossFields.

Common mistakes in query design

• Scoring exact constraints. Status, place, and date belong in filter.
• Leaving minimum_should_match implicit. Its default changes when a filter is added to the same bool.
• Trusting cross_fields across fields with different analysers. Check with _validate/query?explain=true, or force one analyser.
• Sorting by _score alone. Ties are common in names; add a field sort and a unique tiebreaker.
• Highlighting or returning fields the caller may not see. Source filtering and highlight fields are part of the privacy design.
• Unrounded now in date filters. now-90d changes every millisecond and defeats caching; now-90d/d changes once a day.

What you built, and what comes next

The Search API now runs one designed query: a single scored name clause that combines cross-field matching with typo tolerance, filters for every exact constraint, a total sort order, highlighting, and source filtering. You verified the composed request in Dev Tools, in Kotlin, and through the API, and every count against PostgreSQL.

The API still returns only the first page. size stops at 50, and there is no way to ask for the next 50.

Chapter 12 adds aggregations: facet counts by state, city, and status for the same search, with the accuracy limits that come with them. Chapter 13 then adds cursor pagination with search_after and point-in-time.