ES常见Index API操作最佳实践！

左框 requests，右框 response：

3.1 创建

PUT /索引名

如

PUT /test_index?pretty

对应

老版响应：

@JsonpDeserializable
public class CreateIndexResponse implements AcknowledgedResponse, JsonpSerializable {
   
    private final String index;

      // 指示在超时之前是否已为索引中的每个分片启动了必需数量的分片副本
    private final boolean shardsAcknowledged;

      // 指示索引是否已成功在集群中创建
    private final boolean acknowledged;

      // `acknowledged` 或 `shards_acknowledged` 仍可能 `false`，但索引创建已成功。这些值只是指示操作是否在超时前完成
      // 如 `acknowledged` = `false`，则我们在集群状态使用新创建的索引更新之前超时，但它很可能很快就被创建
      // 如 `shards_acknowledged` 为 `false`，则我们在启动必需数量的分片之前超时（默认情况下只是主分片），即使集群状态已成功更新以反映新创建的索引（即 `acknowledged=true`）

创建文档时，若index不存在，ES会自动创建对应的index和type

PUT /index/type/id

可用创建索引 API 将新索引添加到 Elasticsearch 集群。创建索引时，可指定：

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

请求正文

包含查询参数

CreateIndexRequest: PUT /bas_activity {
   "settings":{
   }}

@JsonpDeserializable
public class CreateIndexRequest extends RequestBase implements JsonpSerializable {
   
      // 可选，对象的对象) 索引的别名。`aliases` 对象的属性**`<alias>`**(必填，对象) 键是别名名称。索引别名名称支持 [日期数学]。对象正文包含别名的选项。支持空对象。`<alias>` 的属性**`filter`**(可选，[查询 DSL 对象]用于限制别名可以访问的文档的查询。**`index_routing`**(可选，字符串) 用于将索引操作路由到特定分片的 value。如果指定，这将覆盖索引操作的 `routing` value。**`is_hidden`**(可选，布尔值) 如果为 `true`，则别名是 [隐藏的]。默认值为 `false`。别名的所有索引必须具有相同的 `is_hidden` value。**`is_write_index`**(可选，布尔值) 如果为 `true`，则索引是别名的 [写入索引]。默认值为 `false`。**`routing`**(可选，字符串) 用于将索引和搜索操作路由到特定分片的 value。**`search_routing`**(可选，字符串) 用于将搜索操作路由到特定分片的 value。如果指定，这将覆盖搜索操作的 `routing` value。
    private final Map<String, Alias> aliases;

      // 路径参数 (必填，字符串) 要创建的索引的名称。索引名称必须符合以下条件仅限小写不能包含 `\`、`/`、`*`、`?`、`"`、`<`、`>`、`|`、` `（空格字符）、`,`、`#`7.0 之前的索引可以包含冒号 (`:`)，但这已弃用，在 7.0+ 中将不再支持不能以 `-`、`_`、`+` 开头不能是 `.` 或 `..`不能超过 255 个字节（注意是字节，所以多字节字符将更快地达到 255 个字节的限制）以 `.` 开头的名称已弃用，但 [隐藏索引]和插件管理的内部索引除外
    private final String index;

      // 可选，[映射对象]索引中字段的映射。如果指定，此映射可以包含字段名称[字段数据类型][映射参数]
    @Nullable
    private final TypeMapping mappings;

      // 可选，[时间单位](https://elastic.ac.cn/guide/en/elasticsearch/reference/current/api-conventions.html#time-units)) 等待主节点的时间段。如果在超时时间到期之前主节点不可用，则请求失败并返回错误。默认值为 `30s`。也可以设置为 `-1`，表示请求永远不会超时。
    @Nullable
    private final Time masterTimeout;

      // 可选，[索引设置对象]索引的配置选项
    @Nullable
    private final IndexSettings settings;

      // 可选，[时间单位]等待响应的时间段。如果在超时时间到期之前未收到响应，则请求失败并返回错误。默认值为 `30s`。
    @Nullable
    private final Time timeout;

      // (可选，字符串) 在继续操作之前必须处于活动状态的分片副本数量。设置为 `all` 或任何正整数，直到索引中的分片总数 (`number_of_replicas+1`)。默认值：1，主分片。请参阅 [活动分片](https://elastic.ac.cn/guide/en/elasticsearch/reference/current/docs-index_.html#index-wait-for-active-shards)。
    @Nullable
    private final WaitForActiveShards waitForActiveShards;

示例

索引设置

每个创建的索引都可以具有与其关联的特定设置，这些设置在正文中定义

PUT /my-index-000001
{
   
  "settings": {
   
    "index": {
   
      "number_of_shards": 3,  
      "number_of_replicas": 2 
    }
  }
}

• number_of_shards 的默认值为 1
• number_of_replicas 的默认值为 1（即每个主分片一个副本）

或更简化

PUT /my-index-000001
{
   
  "settings": {
   
    "number_of_shards": 3,
    "number_of_replicas": 2
  }
}

不必在 settings 部分中显式指定 index 部分。

有关创建索引时可以设置的所有不同索引级别设置的更多信息，请查看 索引模块 部分。

映射

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

PUT /test
{
   
  "settings": {
   
    "number_of_shards": 1
  },
  "mappings": {
   
    "properties": {
   
      "field1": {
    "type": "text" }
    }
  }
}

别名

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

PUT /test
{
   
  "aliases": {
   
    "alias_1": {
   },
    "alias_2": {
   
      "filter": {
   
        "term": {
    "user.id": "kimchy" }
      },
      "routing": "shard-1"
    }
  }
}

索引别名名称也支持 日期数学。

PUT /logs
{
   
  "aliases": {
   
    "<logs_{now/M}>": {
   }
  }
}

等待活动分片

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

{
   
  "acknowledged": true,
  "shards_acknowledged": true,
  "index": "logs"
}

可通过索引设置 index.write.wait_for_active_shards 更改仅等待主分片启动的默认值（请注意，更改此设置也会影响所有后续写入操作的 wait_for_active_shards value）

PUT /test
{
   
  "settings": {
   
    "index.write.wait_for_active_shards": "2"
  }
}

或通过请求参数 wait_for_active_shards

PUT /test?wait_for_active_shards=2

查看现有索引

GET _cat/indices

存在（exists）

检查数据流、索引或别名是否存在。

HEAD my-data-stream

请求

HEAD <目标>

路径参数

• <目标>

