# elastic/elasticsearch-java architecture

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

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

## Overview

This is the official Elasticsearch Java client: applications build typed API requests, invoke client methods, and receive typed responses or errors over an HTTP transport. Its documented API coverage spans document and index operations, search, inference, and cluster-management APIs; helper branches include bulk ingestion and ESQL adapters. The excerpts establish the shared client, transport, endpoint, and JSON-mapping responsibilities. Several product subsystems are represented by paths from the tree and README capabilities, but their internal calls were not sampled, so uncertain links are omitted.

Main entry points: [`java-client/src/main/java/co/elastic/clients/elasticsearch/ElasticsearchClient.java`](https://github.com/elastic/elasticsearch-java/blob/main/java-client/src/main/java/co/elastic/clients/elasticsearch/ElasticsearchClient.java) (Elasticsearch client), [`java-client/src/main/java/co/elastic/clients/transport/Transport.java`](https://github.com/elastic/elasticsearch-java/blob/main/java-client/src/main/java/co/elastic/clients/transport/Transport.java) (Transport interface), [`java-client/src/main/java/co/elastic/clients/transport/Endpoint.java`](https://github.com/elastic/elasticsearch-java/blob/main/java-client/src/main/java/co/elastic/clients/transport/Endpoint.java) (Request endpoints), [`java-client/src/main/java/co/elastic/clients/ApiClient.java`](https://github.com/elastic/elasticsearch-java/blob/main/java-client/src/main/java/co/elastic/clients/ApiClient.java) (API client base)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Typed API"]
  node_client["Elasticsearch client"]
  node_async["Async client"]
  node_api_base["API client base<br/>[ApiClient.java]"]
  node_endpoints["Request endpoints<br/>[Endpoint.java]"]
  node_typed_models["Typed API models"]
end

subgraph group_wire["Transport"]
  node_transport["Transport interface<br/>[Transport.java]"]
  node_rest["REST transport<br/>[Rest5Client.java]"]
  node_netty["Netty transport"]
end

subgraph group_json["JSON Mapping"]
  node_mapper["JSON mapper<br/>[JsonpMapper.java]"]
  node_deserializer["JSON deserializers"]
  node_object_deserializer["Object deserializer"]
  node_errors["Error responses<br/>[ErrorResponse.java]"]
end

subgraph group_helpers["Client Helpers"]
  node_bulk["Bulk ingester<br/>[BulkIngester.java]"]
  node_esql["ESQL adapters"]
  node_vector["Vector helpers"]
end

subgraph group_domains["API Domains"]
  node_search["Search and documents"]
  node_inference["Inference APIs"]
  node_ingest["Ingest APIs"]
  node_query_rules["Query rules APIs"]
  node_other_apis["Other API clients"]
end

node_application(("Java application"))
node_server[("Elasticsearch")]

node_application -.->|"calls"| node_client
node_client -.->|"extends"| node_api_base
node_async -.->|"extends"| node_api_base
node_api_base -->|"uses"| node_transport
node_client -.->|"dispatches"| node_endpoints
node_async -.->|"dispatches"| node_endpoints
node_transport -->|"sends HTTP"| node_server
node_transport -->|"implemented by"| node_rest
node_transport -.->|"implemented by"| node_netty
node_transport -->|"provides"| node_mapper
node_mapper -->|"deserializes"| node_deserializer
node_deserializer -.->|"supports"| node_object_deserializer
node_endpoints -.->|"encodes requests"| node_typed_models
node_endpoints -->|"defines decoding"| node_mapper
node_errors -.->|"contains error"| node_typed_models
node_client -->|"supports"| node_search
node_client -.->|"supports"| node_inference
node_client -.->|"supports"| node_ingest
node_client -.->|"supports"| node_query_rules
node_client -->|"supports"| node_other_apis
node_bulk -.->|"assists writes"| node_client
node_esql -.->|"adapts results"| node_client
node_vector -.->|"supports vectors"| node_client

click node_client "https://github.com/elastic/elasticsearch-java/blob/main/java-client/src/main/java/co/elastic/clients/elasticsearch/ElasticsearchClient.java"
click node_async "https://github.com/elastic/elasticsearch-java/blob/main/java-client/src/main/java/co/elastic/clients/elasticsearch/ElasticsearchAsyncClient.java"
click node_api_base "https://github.com/elastic/elasticsearch-java/blob/main/java-client/src/main/java/co/elastic/clients/ApiClient.java"
click node_endpoints "https://github.com/elastic/elasticsearch-java/blob/main/java-client/src/main/java/co/elastic/clients/transport/Endpoint.java"
click node_typed_models "https://github.com/elastic/elasticsearch-java/tree/main/java-client/src/main/java/co/elastic/clients/elasticsearch/_types"
click node_transport "https://github.com/elastic/elasticsearch-java/blob/main/java-client/src/main/java/co/elastic/clients/transport/Transport.java"
click node_rest "https://github.com/elastic/elasticsearch-java/blob/main/rest5-client/src/main/java/co/elastic/clients/transport/rest5_client/low_level/Rest5Client.java"
click node_netty "https://github.com/elastic/elasticsearch-java/blob/main/example-transports/src/main/java/co/elastic/clients/transport/netty/NettyElasticsearchTransport.java"
click node_mapper "https://github.com/elastic/elasticsearch-java/blob/main/java-client/src/main/java/co/elastic/clients/json/JsonpMapper.java"
click node_deserializer "https://github.com/elastic/elasticsearch-java/blob/main/java-client/src/main/java/co/elastic/clients/json/JsonpDeserializer.java"
click node_object_deserializer "https://github.com/elastic/elasticsearch-java/blob/main/java-client/src/main/java/co/elastic/clients/json/ObjectDeserializer.java"
click node_errors "https://github.com/elastic/elasticsearch-java/blob/main/java-client/src/main/java/co/elastic/clients/elasticsearch/_types/ErrorResponse.java"
click node_bulk "https://github.com/elastic/elasticsearch-java/blob/main/java-client/src/main/java/co/elastic/clients/elasticsearch/_helpers/bulk/BulkIngester.java"
click node_esql "https://github.com/elastic/elasticsearch-java/tree/main/java-client/src/main/java/co/elastic/clients/elasticsearch/_helpers/esql"
click node_vector "https://github.com/elastic/elasticsearch-java/blob/main/java-client/src/main/java/co/elastic/clients/elasticsearch/_helpers/vector/AbstractBase64VectorDocument.java"
click node_search "https://github.com/elastic/elasticsearch-java/blob/main/java-client/src/main/java/co/elastic/clients/elasticsearch/ElasticsearchClient.java"
click node_inference "https://github.com/elastic/elasticsearch-java/blob/main/java-client/src/main/java/co/elastic/clients/elasticsearch/inference/ElasticsearchInferenceClient.java"
click node_ingest "https://github.com/elastic/elasticsearch-java/blob/main/java-client/src/main/java/co/elastic/clients/elasticsearch/ingest/ElasticsearchIngestClient.java"
click node_query_rules "https://github.com/elastic/elasticsearch-java/blob/main/java-client/src/main/java/co/elastic/clients/elasticsearch/query_rules/ElasticsearchQueryRulesClient.java"
click node_other_apis "https://github.com/elastic/elasticsearch-java/tree/main/java-client/src/main/java/co/elastic/clients/elasticsearch"

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_async,node_api_base,node_endpoints,node_typed_models toneBlue
class node_transport,node_rest,node_netty,node_server toneAmber
class node_mapper,node_deserializer,node_object_deserializer,node_errors toneMint
class node_bulk,node_esql,node_vector toneRose
class node_search,node_inference,node_ingest,node_query_rules,node_other_apis,node_application toneIndigo
```

## Components

### Typed API

- [Elasticsearch client](https://github.com/elastic/elasticsearch-java/blob/main/java-client/src/main/java/co/elastic/clients/elasticsearch/ElasticsearchClient.java): `java-client/src/main/java/co/elastic/clients/elasticsearch/ElasticsearchClient.java`
- [Async client](https://github.com/elastic/elasticsearch-java/blob/main/java-client/src/main/java/co/elastic/clients/elasticsearch/ElasticsearchAsyncClient.java): `java-client/src/main/java/co/elastic/clients/elasticsearch/ElasticsearchAsyncClient.java`
- [API client base](https://github.com/elastic/elasticsearch-java/blob/main/java-client/src/main/java/co/elastic/clients/ApiClient.java): `java-client/src/main/java/co/elastic/clients/ApiClient.java`
- [Request endpoints](https://github.com/elastic/elasticsearch-java/blob/main/java-client/src/main/java/co/elastic/clients/transport/Endpoint.java): `java-client/src/main/java/co/elastic/clients/transport/Endpoint.java`
- [Typed API models](https://github.com/elastic/elasticsearch-java/tree/main/java-client/src/main/java/co/elastic/clients/elasticsearch/_types): `java-client/src/main/java/co/elastic/clients/elasticsearch/_types`

### Transport

- [Transport interface](https://github.com/elastic/elasticsearch-java/blob/main/java-client/src/main/java/co/elastic/clients/transport/Transport.java): `java-client/src/main/java/co/elastic/clients/transport/Transport.java`
- [REST transport](https://github.com/elastic/elasticsearch-java/blob/main/rest5-client/src/main/java/co/elastic/clients/transport/rest5_client/low_level/Rest5Client.java): `rest5-client/src/main/java/co/elastic/clients/transport/rest5_client/low_level/Rest5Client.java`
- [Netty transport](https://github.com/elastic/elasticsearch-java/blob/main/example-transports/src/main/java/co/elastic/clients/transport/netty/NettyElasticsearchTransport.java): `example-transports/src/main/java/co/elastic/clients/transport/netty/NettyElasticsearchTransport.java`

### JSON Mapping

- [JSON mapper](https://github.com/elastic/elasticsearch-java/blob/main/java-client/src/main/java/co/elastic/clients/json/JsonpMapper.java): `java-client/src/main/java/co/elastic/clients/json/JsonpMapper.java`
- [JSON deserializers](https://github.com/elastic/elasticsearch-java/blob/main/java-client/src/main/java/co/elastic/clients/json/JsonpDeserializer.java): `java-client/src/main/java/co/elastic/clients/json/JsonpDeserializer.java`
- [Object deserializer](https://github.com/elastic/elasticsearch-java/blob/main/java-client/src/main/java/co/elastic/clients/json/ObjectDeserializer.java): `java-client/src/main/java/co/elastic/clients/json/ObjectDeserializer.java`
- [Error responses](https://github.com/elastic/elasticsearch-java/blob/main/java-client/src/main/java/co/elastic/clients/elasticsearch/_types/ErrorResponse.java): `java-client/src/main/java/co/elastic/clients/elasticsearch/_types/ErrorResponse.java`

### Client Helpers

- [Bulk ingester](https://github.com/elastic/elasticsearch-java/blob/main/java-client/src/main/java/co/elastic/clients/elasticsearch/_helpers/bulk/BulkIngester.java): `java-client/src/main/java/co/elastic/clients/elasticsearch/_helpers/bulk/BulkIngester.java`
- [ESQL adapters](https://github.com/elastic/elasticsearch-java/tree/main/java-client/src/main/java/co/elastic/clients/elasticsearch/_helpers/esql): `java-client/src/main/java/co/elastic/clients/elasticsearch/_helpers/esql`
- [Vector helpers](https://github.com/elastic/elasticsearch-java/blob/main/java-client/src/main/java/co/elastic/clients/elasticsearch/_helpers/vector/AbstractBase64VectorDocument.java): `java-client/src/main/java/co/elastic/clients/elasticsearch/_helpers/vector/AbstractBase64VectorDocument.java`

### API Domains

- [Search and documents](https://github.com/elastic/elasticsearch-java/blob/main/java-client/src/main/java/co/elastic/clients/elasticsearch/ElasticsearchClient.java): `java-client/src/main/java/co/elastic/clients/elasticsearch/ElasticsearchClient.java`
- [Inference APIs](https://github.com/elastic/elasticsearch-java/blob/main/java-client/src/main/java/co/elastic/clients/elasticsearch/inference/ElasticsearchInferenceClient.java): `java-client/src/main/java/co/elastic/clients/elasticsearch/inference/ElasticsearchInferenceClient.java`
- [Ingest APIs](https://github.com/elastic/elasticsearch-java/blob/main/java-client/src/main/java/co/elastic/clients/elasticsearch/ingest/ElasticsearchIngestClient.java): `java-client/src/main/java/co/elastic/clients/elasticsearch/ingest/ElasticsearchIngestClient.java`
- [Query rules APIs](https://github.com/elastic/elasticsearch-java/blob/main/java-client/src/main/java/co/elastic/clients/elasticsearch/query_rules/ElasticsearchQueryRulesClient.java): `java-client/src/main/java/co/elastic/clients/elasticsearch/query_rules/ElasticsearchQueryRulesClient.java`
- [Other API clients](https://github.com/elastic/elasticsearch-java/tree/main/java-client/src/main/java/co/elastic/clients/elasticsearch): `java-client/src/main/java/co/elastic/clients/elasticsearch`

### Other components

- **Java application**
- **Elasticsearch**

## Connections

- Java application → Elasticsearch client: calls (evidence: `README.md`)
- Elasticsearch client → API client base: extends (evidence: `java-client/src/main/java/co/elastic/clients/elasticsearch/ElasticsearchClient.java`)
- Async client → API client base: extends
- API client base → Transport interface: uses (evidence: `java-client/src/main/java/co/elastic/clients/ApiClient.java`)
- Elasticsearch client → Request endpoints: dispatches
- Async client → Request endpoints: dispatches
- Transport interface → Elasticsearch: sends HTTP (evidence: `README.md`)
- Transport interface → REST transport: implemented by (evidence: `README.md`)
- Transport interface → Netty transport: implemented by
- Transport interface → JSON mapper: provides (evidence: `java-client/src/main/java/co/elastic/clients/transport/Transport.java`)
- JSON mapper → JSON deserializers: deserializes (evidence: `java-client/src/main/java/co/elastic/clients/json/JsonpDeserializer.java`)
- JSON deserializers → Object deserializer: supports (evidence: `java-client/src/main/java/co/elastic/clients/json/ObjectDeserializer.java`)
- Request endpoints → Typed API models: encodes requests
- Request endpoints → JSON mapper: defines decoding (evidence: `java-client/src/main/java/co/elastic/clients/transport/Endpoint.java`)
- Error responses → Typed API models: contains error (evidence: `java-client/src/main/java/co/elastic/clients/elasticsearch/_types/ErrorResponse.java`)
- Elasticsearch client → Search and documents: supports (evidence: `README.md`)
- Elasticsearch client → Inference APIs: supports
- Elasticsearch client → Ingest APIs: supports
- Elasticsearch client → Query rules APIs: supports
- Elasticsearch client → Other API clients: supports (evidence: `README.md`)
- Bulk ingester → Elasticsearch client: assists writes
- ESQL adapters → Elasticsearch client: adapts results
- Vector helpers → Elasticsearch client: supports vectors
