Part 10 of 1856% complete

2026-05-19•9 min read

Building the Spring Boot search service

This chapter builds the Search API from chapter 04’s architecture. By the end, a Spring Boot 4 service answers GET /api/users/search with filtered, sorted name search, and exact lookups by user ID, email, and mobile number, reading only through user-profile-read over an encrypted connection. It also has an opt-in component that creates the index and its synonyms from the reviewed JSON on an empty cluster, validation that rejects requests outside the capability matrix, and error handling that turns an unreachable cluster into a clean 503.

First, the lab’s Elasticsearch moves from plain HTTP to TLS, as chapter 01 promised. Then the search-api module is added to the chapter 09 project. The query builder here is deliberately simple; chapter 11 replaces it with the full query design. You need the lab and the user-search project from chapter 09. The chapter takes about 60 minutes.

Stage 1 — Turn TLS on in the lab

Until now, credentials and profile data crossed the lab’s network in plain text. Elasticsearch’s HTTP layer supports TLS with certificates you supply. For the lab, a one-shot container creates a private certificate authority (CA) and a certificate for the node with elasticsearch-certutil, the tool shipped in the Elasticsearch image.

Create es/make-certs.sh in the lab directory:

1
#!/usr/bin/env bash
2
# Creates a private CA and a certificate for the Elasticsearch node, once.
3
# LOCAL-DEV SHORTCUT: a self-signed CA on disk. Production uses your organisation's PKI.
4
set -euo pipefail
5
CERTS=/usr/share/elasticsearch/config/certs
6
cd "$CERTS"
7

8
if [[ ! -f ca/ca.crt ]]; then
9
  elasticsearch-certutil ca --silent --pem --out "$CERTS/ca.zip"
10
  unzip -q ca.zip && rm ca.zip
11
fi
12

13
if [[ ! -f elasticsearch/elasticsearch.crt ]]; then
14
  cat > instances.yml <<'YAML'
15
instances:
16
  - name: elasticsearch
17
    dns: [elasticsearch, localhost]
18
    ip: [127.0.0.1]
19
YAML
20
  # certutil resolves relative paths against its own home directory, so pass absolute ones.
21
  elasticsearch-certutil cert --silent --pem --in "$CERTS/instances.yml" \
22
    --ca-cert "$CERTS/ca/ca.crt" --ca-key "$CERTS/ca/ca.key" --out "$CERTS/certs.zip"
23
  unzip -q certs.zip && rm certs.zip
24
fi
25

26
# Elasticsearch runs as uid 1000. Only the CA certificate is world-readable.
27
chown -R 1000:0 "$CERTS"
28
find "$CERTS" -type d -exec chmod 750 {} +
29
find "$CERTS" -type f -exec chmod 640 {} +
30
chmod 755 "$CERTS" "$CERTS/ca"
31
chmod 644 "$CERTS/ca/ca.crt"
32
echo "certificates ready"

Two details come from running it. elasticsearch-certutil resolves relative paths against its own home directory, not the current directory, so every path passed to it is absolute. And only the CA certificate is readable by everyone, because the host’s curl and the Spring service need it; the private keys are not.

Replace compose.yaml with this version. The changes from chapter 01 are the new certs service, the xpack.security.http.ssl.* settings and certificate mount on elasticsearch, HTTPS and the CA in the two health checks, and the CA setting on Kibana.

1
name: user-search-lab
2

3
services:
4
  postgres:
5
    image: postgres:18
6
    environment:
7
      POSTGRES_DB: profiles
8
      POSTGRES_USER: profiles
9
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
10
    ports:
11
      - "127.0.0.1:5432:5432"
12
    volumes:
13
      - pgdata:/var/lib/postgresql
14
      - ./db/init:/docker-entrypoint-initdb.d:ro
15
    healthcheck:
16
      test: ["CMD-SHELL", "pg_isready -U profiles -d profiles"]
17
      interval: 5s
18
      retries: 30
19

20
  # One-shot job: creates a private CA and a node certificate, once. See es/make-certs.sh.
21
  certs:
22
    image: docker.elastic.co/elasticsearch/elasticsearch:${STACK_VERSION}
23
    user: "0"
24
    volumes:
25
      - ./certs:/usr/share/elasticsearch/config/certs
26
      - ./es/make-certs.sh:/usr/local/bin/make-certs.sh:ro
27
    command: ["bash", "/usr/local/bin/make-certs.sh"]
28

29
  elasticsearch:
30
    image: docker.elastic.co/elasticsearch/elasticsearch:${STACK_VERSION}
31
    depends_on:
32
      certs: { condition: service_completed_successfully }
33
    environment:
34
      discovery.type: single-node
35
      ELASTIC_PASSWORD: ${ELASTIC_PASSWORD}
