创建索引 API

创建一个新的索引。

  1. PUT /my-index-000001

请求

PUT /<index>

前置条件

  • 如果 Elasticsearch 安全特性启用，你对目标索引必须有 create_index 或 manage 索引权限。

描述

你可以使用创建索引 API 向 Elasticsearch 集群添加一个新的索引。当创建索引时，你可以指定以下项：

  • 索引设置
  • 索引字段映射
  • 索引别名

路径参数

  • <index>

（必需的，字符串）你希望创建的索引的名字。

索引名字必须符合以下约定：

  1. 只能是小写字符
  2. 不能包含字符：\、/、*、?、"、<、>、|、`(空格)、,、#`
  3. 7.0 之前索引可以包含冒号（:），但在 7.0 之后不推荐。
  4. 不能以 -、_、+ 开头
  5. 不能是 . 或 ..
  6. 长度不能超过 255 字节（注意是字节，所以多字节字符会更快达到 255 的限制）
  7. 名字以 . 开头不推荐，除非由插件管理的隐藏索引和内部索引

查询参数

  • include_type_name [7.0.0开始不推荐] （可选，布尔值）如果为 true，映射体中需要映射类型。

  • wait_for_active_shards （可选，字符串）在操作执行之前必须活动的分片复制数量。设置为 all 或任何正整数，最大值为索引分片总数（number_of_replicas+1）。默认为：1，主分片。

参阅 激活分片

  • master_timeout （可选，时间单位）等待连接到主节点的时间。如果在超时过期前没有收到响应，则请求失败并返回错误。默认为 30s。

  • timeout （可选，时间单位）等待响应的时间。如果在超时过期之前没有收到响应，则请求失败并返回错误。默认为 30s。

请求体

  1. 字段名字
  2. 字段数据类型
  3. 映射参数

参阅映射

示例

索引设置

创建的每个索引可以有与它关联的特定设置，在请求体中定义：

  1. PUT /my-index-000001
  2. {
  3.   "settings": {
  4.     "index": {
  5.       "number_of_shards": 3,  
  6.       "number_of_replicas": 2
  7.     }
  8.   }
  9. }
  1. number_of_shards 默认为 1
  2. number_of_replicas 默认为 1 （例如，每个主分片一个副本）

或更简单：

  1. PUT /my-index-000001
  2. {
  3.   "settings": {
  4.     "number_of_shards": 3,
  5.     "number_of_replicas": 2
  6.   }
  7. }

?> 在 settings 部分中，不必显示指定 index 部分。

有关创建索引时，可以设置的所有不同索引级别设置的详细信息，参阅章节索引模块。

映射

创建索引 API 允许提供映射定义：

  1. PUT /test
  2. {
  3.   "settings": {
  4.     "number_of_shards": 1
  5.   },
  6.   "mappings": {
  7.     "properties": {
  8.       "field1": { "type": "text" }
  9.     }
  10.   }
  11. }

?> 在 7.0.0 之前，mapping（映射）定义用于包含类型名字。尽管现在不推荐在请求中指定类型，但如果设置了请求参数 include_type_name，仍然可以提供类型。更多的信息，参阅移除映射类型。

别名

创建索引 API 也允许提供一组别名。

  1. PUT /test
  2. {
  3.   "aliases": {
  4.     "alias_1": {},
  5.     "alias_2": {
  6.       "filter": {
  7.         "term": { "user.id": "kimchy" }
  8.       },
  9.       "routing": "shard-1"
  10.     }
  11.   }
  12. }

等待激活分片

默认情况下，索引创建只会在每个分片的主副本已启动或请求超时时，向客户端返回响应。索引创建响应将表明发生了什么。

  1. {
  2.   "acknowledged": true,
  3.   "shards_acknowledged": true,
  4.   "index": "test"
  5. }

acknowledged 表明在集群中索引是否成功创建，同时 shards_acknowledged 表明在超时之前，是否为每个分片启动了必需的分片副本数量。注意，acknowledged 或 shards_acknowledged 仍有可能为 false，但索引创建是成功的。这个值只简单表明在超时前操作是否完成。如果 acknowledged 为 false，然后为新创建的索引更新集群状态之前，我们超时了，但它也可能很快被创建。如果 shards_acknowledged 为 false，在启动所需数量的分片之前我们就超时了（默认情况下，只有主碎片），即使集群状态已成功更新以反映新创建的索引（如，acknowledged=true）。

我们可以通过索引设置 index.write.wait_for_active_shards，更改等待主分片启动的默认值（注意改变这个设置也会影响后续写入操作上的 wait_for_active_shards 值）：

  1. PUT /test
  2. {
  3.   "settings": {
  4.     "index.write.wait_for_active_shards": "2"
  5.   }
  6. }

或者通过请求参数 wait_for_active_shards：

  1. PUT /test?wait_for_active_shards=2

对 wait_for_active_shards 的详情解释，及它的可能值能在这里找到。

原文链接