03.elasticsearch_index操作

1. Index API

索引 API 在特定索引中 add ( 添加 ) 或 update ( 更新 ) a typed JSON document ( 类型化的 JSON 文档 )，使其可搜索。以下示例将 JSON 文档插入到 “twitter” 索引中，ID 为1 ：

curl -XPUT 'localhost:9200/tweet/_doc/1?pretty' -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,
    "created" : true,
    "result" : created
}

_shards header 提供有关索引操作的复制过程的信息。

total - 指示应对多少 shard copies ( 分片副本 )（ primary ( 主 )分片和 replica ( 副本 ) 分片）执行索引操作。
successful - 表示索引操作成功的分片副本的数量。
failed - 在索引操作在副本碎片上失败的情况下包含与复制相关的错误的数组。
在 successful 至少为 1 的情况下索引操作成功。

注意事项

当索引操作 successful 返回时，并不一定所有的replica shard都启动了（默认情况下，只需要primary shard是必须的，但可以更改此行为）。在这种情况下， total 将等于基于 number_of_replicas 设置的总分片(也就是理论上的shard数量)，并且 successful 将等于已启动的分片数（主副本和已经启动的副本）。如果没有失败， failed 将是 0 。

2. automatic index creation ( 自动创建索引 )

如果索引操作尚未创建，则索引操作自动创建索引（check out 用于手动创建索引的 create index API），并且如果尚未创建，则自动为特定类型创建 dynamic type mapping( 动态类型映射 )（check out put mapping API 用于手动创建类型映射）。

mapping ( 映射 ) 本身非常灵活，并且是 schema-free ( 无模式的 )。New fields ( 新字段 ) 和 objects ( 对象 )将自动添加到指定类型的映射定义。查看映射部分以获取有关映射定义的更多信息。

可以通过在所有节点的配置文件中将 action.auto_create_index 设置为 false 来禁用 自动创建索引。可以通过将index mapping.dynamic 设置为 false 来禁用当前索引自动映射创建。

自动索引创建可以包括 a pattern based white/black list ( 基于模式的 白/黑 列表 )，例如，设置

action.auto_create_index to +aaa,-bbb,+ccc,- （ + 表示 允许，- 表示不允许）。

PUT _cluster/settings
{
    "persistent": {
        "action.auto_create_index": "twitter,index10,-index1*,+ind*" 
    }
}

PUT _cluster/settings
{
    "persistent": {
        "action.auto_create_index": "false" 
    }
}

PUT _cluster/settings
{
    "persistent": {
        "action.auto_create_index": "true" 
    }
}

3. Operation type ( 操作类型 )

除了允许 “put-if-absent” 行为,index操作还接受可用于强制创建操作的 op_type，使用 create 时，如果索引中已存在该标识的文档，索引操作将失败。

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

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

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

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

4. automatic ID generation ( 自动 ID 生成 )

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

curl -XPOST 'localhost:9200/twitter/_doc/?pretty' -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" : "6a8ca01c-7896-48e9-81cc-9f70661fcb32",
    "_version" : 1,
    "created" : true,
    "result": "created"
}

5. 乐观锁使用

索引操作可以是有条件来控制的，可以控制仅在文档的最后一次因为修改分配的_seq_no和_primary_term 参数和请求时传进来的if_seq_no和if_primary_term参数相等的情况下才能执行操作。如果检测到不匹配，则该操作将导致VersionConflictException和状态码409。有关更多详细信息，请参见乐观并发控制。

PUT products/_doc/1567?if_seq_no=362&if_primary_term=2
{
    "product" : "r2d2",
    "details" : "A resourceful astromech droid",
    "tags": ["droid"]
}

6. Routing ( 路由信息 )

默认情况下，请求分发到那个分片(routing 路由 ) ——通过使用文档的 id 值的哈希值来控制。对于更明确的控制，馈送到由路由使用的散列函数的值可以使用路由参数基于每个操作直接指定。例如：

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

在上面的示例中，“tweet” 文档根据提供的 routing parameter ( 路由参数 ) kimchy发送到 shard ( 分片 ) .

如果显示的设置mapping的话，也可以指定使用doc的某个一个字段来作为routing,如果过设置了_routing mapping 请求的时候没有rounting value或者无法从文档中提取routing value，则请求会报错

7. Distributed ( 分布式 )

索引操作基于其路由定向到 primary shard ( 主分片 ) （参见上面的路由部分），并在包含此分片的实际节点上执行。在主分片完成操作后，如果需要，将更新分发到适用的副本。

8. wait for active shards ( 等待活动分片 )

