0
# Elasticsearch Python Client
1

2
The official Python client for Elasticsearch, providing comprehensive access to Elasticsearch's REST APIs through both synchronous and asynchronous interfaces. The client handles connection management, request serialization, error handling, and response processing while maintaining compatibility with all Elasticsearch versions.
3

4
## Package Information
5

6
- **Package Name**: elasticsearch
7
- **Language**: Python
8
- **Installation**: `pip install elasticsearch`
9

10
## Core Imports
11

12
```python
13
from elasticsearch import Elasticsearch, AsyncElasticsearch
14
```
15

16
For exceptions and serializers:
17

18
```python
19
from elasticsearch import (
20
    ApiError,
21
    NotFoundError,
22
    ConflictError,
23
    AuthenticationException,
24
    JsonSerializer,
25
    OrjsonSerializer
26
)
27
```
28

29
For DSL (Domain Specific Language):
30

31
```python
32
from elasticsearch.dsl import Search, Q, A
33
```
34

35
For helper functions:
36

37
```python
38
from elasticsearch.helpers import bulk, scan
39
from elasticsearch.helpers.vectorstore import VectorStore, DenseVectorStrategy
40
```
41

42
For ES|QL query building:
43

44
```python
45
from elasticsearch.esql import ESQL, and_, or_, not_
46
```
47

48
## Basic Usage
49

50
### Synchronous Client
51

52
```python
53
from elasticsearch import Elasticsearch
54

55
# Connect to Elasticsearch
56
client = Elasticsearch(
57
    hosts=['http://localhost:9200'],
58
    http_auth=('username', 'password'),
59
    timeout=30
60
)
61

62
# Index a document
63
response = client.index(
64
    index="my-index",
65
    id=1,
66
    document={"title": "Test document", "content": "This is a test"}
67
)
68

69
# Search for documents
70
search_response = client.search(
71
    index="my-index",
72
    query={"match": {"title": "test"}}
73
)
74

75
# Get document by ID
76
doc = client.get(index="my-index", id=1)
77
```
78

79
### Asynchronous Client
80

81
```python
82
import asyncio
83
from elasticsearch import AsyncElasticsearch
84

85
async def main():
86
    # Connect to Elasticsearch asynchronously
87
    client = AsyncElasticsearch(
88
        hosts=['http://localhost:9200'],
89
        http_auth=('username', 'password')
90
    )
91
    
92
    # Index a document
93
    await client.index(
94
        index="my-index",
95
        id=1,
96
        document={"title": "Test document", "content": "This is a test"}
97
    )
98
    
99
    # Search for documents
100
    response = await client.search(
101
        index="my-index",
102
        query={"match": {"title": "test"}}
103
    )
104
    
105
    await client.close()
106

107
asyncio.run(main())
108
```
109

110
## Architecture
111

112
The Elasticsearch Python client is built on a layered architecture:
113

114
- **Transport Layer**: Handles HTTP connections, node discovery, and request routing
115
- **Client Layer**: Provides the main API interface with namespace organization
116
- **Serialization Layer**: Manages JSON encoding/decoding with pluggable serializers
117
- **DSL Layer**: Offers Pythonic query building and document modeling
118
- **Helper Layer**: Provides utilities for common operations like bulk indexing
119

120
Both synchronous and asynchronous clients share identical APIs, with async methods returning coroutines. The client automatically handles connection pooling, load balancing, node failure detection, and retry logic.
121

122
## Capabilities
123

124
### Client Operations
125

126
Core document and search operations including indexing, searching, updating, and deleting documents. Provides the fundamental operations for interacting with Elasticsearch clusters.
127

128
```python { .api }
129
class Elasticsearch:
130
    def __init__(self, hosts=None, **kwargs): ...
131
    def index(self, index, document, id=None, **kwargs): ...
132
    def get(self, index, id, **kwargs): ...
133
    def search(self, index=None, query=None, **kwargs): ...
134
    def update(self, index, id, document=None, script=None, **kwargs): ...
135
    def delete(self, index, id, **kwargs): ...
136
    def bulk(self, operations, index=None, **kwargs): ...
137
```
138

139
[Client Operations](./client-operations.md)
140

141
### Index Management
142

143
Index lifecycle operations including creation, deletion, mapping updates, settings configuration, and maintenance operations like refresh and flush.
144

145
```python { .api }
146
class IndicesClient:
147
    def create(self, index, mappings=None, settings=None, **kwargs): ...
148
    def delete(self, index, **kwargs): ...
149
    def get(self, index, **kwargs): ...
150
    def put_mapping(self, index, properties=None, **kwargs): ...
151
    def get_mapping(self, index=None, **kwargs): ...
152
    def put_settings(self, index, settings, **kwargs): ...
153
```
154