36
      xpack.security.enabled: "true"
37
      xpack.security.http.ssl.enabled: "true"
38
      xpack.security.http.ssl.key: certs/elasticsearch/elasticsearch.key
39
      xpack.security.http.ssl.certificate: certs/elasticsearch/elasticsearch.crt
40
      xpack.security.http.ssl.certificate_authorities: certs/ca/ca.crt
41
      xpack.license.self_generated.type: basic
42
      ES_JAVA_OPTS: -Xms1g -Xmx1g
43
    mem_limit: ${ES_MEM_LIMIT}
44
    ulimits:
45
      memlock: { soft: -1, hard: -1 }
46
    ports:
47
      - "127.0.0.1:9200:9200"
48
    volumes:
49
      - esdata:/usr/share/elasticsearch/data
50
      - ./certs:/usr/share/elasticsearch/config/certs:ro
51
    healthcheck:
52
      test: ["CMD-SHELL", "curl -s --cacert config/certs/ca/ca.crt -u elastic:${ELASTIC_PASSWORD} https://localhost:9200/_cluster/health | grep -Eq '\"status\":\"(green|yellow)\"'"]
53
      interval: 10s
54
      retries: 30
55

56
  # One-shot job: gives the built-in kibana_system user a password.
57
  # Kibana should not connect as the elastic superuser.
58
  kibana-setup:
59
    image: docker.elastic.co/elasticsearch/elasticsearch:${STACK_VERSION}
60
    depends_on:
61
      elasticsearch: { condition: service_healthy }
62
    restart: "no"
63
    volumes:
64
      - ./certs:/usr/share/elasticsearch/config/certs:ro
65
    command: >
66
      bash -c 'until curl -s --cacert config/certs/ca/ca.crt -o /dev/null -w "%{http_code}" -u "elastic:${ELASTIC_PASSWORD}"
67
      -X POST https://elasticsearch:9200/_security/user/kibana_system/_password
68
      -H "Content-Type: application/json" -d "{\"password\":\"${KIBANA_PASSWORD}\"}" | grep -q 200;
69
      do sleep 5; done; echo kibana_system password set'
70

71
  kibana:
72
    image: docker.elastic.co/kibana/kibana:${STACK_VERSION}
73
    depends_on:
74
      kibana-setup: { condition: service_completed_successfully }
75
    environment:
76
      ELASTICSEARCH_HOSTS: https://elasticsearch:9200
77
      ELASTICSEARCH_USERNAME: kibana_system
78
      ELASTICSEARCH_PASSWORD: ${KIBANA_PASSWORD}
79
      ELASTICSEARCH_SSL_CERTIFICATEAUTHORITIES: /usr/share/kibana/config/certs/ca/ca.crt
80
    volumes:
81
      - ./certs:/usr/share/kibana/config/certs:ro
82
    ports:
83
      - "127.0.0.1:5601:5601"
84

85
volumes:
86
  pgdata:
87
  esdata:

Apply it. Compose recreates the changed containers and keeps both data volumes, so the index and the profile table survive:

1
docker compose up -d

When docker compose ps -a shows certs and kibana-setup as Exited (0) and the other services up, check the connection three ways:

1
set -a; source .env; set +a
2
curl -s --cacert certs/ca/ca.crt -u "elastic:$ELASTIC_PASSWORD" \
3
  "https://localhost:9200/user-profile-read/_count?filter_path=count"

1
{"count":1000000}

Plain HTTP is now refused, and HTTPS without the CA fails certificate verification:

1
$ curl -s -o /dev/null -w '%{http_code} %{errormsg}\n' -u "elastic:$ELASTIC_PASSWORD" http://localhost:9200/
2
000 Empty reply from server
3
$ curl -s -o /dev/null -w '%{http_code} %{errormsg}\n' -u "elastic:$ELASTIC_PASSWORD" https://localhost:9200/
4
000 SSL certificate OpenSSL verify result: unable to get local issuer certificate (20)

Kibana Dev Tools keeps working unchanged, because Kibana now trusts the same CA. From here on, curl commands in this series use https://localhost:9200 with --cacert certs/ca/ca.crt.

Update chapter 05’s loader the same way: in es/load-v1.sh, set ES="https://localhost:9200", add a line CA="certs/ca/ca.crt", and add --cacert "$CA" to each of its four curl commands. Run it once; every item returns 409, and it reports Failed items: 0.

Security note — This is TLS for the lab, with shortcuts that must not reach production. The CA’s private key sits on disk next to the certificates, and the certificate is valid for localhost. A single node also has no inter-node traffic, so transport-layer TLS, which a multi-node cluster must enable, is not configured here. In production, certificates come from your organisation’s PKI or a managed service, and the application trusts the CA through its deployment secrets. Elastic’s security setup documentation covers both layers.

