# elastic/go-elasticsearch architecture

> Architecture diagram of the GitHub repository elastic/go-elasticsearch, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/elastic/go-elasticsearch
- Repository: https://github.com/elastic/go-elasticsearch

## Overview

go-elasticsearch is the official Go client for Elasticsearch. A Go application configures the client, selects a low-level or typed API operation, and sends an HTTP request to an Elasticsearch cluster; typed query builders can help assemble request bodies. The client also exposes broad API families for search, document updates, ingest, security, and cluster operations, plus documented bulk-indexing and observability capabilities. The graph groups generated endpoints by domain rather than listing every operation. Sampled request code shows transport-backed API calls; links between client setup and endpoint families follow the README’s documented usage, not inspected root wiring.

Main entry points: [`typedapi`](https://github.com/elastic/go-elasticsearch/tree/main/typedapi) (Typed API), [`elasticsearch.go`](https://github.com/elastic/go-elasticsearch/blob/main/elasticsearch.go) (Client setup), [`esapi`](https://github.com/elastic/go-elasticsearch/tree/main/esapi) (Low-level APIs), [`typedapi/ingest`](https://github.com/elastic/go-elasticsearch/tree/main/typedapi/ingest) (Ingest pipelines)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client surface"]
  node_client["Client setup<br/>[elasticsearch.go]"]
  node_transport["HTTP transport"]
  node_lowlevel["Low-level APIs"]
  node_typed["Typed API"]
end

subgraph group_search["Search and query"]
  node_searchops["Search operations"]
  node_searchapp["Search applications<br/>[render_query.go]"]
  node_queryvalidate["Query validation<br/>[validate_query.go]"]
  node_asyncquery["Async ES&#124;QL<br/>[async_query.go]"]
  node_sqlquery["SQL queries<br/>[query.go]"]
end

subgraph group_data["Data and ingest"]
  node_docupdates["Document updates<br/>[update_by_query.go]"]
  node_docdeletes["Document deletes<br/>[delete_by_query.go]"]
  node_ingest["Ingest pipelines"]
  node_logstash["Logstash pipelines"]
  node_pipeline_types["Pipeline models<br/>[ingestpipeline.go]"]
  node_pipeline_dsl["Pipeline builders<br/>[ingestpipeline.go]"]
  node_bulk["Bulk indexing<br/>[indexer.go]"]
end

subgraph group_admin["Cluster and security"]
  node_cat_tasks["Task listings<br/>[tasks.go]"]
  node_snapshot["Snapshot analysis"]
  node_security["Security APIs<br/>[query_api_keys.go]"]
  node_watcher["Watch queries<br/>[query_watches.go]"]
end

subgraph group_extensions["Client capabilities"]
  node_dsl["Query builders"]
  node_observability["Observability hooks"]
  node_interceptors["Interceptors"]
end

node_app(("Go application"))
node_elastic[("Elasticsearch")]

node_app -->|"configures"| node_client
node_app -->|"uses"| node_lowlevel
node_app -->|"uses"| node_typed
node_client -.->|"configures"| node_transport
node_lowlevel -->|"sends requests"| node_elastic
node_typed -->|"sends requests"| node_elastic
node_typed -->|"exposes"| node_searchops
node_typed -->|"exposes"| node_searchapp
node_typed -->|"exposes"| node_queryvalidate
node_typed -->|"exposes"| node_asyncquery
node_typed -->|"exposes"| node_sqlquery
node_typed -->|"exposes"| node_docupdates
node_typed -->|"exposes"| node_docdeletes
node_typed -->|"exposes"| node_ingest
node_typed -->|"exposes"| node_logstash
node_typed -->|"exposes"| node_cat_tasks
node_typed -->|"exposes"| node_snapshot
node_typed -->|"exposes"| node_security
node_typed -->|"exposes"| node_watcher
node_ingest -->|"uses models"| node_pipeline_types
node_pipeline_dsl -->|"builds"| node_pipeline_types
node_typed -->|"offers builders"| node_dsl
node_app -->|"can bulk index"| node_bulk
node_app -->|"can instrument"| node_observability
node_app -->|"can customize"| node_interceptors

click node_client "https://github.com/elastic/go-elasticsearch/blob/main/elasticsearch.go"
click node_lowlevel "https://github.com/elastic/go-elasticsearch/tree/main/esapi"
click node_typed "https://github.com/elastic/go-elasticsearch/tree/main/typedapi"
click node_searchops "https://github.com/elastic/go-elasticsearch/tree/main/typedapi/esql"
click node_searchapp "https://github.com/elastic/go-elasticsearch/blob/main/typedapi/searchapplication/renderquery/render_query.go"
click node_queryvalidate "https://github.com/elastic/go-elasticsearch/blob/main/typedapi/indices/validatequery/validate_query.go"
click node_asyncquery "https://github.com/elastic/go-elasticsearch/blob/main/typedapi/esql/asyncquery/async_query.go"
click node_sqlquery "https://github.com/elastic/go-elasticsearch/blob/main/typedapi/sql/query/query.go"
click node_docupdates "https://github.com/elastic/go-elasticsearch/blob/main/typedapi/core/updatebyquery/update_by_query.go"
click node_docdeletes "https://github.com/elastic/go-elasticsearch/blob/main/typedapi/core/deletebyquery/delete_by_query.go"
click node_ingest "https://github.com/elastic/go-elasticsearch/tree/main/typedapi/ingest"
click node_logstash "https://github.com/elastic/go-elasticsearch/tree/main/typedapi/logstash"
click node_pipeline_types "https://github.com/elastic/go-elasticsearch/blob/main/typedapi/types/ingestpipeline.go"
click node_pipeline_dsl "https://github.com/elastic/go-elasticsearch/blob/main/typedapi/esdsl/ingestpipeline.go"
click node_bulk "https://github.com/elastic/go-elasticsearch/blob/main/_examples/bulk/indexer.go"
click node_cat_tasks "https://github.com/elastic/go-elasticsearch/blob/main/typedapi/cat/tasks/tasks.go"
click node_snapshot "https://github.com/elastic/go-elasticsearch/blob/main/typedapi/snapshot/repositoryanalyze/repository_analyze.go"
click node_security "https://github.com/elastic/go-elasticsearch/blob/main/typedapi/security/queryapikeys/query_api_keys.go"
click node_watcher "https://github.com/elastic/go-elasticsearch/blob/main/typedapi/watcher/querywatches/query_watches.go"
click node_dsl "https://github.com/elastic/go-elasticsearch/tree/main/typedapi/esdsl"
click node_observability "https://github.com/elastic/go-elasticsearch/tree/main/_examples/instrumentation"
click node_interceptors "https://github.com/elastic/go-elasticsearch/tree/main/_examples/interceptor"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_client,node_transport,node_lowlevel,node_typed toneBlue
class node_searchops,node_searchapp,node_queryvalidate,node_asyncquery,node_sqlquery,node_elastic toneAmber
class node_docupdates,node_docdeletes,node_ingest,node_logstash,node_pipeline_types,node_pipeline_dsl,node_bulk toneMint
class node_cat_tasks,node_snapshot,node_security,node_watcher toneRose
class node_dsl,node_observability,node_interceptors,node_app toneIndigo
```

## Components

### Client surface

- [Client setup](https://github.com/elastic/go-elasticsearch/blob/main/elasticsearch.go): `elasticsearch.go`
- **HTTP transport**
- [Low-level APIs](https://github.com/elastic/go-elasticsearch/tree/main/esapi): `esapi`
- [Typed API](https://github.com/elastic/go-elasticsearch/tree/main/typedapi): `typedapi`

### Search and query

- [Search operations](https://github.com/elastic/go-elasticsearch/tree/main/typedapi/esql): `typedapi/esql`
- [Search applications](https://github.com/elastic/go-elasticsearch/blob/main/typedapi/searchapplication/renderquery/render_query.go): `typedapi/searchapplication/renderquery/render_query.go`
- [Query validation](https://github.com/elastic/go-elasticsearch/blob/main/typedapi/indices/validatequery/validate_query.go): `typedapi/indices/validatequery/validate_query.go`
- [Async ES|QL](https://github.com/elastic/go-elasticsearch/blob/main/typedapi/esql/asyncquery/async_query.go): `typedapi/esql/asyncquery/async_query.go`
- [SQL queries](https://github.com/elastic/go-elasticsearch/blob/main/typedapi/sql/query/query.go): `typedapi/sql/query/query.go`

### Data and ingest

- [Document updates](https://github.com/elastic/go-elasticsearch/blob/main/typedapi/core/updatebyquery/update_by_query.go): `typedapi/core/updatebyquery/update_by_query.go`
- [Document deletes](https://github.com/elastic/go-elasticsearch/blob/main/typedapi/core/deletebyquery/delete_by_query.go): `typedapi/core/deletebyquery/delete_by_query.go`
- [Ingest pipelines](https://github.com/elastic/go-elasticsearch/tree/main/typedapi/ingest): `typedapi/ingest`
- [Logstash pipelines](https://github.com/elastic/go-elasticsearch/tree/main/typedapi/logstash): `typedapi/logstash`
- [Pipeline models](https://github.com/elastic/go-elasticsearch/blob/main/typedapi/types/ingestpipeline.go): `typedapi/types/ingestpipeline.go`
- [Pipeline builders](https://github.com/elastic/go-elasticsearch/blob/main/typedapi/esdsl/ingestpipeline.go): `typedapi/esdsl/ingestpipeline.go`
- [Bulk indexing](https://github.com/elastic/go-elasticsearch/blob/main/_examples/bulk/indexer.go): `_examples/bulk/indexer.go`

### Cluster and security

- [Task listings](https://github.com/elastic/go-elasticsearch/blob/main/typedapi/cat/tasks/tasks.go): `typedapi/cat/tasks/tasks.go`
- [Snapshot analysis](https://github.com/elastic/go-elasticsearch/blob/main/typedapi/snapshot/repositoryanalyze/repository_analyze.go): `typedapi/snapshot/repositoryanalyze/repository_analyze.go`
- [Security APIs](https://github.com/elastic/go-elasticsearch/blob/main/typedapi/security/queryapikeys/query_api_keys.go): `typedapi/security/queryapikeys/query_api_keys.go`
- [Watch queries](https://github.com/elastic/go-elasticsearch/blob/main/typedapi/watcher/querywatches/query_watches.go): `typedapi/watcher/querywatches/query_watches.go`

### Client capabilities

- [Query builders](https://github.com/elastic/go-elasticsearch/tree/main/typedapi/esdsl): `typedapi/esdsl`
- [Observability hooks](https://github.com/elastic/go-elasticsearch/tree/main/_examples/instrumentation): `_examples/instrumentation`
- [Interceptors](https://github.com/elastic/go-elasticsearch/tree/main/_examples/interceptor): `_examples/interceptor`

### Other components

- **Go application**
- **Elasticsearch**

## Connections

- Go application → Client setup: configures
- Go application → Low-level APIs: uses
- Go application → Typed API: uses
- Client setup → HTTP transport: configures
- Low-level APIs → Elasticsearch: sends requests
- Typed API → Elasticsearch: sends requests (evidence: `typedapi/ingest/putpipeline/put_pipeline.go`)
- Typed API → Search operations: exposes (evidence: `typedapi/esql/asyncquery/async_query.go`)
- Typed API → Search applications: exposes (evidence: `typedapi/searchapplication/renderquery/render_query.go`)
- Typed API → Query validation: exposes (evidence: `typedapi/indices/validatequery/validate_query.go`)
- Typed API → Async ES|QL: exposes (evidence: `typedapi/esql/asyncquery/async_query.go`)
- Typed API → SQL queries: exposes (evidence: `typedapi/sql/query/query.go`)
- Typed API → Document updates: exposes (evidence: `typedapi/core/updatebyquery/update_by_query.go`)
- Typed API → Document deletes: exposes (evidence: `typedapi/core/deletebyquery/delete_by_query.go`)
- Typed API → Ingest pipelines: exposes (evidence: `typedapi/ingest/getpipeline/get_pipeline.go`)
- Typed API → Logstash pipelines: exposes (evidence: `typedapi/logstash/getpipeline/get_pipeline.go`)
- Typed API → Task listings: exposes (evidence: `typedapi/cat/tasks/tasks.go`)
- Typed API → Snapshot analysis: exposes (evidence: `typedapi/snapshot/repositoryanalyze/repository_analyze.go`)
- Typed API → Security APIs: exposes (evidence: `typedapi/security/queryapikeys/query_api_keys.go`)
- Typed API → Watch queries: exposes (evidence: `typedapi/watcher/querywatches/query_watches.go`)
- Ingest pipelines → Pipeline models: uses models (evidence: `typedapi/ingest/putpipeline/put_pipeline.go`)
- Pipeline builders → Pipeline models: builds (evidence: `typedapi/esdsl/ingestpipeline.go`)
- Typed API → Query builders: offers builders (evidence: `typedapi/esdsl/ingestpipeline.go`)
- Go application → Bulk indexing: can bulk index
- Go application → Observability hooks: can instrument
- Go application → Interceptors: can customize
