elasticsearch 6.x (四) 单一文档 API 介绍和使用 index和get API

大家好，我是烤鸭：

今天分享的是官网6.x 单一文档(Single document APIs)APIs。

本文这是部分翻译，如果想看全部的，还是建议阅读官方api。链接：

https://www.elastic.co/guide/en/elasticsearch/reference/current/docs.html

1. 索引(index)API

添加或更新：（json格式）

PUT twitter/_doc/1
{"user" : "kimchy","post_date" : "2009-11-15T14:12:12","message" : "trying out Elasticsearch"
}

结果：

{"_shards" : {"total" : 2,"failed" : 0,"successful" : 2},"_index" : "twitter","_type" : "_doc","_id" : "1","_version" : 1,"_seq_no" : 0,"_primary_term" : 1,"result" : "created"
}

_shards ：表示接收数据的碎片。

total ：碎片总量（执行当前操作的）。

failed : 操作失败的碎片数量。只要有一个成功，就认为索引是操作成功的。

当索引操作成功返回时，副本碎片可能不会全部启动（默认情况下，仅需要主元素，但此行为可以更改）。在这种情况下，总数将等于基于副本数量设置的总数碎片，并且成功将等于碎片开始数量（主加副本）。如果没有失败，失败将是0。

版本编辑

每个索引文档都有一个版本号。关联的版本号作为对索引API请求的响应的一部分返回。在指定版本参数时，索引API可选地允许乐观并发控制。这将控制将要执行的操作的文档版本。版本控制用例的一个很好的例子是执行事务读然后更新。从最初读取的文档中指定一个版本，确保其间没有发生任何更改（当为了更新而阅读时，建议将preference 设置为_primary）。例如：

PUT twitter/_doc/1?version=2
{"message" : "elasticsearch now has versioning support, double cool!"
}

操作类型编辑

索引操作还接受一个op_type类型，它可以用来强制create操作，允许“put-if-absent”的行为。当使用create 时，如果索引中已经存在该ID的文档，则索引操作将失败。

下面是使用op_type参数的示例：

PUT twitter/_doc/1?op_type=create
{"user" : "kimchy","post_date" : "2009-11-15T14:12:12","message" : "trying out Elasticsearch"
}

另一种写法：

PUT twitter/_doc/1/_create
{"user" : "kimchy","post_date" : "2009-11-15T14:12:12","message" : "trying out Elasticsearch"
}

自动生成ID

可以在不指定ID的情况下执行索引操作。在这种情况下，ID将自动生成。此外，op_type 将被自动设置为create。下面是一个例子（注意使用POST而不是PUT）：

POST twitter/_doc/
{"user" : "kimchy","post_date" : "2009-11-15T14:12:12","message" : "trying out Elasticsearch"
}

结果：

{"_shards" : {"total" : 2,"failed" : 0,"successful" : 2},"_index" : "twitter","_type" : "_doc","_id" : "W0tpsmIBdwcYyG50zbta","_version" : 1,"_seq_no" : 0,"_primary_term" : 1,"result": "created"
}

路由

默认情况下，碎片放置或routing是通过使用文件ID值的散列来控制的。对于更明确的控制，可以使用路由参数在每个操作基础上直接指定馈送到路由器使用的散列函数的值。例如：

POST twitter/_doc?routing=kimchy
{"user" : "kimchy","post_date" : "2009-11-15T14:12:12","message" : "trying out Elasticsearch"
}

在上面的示例中，基于提供的“kimchy”路由参数，将“_doc”文档指引到碎片。

当设置显式映射时，可选地使用_routing 字段来指示索引操作以从文档本身中提取路由值。这样（使用路由的方式）确实使得额外的文档解析传递的成本非常低。如果定义了_routing 映射并设置required，则如果没有提供或提取路由值，则索引操作将失败。

分布式

索引操作根据其路由指向主碎片（参见上面的路由部分），并在包含该碎片的实际节点上执行。在主碎片完成操作之后，如果需要，则将更新分发给可应用的副本。

等待active碎片

