1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
|
---
navigation_title: "Python"
mapped_pages:
- https://www.elastic.co/guide/en/elasticsearch/client/python-api/current/index.html
- https://www.elastic.co/guide/en/elasticsearch/client/python-api/current/overview.html
---
# {{es}} Python client [overview]
This documentation covers the [official Python client for {{es}}](https://github.com/elastic/elasticsearch-py). The goal of the Python client is to provide common ground for all {{es}}-related code in Python. The client is designed to be unopinionated and extendable.
## Example [_example]
::::{tab-set}
:::{tab-item} Standard Python
```python
import os
from elasticsearch import Elasticsearch
def main():
client = Elasticsearch(
hosts=[os.getenv("ELASTICSEARCH_URL")],
api_key=os.getenv("ELASTIC_API_KEY"),
)
resp = client.search(
index="my-index-000001",
from_="40",
size="20",
query={
"term": {
"user.id": "kimchy"
}
},
)
print(resp)
```
:::
:::{tab-item} Async Python
```python
import os
from elasticsearch import AsyncElasticsearch
async def main():
client = AsyncElasticsearch(
hosts=[os.getenv("ELASTICSEARCH_URL")],
api_key=os.getenv("ELASTIC_API_KEY"),
)
resp = await client.search(
index="my-index-000001",
from_="40",
size="20",
query={
"term": {
"user.id": "kimchy"
}
},
)
print(resp)
```
:::
::::
## Overview [_overview]
This package is composed of several modules:
### The actual client
This module, sometimes also called the "low-level" client, implements the support for sending requests to {{es}} servers. The client provides access to the entire surface of the {{es}} API.
* [Getting Started guide](getting-started.md)
* [Ingest data with Python walkthrough](docs-content://manage-data/ingest/ingesting-data-from-applications/ingest-data-with-python-on-elasticsearch-service.md)
* [Reference documentation](https://elasticsearch-py.readthedocs.io/en/stable/es_api.html)
#### Features [_features]
The client's features include:
* Translating basic Python data types to and from JSON
* Configurable automatic discovery of cluster nodes
* Persistent connections
* Load balancing (with pluggable selection strategy) across all available nodes
* Node timeouts on transient errors
* Thread safety
* Pluggable architecture
### Bulk helpers
The bulk helpers are a set of functions that simplify the ingest of large amounts of data through a high-level interface based on Python iterables.
* [User guide](client-helpers.md#bulk-helpers)
* [Reference documentation](https://elasticsearch-py.readthedocs.io/en/stable/api_helpers.html)
### ES|QL query builder
This module offers an idiomatic interface to construct ES|QL queries using Python expressions.
* [User guide](esql-query-builder.md)
* [Reference documentation](https://elasticsearch-py.readthedocs.io/en/stable/esql.html)
### DSL module
The DSL module could be thought of as a "high-level" client for {{es}}. It allows applications to manipulate documents and queries using Python classes and objects instead of primitive types such as dictionaries and lists.
* [User guide](elasticsearch-dsl.md)
* [Reference documentation](https://elasticsearch-py.readthedocs.io/en/stable/dsl.html)
## Compatibility [_compatibility]
| Client version | {{es}} `8.x` | {{es}} `9.x` | {{es}} `10.x` |
|----------------|---------------------------------|---------------------------------|----------------------------------|
| 9.x client | ❌ Not compatible with {{es}} 8.x | ✅ Compatible with {{es}} 9.x | ✅ Compatible with {{es}} 10.x |
| 8.x client | ✅ Compatible with {{es}} 8.x | ✅ Compatible with {{es}} 9.x | ❌ Not compatible with {{es}} 10.x |
Compatibility does not imply feature parity. New {{es}} features are supported only in equivalent client versions. For example, an 8.12 client fully supports {{es}} 8.12 features and works with 8.13 without breaking, but it does not support new {{es}} 8.13 features. An 8.13 client fully supports {{es}} 8.13 features.
{{es}} language clients are also **backward compatible** across minor versions, with default distributions and without guarantees.
### Major version upgrades
:::{important}
To upgrade to a new major version, first [upgrade {{es}}](docs-content://deploy-manage/upgrade.md), then upgrade the Python client.
:::
As of version 8.0, {{es}} offers a [compatibility mode](elasticsearch://reference/elasticsearch/rest-apis/compatibility.md) for smoother upgrades. In compatibility mode, you can upgrade your {{es}} cluster to the next major version while continuing to use your existing client during the transition.
For example, if you're upgrading {{es}} from 8.x to 9.x, you can continue to use the 8.x Python client during and after the {{es}} server upgrade, with the exception of [breaking changes](../release-notes/breaking-changes.md).
In the Python client, compatibility mode is always enabled.
:::{tip}
To support working with multiple client versions, the Python client is also released under the package names `elasticsearch8` and `elasticsearch9` (to prevent name collisions).
:::
|
