README
1Python Elasticsearch Client
2===========================
3
4Official low-level client for Elasticsearch. Its goal is to provide common
5ground for all Elasticsearch-related code in Python; because of this it tries
6to be opinion-free and very extendable.
7
8For a more high level client library with more limited scope, have a look at
9`elasticsearch-dsl`_ - a more pythonic library sitting on top of
10``elasticsearch-py``.
11
12It provides a more convenient and idiomatic way to write and manipulate
13`queries`_. It stays close to the Elasticsearch JSON DSL, mirroring its
14terminology and structure while exposing the whole range of the DSL from Python
15either directly using defined classes or a queryset-like expressions.
16
17It also provides an optional `persistence layer`_ for working with documents as
18Python objects in an ORM-like fashion: defining mappings, retrieving and saving
19documents, wrapping the document data in user-defined classes.
20
21.. _elasticsearch-dsl: https://elasticsearch-dsl.readthedocs.io/
22.. _queries: https://elasticsearch-dsl.readthedocs.io/en/latest/search_dsl.html
23.. _persistence layer: https://elasticsearch-dsl.readthedocs.io/en/latest/persistence.html#doctype
24
25Compatibility
26-------------
27
28The library is compatible with all Elasticsearch versions since ``0.90.x`` but you
29**have to use a matching major version**:
30
31For **Elasticsearch 5.0** and later, use the major version 5 (``5.x.y``) of the
32library.
33
34For **Elasticsearch 2.0** and later, use the major version 2 (``2.x.y``) of the
35library.
36
37For **Elasticsearch 1.0** and later, use the major version 1 (``1.x.y``) of the
38library.
39
40For **Elasticsearch 0.90.x**, use a version from ``0.4.x`` releases of the
41library.
42
43The recommended way to set your requirements in your `setup.py` or
44`requirements.txt` is::
45
46 # Elasticsearch 5.x
47 elasticsearch>=5.0.0,<6.0.0
48
49 # Elasticsearch 2.x
50 elasticsearch>=2.0.0,<3.0.0
51
52 # Elasticsearch 1.x
53 elasticsearch>=1.0.0,<2.0.0
54
55 # Elasticsearch 0.90.x
56 elasticsearch<1.0.0
57
58The development is happening on ``master`` and ``2.x`` branches respectively.
59
60Installation
61------------
62
63Install the ``elasticsearch`` package with `pip
64<https://pypi.python.org/pypi/elasticsearch>`_::
65
66 pip install elasticsearch
67
68
69Example use
70-----------
71
72Simple use-case::
73
74 >>> from datetime import datetime
75 >>> from elasticsearch import Elasticsearch
76
77 # by default we connect to localhost:9200
78 >>> es = Elasticsearch()
79
80 # create an index in elasticsearch, ignore status code 400 (index already exists)
81 >>> es.indices.create(index='my-index', ignore=400)
82 {u'acknowledged': True}
83
84 # datetimes will be serialized
85 >>> es.index(index="my-index", doc_type="test-type", id=42, body={"any": "data", "timestamp": datetime.now()})
86 {u'_id': u'42', u'_index': u'my-index', u'_type': u'test-type', u'_version': 1, u'ok': True}
87
88 # but not deserialized
89 >>> es.get(index="my-index", doc_type="test-type", id=42)['_source']
90 {u'any': u'data', u'timestamp': u'2013-05-12T19:45:31.804229'}
91
92`Full documentation`_.
93
94.. _Full documentation: https://elasticsearch-py.readthedocs.io/
95
96
97Features
98--------
99
100The client's features include:
101
102 * translating basic Python data types to and from json (datetimes are not
103 decoded for performance reasons)
104 * configurable automatic discovery of cluster nodes
105 * persistent connections
106 * load balancing (with pluggable selection strategy) across all available nodes
107 * failed connection penalization (time based - failed connections won't be
108 retried until a timeout is reached)
109 * support for ssl and http authentication
110 * thread safety
111 * pluggable architecture
112
113
114License
115-------
116
117Copyright 2017 Elasticsearch
118
119Licensed under the Apache License, Version 2.0 (the "License");
120you may not use this file except in compliance with the License.
121You may obtain a copy of the License at
122
123 http://www.apache.org/licenses/LICENSE-2.0
124
125Unless required by applicable law or agreed to in writing, software
126distributed under the License is distributed on an "AS IS" BASIS,
127WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
128See the License for the specific language governing permissions and
129limitations under the License.
130
131Build status
132------------
133
134.. image:: https://secure.travis-ci.org/elastic/elasticsearch-py.png
135 :target: http://travis-ci.org/#!/elastic/elasticsearch-py
136
README.rst
1Python Elasticsearch Client
2===========================
3
4Official low-level client for Elasticsearch. Its goal is to provide common
5ground for all Elasticsearch-related code in Python; because of this it tries
6to be opinion-free and very extendable.
7
8For a more high level client library with more limited scope, have a look at
9`elasticsearch-dsl`_ - a more pythonic library sitting on top of
10``elasticsearch-py``.
11
12It provides a more convenient and idiomatic way to write and manipulate
13`queries`_. It stays close to the Elasticsearch JSON DSL, mirroring its
14terminology and structure while exposing the whole range of the DSL from Python
15either directly using defined classes or a queryset-like expressions.
16
17It also provides an optional `persistence layer`_ for working with documents as
18Python objects in an ORM-like fashion: defining mappings, retrieving and saving
19documents, wrapping the document data in user-defined classes.
20
21.. _elasticsearch-dsl: https://elasticsearch-dsl.readthedocs.io/
22.. _queries: https://elasticsearch-dsl.readthedocs.io/en/latest/search_dsl.html
23.. _persistence layer: https://elasticsearch-dsl.readthedocs.io/en/latest/persistence.html#doctype
24
25Compatibility
26-------------
27
28The library is compatible with all Elasticsearch versions since ``0.90.x`` but you
29**have to use a matching major version**:
30
31For **Elasticsearch 5.0** and later, use the major version 5 (``5.x.y``) of the
32library.
33
34For **Elasticsearch 2.0** and later, use the major version 2 (``2.x.y``) of the
35library.
36
37For **Elasticsearch 1.0** and later, use the major version 1 (``1.x.y``) of the
38library.
39
40For **Elasticsearch 0.90.x**, use a version from ``0.4.x`` releases of the
41library.
42
43The recommended way to set your requirements in your `setup.py` or
44`requirements.txt` is::
45
46 # Elasticsearch 5.x
47 elasticsearch>=5.0.0,<6.0.0
48
49 # Elasticsearch 2.x
50 elasticsearch>=2.0.0,<3.0.0
51
52 # Elasticsearch 1.x
53 elasticsearch>=1.0.0,<2.0.0
54
55 # Elasticsearch 0.90.x
56 elasticsearch<1.0.0
57
58The development is happening on ``master`` and ``2.x`` branches respectively.
59
60Installation
61------------
62
63Install the ``elasticsearch`` package with `pip
64<https://pypi.python.org/pypi/elasticsearch>`_::
65
66 pip install elasticsearch
67
68
69Example use
70-----------
71
72Simple use-case::
73
74 >>> from datetime import datetime
75 >>> from elasticsearch import Elasticsearch
76
77 # by default we connect to localhost:9200
78 >>> es = Elasticsearch()
79
80 # create an index in elasticsearch, ignore status code 400 (index already exists)
81 >>> es.indices.create(index='my-index', ignore=400)
82 {u'acknowledged': True}
83
84 # datetimes will be serialized
85 >>> es.index(index="my-index", doc_type="test-type", id=42, body={"any": "data", "timestamp": datetime.now()})
86 {u'_id': u'42', u'_index': u'my-index', u'_type': u'test-type', u'_version': 1, u'ok': True}
87
88 # but not deserialized
89 >>> es.get(index="my-index", doc_type="test-type", id=42)['_source']
90 {u'any': u'data', u'timestamp': u'2013-05-12T19:45:31.804229'}
91
92`Full documentation`_.
93
94.. _Full documentation: https://elasticsearch-py.readthedocs.io/
95
96
97Features
98--------
99
100The client's features include:
101
102 * translating basic Python data types to and from json (datetimes are not
103 decoded for performance reasons)
104 * configurable automatic discovery of cluster nodes
105 * persistent connections
106 * load balancing (with pluggable selection strategy) across all available nodes
107 * failed connection penalization (time based - failed connections won't be
108 retried until a timeout is reached)
109 * support for ssl and http authentication
110 * thread safety
111 * pluggable architecture
112
113
114License
115-------
116
117Copyright 2017 Elasticsearch
118
119Licensed under the Apache License, Version 2.0 (the "License");
120you may not use this file except in compliance with the License.
121You may obtain a copy of the License at
122
123 http://www.apache.org/licenses/LICENSE-2.0
124
125Unless required by applicable law or agreed to in writing, software
126distributed under the License is distributed on an "AS IS" BASIS,
127WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
128See the License for the specific language governing permissions and
129limitations under the License.
130
131Build status
132------------
133
134.. image:: https://secure.travis-ci.org/elastic/elasticsearch-py.png
135 :target: http://travis-ci.org/#!/elastic/elasticsearch-py
136