Stage 2 — Add the search-api module

Add the module to settings.gradle.kts in the user-search project:

1
rootProject.name = "user-search"
2

3
include("search-index", "client-tour", "search-api")

The build uses only what the service needs: web MVC, validation, the Elasticsearch client starter, and Kotlin support for Jackson. Spring Data Elasticsearch is not a dependency, for the reasons in chapter 09.

1
import org.springframework.boot.gradle.plugin.SpringBootPlugin
2

3
plugins {
4
    kotlin("jvm")
5
    kotlin("plugin.spring")
6
    id("org.springframework.boot")
7
}
8

9
kotlin {
10
    jvmToolchain(21)
11
    compilerOptions { freeCompilerArgs.add("-Xjsr305=strict") }
12
}
13

14
dependencies {
15
    implementation(platform(SpringBootPlugin.BOM_COORDINATES))
16
    implementation(project(":search-index"))
17
    implementation("org.springframework.boot:spring-boot-starter-webmvc")
18
    implementation("org.springframework.boot:spring-boot-starter-validation")
19
    implementation("org.springframework.boot:spring-boot-starter-elasticsearch")
20
    implementation("tools.jackson.module:jackson-module-kotlin")
21
    implementation("org.jetbrains.kotlin:kotlin-reflect")
22
}

The configuration names every connection setting, and reads every value from the environment:

1
spring:
2
  application:
3
    name: search-api
4
  elasticsearch:
5
    uris: ${ELASTICSEARCH_URIS}
6
    username: ${ELASTICSEARCH_USERNAME}
7
    password: ${ELASTICSEARCH_PASSWORD}
8
    connection-timeout: 2s
9
    socket-timeout: 5s
10
    restclient:
11
      ssl:
12
        bundle: elasticsearch
13
  ssl:
14
    bundle:
15
      pem:
16
        elasticsearch:
17
          truststore:
18
            certificate: ${ELASTICSEARCH_CA_CERT}
19

20
user-search:
21
  index:
22
    # Creates user-profile-v1 and its aliases at startup if they do not exist.
23
    # Local development only: it needs index-management privileges the Search API should not have.
24
    bootstrap: ${USER_SEARCH_INDEX_BOOTSTRAP:false}

Timeouts are explicit. connection-timeout: 2s fails fast when a node is unreachable. socket-timeout: 5s caps how long one request may take, so a slow cluster cannot hold the service’s request threads indefinitely. Needs validation: set the socket timeout from your latency target and Rally measurements, not from this example.
TLS trust comes from an SSL bundle. spring.ssl.bundle.pem.elasticsearch loads the CA certificate from ELASTICSEARCH_CA_CERT, and spring.elasticsearch.restclient.ssl.bundle applies it to the client. The certificate file is never on the classpath.
Index creation is off by default. Stage 3 explains why.

Security note — The lab passes the elastic superuser’s password in ELASTICSEARCH_PASSWORD. That is a local-development shortcut: the Search API needs read access to one alias and nothing else. Chapter 16 replaces it with an API key restricted to user-profile-read.

Stage 3 — Index management in the shared module

Two applications need to create or inspect the index: this service, in local development and tests, and the indexer in chapter 14. That code belongs in search-index.

Chapter 09’s UserProfileIndex gains the synonyms set, because an empty cluster cannot create the index without it. Replace the file:

1
package `in`.o612.eng.usersearch.index
2

3
/** Names and definitions of the versioned user-profile index. */
4
object UserProfileIndex {
5
    const val READ_ALIAS = "user-profile-read"
6
    const val WRITE_ALIAS = "user-profile-write"
7
    const val SYNONYMS_SET = "profile-name-synonyms"
8

9
    fun indexName(version: Int) = "user-profile-v$version"
10

11
    /** The reviewed index definition for [version], from `es/user-profile-v<version>.json`. */
12
    fun definition(version: Int): String = resource("/es/user-profile-v$version.json")
13

14
    /** The initial name synonyms, from `es/profile-name-synonyms.json`. */
15
    fun synonymsDefinition(): String = resource("/es/$SYNONYMS_SET.json")
16

17
    private fun resource(path: String): String {
18
        val stream = UserProfileIndex::class.java.getResourceAsStream(path)
19
            ?: error("No resource at $path")
20
        return stream.use { it.readBytes().decodeToString() }
21
    }
22
}

Add the initial synonyms as a reviewed resource. It holds the lab’s three rules, including the one chapter 07 added:

1
{
2
  "synonyms_set": [
3
    { "id": "mohammed", "synonyms": "mohammed, mohammad, muhammad, mohd" },
4
    { "id": "lakshmi",  "synonyms": "lakshmi, laxmi" },
5
    { "id": "fatima",   "synonyms": "fatima, fathima" }
6
  ]
7
}

