在上一篇中,我们总结了与索引属性相关的 API。本篇中,我们将介绍一些特殊的管理 API,包括索引模板 API,对索引的监控和状态管理 API,还有特别的悬空索引。

以下全部 API 可以参阅索引 API (opens new window)

# 索引模板

索引模板自动为新索引应用设置、映射以及别名。换句话讲,就是设置了模板的话,在创建新索引时,如果新索引符合模板的规则,那么新索引会自动应用模板中定义的索引相关的设置,不用自己再为每个新索引指定。

  • 创建或更新模板

    PUT /_index_template/<index-template>

    使用 PUT 方法,API 中需要在最后指定模板名字。而请求体中可以指定的参数比较多,示例如下:

    PUT /_index_template/template_1
    {
      "index_patterns" : ["te*"],
      "priority" : 1,
      "template": {
        "settings" : {
          "number_of_shards" : 2
        }
      }
    }
    
    • index_patterns 必填,且最重要的。代表匹配此模板的新索引。只要按此规则匹配上了,就会应用这个模板。
    • priority 可选,代表模板的优先级,默认为最低级 0。要注意的是,如果多个模板都匹配上新索引了,那么会使用优先级最高的模板。而且不能创建内容一样,优先级也一样的模板。
    • template 可选,代表所有应用于索引的属性配置。比如包含 aliasesmappingssettings
    • composed_of 可选,可以选择组成索引模板的组件模板名字,以组件模板来组合索引模板。
  • 获取索引模板

    GET /_index_template/<index-template>

    使用 GET 方法。API 中带上模板名字,名字中还可以使用星号作为通配符。

  • 删除索引模板

    DELETE /_index_template/<index-template>

    使用 DELETE 方法。API 中带上模板名字,还可以用逗号分隔多个名字。但需要注意,如果用多个名字的话,就不能用星号通配符。

  • 创建或更新组件模板

    组件模板是比索引模板还小的模板,可用来组成索引模板。

    PUT /_component_template/<component-template>

    使用 PUT 方法。API 中带上组件模板名字。示例如下:

    PUT _component_template/template_1
    {
      "template": {
        "settings": {
          "number_of_shards": 1
        },
        "mappings": {
          "_source": {
            "enabled": false
          },
          "properties": {
            "host_name": {
              "type": "keyword"
            },
            "created_at": {
              "type": "date",
              "format": "EEE MMM dd HH:mm:ss Z yyyy"
            }
          }
        }
      }
    }
    
    • template 必需的。代表索引相关的属性配置,包含 aliasesmappingssettings
  • 获取组件模板

    GET /_component_template/<component-template>

    使用 GET 方法。API 中带上组件模板名字,可以使用星号通配符。如果完全不写组件模板名字,就会查询出所有组件模板。

  • 删除组件模板

    DELETE /_component_template/<component-template>

    使用 DELETE 方法。API 中带上组件模板名字,可以用逗号分隔多个名字或者使用通配符。

  • 模拟索引

    实验性API 用来模拟如果创建一个新索引,应用索引模板后的索引配置会是哪些。

    POST /_index_template/_simulate_index/<index>

    使用 POST 方法。API 中还要带上模拟的索引的名字。要注意,虽然是 POST 方法,但是并不需要传递请求体数据。

  • 模拟索引模板 POST /_index_template/_simulate/<index-template>

    使用 POST 方法。API 中带上索引模板的名字。请求体和索引模板一样。

以上和模板相关的 API,我们可以看到,Elasticsearch 提供了索引模板增删查改相关的接口,还为索引模板提供了更细粒度的组件模板,让索引模板组合更灵活。更进一步,还提供了模拟接口,可以模拟验证创建索引和模板时生成的配置的具体情况。

# 监测

监控相关的 API,主要用来统计当前索引的一些信息。

  • 索引统计

    GET /<target>/_stats/<index-metric>
    GET /<target>/_stats
    GET /_stats
    

    使用 GET 方法。三种请求形式中,前后两个参数都是可选的。

    • <target> 可选,代表索引的名字,可以不填此参数,或者用 *_all,代表查所有索引的数据。
    • <index-metric>可选,要查询的指标值,包括 _allcompletiondocsfielddataflushgetindexingmergequery_cachequery_cacherefreshrequest_cachesearchsegmentsstoresuggest``translogwarmer

    具体想用哪些参数相关的统计信息,在用的时候再看文档查看即可,参阅索引统计 (opens new window)

  • 索引段

    GET /<target>/_segments
    GET /_segments
    

    使用 GET 方法。两种请求形式其实也只是一种。API 中的参数代表索引名称,如果忽略就代表所有索引。

    此 API 用于统计索引基于 Lucene 的索引段。

  • 索引恢复

    GET /<target>/_recovery
    GET /_recovery
    

    使用 GET 方法。两种请求形式是一种。API 中的参数代表索引名称,忽略则代表所有索引。

    此 API 用于获取正在进行和已完成的分片恢复的信息。

  • 索引分片存储

    GET /<target>/_shard_stores
    GET /_shard_stores
    

    使用 GET 方法。两种请求形式其实也是一种,同上面一样,API 中的参数代表索引名称,忽略则代表所有索引。

    此 API 获取索引中分片的存储信息。

    以上关于监测的 API,可以看到,主要是用于对索引的相关信息进行统计或查询,以了解当前索引的一个运行、占用相关的信息,主要用于常规的监控、检查等用途。