  (可选，字符串) 数据流、索引和别名的逗号分隔列表。支持通配符 (*)。

查询参数

public class ExistsRequest extends RequestBase {
   

      // (可选) false，则如果任何通配符表达式、[索引别名]或_all值仅针对缺少或关闭的索引，则请求将返回错误。即使请求针对其他打开的索引，此行为也适用。如索引以 `foo` 开头，但没有索引以 `bar` 开头，则针对 `foo*,bar*` 的请求将返回错误。默认 `true`
    @Nullable
    private final Boolean allowNoIndices;

      // (可选) 通配符模式可以匹配的索引类型。如果请求可以针对数据流，则此参数确定通配符表达式是否匹配隐藏的数据流。支持逗号分隔的值，例如 `open,hidden`。有效值为**`all`**匹配任何数据流或索引，包括 [隐藏]的数据流或索引。**`open`**匹配打开的、非隐藏的索引。还匹配任何非隐藏的数据流。**`closed`**匹配关闭的、非隐藏的索引。还匹配任何非隐藏的数据流。数据流不能关闭。**`hidden`**匹配隐藏的数据流和隐藏的索引。必须与 `open`、`closed` 或两者结合使用。**`none`**不接受通配符模式。默认为 `open`。
    private final List<ExpandWildcard> expandWildcards;

      // (可选) 如果为 `true`，则以扁平格式返回设置。默认为 `false`。
    @Nullable
    private final Boolean flatSettings;

      // (可选) 如果为 `false`，则如果请求针对缺少或关闭的索引，则请求将返回错误。默认为 `false`
    @Nullable
    private final Boolean ignoreUnavailable;

      // (可选) 如果为 `true`，则在响应中返回所有默认设置。默认为 `false`。
    @Nullable
    private final Boolean includeDefaults;

    private final List<String> index;

      // (可选) 如果为 `true`，则请求仅从本地节点检索信息。默认为 `false`，这意味着信息是从主节点检索的。
    @Nullable
    private final Boolean local;

ExistsRequest: HEAD /bas_activity

[HEAD http://localhost:9200/bas_activity/_doc/318799649324400640]

响应代码

• 200

  所有目标都存在。

• 404

  一个或多个指定的目标不存在。

删除

DELETE /test_index?pretty

删除一个或多个索引。

DeleteIndexRequest: DELETE /bas_activity

DELETE /my-index-000001

请求

DELETE /<index>

描述

删除索引会删除其文档、分片和元数据。 它不会删除相关的 Kibana 组件，例如数据视图、可视化或仪表板。

您无法删除数据流的当前写入索引。 要删除索引，您必须 滚动 数据流，以便创建新的写入索引。 然后，您可以使用删除索引 API 删除之前的写入索引。

路径参数

• <index>

  （必填，字符串）要删除的索引的逗号分隔列表。 不能指定 索引别名。默认情况下，此参数不支持通配符 (*) 或 _all。 要使用通配符或 _all，请将 action.destructive_requires_name 集群设置设置为 false。

查询参数

public class DeleteIndexRequest extends RequestBase {
   

      // （可选）如果为 `false`，则如果任何通配符表达式、[索引别名]或 `_all` 值仅针对缺少或关闭的索引，则请求将返回错误。 即使请求针对其他打开的索引，此行为也适用。 例如，如果索引以 `foo` 开头但没有索引以 `bar` 开头，则针对 `foo*,bar*` 的请求将返回错误。默认为 `true`
    @Nullable
    private final Boolean allowNoIndices;

      // （可选）通配符模式可以匹配的索引类型。 如果请求可以定位数据流，则此参数确定通配符表达式是否匹配隐藏数据流。 支持逗号分隔值，例如 `open,hidden`。 有效值为**`all`**匹配任何数据流或索引，包括 [隐藏的]数据流或索引。**`open`**匹配打开的、非隐藏的索引。 也匹配任何非隐藏的数据流。**`closed`**匹配关闭的、非隐藏的索引。 也匹配任何非隐藏的数据流。 数据流不能关闭。**`hidden`**匹配隐藏的数据流和隐藏的索引。 必须与 `open`、`closed` 或两者结合使用。**`none`**不接受通配符模式。默认为 `open,closed`
    private final List<ExpandWildcard> expandWildcards;

      // （可选）如果为 `false`，则如果请求针对缺少或关闭的索引，则该请求将返回错误。 默认为 `false`
    @Nullable
    private final Boolean ignoreUnavailable;

    private final List<String> index;

      // （可选，[时间单位]等待主节点的时间段。 如果在超时到期之前主节点不可用，则请求失败并返回错误。 默认为 `30s`。 也可以设置为 `-1` 以指示请求永不超时
    @Nullable
    private final Time masterTimeout;

      // （可选，[时间单位]等待响应的时间段。 如果在超时到期之前未收到任何响应，则请求失败并返回错误。 默认为 `30s`
    @Nullable
    private final Time timeout;