Elasticsearch REST API 索引管理

创建索引

PUT /<index>

路径参数索引名 <index>

• 只能是小写字符串
• 不能包括 \，/， *， ?， "， <， >， |， 空格，#，逗号、冒号（7.0之前支持）等特殊字符（“.”，“…”等也不允许）
• 不能以 -，_，+等开头
• 不能超过 255 个字节（注意是字节不是字符长度）
• 以 . 开头的名称已弃用，隐藏索引和插件管理的内部索引才允许以 . 开头

查询参数

• wait_for_active_shards
  （可选，字符串）在继续操作之前必须处于活动状态的分片副本数。设置为all或正整数，最多为索引中分片的总数 ( number_of_replicas+1)。默认值：1，主分片。
• master_timeout
  （可选，时间单位）等待连接到主节点的时间。如果在超时到期之前未收到响应，则请求失败并返回错误。默认为 30s.
• timeout
  （可选，时间单位）等待响应的时间。如果在超时到期之前未收到响应，则请求失败并返回错误。默认为30s.

wait_for_active_shards 是 elastic 为了提高写入系统的弹性，可以将索引操作配置为等待一定数量的活动分片副本，然后再继续操作。如果所需数量的活动分片副本不可用，则写入操作必须等待并重试，直到所需的分片副本已启动或发生超时。

请求正文

• aliases
  （可选，对象的对象）索引的别名列表。
  • <alias> 别名名称
    • filter
      （可选，查询 DSL 对象）用于限制别名可以访问的文档的查询。
    • index_routing
      （可选，字符串）用于将索引操作路由到特定分片的值。如果指定，这将覆盖routing索引操作的值。
    • is_hidden
      （可选，布尔值）true，则隐藏别名。默认为 . 别名的所有索引必须具有相同的值。 falseis_hidden
    • is_write_index
      （可选，布尔值）true，索引是别名的写入索引。默认为false.
    • routing
      （可选，字符串）用于将索引和搜索操作路由到特定分片的值。
    • search_routing
      （可选，字符串）用于将搜索操作路由到特定分片的值。如果指定，这将覆盖routing搜索操作的值。
• mappings
  （可选，映射对象）索引中字段的映射。如果指定，此映射可以包括：
  • 字段名称
  • 字段数据类型
  • 映射参数
• settings
  （可选，索引设置对象）索引的配置选项。

mappings 我们将在后续讲解，此处理解为不设置 Mappings

示例

PUT /person

此为最简便的创建，没有设置别名、mappings、settings

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

acknowledged 表示是否在集群中成功创建索引

shards_acknowledged 表示在超时之前是否为索引中的每个分片启动了必要数量的分片副本

查询索引

GET /<index>

路径参数

<target>
（必需，字符串）用于限制请求的数据流、索引和别名的逗号分隔列表。支持通配符 ( *)。要定位所有索引，省略此参数或使用 * 或者 _all

查询参数

• allow_no_indices
  （可选，布尔值）如果 为false，任何通配符表达式、索引别名或值目标仅丢失或关闭索引，请求将返回错误 。例如，如果请求索引以 foo*,bar* 开头，如果有索引，以foo开头但没有索引以bar开头，则请求定位会返回错误。 默认为true.
• expand_wildcards
  （可选，字符串）通配符模式可以匹配的索引类型。默认为open。支持逗号分隔值，例如open,hidden. 有效值为：
  • all
    匹配任何数据流或索引，包括隐藏的。
  • open
    匹配开放的、非隐藏的索引。也匹配任何非隐藏数据流。
  • closed
    匹配封闭的、非隐藏的索引。也匹配任何非隐藏数据流。数据流无法关闭。
  • hidden
    匹配隐藏的数据流和隐藏的索引。open必须与、 closed或两者 结合使用。
  • none
    不接受通配符模式。
• features
  （可选，字符串）返回有关特定索引功能的信息。支持逗号分隔值。有效值为aliases、mappings和settings。默认为aliases,mappings,settings.
