学习python库：elasticsearch-py

1、介绍

elasticsearch-py是一个官方提供的low-level的elasticsearch python客户端库。为何说它是一个low-level的客户端库呢？由于它只是对elasticsearch的rest API接口作了一层简单的封装，所以提供了最大的灵活性，可是于此同时使用起来就不是太方便。相对于这个low-level的客户端库，官方还提供了一个high-level的python客户端库：elasticsearch-dsl，这个会在另外一篇文章中介绍。

更多介绍参见官方文档：https://elasticsearch-py.readthedocs.io/en/master/

2、安装

不一样的elasticsearch版本要求不一样的客户端版本，因此安装的时候须要根据你的elasticsearch来决定，下面是一个简单的参考：

# Elasticsearch 6.x
elasticsearch>=6.0.0,<7.0.0
# Elasticsearch 5.x
elasticsearch>=5.0.0,<6.0.0
# Elasticsearch 2.x
elasticsearch>=2.0.0,<3.0.0

在兼容的大的版本号下尽可能选择最新的版本。

 pip install elasticsearch 

3、API

3.1 API文档

全部API都尽量紧密的映射原始的rest API。

3.1.1 全局选项

某些被客户端添加的参数可使用在全部的API上。

1.ignore

被用户忽略某些http错误状态码。

from elasticsearch import Elasticsearch
es = Elasticsearch()

# ignore 400 cause by IndexAlreadyExistsException when creating an index
es.indices.create(index='test-index', ignore=400)

# ignore 404 and 400
es.indices.delete(index='test-index', ignore=[400, 404])

2.timeout

被用于设置超时时间。

# only wait for 1 second, regardless of the client's default
es.cluster.health(wait_for_status='yellow', request_timeout=1)

3.filter_path

被用于过滤返回值。

es.search(index='test-index', filter_path=['hits.hits._id', 'hits.hits._type'])

3.1.2 Elasticsearch

Elasticsearch是一个low-level客户端，提供了一个从python到es rest端点的直接映射。这个实例拥有属性cat、cluster、indices、ingest、nodes、snapshot和tasks，经过他们能够访问CatClient、ClusterClient、IndicesClient、IngestClient、NodesClient、SnapshotClient和TasksClient的实例。

elasticsearch类包含了操做elasticsearch许多经常使用方法，例如：get、mget、search、index、bulk、create、delete等，这些方法的具体用法，能够参考elasticsearch-py的官方文档。

在执行以上方法以前，首先须要得到一个elasticsearch的实例，而获取这个实例有两个方法，一个是给elasticsearch的初始化函数传递一个connection class实例，另外一个是给elasticsearch的初始化函数传递要链接的node的host和port，其实最终这些host、port仍是被传递给了connection class。

# create connection to localhost using the ThriftConnection
es = Elasticsearch(connection_class=ThriftConnection)

# connect to localhost directly and another node using SSL on port 443
# and an url_prefix. Note that ``port`` needs to be an int.
es = Elasticsearch([
    {'host': 'localhost'},
    {'host': 'othernode', 'port': 443, 'url_prefix': 'es', 'use_ssl': True},
])

3.1.3 Indices

indices用于操做、查询关于索引的信息，或者能够说是操做、查询索引相关的元数据。

3.1.4 Ingest

ingest是一个插件，用于丰富插入数据的插入。

3.1.5 Cluster

cluster用于获取和集群相关的信息，例如：集群的健康状态、settings等。

3.1.6 Nodes

nodes用于获取和节点相关的信息。

3.1.7 Cat

 cat能够用来获取别名、分片信息、文档数量等信息。

3.1.8 Snapshot

snapshot用于管理快照。

3.1.9 Tasks

tasks是用于任务管理的，官方文档上提示该task是新特性，将来可能会改变，因此要注意。

3.2 X-Pack APIs

X-Pack是Elastic Stack扩展，它将安全性，警报，监视，报告和图形功能捆绑到一个易于安装的程序包中。

3.2.1 Info

3.2.2 Graph Explore

3.3.3 Licensing API

3.3.4 Machine Learning

3.3.5 Security APIS

3.3.6 Watcher APIS

3.3.7 Migration APIS

3.3 异常

这一节展现了使用elasticsearch-py时可能抛出的异常。

3.4 链接层API

connection是负责与集群链接的类。

3.4.1 Transport

transport封装与逻辑相关的传输。处理各个链接的实例化，并建立一个链接池来保存它们。

3.4.2 Connection Pool

connection pool是一个链接池，用于管理链接。

3.4.3 Connection Selector 

connection selector是一个链接选择器，它最好的一个例子是zone-aware选择，能够自动选择本地链接，只有当本地node都没法链接是才会去选择链接其余node。

3.4.4 Urllib3HttpConnection

默认connection class。

3.5 传输类

传输模块列出了能够被当作elasticsearch初始化参数connection_class的connection class。

3.5.1 Connection

connection负责管理与elasticsearch节点的链接。

3.5.2 Urllib3HttpConnection

基于urllib的connection class，是默认connection class。

3.5.3 RequestsHttpConnection

基于requests的connection class，除非要使用requests相关的高级特性，不然建议不要使用该类。

3.6 helpers

helpers是一个简单的辅助函数的集合，这些函数抽象了一些细节或原始API。

3.6.1 bulk helpers

bulk API的特定格式要求致使直接使用它们会很是复杂，所以这里提供了几个bulk API的helper函数，具体使用方法能够参考elasticsearch-py的官方文档。

3.6.2 scan

scan是对scroll API的简单抽象。

3.6.3 reindex

reindex用于将可能知足给定查询的一个索引中的全部文档从新索引到另外一个索引