155
[Index Management](./index-management.md)
156

157
### Search Operations
158

159
Advanced search capabilities including query DSL, aggregations, highlighting, sorting, and specialized search types like async search and scroll.
160

161
```python { .api }
162
def search(self, index=None, query=None, aggs=None, sort=None, **kwargs): ...
163
def msearch(self, searches, index=None, **kwargs): ...
164
def scroll(self, scroll_id, scroll='5m', **kwargs): ...
165
def search_template(self, index=None, id=None, params=None, **kwargs): ...
166
```
167

168
[Search Operations](./search-operations.md)
169

170
### Cluster Management
171

172
Cluster-level operations for monitoring health, managing settings, shard allocation, and node management.
173

174
```python { .api }
175
class ClusterClient:
176
    def health(self, index=None, **kwargs): ...
177
    def state(self, index=None, metric=None, **kwargs): ...
178
    def stats(self, node_id=None, **kwargs): ...
179
    def put_settings(self, persistent=None, transient=None, **kwargs): ...
180
```
181

182
[Cluster Management](./cluster-management.md)
183

184
### Security and Authentication
185

186
User and role management, API key operations, token management, and security configuration for Elasticsearch clusters with security features enabled.
187

188
```python { .api }
189
class SecurityClient:
190
    def authenticate(self, **kwargs): ...
191
    def create_user(self, username, password, roles=None, **kwargs): ...
192
    def create_role(self, name, cluster=None, indices=None, **kwargs): ...
193
    def create_api_key(self, name, role_descriptors=None, **kwargs): ...
194
```
195

196
[Security Operations](./security-operations.md)
197

198
### Machine Learning
199

200
Machine learning job management, anomaly detection, data analysis, and model operations for Elasticsearch's ML capabilities.
201

202
```python { .api }
203
class MlClient:
204
    def put_job(self, job_id, analysis_config, data_description, **kwargs): ...
205
    def open_job(self, job_id, **kwargs): ...
206
    def put_datafeed(self, datafeed_id, indices, job_id, **kwargs): ...
207
    def start_datafeed(self, datafeed_id, **kwargs): ...
208
```
209

210
[Machine Learning](./machine-learning.md)
211

212
### Data Stream and Lifecycle Management
213

214
Index lifecycle management (ILM), snapshot lifecycle management (SLM), and data stream operations for automated data management.
215

216
```python { .api }
217
class IlmClient:
218
    def put_policy(self, name, policy, **kwargs): ...
219
    def get_policy(self, name=None, **kwargs): ...
220
    def explain_lifecycle(self, index, **kwargs): ...
221

222
class SlmClient:
223
    def put_policy(self, name, schedule, name_pattern, repository, **kwargs): ...
224
```
225

226
[Lifecycle Management](./lifecycle-management.md)
227

228
### Additional Namespace Clients
229

230
The Elasticsearch Python client includes many specialized namespace clients for advanced functionality:
231

232
**Text Analysis and Data Processing:**
233
- `client.connector` - Elasticsearch connector management for data ingestion
234
- `client.text_structure` - Text analysis and structure detection  
235
- `client.synonyms` - Synonyms management for search enhancement
236
- `client.query_rules` - Query rule management for search relevance tuning
237

238
**Fleet and Monitoring:**
239
- `client.fleet` - Elastic Agent fleet management for observability
240
- `client.monitoring` - Cluster and node monitoring operations
241
- `client.features` - Elasticsearch features and capabilities discovery
242

243
**Search Applications:**
244
- `client.search_application` - Search application management and configuration
245
- `client.eql` - Event Query Language for security and observability
246
- `client.sql` - SQL query interface for Elasticsearch
247

248
**Data Management:**
249
- `client.transform` - Data transformation and pivot operations
250
- `client.rollup` - Historical data rollup and aggregation
251
- `client.ccr` - Cross-cluster replication management
252
- `client.enrich` - Document enrichment with lookup data
253

254
**Administrative:**
255
- `client.license` - License management and validation
256
- `client.ssl` - SSL certificate management
257
- `client.shutdown` - Node shutdown coordination
258
- `client.migration` - Cluster migration assistance
259

260
**Advanced Features:**
261
- `client.graph` - Graph analytics and exploration
262
- `client.watcher` - Alerting and notification system
263
- `client.autoscaling` - Automatic scaling policies
264
- `client.searchable_snapshots` - Snapshot-based cold storage
265

266
### Helper Functions
267

268
Utility functions for common operations like bulk indexing, scanning large result sets, and reindexing data between indices.
269

270
```python { .api }
271
def bulk(client, actions, **kwargs): ...
272
def scan(client, query=None, scroll='5m', **kwargs): ...
273
def reindex(client, source_index, target_index, **kwargs): ...
274
```
275

