学习python库：elasticsearch-py

一、介绍

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/

二、安装

不同的elasticsearch版本要求不同的客户端版本，所以安装的时候需要根据你的elasticsearch来决定，下面是一个简单的参考：

# Elasticsearch .x
elasticsearch>=6.0.,<7.0.
# Elasticsearch .x
elasticsearch>=5.0.,<6.0.
# Elasticsearch .x
elasticsearch>=2.0.,<3.0.

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

pip install elasticsearch

三、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用于将可能满足给定查询的一个索引中的所有文档重新索引到另一个索引