Document APIs之Index API

Index API在特定的索引中添加或更新JSON文档,使其可搜索以下示例将JSON文档插入ID为1的“twitter”索引中：

PUT twitter/_doc/1
{
    "user" : "kimchy",
    "post_date" : "2009-11-15T14:12:12",
    "message" : "trying out Elasticsearch"
}
Response:
{
    "_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。

自动索引创建

如果索引尚不存在，则索引操作会自动创建索引，并应用已配置的任何索引模板。如果索引模版也尚不存在，则索引操作还会创建动态映射

自动索引创建由action.auto_create_index 设置控制。此设置默认为true，表示始终自动创建索引,false更改为完全禁用自动创建。通过将此设置的值更改为这些模式的逗号分隔列表，仅允许对匹配特定模式的索引创建自动索引。也可以通过在列表中使用(+ or )作为前缀来明确允许和禁止它(-)。

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

1.只允许自动创建名为twitter、index10的索引，不允许其他索引匹配index1*和任何其他匹配ind*的索引。这些模式是按照它们被给出的顺序匹配的。

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

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

Operation Type

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

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

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

PUT twitter/_create/1
{
    "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"
}

response:

{
    "_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参数指定sequence和primary term时才可以执行。如果检测到不匹配，则操作将导致VersionConflictException错误 和状态代码为409

Routing

默认情况下，分片放置的？通过Routing？通过使用文档的id值的hash进行控制。可以使用routing参数在每个操作的基础上直接指定输入到路由器使用的散列函数的值，例如：

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

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

设置显式映射时，_routing可以选择使用该字段指示索引操作从文档本身提取路由值。这样的作法确实会带来非常微小的成本在文档解析过程中。如果_routing映射已定义并设置为required，则如果未提供或提取路由值，则索引操作将失败。
Distributed分布式

索引操作根据路由到相应的主分片,并在包含此分片的实际节点上执行。主分片完成操作后，如果需要，更新将分发到适用的副本。

等待活动分片

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

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

例如，假设我们有一个由三个节点(a、B和C)组成的集群，我们创建了一个索引，其中副本分片的数量设置为3(结果是1个主分片对应3个副本分片，比节点多一个shard)。如果我们尝试索引操作，默认情况下，该操作将只确保每个分片的主分片在继续之前可用。这意味着即使B和C发生故障，并且A承载主分片副本，索引操作仍然复制主分片上的操作到该副本。如果wait_for_active_shards设置请求3(3个节点也都启动了),然后索引操作将需要3 active副本分片 ,这时候应该是满足要求的,因为三个活跃集群中的节点,每一个都持有主分片的副本。但是，如果将wait_for_active_shards设置为all(或4，两者是相同的)，索引操作将不会继续，因为我们没有在索引中激活每个分片的所有4个副本。除非集群中出现一个新节点来承载分片的第四个副本分片，否则操作将超时。

需要注意的是，这个设置极大地降低了写操作未写入到所需碎片副本数量的机会，但它并没有完全消除这种可能性，因为这个检查发生在写操作开始之前。在执行写操作之后，仍然有可能在任意数量的副本分片上复制失败，但在主分片上仍然成功。写操作的响应的_shards部分显示复制成功/失败的shard副本的数量。

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

Refresh

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

Noop更新

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

Timeout

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

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

版本控制

每个索引文档都有一个版本号。默认情况下，使用从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!"
}

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

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

Internal : 仅在给定版本与存储文档的版本相同时才对文档编制索引。

external or external_gt : 只有当给定的版本严格高于存储文档的版本，或者没有现有文档时，才对文档进行索引。给定的版本将作为新版本使用，并与新文档一起存储。所提供的版本必须是非负的长整型数值。

external_gte : 只有当给定的版本等于或高于存储文档的版本时，才对文档进行索引。如果没有现有文档，操作也将成功。给定的版本将作为新版本使用，并与新文档一起存储。所提供的版本必须是非负的长数字。

external_gte版本类型用于特殊的用例，应该谨慎使用。如果使用不当，可能会导致数据丢失。还有另一个选项force，它也是不推荐的，因为它可能导致主分片和副本分片出现数据不一致。