• flat_settings
  （可选，布尔值）true，则以平面格式返回设置。默认为 false.
• include_defaults
  （可选，布尔值）true，则在响应中返回所有默认设置。默认为false.
• ignore_unavailable
  （可选，布尔值）false，以缺失索引为目标的请求将返回错误。默认为 false.
• local
  （可选，布尔值）true，则请求仅从本地节点检索信息。默认为false，这意味着信息是从主节点检索的。
• master_timeout
  （可选，时间单位）等待连接到主节点的时间。如果在超时到期之前未收到响应，则请求失败并返回错误。默认为 30s.

示例

GET /person

{
    "person": {
        "aliases": {},
        "mappings": {},
        "settings": {
            "index": {
                "routing": {
                    "allocation": {
                        "include": {
                            "_tier_preference": "data_content"
                        }
                    }
                },
                "number_of_shards": "1",
                "provided_name": "person",
                "creation_date": "1680685456227",
                "number_of_replicas": "1",
                "uuid": "X2YU2E_dRoGfCdSHYtHYiA",
                "version": {
                    "created": "8060299"
                }
            }
        }
    }
}

我们在创建的时候没有设置settings，目前这些信息为默认添加

number_of_shards：分片数；number_of_replicas：副本数；creation_date：创建时间

删除索引

DELETE /<index>

路径参数

（必需，字符串）要删除的索引的逗号分隔列表。不能指定索引别名。

查询参数

• allow_no_indices
  （可选，布尔值）如果 为false，任何通配符表达式、索引别名或值目标仅丢失或关闭索引，请求将返回错误 。例如，如果请求索引以 foo*,bar* 开头，如果有索引，以foo开头但没有索引以bar开头，则请求定位会返回错误。 默认为true.
• expand_wildcards
  （可选，字符串）通配符模式可以匹配的索引类型。如果请求可以针对数据流，则此参数确定通配符表达式是否匹配隐藏的数据流。支持逗号分隔值。默认为open,closed。例如open,hidden. 有效值为：
  • all
    匹配任何数据流或索引，包括隐藏的。
  • open
    匹配开放的、非隐藏的索引。也匹配任何非隐藏数据流。
  • closed
    匹配封闭的、非隐藏的索引。也匹配任何非隐藏数据流。数据流无法关闭。
  • hidden
    匹配隐藏的数据流和隐藏的索引。open必须与、 closed或两者 结合使用。
  • none
    不接受通配符模式。
• ignore_unavailable
  （可选，布尔值）false，如果请求针对丢失或关闭的索引，则请求返回错误。默认为false.
• master_timeout
  （可选，时间单位）等待连接到主节点的时间。如果在超时到期之前未收到响应，则请求失败并返回错误。默认为 30s.
• timeout
  （可选，时间单位）等待响应的时间。如果在超时到期之前未收到响应，则请求失败并返回错误。默认为30s.

示例

DELETE /person

{
    "acknowledged": true
}

删除别名

DELETE <target>/_alias/<alias>

DELETE <target>/_aliases/<alias>

查询参数

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

查询索引是否存在

HEAD <target>

路径参数

• target 要查询的索引名

查询参数

• allow_no_indices
  （可选，布尔值）如果 为false，任何通配符表达式、索引别名或值目标仅丢失或关闭索引，请求将返回错误 。例如，如果请求索引以 foo*,bar* 开头，如果有索引，以foo开头但没有索引以bar开头，则请求定位会返回错误。 默认为true.
• expand_wildcards
  （可选，字符串）通配符模式可以匹配的索引类型。默认为open。支持逗号分隔值，例如open,hidden. 有效值为：
  • all
    匹配任何数据流或索引，包括隐藏的。
  • open
    匹配开放的、非隐藏的索引。也匹配任何非隐藏数据流。
  • closed
    匹配封闭的、非隐藏的索引。也匹配任何非隐藏数据流。数据流无法关闭。
  • hidden
    匹配隐藏的数据流和隐藏的索引。open必须与、 closed或两者 结合使用。
  • none
    不接受通配符模式。