为了提高写入系统的 resiliency ( 弹性 )，索引操作可以配置为在继续操作之前等待一定数量的活动分片副本。如果所需的活动分片副本数不可用，则写操作必须等待并重试，直到必需的分片副本已启动或发生超时为止。默认情况下，写操作只等待主分片处于活动状态，然后再继续（wait_for_active_shards=1）。可以通过设置 index.write.wait_for_active_shards 来动态地在索引设置中覆盖此默认值。要更改每个操作的此行为，可以使用 wait_for_active_shards 请求参数。

有效值是所有或任何正整数，直到索引中每个分片的配置副本的总数（即 number_of_replicas+1）。指定负值或者大于分片副本数的数字将抛出错误。

例如，假设我们有一个三个节点A，B和C的集群，我们创建一个索引，索引副本数设置为 3 （导致 4 个 shard 副本，比节点多一个副本）。如果我们尝试索引操作，默认情况下，操作将仅确保每个分片的主副本在继续之前可用。这意味着，即使 B 和 C 下降，并且 A 托管主分片副本，索引操作仍然将继续只有一个数据副本。如果对请求设置 wait_for_active_shards 设置为 3 （并且所有3个节点都已启动），则索引操作将在继续之前需要 3 个活动分片副本，这是应该满足的要求，因为在集群有3个活动节点，每个节点有一个碎片的副本。但是，如果我们将 wait_for_active_shards 设置为 all （或者 4， 这是相同的），索引操作将不会继续，因为索引中的每个碎片的所有的 4 个副本没有处于活动状态。该操作将超时，除非在集群中启动新节点以托管分片的第四个副本。

重要的是要注意，这个设置极大地减少了写操作不写入所需数量的分片副本的机会，但是它不能完全消除可能性，因为这种检查在写操作开始之前发生。一旦写操作正在进行，复制仍然可能在任意数量的 shard 副本上失败，但在主数据库上仍然成功。写操作响应的 _shard 部分显示复制成功/失败的分片副本的数量。

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

9. Refresh ( 刷新 )

控制此请求所做的更改对搜索可见。请参阅 刷新 。

10. Noop Updates

当使用索引 API 更新文档时，即使文档没有更改，也始终创建新版本的文档。如果不想这样，请在使用_update API的时候将 detect_noop 设置为 true 。此选项在index API 上不可用，因为index api doesn’t fetch the old source ( 不提取旧源 )，并且无法将其与 new source ( 新源 ) 进行比较。

没有一个强制和快速的规则来判定 noop 更新是不是应该使用。它是许多因素的组合，例如发送noops 的更新的频率，以及每秒有多少次请求。

11. Timeout ( 超时 )

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

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

11. Versioning ( 版本控制 )

目前version是一个update的标识，可以是外部的或者是内部的，但是已经不建议用来作为并发控制了，而是建议使用if_seq_no和if_primary_term参数来进行并发控制
每个索引的文档都有一个版本号。默认情况下，使用内部版本控制，该版本从1开始，并随着每次更新（包括删除）而递增。可以选择将版本号设置为外部值（例如，如果维护在数据库中）。要启用此功能，应将version_type设置为external。提供的值必须是大于或等于0且小于9.2e + 18左右的数字长值。

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

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

注意：

version是完全实时的，并且不受搜索操作的 near real time( 近实时 ) 方面的影响。如果没有提供版本，则在没有任何版本检查的情况下执行操作。

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

使用external version一个很好的作用是，只要使用源数据库中的版本号(目标是要将源数据中的version导入到es当中)，就不需要维护由于对源数据库进行更改而执行的异步索引操作的严格顺序。如果使用外部版本控制，即使使用数据库中的数据更新Elasticsearch索引的简单情况也得以简化，因为如果索引操作由于任何原因而乱序出现，则仅使用最新版本。

1. Version types ( 版本类型 )

在上边解释的 internal ( 内部 ) 和 external ( 外部 ) 版本类型旁边，Elasticsearch 还支持特定用例的其他类型。这里是不同版本类型及其语义的概述。

** 1. internal**

仅在给定版本与存储的文档的版本相同时索引文档。

** 2. external 或 external_gt **

如果给定版本严格高于存储的文档的版本或如果没有现有文档，则仅索引文档。给定版本将用作新版本，并与新文档一起存储。提供的版本必须是 non-negative long number ( 非负长数字 ) 。

** 3. external_gte **

如果给定版本 等于 或者 高于 存储的文档的版本，则仅索引文档。如果没有现有文档，操作也将成功。给定版本将用作新版本，并与新文档一起存储。提供的版本必须是 non-negative long number ( 非负长数字 )。

注意：

external_gte 版本类型适用于特殊用例，应谨慎使用。如果使用不正确，可能会导致数据丢失。还有一个选项，force ，它也被弃用，因为它可能导致主分片和副本分片。