[7.x] Migrate Python documentation to elasticsearch-py
Backport of PR #62710
This commit is contained in:
Seth Michael Larson
GitHub
parent
1f612cccbb
commit
ae24dfc4f0
|
|
@ -1,135 +0,0 @@
|
|||
= elasticsearch-py
|
||||
|
||||
== Overview
|
||||
|
||||
Official low-level client for Elasticsearch. Its goal is to provide common
|
||||
ground for all Elasticsearch-related code in Python; because of this it tries
|
||||
to be opinion-free and very extendable. The full documentation is available at
|
||||
https://elasticsearch-py.readthedocs.org/
|
||||
|
||||
.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.
|
||||
************************************************************************************
|
||||
|
||||
|
||||
=== Installation
|
||||
|
||||
It can be installed with pip:
|
||||
|
||||
[source,sh]
|
||||
------------------------------------
|
||||
pip install elasticsearch
|
||||
------------------------------------
|
||||
|
||||
The legacy version for Elasticsearch version 2.x can be installed with pip:
|
||||
|
||||
[source,sh]
|
||||
------------------------------------
|
||||
pip install elasticsearch2
|
||||
------------------------------------
|
||||
|
||||
=== Versioning
|
||||
|
||||
Current development happens in the master branch.
|
||||
|
||||
The master branch is the only branch under current development and
|
||||
is used to track all the changes for Elasticsearch 5.x and beyond.
|
||||
|
||||
Elasticsearch version 2.x is not longer under active development.
|
||||
We will only backport severe bug fixes.
|
||||
|
||||
The recommended way to set your requirements in your `setup.py` or
|
||||
`requirements.txt` is:
|
||||
|
||||
[source,txt]
|
||||
------------------------------------
|
||||
# Elasticsearch 6.x
|
||||
elasticsearch>=6.0.0,<7.0.0
|
||||
|
||||
# Elasticsearch 2.x
|
||||
elasticsearch2
|
||||
------------------------------------
|
||||
|
||||
=== Example use
|
||||
|
||||
Simple use-case:
|
||||
|
||||
[source,python]
|
||||
------------------------------------
|
||||
>>> from datetime import datetime
|
||||
>>> from elasticsearch import Elasticsearch
|
||||
|
||||
# by default we connect to localhost:9200
|
||||
>>> es = Elasticsearch()
|
||||
|
||||
# datetimes will be serialized
|
||||
>>> es.index(index="my-index-000001", doc_type="test-type", id=42, body={"any": "data", "timestamp": datetime.now()})
|
||||
{u'_id': u'42', u'_index': u'my-index-000001', u'_type': u'test-type', u'_version': 1, u'ok': True}
|
||||
|
||||
# but not deserialized
|
||||
>>> es.get(index="my-index-000001", doc_type="test-type", id=42)['_source']
|
||||
{u'any': u'data', u'timestamp': u'2013-05-12T19:45:31.804229'}
|
||||
------------------------------------
|
||||
|
||||
[NOTE]
|
||||
All the API calls map the raw REST api as closely as possible, including
|
||||
the distinction between required and optional arguments to the calls. This
|
||||
means that the code makes distinction between positional and keyword arguments;
|
||||
we, however, recommend that people use keyword arguments for all calls for
|
||||
consistency and safety.
|
||||
|
||||
=== Features
|
||||
|
||||
The client's features include:
|
||||
|
||||
* translating basic Python data types to and from json (datetimes are not
|
||||
decoded for performance reasons)
|
||||
|
||||
* configurable automatic discovery of cluster nodes
|
||||
|
||||
* persistent connections
|
||||
|
||||
* load balancing (with pluggable selection strategy) across all available nodes
|
||||
|
||||
* failed connection penalization (time based - failed connections won't be
|
||||
retried until a timeout is reached)
|
||||
|
||||
* 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.
|
||||
|
||||
|
||||
=== License
|
||||
|
||||
Copyright 2013-2018 Elasticsearch
|
||||
|
||||
Licensed under the Apache License, Version 2.0 (the "License");
|
||||
you may not use this file except in compliance with the License.
|
||||
You may obtain a copy of the License at
|
||||
|
||||
https://www.apache.org/licenses/LICENSE-2.0
|
||||
|
||||
Unless required by applicable law or agreed to in writing, software
|
||||
distributed under the License is distributed on an "AS IS" BASIS,
|
||||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
See the License for the specific language governing permissions and
|
||||
limitations under the License.
|
||||
Loading…
Reference in New Issue