为了提高对系统的写入的性能，索引操作可以被配置为，在进行操作之前，等待一定数量的活动碎片副本。如果所需的active碎片副本数不可用，则写入操作必须等待并重试，直到所需碎片已开始或超时。默认情况下，写入操作在执行之前只等待主碎片变成active（i.e. wait_for_active_shards=1）。可以通过设置index.write.wait_for_active_shards来动态地在索引设置中修改此默认值。为了改变每种操作的行为，可以使用wait_for_active_shards请求参数。

有效值是全部或任何正整数，与索引中每个碎片的配置拷贝总数（number_of_replicas+1）。指定大于碎片副本数量的负值或数字将引发错误。（翻译注: wait_for_active_shards 这个值不能是负的，也不能大于副本数量。)

例如，假设我们有一个三个节点的集群，A、B和C，并且我们创建一个索引index，其中副本的数量设置为3个（导致4个碎片副本，比节点多一个副本）。如果我们尝试索引操作，默认情况下，操作将只确保每个碎片的主副本在执行之前可用。这意味着，即使B和C挂掉了，并且A托管主碎片副本，索引操作仍然只继续执行，虽然只有一个数据副本。如果wait_for_active_shards 被设置在请求到3（并且所有3个节点都是可用的），那么索引在操作之前将需要3个active 碎片副本，需要满足的要求是，由于在集群中有3个活动节点，每个都持有碎片的副本。但是，如果我们将wait_for_active_shards碎片设置为all（或4，一个意思），则索引操作不会继续进行，因为在索引中的每个碎片的(副本)，所有4个副本不都是active。除非在集群中出现新节点来管理碎片的第四副本，否则操作将超时。
重要的是要注意，写入操作有时不会把数据写到足够数量的碎片副本，这种设置大大降低了这种可能，但因为该检查发生在写入操作开始之前，也不能完全消除可能。一旦写入操作正在进行，复制仍可能在任何碎片的其他副本上失败，但在主副本上仍然成功。写入操作响应的_shards部分表示了复制成功/失败的碎片副本的数量。

{"_shards" : {"total" : 2,"failed" : 0,"successful" : 2}
}

NOOP 更新
当使用索引API更新文档时，即使文档没有更改，也总是创建文档的新版本。如果这是不可接受的，使用 _update API时，将detect_noop设置为true。这个参数在索引API上是不可用的，因为索引API没有获取旧的源，并且无法将它与新的源进行比较。

当NOOP 更新不能使用时，没有一个固定的原因。这是很多因素的组合，比如你的数据源发送多个更新是真的noops的频率，es每秒在碎片上运行多少个查询结果用于update数据。

超时

当执行索引操作时，分配给执行索引操作的主碎片可能不可用。一些原因可能是主碎片目前正在从网关恢复或进行重新定位。默认情况下，索引操作将等待主碎片1分钟。timeout 参数可用于显式指定它等待多长时间。下面是将其设置为5分钟的示例：

PUT twitter/_doc/1?timeout=5m
{"user" : "kimchy","post_date" : "2009-11-15T14:12:12","message" : "trying out Elasticsearch"
}

2. 获取（GET）API

get请求获取json数据:

GET twitter/_doc/0

结果：

{"_index" : "twitter","_type" : "_doc","_id" : "0","_version" : 1,"found": true,"_source" : {"user" : "kimchy","date" : "2009-11-15T14:12:12","likes": 0,"message" : "trying out Elasticsearch"}
}

上述结果包括了我们希望检索的文档的_index, _type, _id和 _version，包括文档的实际_source（如果在响应中found字段标示）。

API还允许使用HEAD检查文档的存在，例如：

HEAD twitter/_doc/0

实时
默认情况下，get API是实时的，并且不受索引刷新率的影响（当数据将成为搜索可见时）。如果文档已被更新，但尚未刷新，则get API将在本地发出刷新调用以使文档可见。这也会使其他文档在可见性上发生变化。为了禁用实时特性，可以将realtime参数设置为false。

源过滤器

默认情况下，get操作返回_source字段的内容，除非您已经使用stored_fields 参数，或者如果禁用了_source 字段。可以通过使用_source 参数来关闭_source检索：

GET twitter/_doc/0?_source=false

