7、index API

原文地址：https://www.elastic.co/guide/en/elasticsearch/reference/current/docs.html

elasticsearch版本：6.5

目录地址：https://blog.csdn.net/mine_1/article/details/85623429

index API在特定索引中添加或更新类型化的JSON文档，使其可搜索。下面的示例将JSON文档插入到“twitter”索引中，该索引位于“_doc”（ID为1）的类型下，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"
}

_shards提供了索引操作的副本信息：

• total — 指示索引操作应在多个碎片分片（主碎片和副本分片）上执行
• successful — 指示索引操作中成功执行的分片数量
• failed — 执行索引失败的分片的数组

index操作当至少有一个成功的操作是操作成功。

(1) 自动创建索引

如果没有指定索引，则elasticsearch会自动创建索引，还会自动为特定类型创建动态类型映射（请签出用于手动创建类型映射的输出映射API）。映射本身非常灵活，并且没有模式限制。新字段和对象将自动添加到指定类型的映射定义中。

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

自动创建索引可以包括基于模式的白/黑列表，例如，将action.auto_create_index设置为+aaa*、-bbb*、+ccc*、-*（+表示允许，-表示不允许）。

Versioning

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

PUT twiter/_doc/1?versoin=2
{
    "message":"elasticsearch now has versoning support, double cool!"
}

注意：版本控制完全是实时的，并且不受搜索操作的近实时方面的影响。如果没有提供版本，则在执行操作时不进行任何版本检查。

默认情况下，使用以1开始的内部版本控制，并随着每次更新、包括删除而递增。或者，可以使用外部值（例如，如果在数据库中维护的话）来补充版本号。要启用此功能，version_type应设置为external。提供的值必须是一个大于或等于0且小于约9.2e+18的数字长值。使用外部版本类型时，系统检查传递给索引请求的版本号是否大于当前存储文档的版本，而不是检查匹配的版本号。如果为真，则将为文档编制索引并使用新版本号。如果提供的值小于或等于存储文档的版本号，将发生版本冲突，索引操作将失败。

elasticsearch索引使用默认的版本时，用户不需要维护由于数据更改而执行的异步索引操作造成的索引更改。如果使用外部版本控制，即使使用数据库中的数据更新elasticsearch索引的情况也很简单，如果由于某些索引操作不正常，只会使用最新版本。

version types

处理上述的内部和外部版本类型，elasticsearch也支持其他的用户自定义类型版本，下面做个简单的介绍：

internal：只有给定的version同已经存在的文件version一样时才进行索引

external 或 external_gt：只有给定的version高于已经存在的文件的版本，或者如果不存在指定的version的文件才进行索引。这一版本将作为新版本使用，并将与新文件保持一致。该类version必须是非负数。

external_gte：只有这给定的version与已经处在的version相等或更高时才进行索引。如果没有存在文件，操作也会继续下去。这一版本将作为新版本使用，并将与新文件保持一致。该类version必须是非负数。external_gte需要谨慎使用，如果使用不当，可能导致丢失数据。

(2)操作类型

index操作还接受可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"    
}

还可以这样使用：

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

(3)自增ID

索引操作可以不给出指定的ID。这种情况下，将会自动生成id。此外，op_type将会自动设置为create。如下例：

PUT twiiter/_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":"W0TPSAdsfwerwefsadf",
    "_version":1,
    "_seq_no":0,
    "_primary_term":1,
    "result":"created"
}

(4)Rounting

默认情况下，通过使用文档ID值的哈希值来控制分片的位置（或路由）。对于更显式的控制，可以使用routing参数在每次操作的基础上直接指定输入到路由器使用的哈希函数的值。例如：

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

在这个例子里面，_doc文档根据给定的routing参数直接路由到指定的分片。

设置显式映射时，可以选择使用_routing字段指导索引操作，从给定的值提取路由值。这确实需要额外的文档解析过程（非常小的）开销。如果定义了路由映射并将其设置为必需，则如果没有提供或提取路由对应的值，则索引操作将失败。

(5) Distributed

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

(6) Wait For Active Shards

为了提高系统写入的健壮性，可以将索引操作配置为在继续操作之前等待一定数量的活动分片。如果所需数量的活动分片副本不可用，则写入操作必须等待并重试，直到所需碎片副本已启动或发生超时。默认情况下，写入操作仅在继续之前等待主碎片处于活动状态（即wait_for_active_shards=1）。这个默认值可以通过设置index.write.wait-for-active-shards在索引设置中被动态覆盖。要更改每个操作的此行为，可以使用wait-for-active-shards请求参数。

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

例如，假设我们有一个由三个节点（A、B和C）组成的集群，并且我们创建了一个索引索引，其中副本数设置为3（结果是4个碎片副本，比节点多一个副本）。如果我们尝试索引操作，默认情况下，该操作将仅确保每个碎片的主副本在继续操作之前可用。这意味着，即使B和C发生故障，并且A托管了主碎片副本，索引操作仍然只会继续进行一个数据副本。如果在请求中将wait-for-active-shards设置为3（并且所有3个节点都已启动），那么索引操作将需要3个活动的shard副本才能继续，这一要求应该满足，因为群集中有3个活动的节点，每个节点都保存一个shard副本。但是，如果我们将wait-for-active-shards设置为all（或设置为4，这是相同的），则索引操作将不会继续，因为索引中没有每个shard的所有4个副本。除非集群中出现一个新节点来承载第四个shard副本，否则操作将超时。

需要注意的是，此设置大大降低了写入操作不写入所需数量的碎片副本的可能性，但它并不能完全消除这种可能性，因为此检查发生在写入操作开始之前。一旦写入操作正在进行中，复制仍有可能在任何数量的shard拷贝上失败，但在主拷贝上仍然成功。写入操作响应的_shards部分显示复制成功/失败的shard拷贝数。

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

(7)Refresh

控制当有更改时在请求结果中是否可见。

(8)Noop Updates

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

当noop更新不能被接受时，没有一个硬性和快速的规则。这是许多因素的组合，比如数据源发送实际为noops的更新的频率，以及ElasticSearch在接收更新时每秒在shard上运行的查询数。

(9)Timeout

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

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