IndexAdmin creates an index version from its JSON definition, after making sure the synonyms set exists, and reports where an alias points:

1
package `in`.o612.eng.usersearch.index
2

3
import co.elastic.clients.elasticsearch.ElasticsearchClient
4
import co.elastic.clients.elasticsearch._types.ElasticsearchException
5
import co.elastic.clients.elasticsearch.indices.CreateIndexRequest
6
import co.elastic.clients.elasticsearch.synonyms.PutSynonymRequest
7
import java.io.StringReader
8

9
/** Index and alias management for the user-profile index. Used by applications and jobs, never by search requests. */
10
class IndexAdmin(private val client: ElasticsearchClient) {
11

12
    /** Indices an alias currently points to; empty if the alias does not exist. */
13
    fun aliasTargets(alias: String): Set<String> =
14
        if (client.indices().existsAlias { it.name(alias) }.value()) {
15
            client.indices().getAlias { it.name(alias) }.aliases().keys
16
        } else {
17
            emptySet()
18
        }
19

20
    /**
21
     * Creates `user-profile-v<version>` from its reviewed definition, aliases included.
22
     * Returns false, and changes nothing, if the index already exists.
23
     */
24
    fun createIndex(version: Int): Boolean {
25
        val name = UserProfileIndex.indexName(version)
26
        if (client.indices().exists { it.index(name) }.value()) return false
27
        ensureSynonymsSet()
28
        val request = CreateIndexRequest.of {
29
            it.index(name).withJson(StringReader(UserProfileIndex.definition(version)))
30
        }
31
        client.indices().create(request)
32
        return true
33
    }
34

35
    /** The name analysers reference the synonyms set, so it must exist before any index version. */
36
    fun ensureSynonymsSet() {
37
        val exists = try {
38
            client.synonyms().getSynonym { it.id(UserProfileIndex.SYNONYMS_SET) }
39
            true
40
        } catch (e: ElasticsearchException) {
41
            if (e.status() != 404) throw e
42
            false
43
        }
44
        if (!exists) {
45
            client.synonyms().putSynonym(
46
                PutSynonymRequest.of {
47
                    it.id(UserProfileIndex.SYNONYMS_SET).withJson(StringReader(UserProfileIndex.synonymsDefinition()))
48
                },
49
            )
50
        }
51
    }
52
}

createIndex does nothing if the index already exists, so calling it twice is safe. ensureSynonymsSet creates the set only when it is missing, so it never overwrites synonyms added on a running cluster.

In search-api, register the Kotlin-aware JSON mapper from chapter 09 and an IndexAdmin bean:

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

3
import co.elastic.clients.elasticsearch.ElasticsearchClient
4
import co.elastic.clients.json.JsonpMapper
5
import `in`.o612.eng.usersearch.index.ElasticsearchJson
6
import `in`.o612.eng.usersearch.index.IndexAdmin
7
import org.springframework.context.annotation.Bean
8
import org.springframework.context.annotation.Configuration
9

10
@Configuration
11
class ElasticsearchConfig {
12
    /** Replaces Spring Boot's default mapper, which cannot construct Kotlin data classes (chapter 09). */
13
    @Bean
14
    fun jsonpMapper(): JsonpMapper = ElasticsearchJson.jsonpMapper()
15

16
    @Bean
17
    fun indexAdmin(client: ElasticsearchClient) = IndexAdmin(client)
18
}

The bootstrapper runs at startup only when user-search.index.bootstrap is true:

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

3
import `in`.o612.eng.usersearch.index.IndexAdmin
4
import `in`.o612.eng.usersearch.index.UserProfileIndex
5
import org.slf4j.LoggerFactory
6
import org.springframework.boot.ApplicationArguments
7
import org.springframework.boot.ApplicationRunner
8
import org.springframework.boot.autoconfigure.condition.ConditionalOnBooleanProperty
9
import org.springframework.stereotype.Component
10

11
/**
12
 * Creates the first index version and its aliases when none exist.
13
 * Enabled only with user-search.index.bootstrap=true, for local development and tests.
14
 */
15
@Component
16
@ConditionalOnBooleanProperty("user-search.index.bootstrap")
17
class IndexBootstrapper(private val indexAdmin: IndexAdmin) : ApplicationRunner {
18

19
    private val log = LoggerFactory.getLogger(javaClass)
20

21
    override fun run(args: ApplicationArguments) {
22
        val targets = indexAdmin.aliasTargets(UserProfileIndex.READ_ALIAS)
23
        if (targets.isNotEmpty()) {
24
            log.info("{} already points to {}; nothing to create", UserProfileIndex.READ_ALIAS, targets)
25
            return
26
        }
27
        val created = indexAdmin.createIndex(version = 1)
28
        log.info("Index {} created: {}", UserProfileIndex.indexName(1), created)
29
    }
30
}

