Elasticsearch6.x索引api

1.索引API

 

索引API在特定索引中添加或更新类型化的JSON文档，使其可搜索。以下示例在类型名为_doc，id为1 的类型下将JSON文档插入“twitter”索引：

curl -X PUT "localhost:9200/twitter/_doc/1" -H 'Content-Type: application/json' -d'
{
    "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

指示应在其上执行索引操作的分片副本（主分片和副本分片）的数量。

successful

指示索引操作成功的分片副本数。

failed

在副本分片上索引操作失败的情况下包含与复制相关的错误的数组。

索引操作成功的情况successful至少为1。

索引操作成功返回时，可能尚未启动全部副本分片（默认情况下，只要求主分片，但可以更改此行为）。

　　　　  在这种情况下， total将等于基于number_of_replicas设置的总分片数，successful将等于已启动的分片数（主分片和副本分片）。如果没有失败，则failed为0。

2.自动创建索引

如果索引尚不存在，则索引操作会自动创建索引，并应用已配置的任何索引模板。（索引模板用于控制索引的一些配置项）

索引操作还会为指定的类型创建动态类型映射（如果尚不存在），相当于传统数据库中列的数据结构的定义。

默认情况下，如果需要，新字段和对象将自动添加到指定类型的映射定义中。

自动索引创建由action.auto_create_index 设置控制。此设置默认为true，表示始终自动创建索引。

通过将此设置的值更改为下面形式，仅允许对匹配特定模式的索引创建自动索引。它也可以通过在列表中添加一个+或前缀来明确允许和-禁止它。最后，可以通过将此设置更改为完全禁用false。

curl -X PUT "localhost:9200/_cluster/settings" -H 'Content-Type: application/json' -d'
{
    "persistent": {
        "action.auto_create_index": "twitter,index10,-index1*,+ind*" 
    }
}
'
curl -X PUT "localhost:9200/_cluster/settings" -H 'Content-Type: application/json' -d'
{
    "persistent": {
        "action.auto_create_index": "false" 
    }
}
'
curl -X PUT "localhost:9200/_cluster/settings" -H 'Content-Type: application/json' -d'
{
    "persistent": {
        "action.auto_create_index": "true" 
    }
}
'

 

3.操作类型

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

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

curl -X PUT "localhost:9200/twitter/_doc/1?op_type=create" -H 'Content-Type: application/json' -d'
{
    "user" : "kimchy",
    "post_date" : "2009-11-15T14:12:12",
    "message" : "trying out Elasticsearch"
}
'

另一个指定的选项create是使用以下uri：

curl -X PUT "localhost:9200/twitter/_doc/1/_create" -H 'Content-Type: application/json' -d'
{
    "user" : "kimchy",
    "post_date" : "2009-11-15T14:12:12",
    "message" : "trying out Elasticsearch"
}
'

4.自动ID生成

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

curl -X POST "localhost:9200/twitter/_doc/" -H 'Content-Type: application/json' -d'
{
    "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"
}

5.乐观并发控制

...

6.路由

默认情况下，分片放置(routing)- 通过使用文档的id值的散列来控制。为了更明确的控制，可以使用routing参数在每个操作的基础上直接指定输入到路由器使用的散列函数的值。例如：

curl -X POST "localhost:9200/twitter/_doc?routing=kimchy" -H 'Content-Type: application/json' -d'
{
    "user" : "kimchy",
    "post_date" : "2009-11-15T14:12:12",
    "message" : "trying out Elasticsearch"
}
'

在上面的示例中，“_ doc”文档根据提供的routing参数路由到分片：“kimchy”。

设置显式映射时，_routing可以选择使用该字段指示索引操作从文档本身提取路由值。

这确实来自另一个文档解析过程的（非常小的）成本。如果_routing映射已定义并设置为required，则如果未提供路由值或者不能提取，则索引操作将失败。

7.分布式

索引操作根据其路由指向主分片（请参阅上面的“路由”部分），并在包含此分片的实际节点上执行。主分片完成操作后，如果需要，更新将分发到适用的副本。

8.等待活动碎片

为了提高对系统写入的弹性，可以将索引操作配置为在继续操作之前等待一定数量的活动分片副本。

如果指定数量的活动分片副本不可用，则写入操作必须等待并重试，直到必需的分片副本已启动或发生超时。

默认情况下，写入操作仅等待主分片处于活动状态（即wait_for_active_shards=1）。可以通过设置索引设置动态地覆盖此默认值index.write.wait_for_active_shards。要更改每个操作的此行为，wait_for_active_shards可以使用request参数。

有效值是all或任何有效正整数，最大为索引中每个分片的已配置副本总数（即number_of_replicas+1）。指定负值或大于分片副本数的数字将引发错误。

例如，假设我们有三个节点的群集，A，B，和C，我们创建索引index设置的副本数量为3（导致4个分片副本，多余节点的数量）。

如果我们尝试索引操作，默认情况下，操作只会确保每个分片的主分片在继续之前可用。这意味着即使B和C关闭，由A托管主分片，索引操作仍将正常完成（主分片A是好的）。

如果wait_for_active_shards在请求上设置为3（并且所有3个节点都已启动），然后索引操作将在继续之前需要3个活动分片副本，这是一个可以满足的要求，因为群集中有3个活动节点，每个活动节点都拥有该分片的副本。

但是，如果我们设置wait_for_active_shards为all（在这里等同于4），索引操作将不会继续，因为我们没有4个分片。除非在群集中启动新节点以托管分片的第四个副本，否则操作将超时。

重要的是要注意，此设置大大降低了写入操作没写入所需数量的分片副本的可能性，但它并未完全消除这种可能性，因为此检查在写入操作开始之前发生。

一旦写入操作正在进行，副本分片复制操作仍然可能失败，但可以在主分片上成功。在_shards写操作的响应部分揭示了其复制成功/失败分片的份数。

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

9.刷新

控制何时此请求所做的更改对搜索可见。

10.Noop更新

使用索引API更新文档时，即使文档未更改，也始终会创建新版本的文档。如果这是不可接受的，请使用设置_updateAPI的 detect_noop为true。此选项在索引API上不可用，因为索引API不会获取旧源，也无法将其与新源进行比较。

关于何时不接受noop更新，没有一条硬性规定。它是许多因素的组合，例如您的数据源发送实际noops更新的频率以及Elasticsearch在接收更新的分片上运行的每秒查询数。

11.超时

执行索引操作时，分配用于执行索引操作的主分片可能不可用。

原因可能是主分片当前正从网关恢复或正在进行重定位。默认情况下，索引操作将在主分片上等待最多1分钟，然后失败并响应错误。该timeout参数可用于显式指定等待的时间。以下是将其设置为5分钟的示例：

curl -X PUT "localhost:9200/twitter/_doc/1?timeout=5m" -H 'Content-Type: application/json' -d'
{
    "user" : "kimchy",
    "post_date" : "2009-11-15T14:12:12",
    "message" : "trying out Elasticsearch"
}
'

12.版本控制

每个索引文档都有一个版本号。默认情况下，使用从1开始的内部版本控制，并在每次更新时递增，包括删除。

版本号也可以设置为外部值（例如，如果在数据库中维护数据）。要启用此功能，应将version_type设置为 external。提供的值必须是大于或等于0且小于大约9.2e + 18的数字长值。

使用外部版本类型时，系统会检查传递给索引请求的版本号是否大于当前存储文档的版本号。如果为true，则将索引文档并使用新版本号。如果提供的值小于或等于存储文档的版本号，则会发生版本冲突，索引操作将失败。例如：

curl -X PUT "localhost:9200/twitter/_doc/1?version=2&version_type=external" -H 'Content-Type: application/json' -d'
{
    "message" : "elasticsearch now has versioning support, double cool!"
}
'

注意：版本控制是完全实时的，不受搜索操作的近实时方面的影响。如果未提供任何版本，则直接执行该操作而不进行任何版本检查。

由于提供的版本2高于当前文档版本1，因此上述操作将成功。如果文档已更新且其版本设置为2或更高，则索引命令将失败并导致冲突（409 http状态代码）。

12.1.版本类型

Elasticsearch还支持特定的其他类型。以下是不同版本类型及其语义的概述。

internal

仅在给定版本与存储文档的版本相同时才对文档编制索引。 [ 6.7.0 ]在6.7.0中弃用。请使用if_seq_no＆if_primary_term代替。有关更多详细信息，请参阅乐观并发控制。

external 或者 external_gt

如果给定版本严格高于存储文档的版本或者没有现有文档，则仅索引文档。给定版本将用作新版本，并将与新文档一起存储。提供的版本必须是非负值。

external_gte

仅在给定版本等于或高于存储文档的版本时索引文档。如果没有现有文档，操作也将成功。给定版本将用作新版本，并将与新文档一起存储。提供的版本必须是非负值。