|
1 | 1 | = elasticsearch-py
|
2 | 2 |
|
3 |
| -== Overview |
| 3 | +:doctype: book |
4 | 4 |
|
5 |
| -Official low-level client for Elasticsearch. Its goal is to provide common |
6 |
| -ground for all Elasticsearch-related code in Python; because of this it tries |
7 |
| -to be opinion-free and very extendable. The full documentation is available at |
8 |
| -https://elasticsearch-py.readthedocs.io |
| 5 | +include::{asciidoc-dir}/../../shared/attributes.asciidoc[] |
9 | 6 |
|
10 |
| -=== Installation |
| 7 | +include::overview.asciidoc[] |
11 | 8 |
|
12 |
| -It can be installed with pip: |
13 |
| - |
14 |
| -[source,sh] |
15 |
| -------------------------------------- |
16 |
| -$ python -m pip install elasticsearch |
17 |
| -------------------------------------- |
18 |
| - |
19 |
| -If your application uses async/await in Python you can install with |
20 |
| -the `async` extra: |
21 |
| - |
22 |
| -[source,sh] |
23 |
| --------------------------------------------- |
24 |
| -$ python -m pip install elasticsearch[async] |
25 |
| --------------------------------------------- |
26 |
| - |
27 |
| -Read more about https://elasticsearch-py.readthedocs.io/en/master/async.html[how to use asyncio with this project]. |
28 |
| - |
29 |
| - |
30 |
| -=== Compatibility |
31 |
| - |
32 |
| -Current development happens in the master branch. |
33 |
| - |
34 |
| -The library is compatible with all Elasticsearch versions since `0.90.x` but you |
35 |
| -**have to use a matching major version**: |
36 |
| - |
37 |
| -For **Elasticsearch 7.0** and later, use the major version 7 (`7.x.y`) of the |
38 |
| -library. |
39 |
| - |
40 |
| -For **Elasticsearch 6.0** and later, use the major version 6 (``6.x.y`) of the |
41 |
| -library. |
42 |
| - |
43 |
| -For **Elasticsearch 5.0** and later, use the major version 5 (`5.x.y`) of the |
44 |
| -library. |
45 |
| - |
46 |
| -For **Elasticsearch 2.0** and later, use the major version 2 (`2.x.y`) of the |
47 |
| -library, and so on. |
48 |
| - |
49 |
| -The recommended way to set your requirements in your `setup.py` or |
50 |
| -`requirements.txt` is:: |
51 |
| - |
52 |
| - # Elasticsearch 7.x |
53 |
| - elasticsearch>=7,<8 |
54 |
| - |
55 |
| - # Elasticsearch 6.x |
56 |
| - elasticsearch>=6,<7 |
57 |
| - |
58 |
| - # Elasticsearch 5.x |
59 |
| - elasticsearch>=5,<6 |
60 |
| - |
61 |
| - # Elasticsearch 2.x |
62 |
| - elasticsearch>=2,<3 |
63 |
| - |
64 |
| -If you have a need to have multiple versions installed at the same time older |
65 |
| -versions are also released as ``elasticsearch2`` and ``elasticsearch5``. |
66 |
| - |
67 |
| -=== Example use |
68 |
| - |
69 |
| -Simple use-case: |
70 |
| - |
71 |
| -[source,python] |
72 |
| ------------------------------------- |
73 |
| ->>> from datetime import datetime |
74 |
| ->>> from elasticsearch import Elasticsearch |
75 |
| -
|
76 |
| -# By default we connect to localhost:9200 |
77 |
| ->>> es = Elasticsearch() |
78 |
| -
|
79 |
| -# Datetimes will be serialized... |
80 |
| ->>> es.index(index="my-index-000001", doc_type="test-type", id=42, body={"any": "data", "timestamp": datetime.now()}) |
81 |
| -{'_id': '42', '_index': 'my-index-000001', '_type': 'test-type', '_version': 1, 'ok': True} |
82 |
| -
|
83 |
| -# ...but not deserialized |
84 |
| ->>> es.get(index="my-index-000001", doc_type="test-type", id=42)['_source'] |
85 |
| -{'any': 'data', 'timestamp': '2013-05-12T19:45:31.804229'} |
86 |
| ------------------------------------- |
87 |
| - |
88 |
| -[NOTE] |
89 |
| -All the API calls map the raw REST API as closely as possible, including |
90 |
| -the distinction between required and optional arguments to the calls. This |
91 |
| -means that the code makes distinction between positional and keyword arguments; |
92 |
| -we, however, recommend that people use keyword arguments for all calls for |
93 |
| -consistency and safety. |
94 |
| - |
95 |
| -=== Features |
96 |
| - |
97 |
| -The client's features include: |
98 |
| - |
99 |
| -* Translating basic Python data types to and from JSON |
100 |
| - |
101 |
| -* Configurable automatic discovery of cluster nodes |
102 |
| - |
103 |
| -* Persistent connections |
104 |
| - |
105 |
| -* Load balancing (with pluggable selection strategy) across all available nodes |
106 |
| - |
107 |
| -* Failed connection penalization (time based - failed connections won't be |
108 |
| - retried until a timeout is reached) |
109 |
| - |
110 |
| -* Thread safety |
111 |
| - |
112 |
| -* Pluggable architecture |
113 |
| - |
114 |
| -The client also contains a convenient set of |
115 |
| -https://elasticsearch-py.readthedocs.org/en/master/helpers.html[helpers] for |
116 |
| -some of the more engaging tasks like bulk indexing and reindexing. |
117 |
| - |
118 |
| - |
119 |
| -=== Elasticsearch DSL |
120 |
| - |
121 |
| -For a more high level client library with more limited scope, have a look at |
122 |
| -https://elasticsearch-dsl.readthedocs.org/[elasticsearch-dsl] - a more Pythonic library |
123 |
| -sitting on top of `elasticsearch-py`. |
124 |
| - |
125 |
| -It provides a more convenient and idiomatic way to write and manipulate |
126 |
| -https://elasticsearch-dsl.readthedocs.org/en/latest/search_dsl.html[queries]. It |
127 |
| -stays close to the Elasticsearch JSON DSL, mirroring its terminology and |
128 |
| -structure while exposing the whole range of the DSL from Python either directly |
129 |
| -using defined classes or a queryset-like expressions. |
130 |
| - |
131 |
| -It also provides an optional |
132 |
| -https://elasticsearch-dsl.readthedocs.org/en/latest/persistence.html#doctype[persistence |
133 |
| -layer] for working with documents as Python objects in an ORM-like fashion: |
134 |
| -defining mappings, retrieving and saving documents, wrapping the document data |
135 |
| -in user-defined classes. |
136 |
| - |
137 |
| - |
138 |
| -=== License |
139 |
| - |
140 |
| -Licensed to Elasticsearch B.V. under one or more contributor |
141 |
| -license agreements. See the NOTICE file distributed with |
142 |
| -this work for additional information regarding copyright |
143 |
| -ownership. Elasticsearch B.V. licenses this file to you under |
144 |
| -the Apache License, Version 2.0 (the "License"); you may |
145 |
| -not use this file except in compliance with the License. |
146 |
| -You may obtain a copy of the License at |
147 |
| - |
148 |
| -http://www.apache.org/licenses/LICENSE-2.0 |
149 |
| - |
150 |
| -Unless required by applicable law or agreed to in writing, |
151 |
| -software distributed under the License is distributed on an |
152 |
| -"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
153 |
| -KIND, either express or implied. See the License for the |
154 |
| -specific language governing permissions and limitations |
155 |
| -under the License. |
| 9 | +include::installation.asciidoc[] |
0 commit comments