Why it is opt-in. Creating indices and synonyms sets needs management privileges on the cluster. A search service that holds those privileges can do far more damage if it is compromised or misconfigured than one that can only read an alias. In production, index versions are created by the indexer or a deployment job with its own credentials (chapter 14). The bootstrapper exists so that a developer’s empty cluster, and chapter 17’s Testcontainers tests, get a working index with one property.

Verified against an empty Elasticsearch 9.5.4 node, the first start logs:

1
INFO ... c.e.u.api.index.IndexBootstrapper : Index user-profile-v1 created: true

and the next start, like a start against the lab:

1
INFO ... c.e.u.api.index.IndexBootstrapper : user-profile-read already points to [user-profile-v1]; nothing to create

Stage 4 — The request and response contract

The DTOs are the Search API’s public contract, and they encode two decisions from earlier chapters: only the filters the capability matrix allows exist, and result lists never contain contact details.

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
/** Query parameters of GET /api/users/search. Only the filters chapter 05's capability matrix allows exist. */
17
data class UserSearchRequest(
18
    @field:Size(min = 2, max = 100) val name: String? = null,
19
    @field:Size(max = 60) val city: String? = null,
20
    @field:Size(max = 60) val state: String? = null,
21
    @field:Pattern(regexp = "\\d{6}") val pincode: String? = null,
22
    val gender: Gender? = null,
23
    val accountStatus: AccountStatus = AccountStatus.ACTIVE,
24
    val updatedSince: Instant? = null,
25
    val sort: SortOrder = SortOrder.RELEVANCE,
26
    @field:Min(1) @field:Max(50) val size: Int = 20,
27
)
28

29
data class UserSearchResponse(
30
    val total: TotalHits,
31
    val hits: List<UserSearchHit>,
32
)
33

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

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

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

UserSearchRequest binds from query parameters, with Bean Validation on each field. size is capped at 50: chapter 13 replaces deeper paging with cursors, and a caller cannot ask for thousands of hits in one response.
Enums instead of strings for gender, accountStatus, and sort. Spring rejects any other value with a 400, so the case-sensitive keyword filters from chapter 05 only ever receive valid values.
accountStatus defaults to ACTIVE. A caller who forgets the filter does not see suspended or deleted profiles by accident.
TotalHits carries exact. Chapter 09 showed that totals stop at 10,000 by default; the contract says which kind of number it is.
UserSearchHit has no email, mobile number, or date of birth. Only ProfileDetail, returned by exact lookups, has them.

Stage 5 — Query builder, service, and controller

The query builder turns a validated request into an Elasticsearch request. It performs no I/O, so chapter 17 tests it without a cluster. This first version matches names with one match query; chapter 11 designs the real one.

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.core.SearchRequest
9
import co.elastic.clients.json.JsonData
10
import `in`.o612.eng.usersearch.api.web.SortOrder
11
import `in`.o612.eng.usersearch.api.web.UserSearchRequest
12
import `in`.o612.eng.usersearch.index.UserProfileIndex
13

14
/**
15
 * Turns a validated search request into an Elasticsearch request. Pure: no I/O, so it is unit-tested directly.
16
 * This first version matches names with a plain `match` query; chapter 11 replaces it.
17
 */
18
object UserQueryBuilder {
19

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

23
    fun build(request: UserSearchRequest): SearchRequest = SearchRequest.of { s ->
24
        s.index(UserProfileIndex.READ_ALIAS)
25
            .size(request.size)
26
            .source { src -> src.filter { f -> f.includes(RESULT_FIELDS) } }
27
            .query(query(request))
28
            .sort(sort(request.sort))
29
    }
30

31
    fun query(request: UserSearchRequest): Query = Query.of { q ->
32
        q.bool { b ->
33
            request.name?.let { name ->
34
                b.must { m -> m.match { mt -> mt.field("fullName").query(name).operator(Operator.And) } }
35
            }
36
            filters(request).forEach { b.filter(it) }
37
            b
38
        }
39
    }
40

41
    /** Exact constraints: filter context, no scoring. */
42
    fun filters(request: UserSearchRequest): List<Query> = buildList {
43
        add(term("accountStatus", request.accountStatus.name))
44
        request.city?.let { add(term("city", it)) }
45
        request.state?.let { add(term("state", it)) }
46
        request.pincode?.let { add(term("pincode", it)) }
47
        request.gender?.let { add(term("gender", it.name)) }
48
        request.updatedSince?.let { since ->
49
            add(Query.of { q -> q.range { r -> r.untyped { u -> u.field("updatedAt").gte(JsonData.of(since.toString())) } } })
50
        }
51
    }
52

53
    /** Relevance first when requested, then newest, then userId so every order is total. */
54
    fun sort(order: SortOrder): List<SortOptions> = buildList {
55
        if (order == SortOrder.RELEVANCE) add(SortOptions.of { it.score { sc -> sc.order(EsSortOrder.Desc) } })
56
        add(SortOptions.of { it.field { f -> f.field("updatedAt").order(EsSortOrder.Desc) } })
57
        add(SortOptions.of { it.field { f -> f.field("userId").order(EsSortOrder.Asc) } })
58
    }
59

60
    private fun term(field: String, value: String): Query =
61
        Query.of { q -> q.term { t -> t.field(field).value(FieldValue.of(value)) } }
62
}