如果您只需要完整的_source内容中的一个或两个字段，则可以使用_source_include＆_source_exclude 参数来包含或过滤掉所需的部分。这对于在大型文档中检索部分内容，是非常有效的，因为可以节省网络开销。两个参数都采用逗号分隔的字段或通配符表达式列表。例如：

GET twitter/_doc/0?_source_include=*.id&_source_exclude=entities

如果只想指定包含，则可以使用更短的符号：

GET twitter/_doc/0?_source=*.id,retweeted

存储字段
get操作允许指定一个存储字段的集合，这些字段将通过stored_fields 参数返回。如果所请求的字段未被存储，它们将被忽略。例如，考虑下面的映射：

PUT twitter
{"mappings": {"_doc": {"properties": {"counter": {"type": "integer","store": false},"tags": {"type": "keyword","store": true}}}}
}

现在新增一个文档：

PUT twitter/_doc/1
{"counter" : 1,"tags" : ["red"]
}

尝试去检索刚才生成的：

GET twitter/_doc/1?stored_fields=tags,counter

结果：

{"_index": "twitter","_type": "_doc","_id": "1","_version": 1,"found": true,"fields": {"tags": ["red"]}
}

从文档本身获取的字段值总是作为数组返回。由于counter字段未被存储，所以GET请求在试图获取stored_fields时忽略它。

还可以检索元数据字段，如_routing 字段：

PUT twitter/_doc/2?routing=user1
{"counter" : 1,"tags" : ["white"]
}

或者：

GET twitter/_doc/2?routing=user1&stored_fields=tags,counter

结果：

{"_index": "twitter","_type": "_doc","_id": "2","_version": 1,"_routing": "user1","found": true,"fields": {"tags": ["white"]}
}

此外，只有leaf字段可以通过stored_field 选项返回。所以不能返回对象字段，这样的请求就会失败。

直接获取_source

使用/{index}/{type}/{id}/_source端点来获取文档的_source字段，而不必在其周围添加任何内容。例如：

GET twitter/_doc/1/_source

还可以使用相同的source filtering参数来控制将返回的_source 的哪些部分：

GET twitter/_doc/1/_source?_source_include=*.id&_source_exclude=entities'

注意，还存在一个用于_source 端点的HEAD 变量，以有效地测试文档源的存在。如果在映射中被禁用，则现有文档将不具有源。

HEAD twitter/_doc/1/_source

路由

当使用索引控制路由时，为了获得文档，还应提供路由值。例如：

GET twitter/_doc/2?routing=user1

以上将得到id是2的twitter，但会基于用户路由。注意，发出一个没有正确路由的get请求导致文档不你能获取。

preference （偏好）

哪个碎片副本来执行GET请求的preference。默认情况下，操作是在碎片副本之间随机进行的。
preference可以设置为：
_primary
操作将只在主碎片上执行。
_local
如果可能的话，操作将更倾向于在本地分配的碎片上执行。
Custom (string) value(自定义字符串值)
自定义值将用于保证相同的碎片将用于相同的自定义值。这可以在不同刷新状态下击中不同碎片时

使用 "jumping values" 。简单的示例值类似于Web session ID或用户名。

刷新
`refresh` 参数可以设置为`true` ，以便在GET操作之前刷新相关碎片并使其可搜索。将其设置为`true` 应经过仔细思考和验证，这不会导致系统上的高负载（而减慢索引）。

分布式

get操作被hash成一个特定的碎片ID。它被重定向到该碎片ID中的一个副本，并返回结果。在该碎片ID组中副本就是的主碎片及其副本。这意味着我们将拥有更多的副本，我们将有更大的范围。

版本支持

只有当当前版本等于指定的版本时，才可以使用version 参数检索文档。这种行为对于所有版本类型都是相同的，除了版本类型为FORCE ，FORCE 一直在检索文档。请注意，FORCE版本类型被弃用。
在内部，es 已经标记旧文档被删除，并添加了一个全新的文档。旧版本的文档不会立即消失，尽管你不能访问它。当继续给更多数据添加索引时，es会在后台清除已删除的文档。

更多关于elasticsearch 6.x内容：

1. elasticsearch 6.x 部署 windows入门(一) spingboot连接

2. elasticsearch 6.x linux部署(二) kibana x-pack 安装

3. elasticsearch 6.x (三) linux 集群多节点部署