• flat_settings
  （可选，布尔值）true，则以平面格式返回设置。默认为 false.
• include_defaults
  （可选，布尔值）true，则在响应中返回所有默认设置。默认为false.
• ignore_unavailable
  （可选，布尔值）false，以缺失索引为目标的请求将返回错误。默认为 false.
• local
  （可选，布尔值）true，则请求仅从本地节点检索信息。默认为false，这意味着信息是从主节点检索的。

示例

HEAD /person

响应

此接口响应没有响应体。直接通过HTTP的响应状态判断。

• 200 表示索引存在
• 404 表示索引不存在

别名是否存在

HEAD _alias/<alias>

HEAD <target>/_alias/<alias>

参数和响应与索引是否存在如出一辙，此处就不详细说明了。

索引的 _cat API

GET /_cat/indices/<target>

GET /_cat/indices

路径参数

• target
  可选，字符串）用于限制请求的数据流、索引和别名的逗号分隔列表。支持通配符 （ * ），* 等同于 all。

查询参数

• bytes
  （可选，字节大小单位）用于显示字节值的单位。b、kb、mb、gb、tb、pb

• format
  （可选，字符串）格式化方式。有效值包括 text (默认) 、 json 、 smile 、 yaml 、 cbor

• h
  （可选，字符串）要显示的以逗号分隔的列名列表

• health
  （可选，字符串）用于限制返回索引的健康状态。有效值为：

  • green 群集是健康的
  • yellow 集群的功能处于降级状态，可能需要修复以避免健康状况恶化red（单机情况下，为yellow）
  • red 集群遇到中断或某些功能不可用
  • unknown 无法确定群集的运行状况

• help
  （可选，布尔值）true，则响应包括帮助信息。默认为false.

• include_unloaded_segments
  （可选，布尔值）true，则响应包括来自未加载到内存中的段的信息。默认为false.

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

• pri（主要分片）
  （可选，布尔值）true，则响应仅包含来自主分片的信息。默认为false.

• s
  （可选，字符串）用于对响应进行排序的列名或列别名的逗号分隔列表。

• time
  （可选，时间单位）用于显示时间值的单位。d、h、m、s、ms、micros（微妙）、nanos（纳秒）

• v
  （可选，布尔值）true，则响应包括列标题。默认为false.

• expand_wildcards
  （可选，字符串）通配符模式可以匹配的索引类型。如果请求可以针对数据流，则此参数确定通配符表达式是否匹配隐藏的数据流。支持逗号分隔值，例如open,hidden. 有效值为：

  • all
    匹配任何数据流或索引，包括隐藏的。
  • open
    匹配开放的、非隐藏的索引。也匹配任何非隐藏数据流。
  • closed
    匹配封闭的、非隐藏的索引。也匹配任何非隐藏数据流。数据流无法关闭。
  • hidden
    匹配隐藏的数据流和隐藏的索引。open必须与、 closed或两者 结合使用。
  • none
    不接受通配符模式。

示例

GET /_cat/indices/person?format=json

响应结果

[
    {
        "health": "yellow",
        "status": "open",
        "index": "person",
        "uuid": "X2YU2E_dRoGfCdSHYtHYiA",
        "pri": "1",
        "rep": "1",
        "docs.count": "1",
        "docs.deleted": "1",
        "store.size": "8.3kb",
        "pri.store.size": "8.3kb"
    }
]

修改索引设置

PUT /<target>/_settings

路径参数

<target>：（可选，字符串）用于限制请求的数据流、索引和别名的逗号分隔列表。支持通配符 ( *)。

查询参数

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

请求正文

• settings
  （可选，索引设置对象）索引的配置选项。

此接口可以设置索引的分析器、分片、副本、映射等，具体的设置我们将在对应的部分进行详细讲解，此处先做了解即可。

关闭索引

POST /<index>/_close

打开索引

POST /<target>/_open

打开和关闭索引的参数和其他的索引操作差别不大，而且也使用的很少，所以此处就不再描述了。