Four choices here carry over into every later version. Exact constraints go into filter clauses, which do not affect scoring. RESULT_FIELDS limits _source to what a result list shows. Every sort ends with userId, so the order is total and repeatable, which chapter 13’s cursors depend on. And the target is always the read alias.

The service executes requests and maps responses into the contract:

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

3
import co.elastic.clients.elasticsearch.ElasticsearchClient
4
import co.elastic.clients.elasticsearch._types.FieldValue
5
import co.elastic.clients.elasticsearch.core.search.TotalHitsRelation
6
import `in`.o612.eng.usersearch.api.web.ProfileDetail
7
import `in`.o612.eng.usersearch.api.web.TotalHits
8
import `in`.o612.eng.usersearch.api.web.UserSearchHit
9
import `in`.o612.eng.usersearch.api.web.UserSearchRequest
10
import `in`.o612.eng.usersearch.api.web.UserSearchResponse
11
import `in`.o612.eng.usersearch.index.UserProfileIndex
12
import org.springframework.stereotype.Service
13
import java.time.Instant
14

15
@Service
16
class UserSearchService(private val client: ElasticsearchClient) {
17

18
    fun search(request: UserSearchRequest): UserSearchResponse {
19
        val response = client.search(UserQueryBuilder.build(request), ResultSource::class.java)
20
        val total = response.hits().total()
21
        return UserSearchResponse(
22
            total = TotalHits(total?.value() ?: 0, exact = total?.relation() == TotalHitsRelation.Eq),
23
            hits = response.hits().hits().mapNotNull { hit ->
24
                hit.source()?.let { src ->
25
                    UserSearchHit(
26
                        userId = src.userId,
27
                        fullName = src.fullName,
28
                        city = src.city,
29
                        state = src.state,
30
                        accountStatus = src.accountStatus,
31
                        updatedAt = src.updatedAt,
32
                        score = hit.score(),
33
                        highlights = hit.highlight(),
34
                    )
35
                }
36
            },
37
        )
38
    }
39

40
    fun findById(userId: String): ProfileDetail? =
41
        client.get({ it.index(UserProfileIndex.READ_ALIAS).id(userId).sourceIncludes(DETAIL_FIELDS) }, DetailSource::class.java)
42
            .source()?.toDetail()
43

44
    fun findByEmail(email: String): ProfileDetail? = findOneByTerm("email", email)
45

46
    fun findByMobile(mobileNumber: String): ProfileDetail? = findOneByTerm("mobileNumber", mobileNumber)
47

48
    /** Exact lookup on a keyword field. PostgreSQL enforces uniqueness; Elasticsearch cannot. */
49
    private fun findOneByTerm(field: String, value: String): ProfileDetail? =
50
        client.search({ s ->
51
            s.index(UserProfileIndex.READ_ALIAS)
52
                .size(1)
53
                .source { src -> src.filter { f -> f.includes(DETAIL_FIELDS) } }
54
                .query { q -> q.term { t -> t.field(field).value(FieldValue.of(value)) } }
55
        }, DetailSource::class.java).hits().hits().firstOrNull()?.source()?.toDetail()
56

57
    /** Source fields read for result lists. */
58
    data class ResultSource(
59
        val userId: String,
60
        val fullName: String,
61
        val city: String,
62
        val state: String,
63
        val accountStatus: String,
64
        val updatedAt: Instant,
65
    )
66

67
    /** Source fields read for exact lookups. */
68
    data class DetailSource(
69
        val userId: String,
70
        val fullName: String,
71
        val email: String,
72
        val mobileNumber: String,
73
        val city: String,
74
        val state: String,
75
        val pincode: String,
76
        val dateOfBirth: java.time.LocalDate?,
77
        val gender: String,
78
        val accountStatus: String,
79
        val updatedAt: Instant,
80
    ) {
81
        fun toDetail() = ProfileDetail(
82
            userId, fullName, email, mobileNumber, city, state, pincode, dateOfBirth, gender, accountStatus, updatedAt,
83
        )
84
    }
85

86
    private companion object {
87
        val DETAIL_FIELDS = listOf(
88
            "userId", "fullName", "email", "mobileNumber", "city", "state", "pincode",
89
            "dateOfBirth", "gender", "accountStatus", "updatedAt",
90
        )
91
    }
92
}