# 状态管理

  • 清除缓存

    POST /<target>/_cache/clear
    POST /_cache/clear
    

    使用 POST 方法。两种请求形式一致。API 中参数代表索引名称,忽略则代表所有索引。

    此 API 用于清除索引的缓存。

  • 刷新

    POST <target>/_refresh
    GET <target>/_refresh
    POST /_refresh
    GET /_refresh
    

    使用 GET 或者 POST 方法。API 中参数代表索引名称,忽略则代表所有索引。

    此 API 进行刷新后,可以使最近对一个或多个索引执行的操作可用于搜索。意思就是说如果你对索引做过一些操作,导致了它的数据变更或者属性变更,后台是需要一定时间才会将变更生效。在生效前,如果你执行搜索,这些变更是不会在搜索中被发现的,然后你想让这些变更立即生效,那就可以执行此 API 让 Elasticsearch 将这些变更立即生效。

    但这里,有一个矛盾的地方是,刷新是一个资源密集型操作,Elasticsearch 本身会按配置进行定时刷新,且刷新操作还是异步的。所以官方更多是建议在操作后添加刷新等待的参数 refresh=wait_for

  • 冲刷

    POST /<target>/_flushGET /<target>/_flushPOST /_flushGET /_flush
    

    使用 GETPOST 方法。API 中参数代表索引名称,忽略则代表所有索引。

    此 API 进行冲刷后,确保索引在事务日志中的数据永久存储在 Lucene 中。从英文来看,刷新的refresh和 冲刷的 flush,中文都有刷新的含义。二者在 API 中的语义区别是:刷新是把操作变更,更新到 Elasticsearch 中,这个时候可能还存储在事务日志中,但可被搜索获取到;而冲刷操作,则是把数据真实的永久存储到底层的 Lucene 中。

  • 同步冲刷

    7.6版本已废弃了,8.0将移除,看一眼就行了。

    POST /<index>/_flush/syncedGET /<index>/_flush/syncedPOST /_flush/syncedGET /_flush/synced
    
  • 强制合并

    POST /<target>/_forcemergePOST /_forcemerge
    

    使用 POST 方法。API 中参数代表索引名字,忽略或者传递*_all 代表所有索引。

    此 API 可以将索引的分片合并在一起,减少片段数,释放被删除文档使用的空间。实际上,官方提到强制合并对于管理数据流的旧备份索引和基于时间的索引非常有用。

以上 API 主要用于对索引的状态管理,人为的将索引的数据所在的状态、存储位置进行更新。

# 悬空索引

  • 列出悬空索引

    GET /_dangling

    使用 GET 方法。将所有悬空的索引列出。悬空索引是指,当前遇到的集群状态中缺少的索引数据,这些索引就会被认为悬空。要恢复的他们的话,可以使用下面的导入,如果不需要他们了,可以使用下面的删除。

  • 导入悬空索引

    POST /_dangling/<index-uuid>?accept_data_loss=true

    使用 POST 方法。API 中参数是必填的,表示要导入的索引的 UUID。

  • 删除悬空索引

    DELETE /_dangling/<index-uuid>?accept_data_loss=true

    使用 DELETE 方法。API 中的参数必填的,表示要删除的索引的 UUID。

本篇所介绍的 API 主要用于对索引本身状态、存储的相关管理,一般使用 Elasticsearch 的情况下,我们可能较少使用这些 API。当开始进阶时,可能才会慢慢使用这些 API 来辅助我们对 Elasticsearch 的高级使用。

通过连续三篇的介绍,我们初步了解了关于索引的一些 API,包括对索引的管理(增删查改),对索引相关属性的介绍(映射、设置、别名),以及本篇对索引的特殊管理(状态、存储)。

接下来我们将对最核心的搜索相关 API 进行介绍,毕竟 Elasticsearch 离不开的,就是一个 搜索/search