276
[Helper Functions](./helper-functions.md)
277

278
### Query DSL
279

280
Pythonic query building with the Domain Specific Language for constructing complex Elasticsearch queries, aggregations, and document modeling.
281

282
```python { .api }
283
class Search:
284
    def __init__(self, using=None, index=None, **kwargs): ...
285
    def query(self, q): ...
286
    def filter(self, f): ...
287
    def aggregate(self, name, agg): ...
288
    def sort(self, *keys): ...
289

290
class Q:
291
    @classmethod
292
    def match(cls, **kwargs): ...
293
    @classmethod
294
    def term(cls, **kwargs): ...
295
    @classmethod
296
    def range(cls, **kwargs): ...
297
```
298

299
[Query DSL](./query-dsl.md)
300

301
### ES|QL Operations
302

303
Execute Elasticsearch Query Language (ES|QL) queries with both synchronous and asynchronous support, providing SQL-like syntax for data analysis and reporting.
304

305
```python { .api }
306
class EsqlClient:
307
    def query(self, query: str, **kwargs): ...
308
    def async_query(self, query: str, keep_alive: str, **kwargs): ...
309
    def async_query_get(self, id: str, **kwargs): ...
310
    def async_query_delete(self, id: str, **kwargs): ...
311
    def list_queries(self, **kwargs): ...
312
```
313

314
[ES|QL Operations](./esql-operations.md)
315

316
### Inference API
317

318
Machine learning inference operations supporting multiple AI service providers for text embeddings, completions, reranking, and sparse embeddings.
319

320
```python { .api }
321
class InferenceClient:
322
    def inference(self, inference_id: str, input: Union[str, List[str]], **kwargs): ...
323
    def text_embedding(self, inference_id: str, input: Union[str, List[str]], **kwargs): ...
324
    def sparse_embedding(self, inference_id: str, input: Union[str, List[str]], **kwargs): ...
325
    def rerank(self, inference_id: str, query: str, input: List[str], **kwargs): ...
326
    def completion(self, inference_id: str, input: Union[str, List[str]], **kwargs): ...
327
    def put_openai(self, inference_id: str, task_type: str, **kwargs): ...
328
    def put_hugging_face(self, inference_id: str, task_type: str, **kwargs): ...
329
    def put_cohere(self, inference_id: str, task_type: str, **kwargs): ...
330
```
331

332
[Inference API](./inference-api.md)
333

334
### Vectorstore Helpers
335

336
High-level abstractions for building vector search applications with pluggable retrieval strategies, embedding services, and support for semantic search patterns.
337

338
```python { .api }
339
class VectorStore:
340
    def __init__(self, client: Elasticsearch, index: str, retrieval_strategy: RetrievalStrategy, **kwargs): ...
341
    def add_documents(self, documents: List[Dict], vectors: Optional[List[List[float]]] = None, **kwargs): ...
342
    def search(self, query: Optional[str] = None, query_vector: Optional[List[float]] = None, **kwargs): ...
343
    def max_marginal_relevance_search(self, query: str, k: int = 4, **kwargs): ...
344

345
class DenseVectorStrategy(RetrievalStrategy): ...
346
class SparseVectorStrategy(RetrievalStrategy): ...
347
class BM25Strategy(RetrievalStrategy): ...
348
class ElasticsearchEmbeddings(EmbeddingService): ...
349
```
350

351
[Vectorstore Helpers](./vectorstore-helpers.md)
352

353
### Exception Handling
354

355
Comprehensive exception hierarchy for handling various error conditions including HTTP errors, connection issues, and authentication failures.
356

357
```python { .api }
358
class ApiError(Exception): ...
359
class NotFoundError(ApiError): ...
360
class ConflictError(ApiError): ...
361
class AuthenticationException(ApiError): ...
362
class ConnectionError(Exception): ...
363
class SerializationError(Exception): ...
364
```
365

366
[Exception Handling](./exception-handling.md)
367

368
## Types
369

370
```python { .api }
371
from typing import Any, Dict, List, Optional, Union
372

373
# Common type aliases
374
Document = Dict[str, Any]
375
Query = Dict[str, Any]
376
Mapping = Dict[str, Any]
377
Settings = Dict[str, Any]
378
Headers = Dict[str, str]
379
Hosts = Union[str, List[str], List[Dict[str, Any]]]
380

381
# Response types
382
class ObjectApiResponse:
383
    def __init__(self, body: Any, meta: Any): ...
384
    @property
385
    def body(self) -> Any: ...
386
    @property
387
    def meta(self) -> Any: ...
388

389
class ApiResponse:
390
    @property
391
    def status_code(self) -> int: ...
392
    @property
393
    def headers(self) -> Dict[str, str]: ...
394
```