Exact lookup by ID uses a get, which goes to one shard. Lookups by email and mobile number use a term query with size(1): those fields are unique in PostgreSQL, but Elasticsearch has no way to enforce uniqueness, so the code takes the first hit rather than assuming exactly one.

The controller exposes four endpoints and validates path and query parameters:

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

3
import `in`.o612.eng.usersearch.api.search.UserSearchService
4
import jakarta.validation.Valid
5
import jakarta.validation.constraints.Email
6
import jakarta.validation.constraints.Pattern
7
import org.springframework.http.ResponseEntity
8
import org.springframework.validation.annotation.Validated
9
import org.springframework.web.bind.annotation.GetMapping
10
import org.springframework.web.bind.annotation.PathVariable
11
import org.springframework.web.bind.annotation.RequestMapping
12
import org.springframework.web.bind.annotation.RequestParam
13
import org.springframework.web.bind.annotation.RestController
14

15
@RestController
16
@RequestMapping("/api/users")
17
@Validated
18
class UserSearchController(private val service: UserSearchService) {
19

20
    @GetMapping("/search")
21
    fun search(@Valid request: UserSearchRequest): UserSearchResponse = service.search(request)
22

23
    @GetMapping("/{userId}")
24
    fun byId(@PathVariable @Pattern(regexp = "\\d{1,19}") userId: String): ResponseEntity<ProfileDetail> =
25
        ResponseEntity.ofNullable(service.findById(userId))
26

27
    @GetMapping("/by-email")
28
    fun byEmail(@RequestParam @Email email: String): ResponseEntity<ProfileDetail> =
29
        ResponseEntity.ofNullable(service.findByEmail(email))
30

31
    @GetMapping("/by-mobile")
32
    fun byMobile(@RequestParam @Pattern(regexp = "\\d{10}") mobileNumber: String): ResponseEntity<ProfileDetail> =
33
        ResponseEntity.ofNullable(service.findByMobile(mobileNumber))
34
}

Failures from Elasticsearch are mapped to responses that say what happened without exposing details:

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

3
import co.elastic.clients.elasticsearch._types.ElasticsearchException
4
import co.elastic.clients.transport.TransportException
5
import org.slf4j.LoggerFactory
6
import org.springframework.http.HttpStatus
7
import org.springframework.http.ProblemDetail
8
import org.springframework.web.bind.annotation.ExceptionHandler
9
import org.springframework.web.bind.annotation.RestControllerAdvice
10
import java.io.IOException
11

12
@RestControllerAdvice
13
class ErrorHandling {
14

15
    private val log = LoggerFactory.getLogger(javaClass)
16

17
    /** Elasticsearch answered with an error: a request this service built is wrong, or the index is missing. */
18
    @ExceptionHandler(ElasticsearchException::class)
19
    fun elasticsearchError(e: ElasticsearchException): ProblemDetail {
20
        log.error("Elasticsearch rejected a request: {} {}", e.status(), e.error().type(), e)
21
        return ProblemDetail.forStatusAndDetail(HttpStatus.BAD_GATEWAY, "Search is temporarily failing.")
22
    }
23

24
    /** Elasticsearch could not be reached, timed out, or returned an unreadable response. */
25
    @ExceptionHandler(TransportException::class, IOException::class)
26
    fun unavailable(e: Exception): ProblemDetail {
27
        log.warn("Search backend unavailable: {}", e.message)
28
        return ProblemDetail.forStatusAndDetail(HttpStatus.SERVICE_UNAVAILABLE, "Search is temporarily unavailable.")
29
    }
30
}

An ElasticsearchException means the cluster answered with an error, such as a missing index or a query it cannot parse. That is this service’s fault or a deployment problem, so it maps to 502 and is logged as an error. A TransportException or IOException means the cluster could not be reached, timed out, or returned something unreadable, which maps to 503, a signal that retrying later may work.

Stage 6 — Run and verify

Start the service against the lab. The CA path must be absolute, with a file: prefix:

1
set -a; source ../user-search-lab/.env; set +a
2
export ELASTICSEARCH_URIS=https://localhost:9200
3
export ELASTICSEARCH_USERNAME=elastic ELASTICSEARCH_PASSWORD="$ELASTIC_PASSWORD"
4
export ELASTICSEARCH_CA_CERT="file:$(cd ../user-search-lab && pwd)/certs/ca/ca.crt"
5
./gradlew :search-api:bootRun

In a second terminal, search by name within a state. state=bihar is lowercase; the normaliser makes it match.

1
curl -s 'localhost:8080/api/users/search?name=prashant%20kumar&state=bihar&size=2'

