《Elasticsearch:权威指南》Document APIs -- Index API

最新推荐文章于 2023-10-18 17:35:30 发布

云川之下

最新推荐文章于 2023-10-18 17:35:30 发布

阅读量191

点赞数

分类专栏： ES

原文链接：https://www.elastic.co/guide/en/elasticsearch/reference/6.8/docs-index_.html#index-versioning

版权

ES 专栏收录该内容

30 篇文章 6 订阅

订阅专栏

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

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"
}

默认情况下的新增操作，如果指定id，存在相同的Index、type和id时，es会执行修改操作，version属性递增；如果不指定id，每次自动生成id，并作为新数据插入库。

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

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

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

注意

当索引操作 successful 返回时，可能不会全部启动副本碎片（默认情况下，只需要主索引，但可以更改此行为）。在这种情况下， total 将等于基于 number_of_replicas 设置的总分片，并且 successful 将等于已启动的分片数（主副本和副本）。如果没有失败， failed 将是 0

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 来禁用自动创建索引。

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

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

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

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

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

备注：
1.仅允许自动创建称为twitter，index10的索引，不允许其他与 index1.*匹配的索引，以及与ind *匹配的任何其他索引。模式按照给定的顺序进行匹配。

2.完全禁用索引的自动创建。

3 .允许使用任何名称自动创建索引。这是默认值。

Operation type ( 操作类型 )

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

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

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

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

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

automatic ID generation ( 自动 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"
}

乐观并发控制

索引操作可以是有条件的，并且仅在对文档的最后一次修改分配了由if_seq_no和if_primary_term参数指定的序列号和主要术语的情况下才能执行。如果检测到不匹配，则该操作将导致VersionConflictException和状态码409。有关更多详细信息，请参见乐观并发控制。

Routing ( 路由信息 )

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

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

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

设置 up explicit mapping( 显式映射 ) 时，可以选择使用 _routing 字段来指示索引操作从文档本身提取路由值。这是在额外的文档解析通过的（非常小）成本。如果定义 _routing 映射并将其设置为必需，则如果未提供或提取路由值，则索引操作将失败。

Distributed ( 分布式 )

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

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

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

默认情况下，只要primary shard 是活跃的，就能索引文档(index操作)，因为wait_for_active_shards=1。若未达到设置的活跃数，则索引操作会超时，超时时间为1分钟，然后报错。

有效值是所有或任何正整数，直到索引中每个分片的配置副本的总数（即 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
    }
}

Refresh ( 刷新 )

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

Noop Updates

更新索引有2中方式：

使用index API 更新文档时，即使文档没有更改，也始终创建新版本的文档。
_update API ， detect_noop 参数默认为 true ，如果文档没有更改，则不更新文档，并返回noop标识。
此选项在index API 上不可用，因为index api doesn’t fetch the old source ( 不提取旧源 )，并且无法将其与 new source ( 新源 ) 进行比较。

更新文档有2中方式，index API和_update API。后者默认情况下，如果修改操作发现内容没有实质的变化，version不会递增。

详情可以参考 Detecting noop updates

没有一个强制和快速的规则，当 noop 更新是不能接受的。它是许多因素的组合，例如数据源发送实际上是 noops 的更新的频率，以及每秒多少查询，elasticsearch 在接收更新时在分片上运行。

Timeout ( 超时 )

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

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

Versioning ( 版本控制 )

每个索引的文档都有一个版本号。默认情况下，使用从 1 开始的内部版本控制，每个 update ( 更新 )，包括 deletes ( 删除 )。可选地，版本号可以用外部值（例如，如果在数据库中维护）来补充。要启用此功能， version_type 应该设置为 external 。提供的值必须是大于或者等于 0 且小于大约 9.2e+18 的数字长值。

当使用 external version type ( 外部版本类型 ) 时，系统检查传递给索引请求的版本号是否大于当前存储的文档的版本，而不是检查匹配的版本号。如果为 true ，则文档将被索引并使用新的版本号。如果提供的值小于或等于存储的文档的版本号，则会出现版本冲突，并且索引操作将失败。

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

注意：

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

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

上面的版本号用法解释为，如果有2个用户同时读取了document，版本都为1，分别提交修改请求，并且带上version为1的参数，那么分片在执行修改命令时，会检查参数与数据库中的version，这样一来，先到的请求会执行成功，并且把version值改为2，而后到的请求会失败，此时 2>2 结果为否

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

Version types ( 版本类型 )

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

internal

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

external 或 external_gt

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

external_gte

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

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

云川之下

关注

0
点赞
踩
0

收藏

觉得还不错? 一键收藏
0
评论
《Elasticsearch:权威指南》Document APIs -- Index API

索引 API 在特定索引中 add ( 添加 ) 或 update ( 更新 ) a typed JSON document ( 类型化的 JSON 文档 )，使其可搜索。以下示例将 JSON 文档插入到 “twitter” 索引中，type 为 _doc ，ID 为1 ：PUT twitter/_doc/1{ "user" : "kimchy", "post_date" : "2009-11-15T14:12:12", "message" : "trying out Elast
复制链接

扫一扫

专栏目录