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
|
[[overview]]
== Overview
This is the official low-level Python client for {es}. Its goal is to provide
common ground for all {es}-related code in Python. For this reason, the client
is designed to be unopinionated and extendable. An API reference is available
on https://elasticsearch-py.readthedocs.io[Read the Docs].
[discrete]
=== Compatibility
Language clients are forward compatible; meaning that the clients support
communicating with greater or equal minor versions of {es} without breaking. It
does not mean that the clients automatically support new features of newer
{es} versions; it is only possible after a release of a new client version. For
example, a 8.12 client version won't automatically support the new features of
the 8.13 version of {es}, the 8.13 client version is required for that. {es}
language clients are only backwards compatible with default distributions and
without guarantees made.
|===
| Elasticsearch version | elasticsearch-py branch | Supported
| main | main |
| 8.x | 8.x | 8.x
| 7.x | 7.x | 7.17
|===
If you have a need to have multiple versions installed at the same time older
versions are also released as `elasticsearch7` and `elasticsearch8`.
[discrete]
=== Example use
Simple use-case:
[source,python]
------------------------------------
>>> from datetime import datetime
>>> from elasticsearch import Elasticsearch
# Connect to 'http://localhost:9200'
>>> client = Elasticsearch("http://localhost:9200")
# Datetimes will be serialized:
>>> client.index(index="my-index-000001", id=42, document={"any": "data", "timestamp": datetime.now()})
{'_id': '42', '_index': 'my-index-000001', '_type': 'test-type', '_version': 1, 'ok': True}
# ...but not deserialized
>>> client.get(index="my-index-000001", id=42)['_source']
{'any': 'data', 'timestamp': '2013-05-12T19:45:31.804229'}
------------------------------------
TIP: For an elaborate example of how to ingest data into Elastic Cloud,
refer to {cloud}/ec-getting-started-python.html[this page].
[discrete]
=== 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
The client also contains a convenient set of
https://elasticsearch-py.readthedocs.org/en/master/helpers.html[helpers] for
some of the more engaging tasks like bulk indexing and reindexing.
[discrete]
=== Elasticsearch DSL
For a more high level client library with more limited scope, have a look at
https://elasticsearch-dsl.readthedocs.org/[elasticsearch-dsl] - a more Pythonic library
sitting on top of `elasticsearch-py`.
It provides a more convenient and idiomatic way to write and manipulate
https://elasticsearch-dsl.readthedocs.org/en/latest/search_dsl.html[queries]. It
stays close to the Elasticsearch JSON DSL, mirroring its terminology and
structure while exposing the whole range of the DSL from Python either directly
using defined classes or a queryset-like expressions.
It also provides an optional
https://elasticsearch-dsl.readthedocs.org/en/latest/persistence.html#doctype[persistence
layer] for working with documents as Python objects in an ORM-like fashion:
defining mappings, retrieving and saving documents, wrapping the document data
in user-defined classes.
|