1
{
2
  "total": { "value": 237, "exact": true },
3
  "hits": [
4
    { "userId": "835200", "fullName": "Prashant Kumar", "city": "Patna", "state": "Bihar",
5
      "accountStatus": "ACTIVE", "updatedAt": "2025-11-03T00:00:00Z", "score": 6.396736, "highlights": {} },
6
    { "userId": "343200", "fullName": "Prashant Kumar", "city": "Patna", "state": "Bihar",
7
      "accountStatus": "ACTIVE", "updatedAt": "2025-10-29T00:00:00Z", "score": 6.396736, "highlights": {} }
8
  ]
9
}

The response is reformatted here. Every hit has the same score, so the updatedAt tiebreaker decides the order. Filter without a name, newest first:

1
curl -s 'localhost:8080/api/users/search?state=bihar&sort=UPDATED_AT&updatedSince=2026-08-01T00:00:00Z&size=2'

1
{
2
  "total": { "value": 78, "exact": true },
3
  "hits": [
4
    { "userId": "560997", "fullName": "Ananya Jha", "city": "Patna", "state": "Bihar",
5
      "accountStatus": "ACTIVE", "updatedAt": "2026-08-28T00:00:00Z", "score": null, "highlights": {} },
6
    { "userId": "196496", "fullName": "Sanjay Mishra", "city": "Patna", "state": "Bihar",
7
      "accountStatus": "ACTIVE", "updatedAt": "2026-08-26T00:00:00Z", "score": null, "highlights": {} }
8
  ]
9
}

PostgreSQL agrees: 78 active profiles in Bihar were updated on or after 1 August 2026. The score is null because a filter-only query sorted by a field computes no scores.

Exact lookups return the full detail, including contact fields:

1
curl -s localhost:8080/api/users/42

1
{
2
  "userId": "42", "fullName": "Suresh Sharma", "email": "suresh.sharma.42@example.com",
3
  "mobileNumber": "9000000042", "city": "Gaya", "state": "Rajasthan", "pincode": "302068",
4
  "dateOfBirth": "1985-02-13", "gender": "MALE", "accountStatus": "SUSPENDED",
5
  "updatedAt": "2026-09-25T20:00:49.833876Z"
6
}

Profile 42’s updatedAt is the moment you ran chapter 04’s UPDATE, so yours differs. GET /api/users/43 returns 404, because chapter 04 deleted it. GET /api/users/by-email?email=PRIYA.KUMAR.1@EXAMPLE.COM returns profile 1, and GET /api/users/by-mobile?mobileNumber=9000000001 returns Priya Kumar.

Requests outside the contract are rejected before they reach Elasticsearch:

1
curl -s 'localhost:8080/api/users/search?size=500&pincode=12'

1
{"timestamp":"2026-09-25T20:21:52.570Z","status":400,"error":"Bad Request","path":"/api/users/search"}

The service log names both violations: size must be at most 50, and pincode must match \d{6}.

Finally, check the failure path. Start a second instance pointing at a port where nothing listens:

1
ELASTICSEARCH_URIS=https://localhost:9201 ./gradlew :search-api:bootRun --args='--server.port=8081'
2
curl -s 'localhost:8081/api/users/search?name=prashant'

1
{"detail":"Search is temporarily unavailable.","instance":"/api/users/search","status":503,"title":"Service Unavailable"}

The log line behind it reads Search backend unavailable: Connect to https://localhost:9201 [localhost/127.0.0.1] failed: Connection refused.

Checkpoint

Four things should now be true: the lab refuses plain HTTP, search-api starts with the CA from ELASTICSEARCH_CA_CERT, the name search returns 237 exact results, and an unreachable cluster produces 503. If startup fails with a certificate error, check that ELASTICSEARCH_CA_CERT has the file: prefix and an absolute path.

Security note — The Search API has no authentication yet, and its exact-lookup endpoints return email addresses, mobile numbers, and dates of birth. Bind it to localhost or keep it on a private network until chapter 16, which adds caller authentication, field-level access rules, and log masking. Elasticsearch cannot make these decisions for you: its security controls apply to the service account, not to the person using your API.

What you built, and what comes next

The lab now speaks only TLS. The user-search project has a Search API that reads through user-profile-read with a verified certificate, validates every request against the contract, returns totals with their exactness, keeps contact fields out of result lists, and maps cluster failures to 502 and 503. The shared search-index module can create an index version and its synonyms from reviewed files on an empty cluster.

What the service does not have yet is good search. It matches names with a single match query, ignores autocomplete and typos, and returns no highlights. Chapter 11 designs the query: query and filter context, bool clauses, scoring and when to ignore it, highlighting, and the complete “active users named Prashant in Bihar, updated recently” request in JSON and in Kotlin.

ElasticsearchSpring BootKotlin