Index APIs | Elasticsearch Guide

别名存在 API

检查是否存在别名。

HEAD _alias/my-alias

请求

edit

HEAD _alias/

HEAD /_alias/

先决条件

edit

如果启用了Elasticsearch安全功能，您必须拥有 view_index_metadata 或 manage 索引权限用于别名。如果您指定了目标，您还必须拥有 view_index_metadata 或 manage 目标索引的权限。

路径参数

edit

<alias>: (可选，字符串) 要检查的别名列表，以逗号分隔。支持通配符 (*)。
<target>: (可选，字符串) 用于限制请求的逗号分隔的数据流或索引列表。支持通配符 (*)。要针对所有数据流和索引，请省略此参数或使用 * 或 _all。

查询参数

edit

expand_wildcards

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

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

默认为 all。

ignore_unavailable

(可选，布尔值) 如果为false，请求中包含在中缺失的数据流或索引时将返回错误。默认为false。

local

(可选，布尔值) 如果 true，请求仅从本地节点检索信息。默认为 false，这意味着信息从主节点检索。

响应代码

edit

200: 所有指定的别名都存在。
404: 一个或多个指定的别名不存在。

别名 API

edit

在一个原子操作中执行一个或多个别名操作。

POST _aliases
{
  "actions": [
    {
      "add": {
        "index": "my-data-stream",
        "alias": "my-alias"
      }
    }
  ]
}

请求

edit

POST _aliases

先决条件

edit

如果启用了Elasticsearch安全功能，您必须拥有以下索引权限：
- 要使用add或remove操作，您必须拥有别名及其数据流或索引的manage索引权限。
- 要使用remove_index操作，您必须拥有该索引的manage索引权限。

查询参数

edit

master_timeout: (可选，时间单位) 等待主节点的时间段。如果在超时到期之前主节点不可用，请求将失败并返回错误。默认为30s。也可以设置为-1，表示请求不应超时。
timeout: (可选，时间单位) 在更新集群元数据后，等待集群中所有相关节点响应的时间段。如果在超时到期之前未收到响应，集群元数据更新仍然适用，但响应将表明它未被完全确认。默认为 30s。也可以设置为 -1 以指示请求不应超时。

请求体

edit

actions

(必需，对象数组) 要执行的操作。

Properties of actions objects

(必需，对象) 键是操作类型。至少需要一个操作。

Valid keys

add: 添加一个数据流或索引到别名。如果别名不存在，add 操作会创建它。
remove: 从别名中移除一个数据流或索引。
remove_index: 删除一个索引。你不能对别名或数据流使用此操作。

对象体包含别名的选项。支持空对象。

Properties of

alias: (Required*, string) 操作的别名。索引别名名称支持日期数学。如果未指定 aliases，add 和 remove 操作需要此参数。对于 remove 操作，此参数支持通配符 (*)。remove_index 操作不支持此参数。
aliases: (Required*, array of strings) 操作的别名。索引别名名称支持日期数学。如果未指定 alias，add 和 remove 操作需要此参数。对于 remove 操作，此参数支持通配符 (*)。remove_index 操作不支持此参数。

filter

(可选, Query DSL 对象用于限制别名可以访问的文档的查询。

只有 add 操作支持此参数。

index

(Required*, string) 操作的数据流或索引。支持通配符 (*)。如果未指定 indices，此参数是必需的。对于 add 和 remove_index 操作，匹配数据流和索引的通配符模式会返回错误。

indices

(Required*, array of strings) 操作的数据流或索引。支持通配符 (*)。如果未指定 index，此参数是必需的。对于 add 和 remove_index 操作，匹配数据流和索引的通配符模式会返回错误。

index_routing

(可选，字符串) 用于将索引操作路由到特定分片的值。如果指定，这将覆盖索引操作的 routing 值。数据流别名不支持此参数。

仅 add 操作支持此参数。

is_hidden

(可选，布尔值) 如果为 true，别名是隐藏的。默认为 false。别名的所有数据流或索引必须具有相同的 is_hidden 值。

只有 add 操作支持此参数。

is_write_index

(可选，布尔值) 如果 true，则为别名设置写索引或数据流。

如果一个别名指向多个索引或数据流，并且未设置 is_write_index，则该别名会拒绝写请求。如果一个索引别名指向一个索引，并且未设置 is_write_index，则该索引会自动充当写索引。即使别名指向一个数据流，数据流别名也不会自动设置写数据流。

只有 add 操作支持此参数。

must_exist

(可选, 布尔值) 影响尝试删除不存在的别名时的行为。如果 true，删除不存在的别名将导致所有操作失败。如果 false，删除不存在的别名只会导致该删除操作失败。默认为 false。

仅 remove 操作支持此参数。

routing

（可选，字符串）用于将索引和搜索操作路由到特定分片的值。数据流别名不支持此参数。

只有 add 操作支持此参数。

search_routing

(可选，字符串) 用于将搜索操作路由到特定分片的值。如果指定，这将覆盖搜索操作的 routing 值。数据流别名不支持此参数。

只有 add 操作支持此参数。

响应体

edit

acknowledged

(布尔值) 如果true，请求在timeout时间内从主节点收到了响应。

errors

(布尔值) 如果true，则至少有一个请求的操作失败。

action_results

(可选，对象数组) 每个请求操作的结果。

Properties of action_results objects

action

(对象) 关联操作请求的描述。

Properties of action object

type: (字符串) 关联操作的类型，可以是 add、remove 或 remove_index 之一。
indices: (字符串数组) 关联操作中的索引列表。
aliases: (字符串数组) 关联操作中的别名列表。

status

(整数) 操作返回的HTTP状态码。

error

(可选，对象) 包含有关失败操作的附加信息。

仅在操作失败时显示。

分析 API

edit

对文本字符串执行分析并返回生成的标记。

GET /_analyze
{
  "analyzer" : "standard",
  "text" : "Quick Brown Foxes!"
}

请求

edit

GET /_analyze

POST /_analyze

GET //_analyze

POST //_analyze

前提条件

edit

如果启用了Elasticsearch安全功能，您必须拥有指定索引的manage 索引权限。

路径参数

edit

<index>

(可选，字符串) 用于派生分析器的索引。

如果指定， analyzer 或参数将覆盖此值。

如果没有指定分析器或字段，分析API将使用索引的默认分析器。

如果没有指定索引或者索引没有默认的分析器，分析API使用标准分析器。

查询参数

edit

analyzer

(可选, 字符串) 应用于提供的 text 的分析器的名称。这可以是内置分析器，或者是已在索引中配置的分析器。

如果未指定此参数， analyze API 将使用字段映射中定义的分析器。

如果没有指定字段， analyze API 使用索引的默认分析器。

如果没有指定索引，或者索引没有默认的分析器， analyze API 使用标准分析器。

attributes

(可选, 字符串数组) 用于过滤 explain 参数输出的标记属性数组。

char_filter

(可选，字符串数组) 用于在分词器之前预处理字符的字符过滤器数组。请参阅字符过滤器参考以获取字符过滤器列表。

explain

(可选, 布尔值) 如果为true，响应将包含令牌属性和其他详细信息。默认为false。 [预览] 其他详细信息的格式在Lucene中被标记为实验性，并且可能会在将来发生变化。

field

(可选, 字符串) 用于派生分析器的字段。要使用此参数，您必须指定一个索引。

如果指定， analyzer 参数将覆盖此值。

如果没有指定字段， analyze API 使用索引的默认分析器。

如果没有指定索引或者索引没有默认的分析器， analyze API 使用标准分析器。

filter

(可选，字符串数组) 用于在分词器之后应用的令牌过滤器数组。请参阅令牌过滤器参考以获取令牌过滤器列表。

normalizer

(可选, 字符串) 用于将文本转换为单个标记的规范化器。请参阅规范化器以获取规范化器列表。

text

(必需，字符串或字符串数组) 要分析的文本。如果提供了字符串数组，则将其作为多值字段进行分析。

tokenizer

(可选，字符串) 用于将文本转换为标记的分词器。请参阅分词器参考以获取分词器列表。

示例

edit

未指定索引

edit

您可以将任何内置分析器应用于文本字符串，而无需指定索引。

GET /_analyze
{
  "analyzer" : "standard",
  "text" : "this is a test"
}

文本字符串数组

edit

如果提供了作为字符串数组的text参数，它将被分析为多值字段。

GET /_analyze
{
  "analyzer" : "standard",
  "text" : ["this is a test", "the second text"]
}

自定义分析器

edit

您可以使用 analyze API 来测试从分词器、分词过滤器和字符过滤器构建的自定义瞬态分析器。分词过滤器使用 filter 参数：

GET /_analyze
{
  "tokenizer" : "keyword",
  "filter" : ["lowercase"],
  "text" : "this is a test"
}

GET /_analyze
{
  "tokenizer" : "keyword",
  "filter" : ["lowercase"],
  "char_filter" : ["html_strip"],
  "text" : "this is a <b>test</b>"
}

自定义分词器、词元过滤器和字符过滤器可以在请求体中按如下方式指定：

GET /_analyze
{
  "tokenizer" : "whitespace",
  "filter" : ["lowercase", {"type": "stop", "stopwords": ["a", "is", "this"]}],
  "text" : "this is a test"
}

特定索引

edit

您也可以针对特定索引运行分析 API：

GET /analyze_sample/_analyze
{
  "text" : "this is a test"
}

上述代码将对“this is a test”文本进行分析，使用与analyze_sample索引关联的默认索引分析器。也可以提供一个analyzer来使用不同的分析器：

GET /analyze_sample/_analyze
{
  "analyzer" : "whitespace",
  "text" : "this is a test"
}

从字段映射派生分析器

edit

分析器可以根据字段映射推导出来，例如：

GET /analyze_sample/_analyze
{
  "field" : "obj1.field1",
  "text" : "this is a test"
}

将基于在映射中为 obj1.field1 配置的分析器进行分析（如果没有配置，则使用默认的索引分析器）。

规范化器

edit

可以为带有与analyze_sample索引关联的normalizer的关键字字段提供normalizer。

GET /analyze_sample/_analyze
{
  "normalizer" : "my_normalizer",
  "text" : "BaR"
}

或者通过构建一个自定义的瞬态规范化器，使用令牌过滤器和字符过滤器。

GET /_analyze
{
  "filter" : ["lowercase"],
  "text" : "BaR"
}

解释分析

edit

如果您想获取更详细的细节，请将 explain 设置为 true（默认为 false）。它将输出每个标记的所有标记属性。您可以通过设置 attributes 选项来过滤您想要输出的标记属性。

附加详细信息的格式在Lucene中被标记为实验性的，并且可能会在将来发生变化。

GET /_analyze
{
  "tokenizer" : "standard",
  "filter" : ["snowball"],
  "text" : "detailed output",
  "explain" : true,
  "attributes" : ["keyword"] 
}

将“keyword”设置为仅输出“keyword”属性

请求返回以下结果：

{
  "detail" : {
    "custom_analyzer" : true,
    "charfilters" : [ ],
    "tokenizer" : {
      "name" : "standard",
      "tokens" : [ {
        "token" : "detailed",
        "start_offset" : 0,
        "end_offset" : 8,
        "type" : "<ALPHANUM>",
        "position" : 0
      }, {
        "token" : "output",
        "start_offset" : 9,
        "end_offset" : 15,
        "type" : "<ALPHANUM>",
        "position" : 1
      } ]
    },
    "tokenfilters" : [ {
      "name" : "snowball",
      "tokens" : [ {
        "token" : "detail",
        "start_offset" : 0,
        "end_offset" : 8,
        "type" : "<ALPHANUM>",
        "position" : 0,
        "keyword" : false 
      }, {
        "token" : "output",
        "start_offset" : 9,
        "end_offset" : 15,
        "type" : "<ALPHANUM>",
        "position" : 1,
        "keyword" : false 
      } ]
    } ]
  }
}

仅输出“keyword”属性，因为请求中指定了“attributes”。

设置令牌限制

edit

生成过多的令牌可能会导致节点内存不足。以下设置允许限制可以生成的令牌数量：

index.analyze.max_token_count: 使用 _analyze API 可以生成的最大令牌数。默认值是 10000。如果生成的令牌数超过此限制，将会抛出一个错误。未指定索引的 _analyze 端点将始终使用 10000 值作为限制。此设置允许您控制特定索引的限制：

PUT /analyze_sample
{
  "settings" : {
    "index.analyze.max_token_count" : 20000
  }
}

GET /analyze_sample/_analyze
{
  "text" : "this is a test"
}

分析索引磁盘使用情况 API

edit

此功能处于技术预览阶段，可能会在未来的版本中进行更改或移除。Elastic 将努力修复任何问题，但技术预览版中的功能不受官方 GA 功能支持 SLA 的约束。

分析索引或数据流中每个字段的磁盘使用情况。此API可能不支持在以前的Elasticsearch版本中创建的索引。小型索引的结果可能不准确，因为索引的某些部分可能不会被API分析。

POST /my-index-000001/_disk_usage?run_expensive_tasks=true

请求

edit

POST //_disk_usage

前提条件

edit

如果启用了Elasticsearch安全功能，您必须拥有目标索引、数据流或别名的manage 索引权限。

路径参数

edit

<target>: (必需，字符串) 用于限制请求的逗号分隔的数据流、索引和别名列表。建议使用单个索引（或数据流的最新后备索引）执行此API，因为该API会显著消耗资源。

查询参数

edit

allow_no_indices

(可选, 布尔值) 如果为false，当任何通配符表达式、索引别名或_all值仅针对缺失或关闭的索引时，请求将返回错误。即使请求针对其他打开的索引，此行为也适用。例如，如果一个请求针对foo*,bar*，但没有任何索引以bar开头，即使存在以foo开头的索引，请求也会返回错误。

默认为 true。

expand_wildcards

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

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

默认为 open。

flush

(可选，布尔值) 如果 true，API 在分析之前执行刷新操作。如果 false，响应可能不包括未提交的数据。默认为 true。

ignore_unavailable

(可选，布尔值) 如果为false，则当请求目标是一个缺失或关闭的索引时，请求将返回错误。默认为false。

run_expensive_tasks

(必需，布尔值) 分析字段磁盘使用是资源密集型的。要使用此API，此参数必须设置为 true。默认为 false。

wait_for_active_shards

(可选，字符串) 在继续操作之前，必须处于活动状态的每个分片的副本数量。设置为 all 或任何非负整数，最大不超过索引中每个分片的副本总数（number_of_replicas+1）。默认为 1，表示仅等待每个主分片处于活动状态。

请参阅Active shards。

示例

edit

POST /my-index-000001/_disk_usage?run_expensive_tasks=true

API返回：

{
    "_shards": {
        "total": 1,
        "successful": 1,
        "failed": 0
    },
    "my-index-000001": {
        "store_size": "929mb", 
        "store_size_in_bytes": 974192723,
        "all_fields": {
            "total": "928.9mb", 
            "total_in_bytes": 973977084,
            "inverted_index": {
                "total": "107.8mb",
                "total_in_bytes": 113128526
            },
            "stored_fields": "623.5mb",
            "stored_fields_in_bytes": 653819143,
            "doc_values": "125.7mb",
            "doc_values_in_bytes": 131885142,
            "points": "59.9mb",
            "points_in_bytes": 62885773,
            "norms": "2.3kb",
            "norms_in_bytes": 2356,
            "term_vectors": "2.2kb",
            "term_vectors_in_bytes": 2310,
            "knn_vectors": "0b",
            "knn_vectors_in_bytes": 0
        },
        "fields": {
            "_id": {
                "total": "49.3mb",
                "total_in_bytes": 51709993,
                "inverted_index": {
                    "total": "29.7mb",
                    "total_in_bytes": 31172745
                },
                "stored_fields": "19.5mb", 
                "stored_fields_in_bytes": 20537248,
                "doc_values": "0b",
                "doc_values_in_bytes": 0,
                "points": "0b",
                "points_in_bytes": 0,
                "norms": "0b",
                "norms_in_bytes": 0,
                "term_vectors": "0b",
                "term_vectors_in_bytes": 0,
                "knn_vectors": "0b",
                "knn_vectors_in_bytes": 0
            },
            "_primary_term": {...},
            "_seq_no": {...},
            "_version": {...},
            "_source": {
                "total": "603.9mb",
                "total_in_bytes": 633281895,
                "inverted_index": {...},
                "stored_fields": "603.9mb", 
                "stored_fields_in_bytes": 633281895,
                "doc_values": "0b",
                "doc_values_in_bytes": 0,
                "points": "0b",
                "points_in_bytes": 0,
                "norms": "0b",
                "norms_in_bytes": 0,
                "term_vectors": "0b",
                "term_vectors_in_bytes": 0,
                "knn_vectors": "0b",
                "knn_vectors_in_bytes": 0
            },
            "context": {
                "total": "28.6mb",
                "total_in_bytes": 30060405,
                "inverted_index": {
                    "total": "22mb",
                    "total_in_bytes": 23090908
                },
                "stored_fields": "0b",
                "stored_fields_in_bytes": 0,
                "doc_values": "0b",
                "doc_values_in_bytes": 0,
                "points": "0b",
                "points_in_bytes": 0,
                "norms": "2.3kb",
                "norms_in_bytes": 2356,
                "term_vectors": "2.2kb",
                "term_vectors_in_bytes": 2310,
                "knn_vectors": "0b",
                "knn_vectors_in_bytes": 0
            },
            "context.keyword": {...},
            "message": {...},
            "message.keyword": {...}
        }
    }
}

	仅分析索引的分片存储大小。
	索引分析分片的字段总大小。这个总和通常小于在<1>中指定的索引大小，因为一些小的元数据文件被忽略，并且数据文件的某些部分可能不会被API扫描。
	存储的 `_id` 字段的大小
	存储的 `_source` 字段的大小。由于存储字段以压缩格式存储在一起，存储字段的大小是估计值，可能不准确。`_id` 字段的存储大小可能被低估，而 `_source` 字段的存储大小可能被高估。

清除缓存 API

edit

清除一个或多个索引的缓存。对于数据流，该API会清除数据流的备份索引的缓存。

POST /my-index-000001/_cache/clear

请求

edit

POST //_cache/clear

POST /_cache/clear

先决条件

edit

如果启用了Elasticsearch安全功能，您必须拥有目标数据流、索引或别名的manage 索引权限。

路径参数

edit

<target>: (可选，字符串) 用于限制请求的逗号分隔的数据流、索引和别名列表。支持通配符 (*)。要针对所有数据流和索引，请省略此参数或使用 * 或 _all。

查询参数

edit

allow_no_indices

(可选, 布尔值) 如果为false，当任何通配符表达式、索引别名或_all值仅针对缺失或关闭的索引时，请求将返回错误。即使请求针对其他打开的索引，此行为也适用。例如，如果一个请求针对foo*,bar*，但没有任何索引以bar开头，即使存在以foo开头的索引，请求也会返回错误。

默认为 true。

expand_wildcards

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

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

默认为 open。

fielddata

(可选, 布尔值) 如果 true, 清除字段缓存。

使用 fields 参数来清除特定字段的缓存。

fields

(可选, 字符串) 用于限制 fielddata 参数的字段名称的逗号分隔列表。

默认为所有字段。

此参数不支持对象或字段别名。

index

(可选, 字符串) 用于限制请求的索引名称的逗号分隔列表。

ignore_unavailable

(可选，布尔值) 如果为false，则当请求目标是一个缺失或关闭的索引时，请求将返回错误。默认为false。

query

(可选, 布尔值) 如果为true，则清除查询缓存。

request

(可选, 布尔值) 如果 true, 清除请求缓存。

示例

edit

清除特定缓存

edit

默认情况下，清除缓存 API 会清除所有缓存。您可以通过将以下查询参数设置为 true 来仅清除特定缓存：

fielddata
查询
请求

POST /my-index-000001/_cache/clear?fielddata=true  
POST /my-index-000001/_cache/clear?query=true      
POST /my-index-000001/_cache/clear?request=true

	仅清除字段缓存
	仅清除查询缓存
	仅清除请求缓存

清除特定字段的缓存

edit

要仅清除特定字段的缓存，请使用fields查询参数。

POST /my-index-000001/_cache/clear?fields=foo,bar

清除foo和bar字段的缓存

清除多个数据流和索引的缓存

edit

POST /my-index-000001,my-index-000002/_cache/clear

清除所有数据流和索引的缓存

edit

POST /_cache/clear

克隆索引 API

edit

克隆一个现有的索引。

POST /my-index-000001/_clone/cloned-my-index-000001

请求

edit

POST //_clone/

PUT //_clone/

先决条件

edit

如果启用了Elasticsearch安全功能，您必须拥有要克隆的索引的管理 索引权限。
要克隆索引，索引必须被标记为只读，并且具有集群健康状态为绿色。

例如，以下请求阻止对 my_source_index 的写操作，因此可以使用添加索引块 API 进行克隆。仍然允许删除索引等元数据更改。

PUT /my_source_index/_block/write

数据流上的当前写入索引无法被克隆。为了克隆当前的写入索引，数据流必须首先被滚动更新，以便创建一个新的写入索引，然后可以克隆之前的写入索引。

描述

edit

使用克隆索引 API 将现有索引克隆到一个新索引中，其中每个原始主分片都会被克隆到新索引中的一个新主分片中。

Elasticsearch 不会将索引模板应用于生成的索引。该 API 也不会从原始索引复制索引元数据。索引元数据包括别名、ILM 阶段定义和 CCR 跟随者信息。例如，如果您克隆一个 CCR 跟随者索引，生成的克隆将不会是跟随者索引。

克隆 API 将大多数索引设置从源索引复制到生成的索引，但 index.number_of_replicas 和 index.auto_expand_replicas 除外。要在生成的索引中设置副本数量，请在克隆请求中配置这些设置。

克隆的工作原理

edit

克隆的工作原理如下：

首先，它会创建一个与源索引定义相同的新目标索引。
然后，它将源索引中的段硬链接到目标索引中。（如果文件系统不支持硬链接，则所有段都会被复制到新索引中，这是一个更加耗时的过程。）
最后，它会像刚刚重新打开的已关闭索引一样恢复目标索引。

克隆一个索引

edit

要将 my_source_index 克隆到一个名为 my_target_index 的新索引中，请发出以下请求：

POST /my_source_index/_clone/my_target_index

上述请求在目标索引被添加到集群状态后立即返回——它不会等待克隆操作开始。

索引只有在满足以下要求时才能被克隆：

目标索引必须不存在。
源索引的主分片数量必须与目标索引相同。
处理克隆过程的节点必须有足够的可用磁盘空间来容纳现有索引的第二个副本。

The _clone API 类似于 create index API 并且接受目标索引的 settings 和 aliases 参数：

POST /my_source_index/_clone/my_target_index
{
  "settings": {
    "index.number_of_shards": 5 
  },
  "aliases": {
    "my_search_indices": {}
  }
}

目标索引中的分片数量。这必须等于源索引中的分片数量。

映射不能在_clone请求中指定。源索引的映射将被用于目标索引。

监控克隆过程

edit

克隆过程可以通过_cat recovery API进行监控，或者可以使用cluster health API来等待，直到所有主分片都被分配，方法是将wait_for_status 参数设置为yellow。

The _clone API 在目标索引被添加到集群状态后立即返回，此时还没有分配任何分片。在这个阶段，所有分片都处于 unassigned 状态。如果由于任何原因，目标索引无法被分配，其主分片将保持 unassigned 状态，直到它可以在该节点上被分配。

一旦主分片被分配，它将进入状态 initializing，并且克隆过程开始。当克隆操作完成时，分片将变为 active。此时，Elasticsearch 将尝试分配任何副本，并可能决定将主分片重新定位到另一个节点。

等待活动分片

edit

因为克隆操作会创建一个新的索引来克隆分片，所以在索引创建时的等待活动分片设置也适用于克隆索引操作。

路径参数

edit

<index>

(必需，字符串) 要克隆的源索引名称。

<target-index>

(必需，字符串) 要创建的目标索引的名称。

索引名称必须满足以下条件：

仅限小写
不能包含 \, /, *, ?, ", <, >, |, ` ` (空格字符), ,, #
7.0 之前的索引可以包含冒号 (:)，但已被弃用，7.0 及以上版本将不再支持
不能以 -, _, + 开头
不能是 . 或 ..
不能超过 255 字节（注意是字节，因此多字节字符会更快达到 255 字节的限制）
以 . 开头的名称已被弃用，除了隐藏索引和插件管理的内部索引

查询参数

edit

wait_for_active_shards

(可选，字符串) 在继续操作之前，必须处于活动状态的每个分片的副本数量。设置为 all 或任何非负整数，最大不超过索引中每个分片的副本总数（number_of_replicas+1）。默认为 1，表示仅等待每个主分片处于活动状态。

请参阅Active shards。

master_timeout

(可选，时间单位) 等待主节点的时间段。如果在超时到期之前主节点不可用，请求将失败并返回错误。默认为30s。也可以设置为-1，表示请求不应超时。

timeout

(可选，时间单位) 在更新集群元数据后，等待集群中所有相关节点响应的时间段。如果在超时到期之前未收到响应，集群元数据更新仍然适用，但响应将表明它未被完全确认。默认为 30s。也可以设置为 -1 以指示请求不应超时。

请求体

edit

aliases

(可选，对象的对象) 结果索引的别名。

Properties of aliases objects

(必需，对象) 键是别名名称。索引别名名称支持日期数学。

对象体包含别名的选项。支持空对象。

Properties of

filter: (可选，Query DSL 对象) 用于限制别名可以访问的文档的查询。
index_routing: (可选，字符串) 用于将索引操作路由到特定分片的值。如果指定，这将覆盖索引操作的 routing 值。
is_hidden: (可选，布尔值) 如果为 true，则别名是隐藏的。默认为 false。别名的所有索引必须具有相同的 is_hidden 值。
is_write_index: (可选，布尔值) 如果为 true，则索引是别名的写入索引。默认为 false。
routing: (可选，字符串) 用于将索引和搜索操作路由到特定分片的值。
search_routing: (可选，字符串) 用于将搜索操作路由到特定分片的值。如果指定，这将覆盖搜索操作的 routing 值。

settings

(可选, 索引设置对象) 目标索引的配置选项。参见索引设置。

关闭索引 API

edit

关闭一个索引。

POST /my-index-000001/_close

请求

edit

POST //_close

前提条件

edit

如果启用了Elasticsearch安全功能，您必须拥有目标索引或索引别名的manage 索引权限。

描述

edit

您可以使用关闭索引 API 来关闭已打开的索引。

一个已关闭的索引被阻止进行读/写操作，并且不允许所有已打开索引允许的操作。无法在已关闭的索引中索引文档或搜索文档。这使得已关闭的索引不必维护用于索引或搜索文档的内部数据结构，从而减少了集群的开销。

当打开或关闭一个索引时，主节点负责重新启动索引分片以反映索引的新状态。然后，分片将经历正常的恢复过程。已打开/关闭的索引数据会由集群自动复制，以确保始终安全地保留足够的分片副本。

您可以打开和关闭多个索引。如果请求明确引用了一个不存在的索引，则会抛出错误。可以使用ignore_unavailable=true参数禁用此行为。

默认情况下，您必须明确命名您正在打开或关闭的索引。要使用_all、*或其他通配符表达式来打开或关闭索引，请将action.destructive_requires_name设置更改为false。此设置也可以通过集群更新设置API进行更改。

关闭的索引会占用大量磁盘空间，这可能会在托管环境中引发问题。可以通过集群设置 API 将 cluster.indices.close.enable 设置为 false 来禁用关闭索引。默认值为 true。

路径参数

edit

<index>

(可选, 字符串) 用于限制请求的索引名称的逗号分隔列表或通配符表达式。

要关闭所有索引，请使用 _all 或 *。默认情况下，您必须明确指定要关闭的索引名称。要使用 _all、* 或其他通配符表达式指定要关闭的索引，请将 action.destructive_requires_name 设置更改为 false。您可以在 elasticsearch.yml 文件中更新此设置，或使用集群更新设置 API。

查询参数

edit

allow_no_indices

(可选, 布尔值) 如果为false，当任何通配符表达式、索引别名或_all值仅针对缺失或关闭的索引时，请求将返回错误。即使请求针对其他打开的索引，此行为也适用。例如，如果一个请求针对foo*,bar*，但没有任何索引以bar开头，即使存在以foo开头的索引，请求也会返回错误。

默认为 true。

expand_wildcards

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

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

默认为 open。

ignore_unavailable

(可选，布尔值) 如果为false，则当请求目标是一个缺失或关闭的索引时，请求将返回错误。默认为false。

wait_for_active_shards

(可选，字符串) 在继续操作之前，必须处于活动状态的每个分片的副本数量。设置为 all 或任何非负整数，最大不超过索引中每个分片的副本总数（number_of_replicas+1）。默认为 1，表示仅等待每个主分片处于活动状态。

请参阅Active shards。

master_timeout

(可选，时间单位) 等待主节点的时间段。如果在超时到期之前主节点不可用，请求将失败并返回错误。默认为30s。也可以设置为-1，表示请求不应超时。

timeout

(可选，时间单位) 在更新集群元数据后，等待集群中所有相关节点响应的时间段。如果在超时到期之前未收到响应，集群元数据更新仍然适用，但响应将表明它未被完全确认。默认为 30s。也可以设置为 -1 以指示请求不应超时。

示例

edit

以下示例展示了如何关闭索引：

POST /my-index-000001/_close

API返回以下响应：

{
  "acknowledged": true,
  "shards_acknowledged": true,
  "indices": {
    "my-index-000001": {
      "closed": true
    }
  }
}

创建索引 API

edit

创建一个新索引。

PUT /my-index-000001

请求

edit

PUT /

先决条件

edit

如果启用了Elasticsearch安全功能，您必须拥有目标索引的create_index或manage 索引权限。要将索引添加到别名中，您必须拥有该别名的manage索引权限。

描述

edit

您可以使用创建索引 API 向 Elasticsearch 集群添加新索引。创建索引时，您可以指定以下内容：

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

路径参数

edit

<index>

(必需，字符串) 您希望创建的索引名称。

索引名称必须满足以下条件：

仅限小写
不能包含 \, /, *, ?, ", <, >, |, ` ` (空格字符), ,, #
7.0 之前的索引可以包含冒号 (:)，但已被弃用，在 7.0+ 中将不再支持
不能以 -, _, + 开头
不能是 . 或 ..
不能超过 255 字节（注意是字节，因此多字节字符会更快达到 255 字节的限制）
以 . 开头的名称已弃用，除了隐藏索引和由插件管理的内部索引

查询参数

edit

wait_for_active_shards

(可选，字符串) 在继续操作之前，必须处于活动状态的每个分片的副本数量。设置为 all 或任何非负整数，最大不超过索引中每个分片的副本总数（number_of_replicas+1）。默认为 1，表示仅等待每个主分片处于活动状态。

请参阅Active shards。

master_timeout

(可选，时间单位) 等待主节点的时间段。如果在超时到期之前主节点不可用，请求将失败并返回错误。默认为30s。也可以设置为-1，表示请求不应超时。

timeout

(可选，时间单位) 在更新集群元数据后，等待集群中所有相关节点响应的时间段。如果在超时到期之前未收到响应，集群元数据更新仍然适用，但响应将表明它未被完全确认。默认为 30s。也可以设置为 -1 以指示请求不应超时。

请求体

edit

aliases

(可选，对象的对象) 索引的别名。

Properties of aliases objects

(必需，对象) 键是别名名称。索引别名名称支持日期数学。

对象体包含别名的选项。支持空对象。

Properties of

filter: (可选，Query DSL 对象) 用于限制别名可以访问的文档的查询。
index_routing: (可选，字符串) 用于将索引操作路由到特定分片的值。如果指定，这将覆盖索引操作的 routing 值。
is_hidden: (可选，布尔值) 如果为 true，则别名是隐藏的。默认为 false。别名的所有索引必须具有相同的 is_hidden 值。
is_write_index: (可选，布尔值) 如果为 true，则索引是别名的写入索引。默认为 false。
routing: (可选，字符串) 用于将索引和搜索操作路由到特定分片的值。
search_routing: (可选，字符串) 用于将搜索操作路由到特定分片的值。如果指定，这将覆盖搜索操作的 routing 值。

mappings

(可选, 映射对象) 索引字段的映射。如果指定，此映射可以包括:

参见映射。

settings

(可选, 索引设置对象) 索引的配置选项。参见索引设置。

示例

edit

索引设置

edit

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

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部分。

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

映射

edit

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

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

别名

edit

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

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

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

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

等待活动分片

edit

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

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

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

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

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

或通过请求参数 wait_for_active_shards：

PUT /test?wait_for_active_shards=2

关于wait_for_active_shards及其可能值的详细解释可以在这里找到。

创建或更新别名 API

edit

将数据流或索引添加到别名。

PUT my-data-stream/_alias/my-alias

请求

edit

POST /_alias/

POST /_aliases/

PUT /_alias/

PUT /_aliases/

先决条件

edit

如果启用了Elasticsearch安全功能，您必须拥有manage 索引权限对于别名及其数据流或索引。

路径参数

edit

<alias>: (必需，字符串) 要更新的别名。如果别名不存在，请求将创建它。索引别名名称支持日期数学。
<target>: (必需，字符串) 要添加的数据流或索引的逗号分隔列表。支持通配符 (*)。同时匹配数据流和索引的通配符模式会返回错误。

查询参数

edit

master_timeout: (可选，时间单位) 等待主节点的时间段。如果在超时到期之前主节点不可用，请求将失败并返回错误。默认为30s。也可以设置为-1，表示请求不应超时。
timeout: (可选，时间单位) 在更新集群元数据后，等待集群中所有相关节点响应的时间段。如果在超时到期之前未收到响应，集群元数据更新仍然适用，但响应将表明它未被完全确认。默认为 30s。也可以设置为 -1 以指示请求不应超时。

请求体

edit

filter

(可选, 查询DSL对象用于限制别名可以访问的文档的查询。

index_routing

(可选，字符串) 用于将索引操作路由到特定分片的值。如果指定，这将覆盖索引操作的 routing 值。数据流别名不支持此参数。

is_hidden

(可选，布尔值) 如果为 true，则别名是隐藏的。默认为 false。别名的所有数据流或索引必须具有相同的 is_hidden 值。

is_write_index

(可选，布尔值) 如果 true，则为别名设置写索引或数据流。

如果一个别名指向多个索引或数据流，并且未设置is_write_index，则该别名会拒绝写请求。如果一个索引别名指向一个索引，并且未设置is_write_index，则该索引会自动充当写索引。即使别名指向一个数据流，数据流别名也不会自动设置写数据流。

must_exist

(可选, 布尔值) 影响尝试删除不存在的别名时的行为。如果true，删除不存在的别名将导致所有操作失败。如果false，删除不存在的别名只会导致该删除操作失败。默认为false。

routing

（可选，字符串）用于将索引和搜索操作路由到特定分片的值。数据流别名不支持此参数。

search_routing

(可选，字符串) 用于将搜索操作路由到特定分片的值。如果指定，这将覆盖搜索操作的 routing 值。数据流别名不支持此参数。

创建或更新组件模板 API

edit

创建或更新组件模板。组件模板是构建用于指定索引的索引模板的构建块，包括映射、设置和别名。

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"
        }
      }
    }
  }
}

请求

edit

PUT /_component_template/<组件模板>

先决条件

edit

如果启用了Elasticsearch安全功能，您必须拥有manage_index_templates或manage 集群权限才能使用此API。

描述

edit

索引模板可以由多个组件模板组成。要使用组件模板，请在索引模板的 composed_of 列表中指定它。组件模板仅作为匹配索引模板的一部分应用于新的数据流和索引。

在索引模板或创建索引请求中直接指定的设置和映射会覆盖组件模板中指定的任何设置或映射。

组件模板仅在创建索引期间使用。对于数据流，这包括数据流创建和流的后备索引的创建。对组件模板的更改不会影响现有索引，包括流的后备索引。

组件模板中的注释

edit

您可以在组件模板中使用C风格的/* */块注释。您可以在请求体的任何位置包含注释，除了在开头的花括号之前。

路径参数

edit

<component-template>

(必需, 字符串) 要创建的组件模板的名称。

Elasticsearch 包括以下内置组件模板：

logs@mappings
logs@settings
metrics@mappings
metrics@settings
metrics@tsdb-settings
synthetics@mapping
synthetics@settings

Elastic Agent 使用这些模板来配置其数据流的备份索引。如果您想自定义这些模板，请不要覆盖它们，因为它们可能在更新后被重置。相反，请在托管索引模板的 composed_of 部分中查找 *@custom 组件模板。这些自定义组件模板允许您自定义托管索引模板的映射，而无需覆盖托管索引模板或组件模板。请注意，自定义组件模板可能尚不存在。在使用创建或更新组件模板创建它们后，它们将被索引模板拾取。请参阅更改数据流的映射和设置以了解如何将更改应用于相应的数据流。

为了避免与内置和Fleet管理的组件模板命名冲突，请避免在您自己的组件模板名称中使用@。该规则的例外是*@custom组件模板，它们允许您安全地自定义托管索引模板。

查询参数

edit

create: (可选, 布尔值) 如果为true，此请求不能替换或更新现有的组件模板。默认为false。
master_timeout: (可选，时间单位) 等待主节点的时间段。如果在超时到期之前主节点不可用，请求将失败并返回错误。默认为30s。也可以设置为-1，表示请求不应超时。

请求体

edit

template

(必需, 对象) 这是要应用的模板，可以选择性地包含一个 mappings、 settings 或 aliases 配置。

Properties of template

aliases

(可选，对象的对象) 要添加的别名。

如果索引模板包含一个data_stream对象，这些是数据流别名。否则，这些是索引别名。数据流别名忽略index_routing、routing和search_routing选项。

Properties of aliases objects

(必需，对象) 键是别名名称。索引别名名称支持日期数学。

对象体包含别名的选项。支持空对象。

Properties of

filter: (可选, 查询DSL对象) 用于限制别名可以访问的文档的查询。
index_routing: (可选, 字符串) 用于将索引操作路由到特定分片的值。如果指定，这将覆盖索引操作的routing值。
is_hidden: (可选, 布尔值) 如果为true，则别名是隐藏的。默认为false。别名的所有索引必须具有相同的is_hidden值。
is_write_index: (可选, 布尔值) 如果为true，则索引是别名的写入索引。默认为false。
routing: (可选, 字符串) 用于将索引和搜索操作路由到特定分片的值。
search_routing: (可选, 字符串) 用于将搜索操作路由到特定分片的值。如果指定，这将覆盖搜索操作的routing值。

mappings

(可选, 映射对象) 索引字段的映射。如果指定，此映射可以包括:

参见映射。

settings

(可选, 索引设置对象) 索引的配置选项。参见索引设置。

version

(可选, 整数) 用于外部管理组件模板的版本号。此编号不是由Elasticsearch自动生成或递增的。

allow_auto_create

(可选，布尔值) 此设置会覆盖 action.auto_create_index 集群设置的值。如果在模板中设置为 true，则即使通过 actions.auto_create_index 禁用了索引的自动创建，也可以使用该模板自动创建索引。如果设置为 false，则与模板匹配的索引或数据流必须始终显式创建，并且可能永远不会自动创建。

_meta

(可选, 对象) 关于组件模板的可选用户元数据。可以包含任何内容。此映射不会由Elasticsearch自动生成。

deprecated

(可选, 布尔值) 将此组件模板标记为已弃用。当引用已弃用的组件模板来创建或更新非弃用的索引模板时， Elasticsearch 将发出弃用警告。 end::template[]

示例

edit

带有索引别名的组件模板

edit

您可以在组件模板中包含索引别名。

PUT _component_template/template_1
{
  "template": {
    "settings" : {
        "number_of_shards" : 1
    },
    "aliases" : {
        "alias1" : {},
        "alias2" : {
            "filter" : {
                "term" : {"user.id" : "kimchy" }
            },
            "routing" : "shard-1"
        },
        "{index}-alias" : {} 
    }
  }
}

别名名称中的 {index} 占位符将在索引创建期间，模板应用到的实际索引名称所替换。

应用组件模板

edit

您不能直接将组件模板应用于数据流或索引。要应用组件模板，必须将其包含在索引模板的composed_of列表中。请参阅索引模板。

组件模板版本控制

edit

您可以使用 version 参数为组件模板添加版本号。外部系统可以使用这些版本号来简化模板管理。

参数 version 是可选的，并且不会被Elasticsearch自动生成或使用。

要取消设置版本，请在不指定版本的情况下替换模板。

PUT /_component_template/template_1
{
  "template": {
    "settings" : {
        "number_of_shards" : 1
    }
  },
  "version": 123
}

要检查版本，您可以使用获取组件模板 API。

组件模板元数据

edit

您可以使用 _meta 参数将任意元数据添加到组件模板中。这个用户定义的对象存储在集群状态中，因此保持其简短是可取的。

参数 _meta 是可选的，不会被 Elasticsearch 自动生成或使用。

要取消设置_meta，请在不指定的情况下替换模板。

PUT /_component_template/template_1
{
  "template": {
    "settings" : {
        "number_of_shards" : 1
    }
  },
  "_meta": {
    "description": "set number of shards to one",
    "serialization": {
      "class": "MyComponentTemplate",
      "id": 10
    }
  }
}

要检查 _meta，您可以使用获取组件模板 API。

创建或更新索引模板 API

edit

创建或更新索引模板。索引模板定义了设置、映射和别名，这些可以自动应用于新索引。

PUT /_index_template/template_1
{
  "index_patterns" : ["template*"],
  "priority" : 1,
  "template": {
    "settings" : {
      "number_of_shards" : 2
    }
  }
}

请求

edit

PUT /_index_template/

先决条件

edit

如果启用了Elasticsearch安全功能，您必须拥有manage_index_templates或manage 集群权限才能使用此API。

描述

edit

Elasticsearch 根据与索引名称匹配的通配符模式将模板应用于新索引。

索引模板在数据流或索引创建时应用。对于数据流，这些设置和映射在流的后备索引创建时应用。

在创建索引请求中指定的设置和映射会覆盖索引模板中指定的任何设置或映射。

索引模板的更改不会影响现有索引，包括数据流的现有后备索引。

索引模板中的注释

edit

您可以在索引模板中使用C风格的/* */块注释。您可以在请求体中的任何位置包含注释，除了在开括号之前。

路径参数

edit

<index-template>: (必需, 字符串) 要创建的索引模板的名称。

查询参数

edit

create: (可选，布尔值) 如果为true，此请求不能替换或更新现有的索引模板。默认为false。
master_timeout: (可选，时间单位) 等待主节点的时间段。如果在超时到期之前主节点不可用，请求将失败并返回错误。默认为30s。也可以设置为-1，表示请求不应超时。

请求体

edit

composed_of: (可选，字符串数组) 一个有序的组件模板名称列表。组件模板按照指定的顺序合并，这意味着最后指定的组件模板具有最高的优先级。有关示例，请参见组合多个组件模板。

data_stream

(可选, 对象) 如果包含此对象，模板将用于创建数据流及其支持的索引。支持空对象。

数据流需要一个匹配的索引模板，其中包含一个data_stream对象。请参阅创建索引模板。

Properties of data_stream

allow_custom_routing

(可选, 布尔值) 如果 true，数据流支持自定义路由。默认为 false。

hidden

(可选, 布尔值) 如果 true，数据流是隐藏的。默认为 false。

index_mode

(可选, 字符串) 要创建的数据流类型。有效值为 null (常规数据流) 和 time_series (时间序列数据流)。

如果 time_series，每个后备索引都有一个 index.mode 索引设置为 time_series。

index_patterns

(必需，字符串数组) 用于在创建时匹配数据流和索引名称的通配符 (*) 表达式数组。

Elasticsearch 包含多个内置的索引模板。为了避免与这些模板发生命名冲突，请参阅避免索引模式冲突。

_meta

(可选, 对象) 关于索引模板的可选用户元数据。可以包含任何内容。此映射不会由Elasticsearch自动生成。

priority

(可选, 整数) 用于确定在新数据流或索引创建时索引模板的优先级。具有最高优先级的索引模板将被选择。如果没有指定优先级，模板将被视为优先级为0（最低优先级）。此数字不会由Elasticsearch自动生成。

template

(可选, 对象) 要应用的模板。它可以选择性地包括一个 aliases、mappings 或 settings 配置。

Properties of template

aliases

(可选，对象的对象) 要添加的别名。

如果索引模板包含一个data_stream对象，这些是数据流别名。否则，这些是索引别名。数据流别名忽略index_routing、routing和search_routing选项。

Properties of aliases objects

(必需，对象) 键是别名名称。索引别名名称支持日期数学。

对象体包含别名的选项。支持空对象。

Properties of

filter: (可选, 查询DSL对象) 用于限制别名可以访问的文档的查询。
index_routing: (可选, 字符串) 用于将索引操作路由到特定分片的值。如果指定，这将覆盖索引操作的routing值。
is_hidden: (可选, 布尔值) 如果为true，则别名是隐藏的。默认为false。别名的所有索引必须具有相同的is_hidden值。
is_write_index: (可选, 布尔值) 如果为true，则索引是别名的写入索引。默认为false。
routing: (可选, 字符串) 用于将索引和搜索操作路由到特定分片的值。
search_routing: (可选, 字符串) 用于将搜索操作路由到特定分片的值。如果指定，这将覆盖搜索操作的routing值。

mappings

(可选, 映射对象) 索引字段的映射。如果指定，此映射可以包括:

参见映射。

settings

(可选, 索引设置对象) 索引的配置选项。参见索引设置。

version

(可选, 整数) 用于外部管理索引模板的版本号。此编号不由Elasticsearch自动生成。

deprecated

(可选, 布尔值) 将此索引模板标记为已弃用。当创建或更新使用已弃用组件的非弃用索引模板时， Elasticsearch 将发出弃用警告。

示例

edit

带有索引别名的索引模板

edit

您可以在索引模板中包含索引别名。

PUT _index_template/template_1
{
  "index_patterns" : ["template*"],
  "template": {
    "settings" : {
        "number_of_shards" : 1
    },
    "aliases" : {
        "alias1" : {},
        "alias2" : {
            "filter" : {
                "term" : {"user.id" : "kimchy" }
            },
            "routing" : "shard-1"
        },
        "{index}-alias" : {} 
    }
  }
}

别名名称中的 {index} 占位符将在索引创建期间，模板应用到的实际索引名称所替换。

多个匹配的模板

edit

如果多个索引模板匹配新索引或数据流的名称，则使用优先级最高的模板。例如：

PUT /_index_template/template_1
{
  "index_patterns" : ["temp*"],
  "priority" : 0,
  "template": {
    "settings" : {
      "number_of_shards" : 1,
      "number_of_replicas": 0
    },
    "mappings" : {
      "_source" : { "enabled" : false }
    }
  }
}

PUT /_index_template/template_2
{
  "index_patterns" : ["template*"],
  "priority" : 1,
  "template": {
    "settings" : {
      "number_of_shards" : 2
    },
    "mappings" : {
      "_source" : { "enabled" : true }
    }
  }
}

对于以 template* 开头的索引，_source 将被启用，并且该索引将有两个主分片和一个副本，因为只有 template_2 会被应用。

不允许在同一优先级下创建具有重叠索引模式的多个模板，并且在尝试创建与现有索引模板匹配的模板时，将会抛出错误。

模板版本控制

edit

您可以使用 version 参数为索引模板添加版本号。外部系统可以使用这些版本号来简化模板管理。

参数 version 是可选的，并且不会被Elasticsearch自动生成或使用。

要取消设置版本，请在不指定版本的情况下替换模板。

PUT /_index_template/template_1
{
  "index_patterns" : ["foo", "bar"],
  "priority" : 0,
  "template": {
    "settings" : {
        "number_of_shards" : 1
    }
  },
  "version": 123
}

要检查版本，您可以使用获取索引模板 API。

模板元数据

edit

您可以使用 _meta 参数将任意元数据添加到索引模板中。这个用户定义的对象存储在集群状态中，因此保持其简短是可取的。

参数 _meta 是可选的，不会被 Elasticsearch 自动生成或使用。

要取消设置_meta，请在不指定的情况下替换模板。

PUT /_index_template/template_1
{
  "index_patterns": ["foo", "bar"],
  "template": {
    "settings" : {
        "number_of_shards" : 3
    }
  },
  "_meta": {
    "description": "set number of shards to three",
    "serialization": {
      "class": "MyIndexTemplate",
      "id": 17
    }
  }
}

要检查 _meta，您可以使用获取索引模板 API。

数据流定义

edit

要为数据流使用索引模板，模板必须包含一个data_stream对象。请参阅创建索引模板。

PUT /_index_template/template_1
{
  "index_patterns": ["logs-*"],
  "data_stream": { }
}

组合别名、映射和设置

edit

当在索引模板中为composed_of字段指定多个组件模板时，它们会按照指定的顺序合并，这意味着后面的组件模板会覆盖前面的组件模板。父索引模板中的任何映射、设置或别名都会在此之后合并。最后，索引请求本身的任何配置也会被合并。

在这个例子中，两个组件模板的顺序改变了索引的分片数量：

PUT /_component_template/template_with_2_shards
{
  "template": {
    "settings": {
      "index.number_of_shards": 2
    }
  }
}

PUT /_component_template/template_with_3_shards
{
  "template": {
    "settings": {
      "index.number_of_shards": 3
    }
  }
}

PUT /_index_template/template_1
{
  "index_patterns": ["t*"],
  "composed_of": ["template_with_2_shards", "template_with_3_shards"]
}

在这种情况下，匹配 t* 的索引将有三个主分片。如果组合模板的顺序被反转，索引将有两个主分片。

映射定义是递归合并的，这意味着后面的映射组件可以引入新的字段映射并更新映射配置。如果一个字段映射已经包含在较早的组件中，它的定义将被后面的定义完全覆盖。

这种递归合并策略不仅适用于字段映射，还适用于根选项，如dynamic_templates和meta。如果较早的组件包含一个dynamic_templates块，那么默认情况下新的dynamic_templates条目会被附加到末尾。如果已经存在具有相同键的条目，则它会被新的定义覆盖。

创建或更新索引模板 API

edit

本文档是关于遗留索引模板的内容，这些模板已被弃用，并将被Elasticsearch 7.8中引入的可组合模板所取代。有关可组合模板的信息，请参阅索引模板。

创建或更新索引模板。

PUT _template/template_1
{
  "index_patterns": ["te*", "bar*"],
  "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"
      }
    }
  }
}

请求

edit

PUT /_template/

先决条件

edit

如果启用了Elasticsearch的安全功能，您必须拥有manage_index_templates或manage 集群权限才能使用此API。

描述

edit

索引模板定义了在创建新索引时可以自动应用的设置和映射。 Elasticsearch 根据与索引名称匹配的索引模式将模板应用于新索引。

可组合模板始终优先于传统模板。如果没有可组合模板匹配新索引，则根据其顺序应用匹配的传统模板。

索引模板仅在创建索引时应用。对索引模板的更改不会影响现有索引。在创建索引 API 请求中指定的设置和映射会覆盖索引模板中指定的任何设置或映射。

索引模板中的注释

edit

您可以在索引模板中使用C风格的/* */块注释。您可以在请求体中的任何位置包含注释，除了在开括号之前。

获取模板

edit

参见获取索引模板 (旧版)。

路径参数

edit

<index-template>: (必需，字符串) 要创建的索引模板的名称。

查询参数

edit

create

(可选, 布尔值) 如果为true，此请求不能替换或更新现有的索引模板。默认为false。

order

(可选, 整数) 如果索引匹配多个模板，Elasticsearch 应用此模板的顺序。

具有较低order值的模板首先合并。具有较高order值的模板稍后合并，覆盖具有较低值的模板。

master_timeout

(可选，时间单位) 等待主节点的时间段。如果在超时到期之前主节点不可用，请求将失败并返回错误。默认为30s。也可以设置为-1，表示请求不应超时。

请求体

edit

index_patterns

(必需，字符串数组) 用于在创建时匹配索引名称的通配符表达式数组。

aliases

(可选，对象的对象) 索引的别名。

Properties of aliases objects

(必需，对象) 键是别名名称。索引别名名称支持日期数学。

对象体包含别名的选项。支持空对象。

Properties of

filter: (可选，Query DSL 对象) 用于限制别名可以访问的文档的查询。
index_routing: (可选，字符串) 用于将索引操作路由到特定分片的值。如果指定，这将覆盖索引操作的 routing 值。
is_hidden: (可选，布尔值) 如果为 true，则别名是隐藏的。默认为 false。别名的所有索引必须具有相同的 is_hidden 值。
is_write_index: (可选，布尔值) 如果为 true，则索引是别名的写入索引。默认为 false。
routing: (可选，字符串) 用于将索引和搜索操作路由到特定分片的值。
search_routing: (可选，字符串) 用于将搜索操作路由到特定分片的值。如果指定，这将覆盖搜索操作的 routing 值。

mappings

(可选, 映射对象) 索引字段的映射。如果指定，此映射可以包括:

参见映射。

settings

(可选, 索引设置对象) 索引的配置选项。参见索引设置。

version

(可选, 整数) 用于外部管理索引模板的版本号。此编号不由Elasticsearch自动生成。

示例

edit

带有索引别名的索引模板

edit

您可以在索引模板中包含索引别名。

PUT _template/template_1
{
  "index_patterns" : ["te*"],
  "settings" : {
    "number_of_shards" : 1
  },
  "aliases" : {
    "alias1" : {},
    "alias2" : {
      "filter" : {
        "term" : {"user.id" : "kimchy" }
      },
      "routing" : "shard-1"
    },
    "{index}-alias" : {} 
  }
}

别名名称中的 {index} 占位符将在索引创建期间，模板应用到的实际索引名称所替换。

匹配多个模板的索引

edit

多个索引模板可能会匹配一个索引，在这种情况下，设置和映射都会合并到索引的最终配置中。合并的顺序可以通过order参数来控制，较低的顺序会先应用，较高的顺序会覆盖它们。例如：

PUT /_template/template_1
{
  "index_patterns" : ["te*"],
  "order" : 0,
  "settings" : {
    "number_of_shards" : 1
  },
  "mappings" : {
    "_source" : { "enabled" : false }
  }
}

PUT /_template/template_2
{
  "index_patterns" : ["tes*"],
  "order" : 1,
  "settings" : {
    "number_of_shards" : 1
  },
  "mappings" : {
    "_source" : { "enabled" : true }
  }
}

上述内容将禁用存储_source，但对于以tes*开头的索引，_source仍将启用。注意，对于映射，合并是“深层次”的，这意味着可以在更高阶的模板中轻松添加/覆盖基于对象/属性的映射，而较低阶的模板则提供基础。

具有相同顺序值的多个匹配模板将导致非确定性的合并顺序。

模板版本控制

edit

您可以使用 version 参数为索引模板添加一个可选的版本号。外部系统可以使用这些版本号来简化模板管理。

参数 version 是完全可选的，并且不会由 Elasticsearch 自动生成。

要取消设置版本，请在不指定版本的情况下替换模板。

PUT /_template/template_1
{
  "index_patterns" : ["my-index-*"],
  "order" : 0,
  "settings" : {
    "number_of_shards" : 1
  },
  "version": 123
}

要检查版本，您可以使用获取索引模板 API 并结合filter_path查询参数以仅返回版本号：

GET /_template/template_1?filter_path=*.version

API返回以下响应：

{
  "template_1" : {
    "version" : 123
  }
}

删除组件模板 API

edit

删除现有的组件模板。

DELETE _component_template/template_1

提供的可能包含多个模板名称，这些名称由逗号分隔。如果指定了多个模板名称，则不支持通配符，并且提供的名称应与现有的组件模板完全匹配。

请求

edit

DELETE /_component_template/

前提条件

edit

如果启用了Elasticsearch安全功能，您必须拥有manage_index_templates或manage 集群权限才能使用此API。

描述

edit

使用删除组件模板 API 来删除一个或多个组件模板。组件模板是构建索引模板的构建块，用于指定索引映射、设置和别名。

路径参数

edit

<component-template>: (必需，字符串) 用于限制请求的组件模板名称的逗号分隔列表或通配符表达式。

查询参数

edit

master_timeout: (可选，时间单位) 等待主节点的时间段。如果在超时到期之前主节点不可用，请求将失败并返回错误。默认为30s。也可以设置为-1，表示请求不应超时。

删除悬空索引 API

edit

删除一个悬空索引。

请求

edit

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

先决条件

edit

如果启用了Elasticsearch安全功能，您必须拥有manage 集群权限才能使用此API。

描述

edit

如果 Elasticsearch 遇到当前集群状态中不存在的索引数据，这些索引将被视为悬空索引。例如，如果你在 Elasticsearch 节点离线时删除了超过 cluster.indices.tombstones.size 个索引，就可能发生这种情况。

通过引用其UUID删除悬空索引。使用列出悬空索引API来定位索引的UUID。

路径参数

edit

<index-uuid>: (必需，字符串) 要删除的索引的UUID。您可以使用 List dangling indices API找到此信息。

查询参数

edit

accept_data_loss: (可选, 布尔值) 此字段必须设置为 true 才能执行导入，因为从悬空索引中将不再可能恢复数据。
master_timeout: (可选，时间单位) 等待主节点的时间段。如果在超时到期之前主节点不可用，请求将失败并返回错误。默认为30s。也可以设置为-1，表示请求不应超时。
timeout: (可选，时间单位) 在更新集群元数据后，等待集群中所有相关节点响应的时间段。如果在超时到期之前未收到响应，集群元数据更新仍然适用，但响应将表明它未被完全确认。默认为 30s。也可以设置为 -1 以指示请求不应超时。

删除别名 API

edit

从别名中移除数据流或索引。

DELETE my-data-stream/_alias/my-alias

请求

edit

DELETE /_alias/

DELETE /_aliases/

先决条件

edit

如果启用了Elasticsearch安全功能，您必须拥有别名及其数据流或索引的manage 索引权限。

路径参数

edit

<alias>: (必需，字符串) 要移除的别名列表，以逗号分隔。支持通配符 (*)。要移除所有别名，请使用 * 或 _all。
<target>: (必需，字符串) 用于限制请求的逗号分隔的数据流或索引列表。支持通配符 (*)。

查询参数

edit

master_timeout: (可选，时间单位) 等待主节点的时间段。如果在超时到期之前主节点不可用，请求将失败并返回错误。默认为30s。也可以设置为-1，表示请求不应超时。
timeout: (可选，时间单位) 在更新集群元数据后，等待集群中所有相关节点响应的时间段。如果在超时到期之前未收到响应，集群元数据更新仍然适用，但响应将表明它未被完全确认。默认为 30s。也可以设置为 -1 以指示请求不应超时。

删除索引 API

edit

删除一个或多个索引。

DELETE /my-index-000001

请求

edit

DELETE /

前提条件

edit

如果启用了Elasticsearch安全功能，您必须拥有目标索引的delete_index或manage 索引权限。

描述

edit

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

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

路径参数

edit

<index>

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

默认情况下，此参数不支持通配符（*）或_all。要使用通配符或_all，请将action.destructive_requires_name集群设置设置为false。

查询参数

edit

allow_no_indices

(可选, 布尔值) 如果为false，当任何通配符表达式、索引别名或_all值仅针对缺失或关闭的索引时，请求将返回错误。即使请求针对其他打开的索引，此行为也适用。例如，如果一个请求针对foo*,bar*，但没有任何索引以bar开头，即使存在以foo开头的索引，请求也会返回错误。

默认为 true。

expand_wildcards

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

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

默认为 open,closed。

ignore_unavailable

(可选，布尔值) 如果为false，则当请求目标是一个缺失或关闭的索引时，请求将返回错误。默认为false。

master_timeout

(可选，时间单位) 等待主节点的时间段。如果在超时到期之前主节点不可用，请求将失败并返回错误。默认为30s。也可以设置为-1，表示请求不应超时。

timeout

(可选，时间单位) 在更新集群元数据后，等待集群中所有相关节点响应的时间段。如果在超时到期之前未收到响应，集群元数据更新仍然适用，但响应将表明它未被完全确认。默认为 30s。也可以设置为 -1 以指示请求不应超时。

删除索引模板 API

edit

删除一个索引模板。

DELETE /_index_template/my-index-template

请求

edit

DELETE /_index_template/

提供的可能包含多个模板名称，这些名称由逗号分隔。如果指定了多个模板名称，则不支持通配符，并且提供的名称应与现有模板完全匹配。

前提条件

edit

如果启用了Elasticsearch安全功能，您必须拥有manage_index_templates或manage 集群权限才能使用此API。

描述

edit

使用删除索引模板 API 来删除一个或多个索引模板。索引模板定义了设置、映射和别名，这些可以自动应用于新索引。

路径参数

edit

<index-template>: (必需，字符串) 用于限制请求的索引模板名称的逗号分隔列表。支持通配符 (*) 表达式。

查询参数

edit

master_timeout: (可选，时间单位) 等待主节点的时间段。如果在超时到期之前主节点不可用，请求将失败并返回错误。默认为30s。也可以设置为-1，表示请求不应超时。

删除索引模板 API

edit

本文档是关于旧版索引模板，这些模板已被弃用，并将在 Elasticsearch 7.8 中被可组合模板所取代。有关可组合模板的信息，请参阅索引模板。

删除一个旧版索引模板。

DELETE /_template/my-legacy-index-template

请求

edit

DELETE /_template/

先决条件

edit

如果启用了Elasticsearch安全功能，您必须拥有manage_index_templates或manage 集群权限才能使用此API。

路径参数

edit

<legacy-index-template>: (必需，字符串) 要删除的旧索引模板的名称。支持通配符 (*) 表达式。

查询参数

edit

master_timeout: (可选，时间单位) 等待主节点的时间段。如果在超时到期之前主节点不可用，请求将失败并返回错误。默认为30s。也可以设置为-1，表示请求不应超时。

存在 API

edit

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

HEAD my-data-stream

请求

edit

HEAD <目标>

先决条件

edit

如果启用了Elasticsearch安全功能，您必须拥有目标的view_index_metadata或manage 索引权限。

路径参数

edit

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

查询参数

edit

allow_no_indices

(可选, 布尔值) 如果为false，当任何通配符表达式、索引别名或_all值仅针对缺失或关闭的索引时，请求将返回错误。即使请求针对其他打开的索引，此行为也适用。例如，如果一个请求针对foo*,bar*，但没有任何索引以bar开头，即使存在以foo开头的索引，请求也会返回错误。

默认为 true。

expand_wildcards

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

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

默认为 open。

flat_settings

(可选，布尔值) 如果 true，返回设置为扁平格式。默认为 false。

include_defaults

(可选，布尔值) 如果 true，返回响应中的所有默认设置。默认为 false。

ignore_unavailable

(可选，布尔值) 如果为false，则当请求目标是一个缺失或关闭的索引时，请求将返回错误。默认为false。

local

(可选，布尔值) 如果 true，请求仅从本地节点检索信息。默认为 false，这意味着信息从主节点检索。

响应代码

edit

200: 所有目标都存在。
404: 一个或多个指定的目标不存在。

字段使用统计 API

edit

此功能处于技术预览阶段，可能会在未来的版本中进行更改或移除。Elastic 将努力修复任何问题，但技术预览版中的功能不受官方 GA 功能支持 SLA 的约束。

返回索引中每个分片和字段的字段使用信息。当查询在集群上运行时，字段使用统计信息会自动捕获。访问给定字段的每个分片级别的搜索请求，即使在该请求期间多次访问，也计为一次使用。

GET /my-index-000001/_field_usage_stats

请求

edit

GET //_field_usage_stats

先决条件

edit

如果启用了Elasticsearch安全功能，您必须拥有目标索引或索引别名的manage 索引权限。

路径参数

edit

<index>: (可选，字符串) 用于限制请求的索引名称的逗号分隔列表或通配符表达式。

查询参数

edit

allow_no_indices

(可选, 布尔值) 如果为false，当任何通配符表达式、索引别名或_all值仅针对缺失或关闭的索引时，请求将返回错误。即使请求针对其他打开的索引，此行为也适用。例如，如果一个请求针对foo*,bar*，但没有任何索引以bar开头，即使存在以foo开头的索引，请求也会返回错误。

expand_wildcards

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

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

ignore_unavailable

(可选，布尔值) 如果为false，则当请求目标是一个缺失或关闭的索引时，请求将返回错误。默认为false。

wait_for_active_shards

(可选，字符串) 在继续操作之前，必须处于活动状态的每个分片的副本数量。设置为 all 或任何非负整数，最大不超过索引中每个分片的副本总数（number_of_replicas+1）。默认为 1，表示仅等待每个主分片处于活动状态。

请参阅Active shards。

fields

(可选，字符串) 逗号分隔的字段列表或通配符表达式，用于包含在统计信息中。

响应体

edit

响应正文报告了支持索引中字段的数据结构的每个分片使用计数。即使请求多次访问同一字段，给定请求也会将每个计数最多增加1。

any

(整数) 表示对该字段的任何类型的使用（例如通过倒排索引、存储字段、文档值等），使得在给定的搜索请求中，任何使用都被计数一次。

inverted_index

(对象) 倒排索引 由 index 映射参数启用，并通过为字段设置 index_options 进行配置。

Properties of inverted_index:

terms: (整数) 表示 terms 在 倒排索引 中的使用情况，回答问题“该字段的倒排索引是否被使用？”。
postings: (整数) 表示包含给定术语的文档ID的 posting list 的使用情况。
proximity: (整数) 表示在 倒排索引 中对 positions、offsets 或 payloads 的任何使用情况，使得在给定的搜索请求中，任何使用情况都被计算一次。
positions: (整数) 表示在 倒排索引 中对 position 数据（术语的顺序）的使用情况。
term_frequencies: (整数) 表示在 倒排索引 中对 term frequencies 的使用情况，这些频率用于计算分数。
offsets: (整数) 表示在 倒排索引 中对 offsets 的使用情况，这些偏移量存储术语的起始和结束字符偏移量。
payloads: (整数) 表示在 倒排索引 中对 payloads 的使用情况，例如通过分隔的payload token filter，或由用户定义的分析组件和插件。

stored_fields

(整数) 表示存储字段的使用。这些字段通过store映射选项启用，并通过指定stored_fields查询选项来访问。请注意，_source和_id字段默认存储，并且它们的使用在此处计数。

doc_values

(整数) 表示使用doc values，这些主要用于排序和聚合。这些是通过doc_values映射参数启用的。

points

(整数) 表示使用Lucene的PointValues，这是大多数数值字段数据类型的基础，包括空间数据类型、数字、日期等。这些用于查询/聚合的范围、计数、分桶、最小/最大值、直方图、空间等操作。

norms

(整数) 表示使用了包含用于评分的索引时提升值的norms。

term_vectors

(整数) 表示使用词向量，这允许在搜索时检索文档的词项。用途包括高亮显示和类似查询。

knn_vectors

(整数) 表示使用knn_vectors字段类型，主要用于k-近邻 (kNN) 搜索。

示例

edit

以下请求检索索引 my-index-000001 在当前可用分片上的字段使用信息。

GET /my-index-000001/_field_usage_stats

API返回以下响应：

{
    "_shards": {
        "total": 1,
        "successful": 1,
        "failed": 0
    },
    "my-index-000001": {
        "shards": [
            {
                "tracking_id": "MpOl0QlTQ4SYYhEe6KgJoQ",
                "tracking_started_at_millis": 1625558985010,
                "routing": {
                    "state": "STARTED",
                    "primary": true,
                    "node": "gA6KeeVzQkGURFCUyV-e8Q",
                    "relocating_node": null
                },
                "stats" : {
                    "all_fields": { 
                        "any": "6",
                        "inverted_index": {
                            "terms" : 1,
                            "postings" : 1,
                            "proximity" : 1,
                            "positions" : 0,
                            "term_frequencies" : 1,
                            "offsets" : 0,
                            "payloads" : 0
                        },
                        "stored_fields" : 2,
                        "doc_values" : 1,
                        "points" : 0,
                        "norms" : 1,
                        "term_vectors" : 0,
                        "knn_vectors" : 0
                    },
                    "fields": {
                        "_id": { 
                            "any" : 1,
                            "inverted_index": {
                                "terms" : 1,
                                "postings" : 1,
                                "proximity" : 1,
                                "positions" : 0,
                                "term_frequencies" : 1,
                                "offsets" : 0,
                                "payloads" : 0
                            },
                            "stored_fields" : 1,
                            "doc_values" : 0,
                            "points" : 0,
                            "norms" : 0,
                            "term_vectors" : 0,
                            "knn_vectors" : 0
                        },
                        "_source": {...},
                        "context": {...},
                        "message.keyword": {...}
                    }
                }
            }
        ]
    }
}

	报告索引中所有字段的使用计数总和（在列出的分片上）。
	报告以下使用计数的字段名称（在列出的分片上）。

刷新 API

edit

刷新一个或多个数据流或索引。

POST /my-index-000001/_flush

请求

edit

POST //_flush

GET //_flush

POST /_flush

GET /_flush

先决条件

edit

如果启用了Elasticsearch安全功能，您必须拥有目标数据流、索引或别名的maintenance或manage索引权限。

描述

edit

刷新数据流或索引是指确保当前仅存储在事务日志中的任何数据也永久存储在Lucene索引中。当重新启动时，Elasticsearch会重放事务日志中的任何未刷新操作到Lucene索引中，以将其恢复到重新启动之前的状态。Elasticsearch会根据需要自动触发刷新，使用启发式方法在未刷新的事务日志大小与执行每次刷新的成本之间进行权衡。

一旦每个操作都被刷新，它就会永久存储在Lucene索引中。这可能意味着不需要在事务日志中维护它的额外副本。事务日志由多个文件组成，称为代，Elasticsearch会在不再需要时删除任何代文件，从而释放磁盘空间。

也可以使用 flush API 触发一个或多个索引的刷新操作，尽管用户很少需要直接调用此 API。如果在索引一些文档后调用 flush API，那么成功的响应表明 Elasticsearch 已经刷新了在调用 flush API 之前索引的所有文档。

路径参数

edit

<target>: (可选，字符串) 逗号分隔的数据流、索引和别名列表，用于刷新。支持通配符 (*)。要刷新所有数据流和索引，请省略此参数或使用 * 或 _all。

查询参数

edit

allow_no_indices

(可选, 布尔值) 如果为false，当任何通配符表达式、索引别名或_all值仅针对缺失或关闭的索引时，请求将返回错误。即使请求针对其他打开的索引，此行为也适用。例如，如果一个请求针对foo*,bar*，但没有任何索引以bar开头，即使存在以foo开头的索引，请求也会返回错误。

默认为 true。

expand_wildcards

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

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

默认为 open。

force

(可选，布尔值) 如果true，请求将强制刷新，即使索引中没有需要提交的更改。默认为false。

您可以使用此参数来增加事务日志的生成编号。

此参数被视为内部参数。

ignore_unavailable

(可选，布尔值) 如果为false，则当请求目标是一个缺失或关闭的索引时，请求将返回错误。默认为false。

wait_if_ongoing

(可选, 布尔值) 如果 true, 刷新操作会阻塞直到执行当另一个刷新操作正在运行时。

如果 false，当另一个刷新操作正在运行时， Elasticsearch 会返回一个错误。

默认为 true。

示例

edit

刷新特定数据流或索引

edit

POST /my-index-000001/_flush

刷新多个数据流和索引

edit

POST /my-index-000001,my-index-000002/_flush

刷新集群中的所有数据流和索引

edit

POST /_flush

强制合并 API

edit

强制对一个或多个索引的分片进行合并。对于数据流，API强制对流的备份索引的分片进行合并。

POST /my-index-000001/_forcemerge

请求

edit

POST //_forcemerge

POST /_forcemerge

先决条件

edit

如果启用了Elasticsearch安全功能，您必须具有目标数据流、索引或别名的maintenance或manage索引权限。

描述

edit

使用force merge API来强制对一个或多个索引的分片进行合并。合并通过将一些段合并在一起，减少了每个分片中的段数量，并且释放了被删除文档占用的空间。合并通常会自动进行，但有时手动触发合并是有用的。

我们建议仅对只读索引（意味着该索引不再接收写入）进行强制合并。 当文档被更新或删除时，旧版本不会立即被移除，而是被软删除并标记为“墓碑”。这些软删除的文档会在常规段合并期间自动清理。但强制合并可能会产生非常大的（> 5GB）段，这些段不符合常规合并的条件。因此，软删除文档的数量可能会迅速增加，导致磁盘使用率更高和搜索性能更差。如果您定期对正在接收写入的索引进行强制合并，这也可能使快照成本更高，因为新文档无法增量备份。

强制合并期间的块

edit

调用此API会阻塞，直到合并完成（除非请求包含wait_for_completion=false，默认为true）。如果客户端连接在完成之前丢失，则强制合并过程将继续在后台进行。任何对相同索引进行强制合并的新请求也将阻塞，直到正在进行的强制合并完成。

异步运行强制合并

edit

如果请求包含wait_for_completion=false，Elasticsearch 会执行一些预检操作，启动请求，并返回一个 任务，您可以使用它来获取任务的状态。但是，您不能取消此任务，因为强制合并任务是不可取消的。Elasticsearch 会在_tasks/处创建此任务的记录文档。当您完成任务后，应删除任务文档，以便Elasticsearch 可以回收空间。

强制合并多个索引

edit

您可以通过以下方式在一次请求中强制合并多个索引：

一个或多个包含多个后备索引的数据流
多个索引
一个或多个别名
集群中的所有数据流和索引

每个目标分片分别使用 force_merge 线程池进行强制合并。默认情况下，每个节点只有一个 force_merge 线程，这意味着该节点上的分片一次只能强制合并一个。如果你扩展了节点上的 force_merge 线程池，那么它将并行强制合并其分片。

强制合并会使正在合并的分片的存储暂时增加，因为在将所有段重写为新段时，如果max_num_segments参数设置为1，可能需要多达其三倍的可用空间。

路径参数

edit

<target>: (可选，字符串) 用于限制请求的逗号分隔的数据流、索引和别名列表。支持通配符 (*)。要针对所有数据流和索引，请省略此参数或使用 * 或 _all。

查询参数

edit

allow_no_indices

(可选, 布尔值) 如果为false，当任何通配符表达式、索引别名或_all值仅针对缺失或关闭的索引时，请求将返回错误。即使请求针对其他打开的索引，此行为也适用。例如，如果一个请求针对foo*,bar*，但没有任何索引以bar开头，即使存在以foo开头的索引，请求也会返回错误。

默认为 true。

expand_wildcards

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

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

默认为 open。

flush

(可选，布尔值) 如果为true， Elasticsearch 在强制合并后对索引执行刷新。默认为true。

ignore_unavailable

(可选，布尔值) 如果为false，则当请求目标是一个缺失或关闭的索引时，请求将返回错误。默认为false。

max_num_segments

(可选, 整数) 要合并的段数。要完全合并索引，将其设置为 1。

默认检查是否需要执行合并。如果是，则执行合并。

您不能在同一请求中同时指定此参数和only_expunge_deletes。

only_expunge_deletes

(可选, 布尔值) 如果为true, 将删除所有包含超过index.merge.policy.expunge_deletes_allowed (默认为 10) 百分比的已删除文档的段。默认为false。

在Lucene中，一个文档不会从一个段落中删除；只是被标记为删除。在合并过程中，会创建一个新的段落，该段落不包含那些被删除的文档。

您不能在同一请求中指定此参数和max_num_segments。

wait_for_completion

(可选, 布尔值) 如果 true，请求将阻塞直到操作完成。默认为 true。

示例

edit

强制合并特定的数据流或索引

edit

POST /my-index-000001/_forcemerge

强制合并多个数据流或索引

edit

POST /my-index-000001,my-index-000002/_forcemerge

强制合并所有索引

edit

POST /_forcemerge

数据流和基于时间的索引

edit

强制合并对于管理数据流的旧后备索引和其他基于时间的索引非常有用，尤其是在执行滚动更新之后。在这些情况下，每个索引只在特定时间段内接收索引流量。一旦索引不再接收写入，其分片可以被强制合并为一个段。

POST /.ds-my-data-stream-2099.03.07-000001/_forcemerge?max_num_segments=1

这是一个好主意，因为单段分片有时可以使用更简单和更高效的数据结构来执行搜索。

获取别名 API

edit

检索一个或多个别名的信息。

GET my-data-stream/_alias/my-alias

请求

edit

GET _alias/

GET _alias

GET /_alias/

先决条件

edit

如果启用了Elasticsearch安全功能，您必须拥有view_index_metadata或manage 索引权限对于别名。如果您指定了目标，您还必须拥有view_index_metadata 或manage索引权限对于目标。

路径参数

edit

<alias>: (可选，字符串) 要检索的别名列表，以逗号分隔。支持通配符 (*)。要检索所有别名，请省略此参数或使用 * 或 _all。
<target>: (可选，字符串) 用于限制请求的逗号分隔的数据流或索引列表。支持通配符 (*)。要针对所有数据流和索引，请省略此参数或使用 * 或 _all。

查询参数

edit

allow_no_indices

(可选, 布尔值) 如果为false，当任何通配符表达式、索引别名或_all值仅针对缺失或关闭的索引时，请求将返回错误。即使请求针对其他打开的索引，此行为也适用。例如，如果一个请求针对foo*,bar*，但没有任何索引以bar开头，即使存在以foo开头的索引，请求也会返回错误。

默认为 true。

expand_wildcards

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

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

默认为 all。

ignore_unavailable

(可选，布尔值) 如果为false，请求中包含在中缺失的数据流或索引时将返回错误。默认为false。

local

(可选，布尔值) 如果 true，请求仅从本地节点检索信息。默认为 false，这意味着信息从主节点检索。

获取组件模板 API

edit

检索一个或多个组件模板的信息。

GET /_component_template/template_1

请求

edit

GET /_component_template/

先决条件

edit

如果启用了Elasticsearch安全功能，您必须拥有manage_index_templates或manage 集群权限来更新模板，或者拥有monitor集群权限来检索模板。

路径参数

edit

<component-template>: (可选, 字符串) 用于限制请求的组件模板名称的逗号分隔列表。支持通配符 (*) 表达式。

查询参数

edit

flat_settings: (可选，布尔值) 如果 true，返回设置为扁平格式。默认为 false。
local: (可选，布尔值) 如果 true，请求仅从本地节点检索信息。默认为 false，这意味着信息从主节点检索。
master_timeout: (可选，时间单位) 等待主节点的时间段。如果在超时到期之前主节点不可用，请求将失败并返回错误。默认为30s。也可以设置为-1，表示请求不应超时。
include_defaults: (可选, 布尔值) 功能处于 [技术预览] 此功能处于技术预览阶段，可能会在未来的版本中更改或移除。Elastic 将努力修复任何问题，但技术预览中的功能不受正式 GA 功能支持 SLA 的约束。。如果 true，则在响应中返回所有默认设置。默认为 false。

示例

edit

使用通配符表达式获取组件模板

edit

GET /_component_template/temp*

获取所有组件模板

edit

GET /_component_template

获取字段映射 API

edit

检索一个或多个字段的映射定义。对于数据流，API检索流的支持索引的字段映射。

如果你不需要一个完整的映射，或者如果一个索引映射包含大量字段，这个API非常有用。

GET /my-index-000001/_mapping/field/user

请求

edit

GET /_mapping/field/

GET //_mapping/field/

先决条件

edit

如果启用了Elasticsearch安全功能，您必须拥有目标数据流、索引或别名的view_index_metadata或manage 索引权限。

路径参数

edit

<target>: (可选，字符串) 用于限制请求的逗号分隔的数据流、索引和别名列表。支持通配符 (*)。要针对所有数据流和索引，请省略此参数或使用 * 或 _all。
<field>: (可选，字符串) 用于限制返回信息的字段列表或通配符表达式，以逗号分隔。

查询参数

edit

allow_no_indices

(可选, 布尔值) 如果为false，当任何通配符表达式、索引别名或_all值仅针对缺失或关闭的索引时，请求将返回错误。即使请求针对其他打开的索引，此行为也适用。例如，如果一个请求针对foo*,bar*，但没有任何索引以bar开头，即使存在以foo开头的索引，请求也会返回错误。

默认为 true。

expand_wildcards

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

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

ignore_unavailable

(可选，布尔值) 如果为false，则当请求目标是一个缺失或关闭的索引时，请求将返回错误。默认为false。

include_defaults

(可选，布尔值) 如果 true，响应将包含默认映射值。默认为 false。

示例

edit

带有索引设置的示例

edit

您可以在创建新索引时提供字段映射。以下创建索引 API 请求创建了 publications 索引，并包含多个字段映射。

PUT /publications
{
  "mappings": {
    "properties": {
      "id": { "type": "text" },
      "title": { "type": "text" },
      "abstract": { "type": "text" },
      "author": {
        "properties": {
          "id": { "type": "text" },
          "name": { "type": "text" }
        }
      }
    }
  }
}

以下仅返回字段 title 的映射：

GET publications/_mapping/field/title

API返回以下响应：

{
   "publications": {
      "mappings": {
          "title": {
             "full_name": "title",
             "mapping": {
                "title": {
                   "type": "text"
                }
             }
          }
       }
   }
}

指定字段

edit

get mapping API 允许您指定一个以逗号分隔的字段列表。

例如，要选择author字段的id，您必须使用其全名author.id。

GET publications/_mapping/field/author.id,abstract,name

返回：

{
   "publications": {
      "mappings": {
        "author.id": {
           "full_name": "author.id",
           "mapping": {
              "id": {
                 "type": "text"
              }
           }
        },
        "abstract": {
           "full_name": "abstract",
           "mapping": {
              "abstract": {
                 "type": "text"
              }
           }
        }
     }
   }
}

获取字段映射 API 也支持通配符表示法。

GET publications/_mapping/field/a*

返回：

{
   "publications": {
      "mappings": {
         "author.name": {
            "full_name": "author.name",
            "mapping": {
               "name": {
                 "type": "text"
               }
            }
         },
         "abstract": {
            "full_name": "abstract",
            "mapping": {
               "abstract": {
                  "type": "text"
               }
            }
         },
         "author.id": {
            "full_name": "author.id",
            "mapping": {
               "id": {
                  "type": "text"
               }
            }
         }
      }
   }
}

多个目标和字段

edit

get field mapping API 可用于通过单个请求从多个数据流或索引中获取多个字段的映射。

The 和请求路径参数都支持逗号分隔的列表和通配符表达式。

您可以省略参数或使用值*或_all来针对集群中的所有数据流和索引。

同样地，你可以省略参数或使用值*来检索目标数据流或索引中所有字段的映射。然而，参数不支持_all值。

例如，以下请求检索名为 my-index-000001 或 my-index-000002 的任何数据流或索引中 message 字段的映射。

GET /my-index-000001,my-index-000002/_mapping/field/message

以下请求检索集群中任何数据流或索引中的message和user.id字段的映射。

GET /_all/_mapping/field/message

以下请求检索集群中任何数据流或索引中具有id属性的字段的映射。

GET /_all/_mapping/field/*.id

获取索引 API

edit

返回一个或多个索引的信息。对于数据流，API返回关于流的后备索引的信息。

GET /my-index-000001

请求

edit

GET /

先决条件

edit

如果启用了Elasticsearch安全功能，您必须拥有目标数据流、索引或别名的view_index_metadata或manage 索引权限。

路径参数

edit

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

查询参数

edit

allow_no_indices

(可选, 布尔值) 如果为false，当任何通配符表达式、索引别名或_all值仅针对缺失或关闭的索引时，请求将返回错误。即使请求针对其他打开的索引，此行为也适用。例如，如果一个请求针对foo*,bar*，但没有任何索引以bar开头，即使存在以foo开头的索引，请求也会返回错误。

默认为 true。

expand_wildcards

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

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

默认为 open。

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。也可以设置为-1，表示请求不应超时。

获取索引设置 API

edit

返回一个或多个索引的设置信息。对于数据流，API返回流的后备索引的设置信息。

GET /my-index-000001/_settings

请求

edit

GET //_settings

GET //_settings/

先决条件

edit

如果启用了Elasticsearch安全功能，您必须拥有目标数据流、索引或别名的view_index_metadata、monitor或manage 索引权限。

路径参数

edit

<target>: (可选，字符串) 用于限制请求的逗号分隔的数据流、索引和别名列表。支持通配符 (*)。要针对所有数据流和索引，请省略此参数或使用 * 或 _all。
<setting>: (可选, 字符串) 用于限制请求的设置名称的逗号分隔列表或通配符表达式。

查询参数

edit

allow_no_indices

(可选, 布尔值) 如果为false，当任何通配符表达式、索引别名或_all值仅针对缺失或关闭的索引时，请求将返回错误。即使请求针对其他打开的索引，此行为也适用。例如，如果一个请求针对foo*,bar*，但没有任何索引以bar开头，即使存在以foo开头的索引，请求也会返回错误。

默认为 true。

expand_wildcards

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

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

默认为 open。

flat_settings

(可选，布尔值) 如果 true，返回设置为扁平格式。默认为 false。

include_defaults

(可选，布尔值) 如果 true，返回响应中的所有默认设置。默认为 false。

ignore_unavailable

(可选，布尔值) 如果为false，则当请求目标是一个缺失或关闭的索引时，请求将返回错误。默认为false。

local

(可选，布尔值) 如果 true，请求仅从本地节点检索信息。默认为 false，这意味着信息从主节点检索。

master_timeout

(可选，时间单位) 等待主节点的时间段。如果在超时到期之前主节点不可用，请求将失败并返回错误。默认为30s。也可以设置为-1，表示请求不应超时。

示例

edit

多个数据流和索引

edit

get settings API 可以用于通过一次调用来获取多个数据流或索引的设置。要获取集群中所有索引的设置，可以使用 _all 或 * 作为。通配符表达式也是支持的。以下是一些示例：

GET /my-index-000001,my-index-000002/_settings

GET /_all/_settings

GET /log_2099_*/_settings

按名称过滤设置

edit

返回的设置可以通过通配符匹配进行过滤，如下所示：

GET /log_2099_-*/_settings/index.number_*

获取索引模板 API

edit

返回一个或多个索引模板的信息。

GET /_index_template/template_1

请求

edit

GET /_index_template/

先决条件

edit

如果启用了Elasticsearch安全功能，您必须拥有manage_index_templates或manage 集群权限才能使用此API，或者拥有monitor集群权限以检索模板。

路径参数

edit

(可选，字符串) 要返回的模板的名称。接受通配符表达式。如果省略，则返回所有模板。

查询参数

edit

flat_settings: (可选，布尔值) 如果 true，返回设置为扁平格式。默认为 false。
local: (可选，布尔值) 如果 true，请求仅从本地节点检索信息。默认为 false，这意味着信息从主节点检索。
master_timeout: (可选，时间单位) 等待主节点的时间段。如果在超时到期之前主节点不可用，请求将失败并返回错误。默认为30s。也可以设置为-1，表示请求不应超时。
include_defaults: (可选, 布尔值) 功能处于 [技术预览] 此功能处于技术预览阶段，可能会在未来的版本中更改或移除。Elastic 将努力修复任何问题，但技术预览中的功能不受正式 GA 功能支持 SLA 的约束。。如果 true，则在响应中返回所有默认设置。默认为 false。

示例

edit

使用通配符表达式获取索引模板

edit

GET /_index_template/temp*

获取所有索引模板

edit

GET /_index_template

获取索引模板 API

edit

本文档是关于遗留索引模板的内容，这些模板已被弃用，并将被Elasticsearch 7.8中引入的可组合模板所取代。有关可组合模板的信息，请参阅索引模板。

检索一个或多个索引模板的信息。

GET /_template/template_1

请求

edit

GET /_template/

先决条件

edit

如果启用了Elasticsearch安全功能，您必须拥有manage_index_templates或manage 集群权限才能使用此API。

路径参数

edit

<index-template>

(必需，字符串) 用于限制请求的索引模板名称的逗号分隔列表。支持通配符 (*) 表达式。

要返回所有索引模板，请省略此参数或使用值 _all 或 *。

查询参数

edit

flat_settings: (可选，布尔值) 如果 true，返回设置为扁平格式。默认为 false。
local: (可选，布尔值) 如果 true，请求仅从本地节点检索信息。默认为 false，这意味着信息从主节点检索。
master_timeout: (可选，时间单位) 等待主节点的时间段。如果在超时到期之前主节点不可用，请求将失败并返回错误。默认为30s。也可以设置为-1，表示请求不应超时。

示例

edit

获取多个索引模板

edit

GET /_template/template_1,template_2

使用通配符表达式获取索引模板

edit

GET /_template/temp*

获取所有索引模板

edit

GET /_template

获取映射 API

edit

检索一个或多个索引的映射定义。对于数据流，API 检索流的后备索引的映射。

GET /my-index-000001/_mapping

请求

edit

GET /_mapping

GET //_mapping

先决条件

edit

如果启用了Elasticsearch安全功能，您必须拥有目标数据流、索引或别名的view_index_metadata或manage 索引权限。

路径参数

edit

<target>: (可选，字符串) 用于限制请求的逗号分隔的数据流、索引和别名列表。支持通配符 (*)。要针对所有数据流和索引，请省略此参数或使用 * 或 _all。

查询参数

edit

allow_no_indices

(可选, 布尔值) 如果为false，当任何通配符表达式、索引别名或_all值仅针对缺失或关闭的索引时，请求将返回错误。即使请求针对其他打开的索引，此行为也适用。例如，如果一个请求针对foo*,bar*，但没有任何索引以bar开头，即使存在以foo开头的索引，请求也会返回错误。

默认为 true。

expand_wildcards

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

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

默认为 open。

ignore_unavailable

(可选，布尔值) 如果为false，则当请求目标是一个缺失或关闭的索引时，请求将返回错误。默认为false。

local

(可选，布尔值) 如果 true，请求仅从本地节点检索信息。默认为 false，这意味着信息从主节点检索。

master_timeout

(可选，时间单位) 等待主节点的时间段。如果在超时到期之前主节点不可用，请求将失败并返回错误。默认为30s。也可以设置为-1，表示请求不应超时。

示例

edit

多个数据流和索引

edit

get mapping API 可以用于在一次调用中获取多个数据流或索引。API 的常规用法遵循以下语法： host:port//_mapping 其中可以接受逗号分隔的名称列表。要获取集群中所有数据流和索引的映射，请使用 _all 或 * 作为或省略参数。以下是一些示例：

GET /my-index-000001,my-index-000002/_mapping

如果你想获取集群中所有索引的映射，以下示例是等效的：

GET /*/_mapping

GET /_all/_mapping

GET /_mapping

导入悬空索引 API

edit

导入一个悬空索引。

请求

edit

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

先决条件

edit

如果启用了Elasticsearch安全功能，您必须拥有manage 集群权限才能使用此API。

描述

edit

如果 Elasticsearch 遇到当前集群状态中不存在的索引数据，这些索引将被视为悬空索引。例如，如果你在 Elasticsearch 节点离线时删除了超过 cluster.indices.tombstones.size 个索引，就可能发生这种情况。

通过引用其UUID将单个索引导入集群。使用列出悬空索引API来定位索引的UUID。

路径参数

edit

<index-uuid>: (必需，字符串) 要导入的索引的UUID，您可以使用列出悬空索引 API找到。

查询参数

edit

accept_data_loss: (必需, 布尔值) 此字段必须设置为 true 以导入一个悬空索引。因为 Elasticsearch 无法知道悬空索引数据来自何处或确定哪些分片副本是最新的，哪些是陈旧的，它无法保证导入的数据表示索引在集群中最后一次存在时的最新状态。
master_timeout: (可选，时间单位) 等待主节点的时间段。如果在超时到期之前主节点不可用，请求将失败并返回错误。默认为30s。也可以设置为-1，表示请求不应超时。
timeout: (可选，时间单位) 在更新集群元数据后，等待集群中所有相关节点响应的时间段。如果在超时到期之前未收到响应，集群元数据更新仍然适用，但响应将表明它未被完全确认。默认为 30s。也可以设置为 -1 以指示请求不应超时。

示例

edit

以下示例展示了如何导入一个悬空索引：

POST /_dangling/zmM4e0JtBkeUjiHD-MihPQ?accept_data_loss=true

API返回以下响应：

{
  "acknowledged" : true
}

索引恢复 API

edit

返回一个或多个索引的正在进行和已完成的分片恢复信息。对于数据流，API返回流的后备索引的信息。

GET /my-index-000001/_recovery

请求

edit

GET //_recovery

GET /_recovery

先决条件

edit

如果启用了Elasticsearch安全功能，您必须拥有目标数据流、索引或别名的monitor或manage 索引权限。

描述

edit

使用索引恢复 API 获取有关正在进行和已完成的分片恢复的信息。

分片恢复是指初始化一个分片副本的过程，例如从快照中恢复主分片或从主分片创建副本分片。当分片恢复完成时，恢复的分片可用于搜索和索引。

恢复会在以下过程中自动进行：

首次创建索引时。
当一个节点重新加入集群并使用其数据路径中保存的数据启动任何缺失的主分片副本时。
从主分片创建新的副本分片副本。
将分片副本重新定位到同一集群中的不同节点。
一个快照恢复操作。
一个克隆、收缩或拆分操作。

您可以使用recovery或cat recovery API来确定分片恢复的原因。

索引恢复API仅报告当前存在于集群中的分片副本的已完成恢复信息。它仅报告每个分片副本的最后一次恢复，并且不报告有关早期恢复的历史信息，也不报告有关不再存在的分片副本的恢复信息。这意味着如果一个分片副本完成恢复后，Elasticsearch将其重新定位到不同的节点，那么关于原始恢复的信息将不会显示在恢复API中。

路径参数

edit

<target>: (可选，字符串) 用于限制请求的逗号分隔的数据流、索引和别名列表。支持通配符 (*)。要针对所有数据流和索引，请省略此参数或使用 * 或 _all。

查询参数

edit

active_only: (可选，布尔值) 如果为true，响应仅包括正在进行中的分片恢复。默认为false。
detailed: (可选，布尔值) 如果为true，响应将包含有关分片恢复的详细信息。默认为false。
index: (可选, 字符串) 用于限制请求的索引名称的逗号分隔列表或通配符表达式。

响应体

edit

id

(整数) 分片的ID。

type

(字符串) 分片的恢复源。返回的值包括：

EMPTY_STORE: 一个空的存储。表示一个新的主分片或使用集群重新路由API强制分配的空主分片。
EXISTING_STORE: 现有主分片的存储。表示恢复与节点启动或现有主分片的分配有关。
LOCAL_SHARDS: 同一节点上另一个索引的分片。表示恢复与克隆、收缩或拆分操作有关。
PEER: 另一个节点上的主分片。表示恢复与分片复制有关。
SNAPSHOT: 一个快照。表示恢复与快照恢复操作有关。

STAGE

(字符串) 恢复阶段。返回的值可以包括：

INIT: 恢复尚未开始。
INDEX: 读取索引元数据并将字节从源复制到目标。
VERIFY_INDEX: 验证索引的完整性。
TRANSLOG: 重放事务日志。
FINALIZE: 清理。
DONE: 完成。

primary

(布尔值) 如果true，则该分片是主分片。

start_time

(字符串) 恢复开始的时间戳。

stop_time

(字符串) 恢复完成的时间戳。

total_time_in_millis

(字符串) 恢复分片所需的总时间，单位为毫秒。

source

(对象) 恢复源。这可以包括：

如果从快照恢复，则包括仓库描述
源节点的描述

target

(对象) 目标节点。

index

(对象) 物理索引恢复的统计信息。

translog

(对象) 关于事务日志恢复的统计信息。

start

(对象) 关于打开和启动索引的时间统计。

示例

edit

获取多个数据流和索引的恢复信息

edit

GET index1,index2/_recovery?human

获取集群中所有数据流和索引的分段信息

edit

GET /_recovery?human

API返回以下响应：

{
  "index1" : {
    "shards" : [ {
      "id" : 0,
      "type" : "SNAPSHOT",
      "stage" : "INDEX",
      "primary" : true,
      "start_time" : "2014-02-24T12:15:59.716",
      "start_time_in_millis": 1393244159716,
      "stop_time" : "0s",
      "stop_time_in_millis" : 0,
      "total_time" : "2.9m",
      "total_time_in_millis" : 175576,
      "source" : {
        "repository" : "my_repository",
        "snapshot" : "my_snapshot",
        "index" : "index1",
        "version" : "{version}",
        "restoreUUID": "PDh1ZAOaRbiGIVtCvZOMww"
      },
      "target" : {
        "id" : "ryqJ5lO5S4-lSFbGntkEkg",
        "host" : "my.fqdn",
        "transport_address" : "my.fqdn",
        "ip" : "10.0.1.7",
        "name" : "my_es_node"
      },
      "index" : {
        "size" : {
          "total" : "75.4mb",
          "total_in_bytes" : 79063092,
          "reused" : "0b",
          "reused_in_bytes" : 0,
          "recovered" : "65.7mb",
          "recovered_in_bytes" : 68891939,
          "recovered_from_snapshot" : "0b",
          "recovered_from_snapshot_in_bytes" : 0,
          "percent" : "87.1%"
        },
        "files" : {
          "total" : 73,
          "reused" : 0,
          "recovered" : 69,
          "percent" : "94.5%"
        },
        "total_time" : "0s",
        "total_time_in_millis" : 0,
        "source_throttle_time" : "0s",
        "source_throttle_time_in_millis" : 0,
        "target_throttle_time" : "0s",
        "target_throttle_time_in_millis" : 0
      },
      "translog" : {
        "recovered" : 0,
        "total" : 0,
        "percent" : "100.0%",
        "total_on_start" : 0,
        "total_time" : "0s",
        "total_time_in_millis" : 0
      },
      "verify_index" : {
        "check_index_time" : "0s",
        "check_index_time_in_millis" : 0,
        "total_time" : "0s",
        "total_time_in_millis" : 0
      }
    } ]
  }
}

此响应包括关于恢复单个分片的单个索引的信息。恢复的来源是快照仓库，恢复的目标是my_es_node节点。

响应还包括恢复的文件数量和字节数及其百分比。

获取详细的恢复信息

edit

要获取恢复中的物理文件列表，请将detailed查询参数设置为true。

GET _recovery?human&detailed=true

API返回以下响应：

{
  "index1" : {
    "shards" : [ {
      "id" : 0,
      "type" : "EXISTING_STORE",
      "stage" : "DONE",
      "primary" : true,
      "start_time" : "2014-02-24T12:38:06.349",
      "start_time_in_millis" : "1393245486349",
      "stop_time" : "2014-02-24T12:38:08.464",
      "stop_time_in_millis" : "1393245488464",
      "total_time" : "2.1s",
      "total_time_in_millis" : 2115,
      "source" : {
        "id" : "RGMdRc-yQWWKIBM4DGvwqQ",
        "host" : "my.fqdn",
        "transport_address" : "my.fqdn",
        "ip" : "10.0.1.7",
        "name" : "my_es_node"
      },
      "target" : {
        "id" : "RGMdRc-yQWWKIBM4DGvwqQ",
        "host" : "my.fqdn",
        "transport_address" : "my.fqdn",
        "ip" : "10.0.1.7",
        "name" : "my_es_node"
      },
      "index" : {
        "size" : {
          "total" : "24.7mb",
          "total_in_bytes" : 26001617,
          "reused" : "24.7mb",
          "reused_in_bytes" : 26001617,
          "recovered" : "0b",
          "recovered_in_bytes" : 0,
          "recovered_from_snapshot" : "0b",
          "recovered_from_snapshot_in_bytes" : 0,
          "percent" : "100.0%"
        },
        "files" : {
          "total" : 26,
          "reused" : 26,
          "recovered" : 0,
          "percent" : "100.0%",
          "details" : [ {
            "name" : "segments.gen",
            "length" : 20,
            "recovered" : 20
          }, {
            "name" : "_0.cfs",
            "length" : 135306,
            "recovered" : 135306,
            "recovered_from_snapshot": 0
          }, {
            "name" : "segments_2",
            "length" : 251,
            "recovered" : 251,
            "recovered_from_snapshot": 0
          }
          ]
        },
        "total_time" : "2ms",
        "total_time_in_millis" : 2,
        "source_throttle_time" : "0s",
        "source_throttle_time_in_millis" : 0,
        "target_throttle_time" : "0s",
        "target_throttle_time_in_millis" : 0
      },
      "translog" : {
        "recovered" : 71,
        "total" : 0,
        "percent" : "100.0%",
        "total_on_start" : 0,
        "total_time" : "2.0s",
        "total_time_in_millis" : 2025
      },
      "verify_index" : {
        "check_index_time" : 0,
        "check_index_time_in_millis" : 0,
        "total_time" : "88ms",
        "total_time_in_millis" : 88
      }
    } ]
  }
}

响应包括任何已恢复的物理文件的列表及其大小。

响应还包括恢复各个阶段的计时，以毫秒为单位：

索引检索
Translog 重放
索引启动时间

此响应表明恢复已完成。

所有恢复，无论是正在进行还是已完成，都会保留在集群状态中，并可能随时被报告。

要仅返回有关正在进行恢复的信息，请将active_only查询参数设置为true。

索引段 API

edit

返回关于索引分片中Lucene段的低级信息。对于数据流，API返回关于流的后备索引的信息。

GET /my-index-000001/_segments

请求

edit

GET //_segments

GET /_segments

先决条件

edit

如果启用了Elasticsearch安全功能，您必须拥有目标数据流、索引或别名的monitor或manage 索引权限。

路径参数

edit

<target>: (可选，字符串) 用于限制请求的逗号分隔的数据流、索引和别名列表。支持通配符 (*)。要针对所有数据流和索引，请省略此参数或使用 * 或 _all。

查询参数

edit

<vector_formats>

(可选, 布尔值) 如果为true，则每个段落中字段使用的向量格式的列表将包含在输出属性中。默认为false。

allow_no_indices

(可选, 布尔值) 如果为false，当任何通配符表达式、索引别名或_all值仅针对缺失或关闭的索引时，请求将返回错误。即使请求针对其他打开的索引，此行为也适用。例如，如果一个请求针对foo*,bar*，但没有任何索引以bar开头，即使存在以foo开头的索引，请求也会返回错误。

默认为 true。

expand_wildcards

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

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

默认为 open。

ignore_unavailable

(可选，布尔值) 如果为false，则当请求目标是一个缺失或关闭的索引时，请求将返回错误。默认为false。

响应体

edit

<segment>

(字符串) 段的名称，例如 _0。段名称由段生成派生，并在分片的目录中用于创建文件名。

generation

(整数) 代数编号，例如 0。Elasticsearch 为每次写入的段递增此代数编号。Elasticsearch 然后使用此编号来派生段名称。

num_docs

(整数) 由Lucene报告的文档数量。这不包括已删除的文档，并将任何嵌套文档与其父文档分别计数。它还排除了最近索引但尚未属于某个段的文档。

deleted_docs

(整数) Lucene报告的已删除文档数量，可能高于或低于您执行的删除操作数量。此数量不包括最近执行的删除操作，这些操作尚未属于某个段。如果这样做有意义，已删除的文档将由自动合并过程清理。此外，Elasticsearch会创建额外的已删除文档，以内部跟踪分片上最近的操作历史。

size_in_bytes

(整数) 段所使用的磁盘空间，例如 50kb。

committed

(布尔值) 如果true，段将被同步到磁盘。同步的段可以在硬重启后存活。

如果 false，未提交段的数据也会存储在事务日志中，以便 Elasticsearch 能够在下次启动时重放更改。

search

(布尔值) 如果为true，则该段是可搜索的。

如果 false，该段可能已被写入磁盘但需要一个刷新才能被搜索到。

version

(字符串) 用于写入段的Lucene版本。

compound

(布尔值) 如果true，Lucene将段中的所有文件合并为一个文件以节省文件描述符。

attributes

(对象) 包含关于（i）是否启用了高压缩，（ii）每个字段的向量格式的信息。

示例

edit

获取特定数据流或索引的分段信息

edit

GET /test/_segments

获取多个数据流和索引的分段信息

edit

GET /test1,test2/_segments

获取集群中所有数据流和索引的分段信息

edit

GET /_segments

API返回以下响应：

{
  "_shards": ...
  "indices": {
    "test": {
      "shards": {
        "0": [
          {
            "routing": {
              "state": "STARTED",
              "primary": true,
              "node": "zDC_RorJQCao9xf9pg3Fvw"
            },
            "num_committed_segments": 0,
            "num_search_segments": 1,
            "segments": {
              "_0": {
                "generation": 0,
                "num_docs": 1,
                "deleted_docs": 0,
                "size_in_bytes": 3800,
                "committed": false,
                "search": true,
                "version": "7.0.0",
                "compound": true,
                "attributes": {
                }
              }
            }
          }
        ]
      }
    }
  }
}

索引分片存储 API

edit

检索一个或多个索引中副本分片的存储信息。对于数据流，API检索流的后备索引的存储信息。

GET /my-index-000001/_shard_stores

请求

edit

GET //_shard_stores

GET /_shard_stores

先决条件

edit

如果启用了Elasticsearch安全功能，您必须拥有目标数据流、索引或别名的monitor或manage 索引权限。

描述

edit

索引分片存储API返回以下信息：

每个副本分片所在的节点
每个副本分片的分配ID
每个副本分片的唯一ID
在打开分片索引时遇到的任何错误或来自早期故障的错误

默认情况下，API 仅返回未分配的主分片或有一个或多个未分配副本分片的存储信息。

路径参数

edit

<target>: (可选，字符串) 用于限制请求的逗号分隔的数据流、索引和别名列表。支持通配符 (*)。要针对所有数据流和索引，请省略此参数或使用 * 或 _all。

查询参数

edit

allow_no_indices

(可选, 布尔值) 如果为false，当任何通配符表达式、索引别名或_all值仅针对缺失或关闭的索引时，请求将返回错误。即使请求针对其他打开的索引，此行为也适用。例如，如果一个请求针对foo*,bar*，但没有任何索引以bar开头，即使存在以foo开头的索引，请求也会返回错误。

默认为 true。

expand_wildcards

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

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

默认为 open。

ignore_unavailable

(可选，布尔值) 如果为false，则当请求目标是一个缺失或关闭的索引时，请求将返回错误。默认为false。

status

(可选，字符串) 逗号分隔的分片健康状态列表，用于限制请求。

有效值包括：

green: 主分片和所有副本分片都已分配。
yellow: 一个或多个副本分片未分配。
red: 主分片未分配。
all: 返回所有分片，无论健康状态如何。

默认为 黄色,红色。

max_concurrent_shard_requests

(可选，整数) 协调节点发送的并发分片级别请求的最大数量。默认为 100。较大的值可能会使针对多个分片的请求更快响应，但也可能会对其他集群操作产生更大的影响。

示例

edit

获取特定数据流或索引的分片存储信息

edit

GET /test/_shard_stores

获取多个数据流和索引的分片存储信息

edit

GET /test1,test2/_shard_stores

获取所有数据流和索引的分片存储信息

edit

GET /_shard_stores

根据集群健康状况获取分片存储信息

edit

您可以使用 status 查询参数来根据分片健康状况限制返回的信息。

以下请求仅返回有关已分配的主分片和副本分片的信息。

GET /_shard_stores?status=green

API返回以下响应：

{
   "indices": {
       "my-index-000001": {
           "shards": {
              "0": { 
                "stores": [ 
                    {
                        "sPa3OgxLSYGvQ4oPs-Tajw": { 
                            "name": "node_t0",
                            "ephemeral_id" : "9NlXRFGCT1m8tkvYCMK-8A",
                            "transport_address": "local[1]",
                            "external_id": "node_t0",
                            "attributes": {},
                            "roles": [...],
                            "version": "8.10.0",
                            "min_index_version": 7000099,
                            "max_index_version": 8100099
                        },
                        "allocation_id": "2iNySv_OQVePRX-yaRH_lQ", 
                        "allocation" : "primary|replica|unused" 
                        "store_exception": ... 
                    }
                ]
              }
           }
       }
   }
}

	关键是对应于存储信息的碎片ID
	所有分片副本的存储信息列表
	托管存储副本的节点信息，键是唯一的节点ID。
	存储副本的分配ID
	存储副本的状态，是否用作主副本、副本或根本不使用
	在打开分片索引时遇到的任何异常或来自早期引擎故障的异常

索引统计 API

edit

返回一个或多个索引的统计信息。对于数据流，API会检索流的后备索引的统计信息。

GET /my-index-000001/_stats

请求

edit

GET //_stats/

GET //_stats

GET /_stats

先决条件

edit

如果启用了Elasticsearch安全功能，您必须拥有目标数据流、索引或别名的monitor或manage 索引权限。

描述

edit

使用索引统计 API 获取一个或多个数据流和索引的高级聚合和统计信息。

默认情况下，返回的统计信息是索引级别的，包含primaries和total的聚合。primaries是仅主分片的值。total是主分片和副本分片的累积值。

要获取分片级别的统计信息，请将level参数设置为shards。

当移动到另一个节点时，分片的分片级统计信息会被清除。尽管该分片不再是节点的一部分，但该节点保留了分片所贡献的任何节点级统计信息。

路径参数

edit

<target>

(可选，字符串) 用于限制请求的逗号分隔的数据流、索引和别名列表。支持通配符 (*)。要针对所有数据流和索引，请省略此参数或使用 * 或 _all。

<index-metric>

(可选，字符串) 用于限制请求的指标的逗号分隔列表。支持的指标包括：

_all

返回所有统计信息。

completion

Completion suggester 统计信息。

dense_vector

索引的密集向量的总数。索引刷新可能会影响此统计信息。

docs

文档数量，未合并的已删除文档数量，以及总大小（以字节为单位）。索引刷新可能会影响此统计信息。

fielddata

Fielddata 统计信息。

flush

Flush 统计信息。

get

获取统计信息，包括缺失的统计信息。

indexing

Indexing 统计信息。

merge

Merge 统计信息。

query_cache

Query cache 统计信息。

refresh

Refresh 统计信息。

request_cache

Shard request cache 统计信息。

search

搜索统计信息，包括建议统计信息。您可以通过添加额外的 groups 参数来包含自定义组的统计信息（搜索操作可以与一个或多个组相关联）。 groups 参数接受逗号分隔的组名列表。使用 _all 返回所有组的统计信息。

segments

所有打开段的内存使用情况。

如果 include_segment_file_sizes 参数为 true，此指标包括每个 Lucene 索引文件的聚合磁盘使用情况。

sparse_vector

索引的稀疏向量的总数。

索引刷新可能会影响此统计信息。

store: 索引的大小（以字节单位表示）。
translog: Translog 统计信息。

查询参数

edit

expand_wildcards

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

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

默认为 open。

fields

(可选，字符串) 逗号分隔的字段列表或通配符表达式，用于包含在统计信息中。

用作默认列表，除非在 completion_fields 或 fielddata_fields 参数中提供了特定的字段列表。

completion_fields

(可选，字符串) 以逗号分隔的字段列表或通配符表达式，用于包含在fielddata和suggest统计信息中。

fielddata_fields

(可选，字符串) 以逗号分隔的字段列表或通配符表达式，用于包含在fielddata统计信息中。

forbid_closed_indices

(可选，布尔值) 如果为true，则不会从已关闭的索引中收集统计信息。默认为true。

groups

(可选，字符串) 逗号分隔的搜索组列表包含在搜索统计信息中。

level

(可选, 字符串) 指示统计信息是在集群、索引还是分片级别聚合的。如果请求了分片级别，则会显示一些额外的分片特定统计信息。

有效值为：

cluster
indices
shards

include_segment_file_sizes

(可选, 布尔值) 如果true，调用将报告每个Lucene索引文件的聚合磁盘使用情况（仅在请求段统计信息时适用）。默认为false。

include_unloaded_segments

(可选，布尔值) 如果为 true，响应将包含来自未加载到内存中的分段的信息。默认为 false。

示例

edit

获取多个数据流和索引的统计信息

edit

GET /index1,index2/_stats

获取集群中所有数据流和索引的统计信息

edit

GET /_stats

获取特定统计信息

edit

以下请求仅返回所有索引的merge和refresh统计信息。

GET /_stats/merge,refresh

获取特定搜索组的统计信息

edit

以下请求仅返回group1和group2搜索组的搜索统计信息。

GET /_stats/search?groups=group1,group2

索引模板存在 API

edit

本文档是关于旧版索引模板，这些模板已被弃用，并将在 Elasticsearch 7.8 中被可组合模板所取代。有关可组合模板的信息，请参阅索引模板。

检查是否存在旧版索引模板。

HEAD /_template/template_1

请求

edit

HEAD /_template/

先决条件

edit

如果启用了Elasticsearch安全功能，您必须拥有manage_index_templates或manage 集群权限才能使用此API。

描述

edit

使用索引模板存在 API 来确定一个或多个索引模板是否存在。

索引模板定义了可以自动应用于新索引的设置、映射和别名。

路径参数

edit

<index-template>: (必需，字符串) 用于限制请求的索引模板名称的逗号分隔列表。支持通配符 (*) 表达式。

查询参数

edit

flat_settings: (可选，布尔值) 如果 true，返回设置为扁平格式。默认为 false。
local: (可选，布尔值) 如果 true，请求仅从本地节点检索信息。默认为 false，这意味着信息从主节点检索。
master_timeout: (可选，时间单位) 等待主节点的时间段。如果在超时到期之前主节点不可用，请求将失败并返回错误。默认为30s。也可以设置为-1，表示请求不应超时。

响应代码

edit

200: 表示所有指定的索引模板都存在。
404: 指示一个或多个指定的索引模板不存在。

列出悬空索引 API

edit

列出悬空索引。

请求

edit

GET /_dangling

先决条件

edit

如果启用了Elasticsearch安全功能，您必须拥有manage 集群权限才能使用此API。

描述

edit

如果 Elasticsearch 遇到当前集群状态中不存在的索引数据，这些索引将被视为悬空索引。例如，如果你在 Elasticsearch 节点离线时删除了超过 cluster.indices.tombstones.size 个索引，就可能发生这种情况。

使用此API列出悬空索引，然后您可以导入或删除。

示例

edit

API返回以下响应：

{
  "dangling_indices": [
   {
    "index_name": "my-index-000001",
    "index_uuid": "zmM4e0JtBkeUjiHD-MihPQ",
    "creation_date_millis": 1589414451372,
    "node_ids": [
      "pL47UN3dAb2d5RCWP6lQ3e"
    ]
   }
  ]
}

打开索引 API

edit

打开一个已关闭的索引。对于数据流，API会打开任何已关闭的备份索引。

POST /my-index-000001/_open

请求

edit

POST //_open

先决条件

edit

如果启用了Elasticsearch安全功能，您必须拥有目标数据流、索引或别名的manage 索引权限。

描述

edit

您可以使用开放索引API重新打开已关闭的索引。如果请求针对的是数据流，该请求将重新打开数据流的任何已关闭的备份索引。

一个已关闭的索引被阻止进行读/写操作，并且不允许所有已打开索引允许的操作。无法在已关闭的索引中索引文档或搜索文档。这使得已关闭的索引不必维护用于索引或搜索文档的内部数据结构，从而减少了集群的开销。

当打开或关闭一个索引时，主节点负责重新启动索引分片以反映索引的新状态。然后，分片将经历正常的恢复过程。已打开/关闭的索引数据会由集群自动复制，以确保始终安全地保留足够的分片副本。

您可以打开和关闭多个索引。如果请求明确引用了一个不存在的索引，则会抛出错误。可以使用ignore_unavailable=true参数禁用此行为。

默认情况下，您必须明确命名您正在打开或关闭的索引。要使用_all、*或其他通配符表达式来打开或关闭索引，请将action.destructive_requires_name设置更改为false。此设置也可以通过集群更新设置API进行更改。

关闭的索引会占用大量磁盘空间，这可能会在托管环境中引发问题。可以通过集群设置 API 将 cluster.indices.close.enable 设置为 false 来禁用关闭索引。默认值为 true。

等待活动分片

edit

因为打开或关闭索引会分配其分片，所以在索引创建时的 wait_for_active_shards 设置也适用于 _open 和 _close 索引操作。

路径参数

edit

<target>

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

默认情况下，您必须明确指定要使用的索引来限制请求。要使用 _all、* 或其他通配符表达式来限制请求，请将 action.destructive_requires_name 设置更改为 false。您可以在 elasticsearch.yml 文件中更新此设置，或使用集群更新设置 API。

查询参数

edit

allow_no_indices

(可选, 布尔值) 如果为false，当任何通配符表达式、索引别名或_all值仅针对缺失或关闭的索引时，请求将返回错误。即使请求针对其他打开的索引，此行为也适用。例如，如果一个请求针对foo*,bar*，但没有任何索引以bar开头，即使存在以foo开头的索引，请求也会返回错误。

默认为 true。

expand_wildcards

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

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

默认为 关闭。

ignore_unavailable

(可选，布尔值) 如果为false，则当请求目标是一个缺失或关闭的索引时，请求将返回错误。默认为false。

wait_for_active_shards

(可选，字符串) 在继续操作之前，必须处于活动状态的每个分片的副本数量。设置为 all 或任何非负整数，最大不超过索引中每个分片的副本总数（number_of_replicas+1）。默认为 1，表示仅等待每个主分片处于活动状态。

请参阅Active shards。

master_timeout

(可选，时间单位) 等待主节点的时间段。如果在超时到期之前主节点不可用，请求将失败并返回错误。默认为30s。也可以设置为-1，表示请求不应超时。

timeout

(可选，时间单位) 在更新集群元数据后，等待集群中所有相关节点响应的时间段。如果在超时到期之前未收到响应，集群元数据更新仍然适用，但响应将表明它未被完全确认。默认为 30s。也可以设置为 -1 以指示请求不应超时。

示例

edit

以下请求重新打开一个名为 my-index-000001 的已关闭索引。

POST /my-index-000001/_open

API返回以下响应：

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

刷新 API

edit

刷新操作使得最近在一个或多个索引上执行的操作可以用于搜索。对于数据流，API会在流的备份索引上执行刷新操作。有关刷新操作的更多信息，请参阅近实时搜索。

POST /my-index-000001/_refresh

请求

edit

POST /_refresh

GET /_refresh

POST /_refresh

GET /_refresh

先决条件

edit

如果启用了Elasticsearch安全功能，您必须具有目标数据流、索引或别名的maintenance或manage索引权限。

描述

edit

使用刷新 API 显式地使自上次刷新以来在一个或多个索引上执行的所有操作可用于搜索。如果请求针对数据流，它将刷新数据流的备份索引。

默认情况下，Elasticsearch 每秒定期刷新索引，但仅在最近 30 秒内收到一次或多次搜索请求的索引上进行。您可以使用 index.refresh_interval 设置来更改此默认间隔。

刷新请求是同步的，在刷新操作完成之前不会返回响应。

刷新是资源密集型的操作。为了确保良好的集群性能，我们建议尽可能等待Elasticsearch的周期性刷新，而不是在可能的情况下执行显式刷新。

如果您的应用程序工作流程先索引文档，然后运行搜索以检索已索引的文档，我们建议使用index API的 refresh=wait_for查询参数选项。此选项确保索引操作等待在运行搜索之前进行定期刷新。

路径参数

edit

<target>: (可选，字符串) 用于限制请求的逗号分隔的数据流、索引和别名列表。支持通配符 (*)。要针对所有数据流和索引，请省略此参数或使用 * 或 _all。

查询参数

edit

allow_no_indices

(可选, 布尔值) 如果为false，当任何通配符表达式、索引别名或_all值仅针对缺失或关闭的索引时，请求将返回错误。即使请求针对其他打开的索引，此行为也适用。例如，如果一个请求针对foo*,bar*，但没有任何索引以bar开头，即使存在以foo开头的索引，请求也会返回错误。

默认为 true。

expand_wildcards

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

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

默认为 open。

ignore_unavailable

(可选，布尔值) 如果为false，则当请求目标是一个缺失或关闭的索引时，请求将返回错误。默认为false。

示例

edit

刷新多个数据流和索引

edit

POST /my-index-000001,my-index-000002/_refresh

刷新集群中的所有数据流和索引

edit

POST /_refresh

解析索引 API

edit

解析指定的名称和/或索引模式，用于索引、别名和数据流。支持多个模式和远程集群。

GET /_resolve/index/my-index-*

请求

edit

GET /_resolve/index/

先决条件

edit

如果启用了Elasticsearch安全功能，您必须拥有目标数据流、索引或索引别名的view_index_metadata或manage 索引权限。

路径参数

edit

<name>: (必需，字符串) 使用多目标语法解析的索引、别名和数据流的逗号分隔名称或索引模式。可以通过 : 语法指定远程集群上的资源。

查询参数

edit

expand_wildcards

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

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

默认为 open。

ignore_unavailable

(可选，布尔值) 如果为false，则当请求目标是一个缺失或关闭的索引时，请求将返回错误。默认为false。

默认为 false。

allow_no_indices

(可选, 布尔值) 如果为false，当任何通配符表达式、索引别名或_all值仅针对缺失或关闭的索引时，请求将返回错误。即使请求针对其他打开的索引，此行为也适用。例如，如果一个请求针对foo*,bar*，但没有任何索引以bar开头，即使存在以foo开头的索引，请求也会返回错误。

默认为 true。

ignore_throttled

(可选，布尔值) 如果为 true，冻结时会忽略具体的、扩展的或别名的索引。默认为 false。

[7.16.0] 在7.16.0中已弃用。

示例

edit

GET /_resolve/index/f*,remoteCluster1:bar*?expand_wildcards=all

API返回以下响应：

{
  "indices": [                                 
    {
      "name": "foo_closed",
      "attributes": [
        "closed"                               
      ]
    },
    {
      "name": "freeze-index",
      "aliases": [
        "f-alias"
      ],
      "attributes": [
        "open"
      ]
    },
    {
      "name": "remoteCluster1:bar-01",
      "attributes": [
        "open"
      ]
    }
  ],
  "aliases": [                                 
    {
      "name": "f-alias",
      "indices": [
        "freeze-index",
        "my-index-000001"
      ]
    }
  ],
  "data_streams": [                            
    {
      "name": "foo",
      "backing_indices": [
        ".ds-foo-2099.03.07-000001"
      ],
      "timestamp_field": "@timestamp"
    }
  ]
}

	所有匹配提供的名称或表达式的索引
	可能的索引属性包括 `open`、`closed`、`hidden`、`system` 和 `frozen`
	所有匹配提供的名称或表达式的别名
	所有匹配所提供名称或表达式的数据流

解析集群API

edit

解析指定的索引表达式以返回有关每个集群的信息，包括本地集群（如果包含）。

在进行跨集群搜索之前，此端点用于确定应在搜索中包含哪些远程集群。

您在此端点上使用的索引表达式与跨集群搜索时使用的相同。索引和集群排除也支持此端点。

对于索引表达式中的每个集群，返回以下信息：

查询（“本地”）集群当前是否连接到索引表达式范围内的每个远程集群
每个远程集群是否配置了skip_unavailable为true或false
该集群上是否有任何与索引表达式匹配的索引、别名或数据流
当你进行跨集群搜索时，搜索是否可能会返回错误（包括如果你的用户没有权限查询索引时的任何授权错误）
集群版本信息，包括Elasticsearch服务器版本

GET /_resolve/cluster/my-index-*,cluster*:my-index-*

这将返回有关本地集群和所有以别名 cluster* 开头的远程配置集群的信息。每个集群将返回有关其是否具有与 my-index-* 匹配的任何索引、别名或数据流的信息。

请求

edit

GET /_resolve/cluster/

先决条件

edit

如果启用了Elasticsearch安全功能，您必须拥有目标数据流、索引或别名的view_index_metadata、read或manage 索引权限。

路径参数

edit

<index_expression>: (必需，字符串) 使用多目标语法解析的索引、别名和数据流的逗号分隔名称或索引模式。可以通过 : 语法指定远程集群上的资源。

查询参数

edit

expand_wildcards

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

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

默认为 open。

ignore_unavailable

(可选，布尔值) 如果为false，则当请求目标是一个缺失或关闭的索引时，请求将返回错误。默认为false。

默认为 false。

allow_no_indices

(可选, 布尔值) 如果为false，当任何通配符表达式、索引别名或_all值仅针对缺失或关闭的索引时，请求将返回错误。即使请求针对其他打开的索引，此行为也适用。例如，如果一个请求针对foo*,bar*，但没有任何索引以bar开头，即使存在以foo开头的索引，请求也会返回错误。

默认为 true。

ignore_throttled

(可选，布尔值) 如果为 true，冻结时会忽略具体的、扩展的或别名的索引。默认为 false。

[7.16.0] 在7.16.0中已弃用。

在跨集群搜索前使用此端点的优势

edit

您可能希望在以下情况下从搜索中排除集群或索引：

远程集群当前未连接，并且配置了skip_unavailable=false。在这些条件下执行跨集群搜索将导致整个搜索失败。
集群没有与索引表达式匹配的索引、别名或数据流（或者您的用户没有权限搜索它们）。例如，假设您的索引表达式是logs*,remote1:logs*，而remote1集群没有匹配logs*的索引、别名或数据流。在这种情况下，如果您在跨集群搜索中包含该集群，该集群将不会返回任何结果。
索引表达式（结合您指定的任何查询参数）可能会在执行搜索时引发异常。在这些情况下，_resolve/cluster响应中的“error”字段将存在。（这也是显示安全/权限错误的地方。）
远程集群是一个较旧的版本，不支持您在搜索中想要使用的功能。

示例

edit

GET /_resolve/cluster/my-index*,clust*:my-index*

API返回以下响应：

{
  "(local)": {          
    "connected": true,
    "skip_unavailable": false,
    "matching_indices": true,
    "version": {
      "number": "8.13.0",
      "build_flavor": "default",
      "minimum_wire_compatibility_version": "7.17.0",
      "minimum_index_compatibility_version": "7.0.0"
    }
  },
  "cluster_one": {
    "connected": true,         
    "skip_unavailable": true,  
    "matching_indices": true,  
    "version": {
      "number": "8.13.0",      
      "build_flavor": "default",
      "minimum_wire_compatibility_version": "7.17.0",
      "minimum_index_compatibility_version": "7.0.0"
    }
  },
  "cluster_two": {
    "connected": true,
    "skip_unavailable": false,
    "matching_indices": true,
    "version": {
      "number": "8.13.0",
      "build_flavor": "default",
      "minimum_wire_compatibility_version": "7.17.0",
      "minimum_index_compatibility_version": "7.0.0"
    }
  }
}

	每个集群都有自己的响应部分。您发送请求的集群被标记为“(本地)”。
	查询集群尝试向每个远程集群发出请求。如果成功，`connected`=`true`。
	本地集群上配置的每个远程集群的`skip_unavailable`设置。
	指示是否任何索引、别名或数据流与该集群指定的索引表达式匹配。
	Elasticsearch 服务器版本。

识别跨集群搜索的潜在问题

edit

以下请求展示了如何通过修改查询来防止搜索失败的几个示例。

GET /_resolve/cluster/not-present,clust*:my-index*,oldcluster:*?ignore_unavailable=false

{
  "(local)": {
    "connected": true,
    "skip_unavailable": false,
    "error": "no such index [not_present]"  
  },
  "cluster_one": {
    "connected": true,
    "skip_unavailable": true,
    "matching_indices": false,    
    "version": {
      "number": "8.13.0",
      "build_flavor": "default",
      "minimum_wire_compatibility_version": "7.17.0",
      "minimum_index_compatibility_version": "7.0.0"
    }
  },
  "cluster_two": {
    "connected": false,           
    "skip_unavailable": false,
    "matching_indices": true,
    "version": {
      "number": "8.13.0",
      "build_flavor": "default",
      "minimum_wire_compatibility_version": "7.17.0",
      "minimum_index_compatibility_version": "7.0.0"
    }
  },
  "oldcluster": {         
    "connected": true,
    "skip_unavailable": false,
    "matching_indices": true
  }
}

	本地集群中没有名为 `not_present` 的索引。使用指定的 `ignore_unavailable=false` 参数对其进行搜索将返回“无此索引”错误。其他类型的错误也可能出现在这里，例如当用户没有权限搜索指定索引时的安全权限错误。
	远程集群 `cluster_one` 没有匹配模式 `my-index*` 的索引。可能没有匹配该模式的索引，或者索引可能已关闭。（您可以通过使用 resolve index API 来检查这一点。）
	远程集群 `cluster_two` 未连接（连接尝试失败）。由于该集群被标记为 `skip_unavailable=false`，您可能应该通过在搜索索引表达式中添加 `-cluster_two:*` 来排除此集群。
	远程集群 `oldcluster` 显示它有匹配的索引，但没有包含版本信息。这表明集群版本早于 8.13.0 中引入的 `_resolve/cluster` API，因此您可能希望将其从跨集群搜索中排除。（注意：端点能够检测到匹配的索引，因为它回退到使用 resolve index API。）

滚动更新 API

edit

为数据流或索引别名创建一个新索引。

POST my-data-stream/_rollover

请求

edit

POST //_rollover/

前提条件

edit

如果启用了Elasticsearch安全功能，您必须对滚动目标具有manage 索引权限。

描述

edit

我们建议使用 ILM 的 rollover 操作来自动化滚动更新。请参阅索引生命周期。

滚动更新 API 为数据流或索引别名创建一个新索引。 API 的行为取决于滚动更新目标。

滚动查看数据流

如果您滚动一个数据流，API会为该流创建一个新的写入索引。该流的先前写入索引变为常规的后备索引。滚动操作还会增加数据流的代数。请参阅滚动。

滚动一个带有写入索引的索引别名

在Elasticsearch 7.9之前，您通常会使用一个带有写入索引的索引别名来管理时间序列数据。数据流取代了这一功能，减少了维护工作量，并自动与数据层集成。

参见将索引别名转换为数据流。

如果一个索引别名指向多个索引，其中一个索引必须是写入索引。滚动API为别名创建一个新的写入索引，并将is_write_index设置为true。该API还会将 is_write_index设置为false，用于之前的写入索引。

滚动一个索引别名到一个索引

如果您将鼠标悬停在一个指向单个索引的索引别名上，API会为该别名创建一个新索引，并从别名中移除原始索引。

为别名递增索引名称

edit

当您滚动一个索引别名时，您可以为新索引指定一个名称。如果您不指定名称，并且当前索引以-和一个数字结尾，例如my-index-000001或my-index-3，新索引名称将递增该数字。例如，如果您滚动一个当前索引为my-index-000001的别名，滚动操作将创建一个名为my-index-000002的新索引。无论前一个索引的名称如何，此数字始终为6个字符，并且用零填充。

等待活动分片

edit

滚动创建一个新索引，并受wait_for_active_shards设置的约束。

路径参数

edit

<rollover-target>

(必需，字符串) 要翻转的数据流或索引别名的名称。

<target-index>

(可选，字符串) 要创建的索引名称。支持日期数学。数据流不支持此参数。

如果别名的当前写入索引名称不以-和一个数字结尾，例如my-index-000001或my-index-3，则此参数是必需的。

索引名称必须满足以下条件：

仅限小写
不能包含 \, /, *, ?, ", <, >, |, ` ` (空格字符), ,, #
7.0 之前的索引可以包含冒号 (:)，但已被弃用，在 7.0+ 中将不再支持
不能以 -, _, + 开头
不能是 . 或 ..
不能超过 255 字节（注意是字节，因此多字节字符会更快达到 255 字节的限制）
以 . 开头的名称已被弃用，除了隐藏索引和由插件管理的内部索引

查询参数

edit

dry_run

(可选，布尔值) 如果为true，则检查当前索引是否满足指定的条件，但不执行翻转操作。默认为false。

lazy

(可选，布尔值) 如果为true，表示当发生下一次索引操作时，数据流将被滚动更新。仅适用于数据流。默认为false。

wait_for_active_shards

(可选，字符串) 在继续操作之前，必须处于活动状态的每个分片的副本数量。设置为 all 或任何非负整数，最大不超过索引中每个分片的副本总数（number_of_replicas+1）。默认为 1，表示仅等待每个主分片处于活动状态。

请参阅Active shards。

master_timeout

(可选，时间单位) 等待主节点的时间段。如果在超时到期之前主节点不可用，请求将失败并返回错误。默认为30s。也可以设置为-1，表示请求不应超时。

timeout

(可选，时间单位) 在更新集群元数据后，等待集群中所有相关节点响应的时间段。如果在超时到期之前未收到响应，集群元数据更新仍然适用，但响应将表明它未被完全确认。默认为 30s。也可以设置为 -1 以指示请求不应超时。

请求体

edit

aliases

(可选，对象的对象) 目标索引的别名。数据流不支持此参数。

Properties of aliases objects

(必需，对象) 键是别名名称。索引别名名称支持日期数学。

对象体包含别名的选项。支持空对象。

Properties of

filter: (可选，查询DSL对象) 用于限制别名可以访问的文档的查询。
index_routing: (可选，字符串) 用于将索引操作路由到特定分片的值。如果指定，这将覆盖索引操作的routing值。
is_hidden: (可选，布尔值) 如果为true，则别名是隐藏的。默认为false。别名的所有索引必须具有相同的is_hidden值。
is_write_index: (可选，布尔值) 如果为true，则索引是别名的写入索引。默认为false。
routing: (可选，字符串) 用于将索引和搜索操作路由到特定分片的值。
search_routing: (可选，字符串) 用于将搜索操作路由到特定分片的值。如果指定，这将覆盖搜索操作的routing值。

conditions

(可选, 对象) 滚动更新的条件。如果指定，Elasticsearch 仅在当前索引满足这些条件时执行滚动更新。如果未指定此参数，Elasticsearch 将无条件执行滚动更新。

如果指定了条件，其中至少有一个必须是max_*条件。如果满足任何max_*条件且所有min_*条件都满足，索引将会滚动。

要触发滚动更新，当前索引在请求时必须满足这些条件。Elasticsearch在API响应后不会监控索引。要自动化滚动更新，请使用ILM的rollover。

Properties of conditions

max_age: (可选, 时间单位) 在索引创建后达到最大经过时间时触发滚动更新。经过的时间始终从索引创建时间计算，即使索引起始日期配置为自定义日期，例如使用 index.lifecycle.parse_origination_date 或 index.lifecycle.origination_date 设置。
max_docs: (可选, 整数) 在达到指定最大文档数量时触发滚动更新。自上次刷新以来添加的文档不计入文档数量。文档数量不包括副本分片中的文档。
max_size: (可选, 字节单位) 当索引达到一定大小时触发滚动更新。这是索引中所有主分片的总大小。副本不计入最大索引大小。

要查看当前索引大小，请使用_cat indices API。 pri.store.size 值显示所有主分片的总大小。
max_primary_shard_size: (可选, 字节单位) 当索引中最大的主分片达到一定大小时触发翻转。这是索引中主分片的最大大小。与max_size一样，副本被忽略。

要查看当前分片大小，请使用 _cat shards API。 store 值显示每个分片的大小，而 prirep 指示分片是主分片（p）还是副本（r）。
max_primary_shard_docs: (可选, 整数) 当索引中最大的主分片达到一定数量的文档时触发翻转。这是索引中主分片的文档最大数量。与max_docs一样，副本被忽略。

要查看当前分片的文档，请使用 _cat shards API。 docs 值显示每个分片的文档数量。
min_age: (可选, 时间单位) 在索引创建后达到最小经过时间之前阻止滚动更新。参见 max_age 的注释。
min_docs: (可选, 整数) 在达到指定最小文档数量之前阻止滚动更新。参见 max_docs 的注释。
min_size: (可选, 字节单位) 在索引达到一定大小之前阻止滚动更新。参见 max_size 的注释。
min_primary_shard_size: (可选, 字节单位) 在索引中最大的主分片达到一定大小之前阻止滚动更新。参见 max_primary_shard_size 的注释。
min_primary_shard_docs: (可选, 整数) 在索引中最大的主分片达到一定数量的文档之前阻止滚动更新。参见 max_primary_shard_docs 的注释。

mappings

(可选, 映射对象) 索引字段的映射。如果指定，此映射可以包括:

参见映射。

数据流不支持此参数。

settings

(可选, 索引设置对象) 索引的配置选项。参见索引设置。

数据流不支持此参数。

响应体

edit

acknowledged

(布尔值) 如果true，请求在timeout时间内从主节点收到了响应。

shards_acknowledged

(布尔值) 如果为true，表示请求在master_timeout 期间内收到了来自活动分片的响应。

old_index

(字符串) 数据流或索引别名的前一个索引。对于具有写入索引的数据流和索引别名，这是前一个写入索引。

new_index

(字符串) 由滚动创建的索引。对于数据流和具有写入索引的索引别名，这是当前的写入索引。

rolled_over

(布尔值) 如果true，数据流或索引别名已滚动更新。

dry_run

(布尔值) 如果true，Elasticsearch 没有执行滚动更新。

condition

(对象) 请求中每个条件的结果 conditions。如果没有指定条件，这是一个空对象。

属性 condition

: (布尔值) 键是每个条件。值是其结果。如果 true，则索引满足该条件。

lazy

(布尔值) 如果true，Elasticsearch 没有执行滚动更新，但成功标记了数据流在下一次索引事件时进行滚动更新。

示例

edit

滚动数据流

edit

以下请求无条件地滚动一个数据流。

POST my-data-stream/_rollover

以下请求将数据流延迟滚动，这意味着数据流将在下一次索引事件时滚动。这确保了映射和设置更改将应用于即将到来的数据，但它将避免为具有缓慢摄取的数据流创建额外的后备索引。

POST my-data-stream/_rollover?lazy

以下请求仅在当前写入索引满足以下一个或多个条件时才会滚动数据流：

索引是在7天或更久之前创建的。
索引包含1,000个或更多文档。
索引的最大主分片为50GB或更大。

POST my-data-stream/_rollover
{
  "conditions": {
    "max_age": "7d",
    "max_docs": 1000,
    "max_primary_shard_size": "50gb",
    "max_primary_shard_docs": "2000"
  }
}

API返回：

{
  "acknowledged": true,
  "shards_acknowledged": true,
  "old_index": ".ds-my-data-stream-2099.05.06-000001",
  "new_index": ".ds-my-data-stream-2099.05.07-000002",
  "rolled_over": true,
  "dry_run": false,
  "lazy": false,
  "conditions": {
    "[max_age: 7d]": false,
    "[max_docs: 1000]": true,
    "[max_primary_shard_size: 50gb]": false,
    "[max_primary_shard_docs: 2000]": false
  }
}

使用写入索引滚动索引别名

edit

以下请求创建并将其设置为 my-alias 的写入索引。

# PUT <my-index-{now/d}-000001>
PUT %3Cmy-index-%7Bnow%2Fd%7D-000001%3E
{
  "aliases": {
    "my-alias": {
      "is_write_index": true
    }
  }
}

以下请求仅在当前写入索引满足以下一个或多个条件时才会滚动别名：

索引是在7天或更久之前创建的。
索引包含1,000个或更多文档。
索引的最大主分片为50GB或更大。

POST my-alias/_rollover
{
  "conditions": {
    "max_age": "7d",
    "max_docs": 1000,
    "max_primary_shard_size": "50gb",
    "max_primary_shard_docs": "2000"
  }
}

API返回：

{
  "acknowledged": true,
  "shards_acknowledged": true,
  "old_index": "my-index-2099.05.06-000001",
  "new_index": "my-index-2099.05.07-000002",
  "rolled_over": true,
  "dry_run": false,
  "lazy": false,
  "conditions": {
    "[max_age: 7d]": false,
    "[max_docs: 1000]": true,
    "[max_primary_shard_size: 50gb]": false,
    "[max_primary_shard_docs: 2000]": false
  }
}

如果别名的索引名称使用日期数学，并且您定期滚动索引，您可以使用日期数学来缩小搜索范围。例如，以下搜索针对过去三天内创建的索引。

# GET /<my-index-{now/d}-*>,<my-index-{now/d-1d}-*>,<my-index-{now/d-2d}-*>/_search
GET /%3Cmy-index-%7Bnow%2Fd%7D-*%3E%2C%3Cmy-index-%7Bnow%2Fd-1d%7D-*%3E%2C%3Cmy-index-%7Bnow%2Fd-2d%7D-*%3E/_search

滚动一个索引别名与一个索引

edit

以下请求创建及其别名 my-write-alias。

# PUT <my-index-{now/d}-000001>
PUT %3Cmy-index-%7Bnow%2Fd%7D-000001%3E
{
  "aliases": {
    "my-write-alias": { }
  }
}

以下请求仅在当前索引满足以下条件之一或多个时，才会滚动别名：

索引是在7天或更久之前创建的。
索引包含1,000个或更多文档。
索引的最大主分片为50GB或更大。

POST my-write-alias/_rollover
{
  "conditions": {
    "max_age": "7d",
    "max_docs": 1000,
    "max_primary_shard_size": "50gb",
    "max_primary_shard_docs": "2000"
  }
}

API返回：

{
  "acknowledged": true,
  "shards_acknowledged": true,
  "old_index": "my-index-2099.05.06-000001",
  "new_index": "my-index-2099.05.07-000002",
  "rolled_over": true,
  "dry_run": false,
  "lazy": false,
  "conditions": {
    "[max_age: 7d]": false,
    "[max_docs: 1000]": true,
    "[max_primary_shard_size: 50gb]": false,
    "[max_primary_shard_docs: 2000]": false
  }
}

在滚动更新期间指定设置

edit

通常，您使用一个索引模板来自动配置在滚动更新期间创建的索引。如果您滚动更新一个索引别名，您可以使用滚动更新API来添加额外的索引设置或覆盖模板中的设置。数据流不支持settings参数。

POST my-alias/_rollover
{
  "settings": {
    "index.number_of_shards": 2
  }
}

收缩索引 API

edit

将现有索引收缩为具有较少主分片的新索引。

POST /my-index-000001/_shrink/shrunk-my-index-000001

请求

edit

POST //_shrink/

PUT //_shrink/

先决条件

edit

如果启用了Elasticsearch安全功能，您必须拥有该索引的manage 索引权限。
在您可以收缩一个索引之前：
- 索引必须是只读的。
- 索引中的每个分片副本必须位于同一节点上。
- 索引必须具有green 健康状态。

为了使分片分配更加容易，我们建议您同时移除索引的副本分片。您可以在缩减操作过程中重新添加副本分片。

您可以使用以下更新索引设置 API 请求来移除索引的副本分片，并将索引的剩余分片重新定位到同一节点。

PUT /my_source_index/_settings
{
  "settings": {
    "index.number_of_replicas": 0,                                
    "index.routing.allocation.require._name": "shrink_node_name"  
  }
}

	移除索引的副本分片。
	将索引的分片重新定位到`shrink_node_name`节点。请参阅索引级别的分片分配过滤。

重新定位源索引可能需要一些时间。可以通过_cat recovery API跟踪进度，或者可以使用cluster health API并设置wait_for_no_relocating_shards参数来等待所有分片完成重新定位。

然后，您可以使用以下请求通过添加索引块 API将索引设置为只读：

PUT /my_source_index/_block/write

描述

edit

收缩索引 API 允许您将现有索引收缩为一个新的索引，该索引具有较少的主分片。目标索引中请求的主分片数量必须是源索引中分片数量的因数。例如，一个具有 8 个主分片的索引可以收缩为 4、2 或 1 个主分片，或者一个具有 15 个主分片的索引可以收缩为 5、3 或 1 个主分片。如果索引中的分片数量是质数，它只能收缩为一个主分片。在收缩之前，索引中的每个分片（主分片或副本）的副本必须存在于同一节点上。

数据流上的当前写入索引无法缩小。为了缩小当前写入索引，必须首先将数据流滚动更新，以便创建新的写入索引，然后才能缩小之前的写入索引。

收缩的工作原理

edit

一个收缩操作：

创建一个新的目标索引，其定义与源索引相同，但主分片数量较少。
将段从源索引硬链接到目标索引。（如果文件系统不支持硬链接，则所有段都会被复制到新索引中，这是一个更加耗时的过程。此外，如果使用多个数据路径，不同数据路径上的分片如果不在同一磁盘上，则需要完整复制段文件，因为硬链接不能跨磁盘工作）
将目标索引恢复为如同刚刚重新打开的已关闭索引。恢复分片到索引设置 .routing.allocation.initial_recovery._id。

缩小索引

edit

要将 my_source_index 缩减到一个名为 my_target_index 的新索引中，请发出以下请求：

POST /my_source_index/_shrink/my_target_index
{
  "settings": {
    "index.routing.allocation.require._name": null, 
    "index.blocks.write": null 
  }
}

	清除从源索引复制的分配要求。
	清除从源索引复制的索引写入块。

上述请求在目标索引被添加到集群状态后立即返回——它不会等待收缩操作开始。

索引只有在满足以下要求时才能被收缩：

目标索引必须不存在。
源索引的主分片数必须多于目标索引。
目标索引中的主分片数必须是源索引中主分片数的因子。源索引的主分片数必须多于目标索引。
索引中的文档总数不得超过2,147,483,519，因为这是单个分片可以容纳的最大文档数。
处理收缩过程的节点必须有足够的可用磁盘空间来容纳现有索引的第二个副本。

The _shrink API 类似于 create index API 并且接受目标索引的 settings 和 aliases 参数：

POST /my_source_index/_shrink/my_target_index
{
  "settings": {
    "index.number_of_replicas": 1,
    "index.number_of_shards": 1, 
    "index.codec": "best_compression" 
  },
  "aliases": {
    "my_search_indices": {}
  }
}

	目标索引中的分片数量。这必须是源索引中分片数量的一个因子。
	最佳压缩效果只有在向索引进行新的写入时才会生效，例如在将分片强制合并为一个段时。

映射不能在_shrink请求中指定。

监控收缩过程

edit

收缩过程可以通过_cat recovery API进行监控，或者可以使用cluster health API来等待，直到所有主分片都被分配，方法是将wait_for_status 参数设置为yellow。

The _shrink API 在目标索引被添加到集群状态后立即返回，此时还没有任何分片被分配。在这个阶段，所有分片都处于 unassigned 状态。如果由于任何原因，目标索引无法在收缩节点上分配，其主分片将保持 unassigned 状态，直到它可以在该节点上分配。

一旦主分片被分配，它将进入状态 initializing，并且缩减过程开始。当缩减操作完成后，分片将变为 active。此时，Elasticsearch 将尝试分配任何副本，并可能决定将主分片重新定位到另一个节点。

等待活动分片

edit

因为收缩操作会创建一个新的索引来收缩分片，所以索引创建时的等待活动分片设置也适用于收缩索引操作。

路径参数

edit

<index>

(必需，字符串) 要缩小的源索引的名称。

<target-index>

(必需，字符串) 要创建的目标索引的名称。

索引名称必须满足以下条件：

仅限小写
不能包含 \, /, *, ?, ", <, >, |, ` ` (空格字符), ,, #
7.0 之前的索引可以包含冒号 (:)，但已被弃用，7.0 及以上版本将不再支持
不能以 -, _, + 开头
不能是 . 或 ..
不能超过 255 字节（注意是字节，因此多字节字符会更快达到 255 字节的限制）
以 . 开头的名称已被弃用，除了隐藏索引和插件管理的内部索引

查询参数

edit

wait_for_active_shards

(可选，字符串) 在继续操作之前，必须处于活动状态的每个分片的副本数量。设置为 all 或任何非负整数，最大不超过索引中每个分片的副本总数（number_of_replicas+1）。默认为 1，表示仅等待每个主分片处于活动状态。

请参阅Active shards。

master_timeout

(可选，时间单位) 等待主节点的时间段。如果在超时到期之前主节点不可用，请求将失败并返回错误。默认为30s。也可以设置为-1，表示请求不应超时。

timeout

(可选，时间单位) 在更新集群元数据后，等待集群中所有相关节点响应的时间段。如果在超时到期之前未收到响应，集群元数据更新仍然适用，但响应将表明它未被完全确认。默认为 30s。也可以设置为 -1 以指示请求不应超时。

请求体

edit

aliases

(可选，对象的对象) 结果索引的别名。

Properties of aliases objects

(必需，对象) 键是别名名称。索引别名名称支持日期数学。

对象体包含别名的选项。支持空对象。

Properties of

filter: (可选，Query DSL 对象) 用于限制别名可以访问的文档的查询。
index_routing: (可选，字符串) 用于将索引操作路由到特定分片的值。如果指定，这将覆盖索引操作的 routing 值。
is_hidden: (可选，布尔值) 如果为 true，则别名是隐藏的。默认为 false。别名的所有索引必须具有相同的 is_hidden 值。
is_write_index: (可选，布尔值) 如果为 true，则索引是别名的写入索引。默认为 false。
routing: (可选，字符串) 用于将索引和搜索操作路由到特定分片的值。
search_routing: (可选，字符串) 用于将搜索操作路由到特定分片的值。如果指定，这将覆盖搜索操作的 routing 值。

settings

(可选, 索引设置对象) 目标索引的配置选项。参见索引设置。

max_primary_shard_size

(可选, 字节单位) 目标索引的最大主分片大小。用于为目标索引找到最佳的分片数量。当设置此参数时，目标索引中每个分片的存储大小将不会超过此参数。目标索引的分片数量仍然是源索引分片数量的一个因素，但如果此参数小于源索引中单个分片的大小，则目标索引的分片数量将等于源索引的分片数量。例如，当此参数设置为50gb时，如果源索引有60个主分片，总计100gb，则目标索引将有2个主分片，每个分片大小为50gb；如果源索引有60个主分片，总计1000gb，则目标索引将有20个主分片；如果源索引有60个主分片，总计4000gb，则目标索引仍将有60个主分片。此参数与settings中的number_of_shards冲突，只能设置其中一个。

模拟索引 API

edit

返回将应用于指定索引的索引配置，该配置来自现有的索引模板。

POST /_index_template/_simulate_index/my-index-000001

请求

edit

POST /_index_template/_simulate_index/

先决条件

edit

如果启用了Elasticsearch安全功能，您必须拥有manage_index_templates或manage 集群权限才能使用此API。

路径参数

edit

<index>: (必需，字符串) 要模拟的索引名称。

查询参数

edit

master_timeout: (可选，时间单位) 等待主节点的时间段。如果在超时到期之前主节点不可用，请求将失败并返回错误。默认为30s。也可以设置为-1，表示请求不应超时。
include_defaults: (可选, 布尔值) 功能处于 [技术预览] 此功能处于技术预览阶段，可能会在未来的版本中更改或移除。Elastic 将努力修复任何问题，但技术预览中的功能不受正式 GA 功能支持 SLA 的约束。。如果 true，则在响应中返回所有默认设置。默认为 false。

响应体

edit

overlapping

(数组) 任何也匹配索引但被更高优先级模板取代的模板。响应包括一个空数组，如果没有重叠的模板。

Properties of overlapping

name: (字符串) 被取代模板的名称。
index_patterns: (数组) 被取代模板适用的索引模式。

template

(对象) 将应用于索引的设置、映射和别名。

Properties of template

aliases

(对象) 索引的别名。如果没有别名适用，响应将返回一个空的 aliases 对象。

(对象) 键是别名名称。对象体包含别名的选项。

Properties of

filter: (Query DSL object) 用于限制别名可以访问的文档的查询。
index_routing: (字符串) 用于将索引操作路由到特定分片的值。这将覆盖索引操作的 routing 值。
is_hidden: (布尔值) 如果为 true，则别名是隐藏的。
is_write_index: (布尔值) 如果为 true，则索引是别名的写入索引。
routing: (字符串) 用于将索引和搜索操作路由到特定分片的值。
search_routing: (字符串) 用于将搜索操作路由到特定分片的值。这将覆盖搜索操作的 routing 值。

mappings

(可选, 映射对象) 索引字段的映射。如果指定，此映射可以包括:

参见 Mapping。

如果没有任何映射会被应用，则从响应中省略。

settings

(可选, 索引设置对象) 索引的配置选项。参见索引设置。

如果没有任何设置会被应用，响应将包含一个空对象。

示例

edit

以下示例展示了将应用于 my-index-000001 的现有模板的配置。

PUT /_component_template/ct1                    
{
  "template": {
    "settings": {
      "index.number_of_shards": 2
    }
  }
}

PUT /_component_template/ct2                    
{
  "template": {
    "settings": {
      "index.number_of_replicas": 0
    },
    "mappings": {
      "properties": {
        "@timestamp": {
          "type": "date"
        }
      }
    }
  }
}

PUT /_index_template/final-template             
{
  "index_patterns": ["my-index-*"],
  "composed_of": ["ct1", "ct2"],
  "priority": 5
}

POST /_index_template/_simulate_index/my-index-000001

	创建一个组件模板（`ct1`），将分片数量设置为2
	创建第二个组件模板（`ct2`），将副本数量设置为0并定义一个映射
	创建一个索引模板（`final-template`），该模板使用组件模板
	显示将应用于`my-index-000001`的配置

响应显示了由final-template应用的索引设置、映射和别名：

{
  "template" : {
    "settings" : {
      "index" : {
        "number_of_shards" : "2",
        "number_of_replicas" : "0",
        "routing" : {
          "allocation" : {
            "include" : {
              "_tier_preference" : "data_content"
            }
          }
        }
      }
    },
    "mappings" : {
      "properties" : {
        "@timestamp" : {
          "type" : "date"
        }
      }
    },
    "aliases" : { }
  },
  "overlapping" : [
    {
      "name" : "template_1",
      "index_patterns" : [
        "my-index-*"
      ]
    }
  ]
}

模拟索引模板 API

edit

返回特定索引模板将应用的索引配置。

POST /_index_template/_simulate/template_1

请求

edit

POST /_index_template/_simulate/

先决条件

edit

如果启用了Elasticsearch安全功能，您必须拥有manage_index_templates或manage 集群权限才能使用此API。

路径参数

edit

<index-template>: (可选，字符串) 要模拟的索引模板的名称。要在将其添加到集群之前测试模板配置，请省略此参数并在请求体中指定模板配置。

查询参数

edit

create: (可选, 布尔值) 如果 true, 则仅当没有现有模板与相同的索引模式匹配时，才使用正文中传递的模板。如果 false, 模拟将使用具有最高优先级的模板。请注意，无论哪种情况，模板都不会永久添加或更新；它仅用于模拟。默认为 false。
master_timeout: (可选，时间单位) 等待主节点的时间段。如果在超时到期之前主节点不可用，请求将失败并返回错误。默认为30s。也可以设置为-1，表示请求不应超时。
include_defaults: (可选, 布尔值) 功能处于 [技术预览] 此功能处于技术预览阶段，可能会在未来的版本中更改或移除。Elastic 将努力修复任何问题，但技术预览中的功能不受正式 GA 功能支持 SLA 的约束。。如果 true，则在响应中返回所有默认设置。默认为 false。

请求体

edit

data_stream

(可选, 对象) 如果包含此对象，模板将用于创建数据流及其支持的索引。支持空对象。

数据流需要一个匹配的索引模板，其中包含一个data_stream对象。请参阅创建索引模板。

Properties of data_stream

allow_custom_routing

(可选, 布尔值) 如果 true，数据流支持自定义路由。默认为 false。

hidden

(可选, 布尔值) 如果 true，数据流是隐藏的。默认为 false。

index_mode

(可选, 字符串) 要创建的数据流类型。有效值为 null (常规数据流) 和 time_series (时间序列数据流)。

如果 time_series，每个后备索引都有一个 index.mode 索引设置为 time_series。

index_patterns

(必需，字符串数组) 用于在创建时匹配数据流和索引名称的通配符 (*) 表达式数组。

Elasticsearch 包含多个内置的索引模板。为了避免与这些模板发生命名冲突，请参阅避免索引模式冲突。

_meta

(可选, 对象) 关于索引模板的可选用户元数据。可以包含任何内容。此映射不会由Elasticsearch自动生成。

priority

(可选, 整数) 用于确定在新数据流或索引创建时索引模板的优先级。具有最高优先级的索引模板将被选择。如果没有指定优先级，模板将被视为优先级为0（最低优先级）。此数字不会由Elasticsearch自动生成。

template

(可选, 对象) 要应用的模板。它可以选择性地包括一个 aliases、mappings 或 settings 配置。

Properties of template

aliases

(可选，对象的对象) 要添加的别名。

如果索引模板包含一个data_stream对象，这些是数据流别名。否则，这些是索引别名。数据流别名忽略index_routing、routing和search_routing选项。

Properties of aliases objects

(必需，对象) 键是别名名称。索引别名名称支持日期数学。

对象体包含别名的选项。支持空对象。

Properties of

filter: (可选, 查询DSL对象) 用于限制别名可以访问的文档的查询。
index_routing: (可选, 字符串) 用于将索引操作路由到特定分片的值。如果指定，这将覆盖索引操作的routing值。
is_hidden: (可选, 布尔值) 如果为true，则别名是隐藏的。默认为false。别名的所有索引必须具有相同的is_hidden值。
is_write_index: (可选, 布尔值) 如果为true，则索引是别名的写入索引。默认为false。
routing: (可选, 字符串) 用于将索引和搜索操作路由到特定分片的值。
search_routing: (可选, 字符串) 用于将搜索操作路由到特定分片的值。如果指定，这将覆盖搜索操作的routing值。

mappings

(可选, 映射对象) 索引字段的映射。如果指定，此映射可以包括:

参见映射。

settings

(可选, 索引设置对象) 索引的配置选项。参见索引设置。

version

(可选, 整数) 用于外部管理索引模板的版本号。此编号不由Elasticsearch自动生成。

deprecated

(可选, 布尔值) 将此索引模板标记为已弃用。当创建或更新使用已弃用组件的非弃用索引模板时， Elasticsearch 将发出弃用警告。

响应体

edit

overlapping

(数组) 被指定模板取代的任何模板。

Properties of overlapping

index_patterns: (数组) 被取代模板应用的索引模式。
name: (字符串) 被取代模板的名称。

template

(对象) 将应用于匹配索引的设置、映射和别名。

Properties of template

aliases

(可选，对象的对象) 索引的别名。如果索引模板包含 data_stream，则不支持此参数。

Properties of aliases objects

(必需，对象) 键是别名名称。索引别名名称支持日期数学。

对象体包含别名的选项。支持空对象。

Properties of

filter: (可选, Query DSL object) 用于限制别名可以访问的文档的查询。
index_routing: (可选, 字符串) 用于将索引操作路由到特定分片的值。如果指定，这将覆盖索引操作的 routing 值。
is_hidden: (可选, 布尔值) 如果为 true，则别名是隐藏的。默认为 false。别名的所有索引必须具有相同的 is_hidden 值。
is_write_index: (可选, 布尔值) 如果为 true，则索引是别名的写入索引。默认为 false。
routing: (可选, 字符串) 用于将索引和搜索操作路由到特定分片的值。
search_routing: (可选, 字符串) 用于将搜索操作路由到特定分片的值。如果指定，这将覆盖搜索操作的 routing 值。

mappings

(可选, 映射对象) 索引字段的映射。如果指定，此映射可以包括:

参见 Mapping。

settings

(可选, 索引设置对象) 索引的配置选项。参见 Index settings。

示例

edit

模拟现有模板

edit

以下示例创建并模拟了一个组合模板：

PUT /_component_template/ct1                   
{
  "template": {
    "settings": {
      "index.number_of_shards": 2
    }
  }
}

PUT /_component_template/ct2                    
{
  "template": {
    "settings": {
      "index.number_of_replicas": 0
    },
    "mappings": {
      "properties": {
        "@timestamp": {
          "type": "date"
        }
      }
    }
  }
}

PUT /_index_template/final-template            
{
  "index_patterns": ["my-index-*"],
  "composed_of": ["ct1", "ct2"],
  "priority": 5
}

POST /_index_template/_simulate/final-template

	创建一个组件模板（`ct1`），将分片数量设置为2
	创建一个组件模板（`ct2`），将副本数量设置为0并定义一个映射
	创建一个索引模板（`final-template`），该模板使用组件模板
	显示由`final-template`应用的配置

响应显示了由final-template应用的索引设置、映射和别名：

{
  "template" : {
    "settings" : {
      "index" : {
        "number_of_shards" : "2",  
        "number_of_replicas" : "0", 
        "routing" : {
          "allocation" : {
            "include" : {
              "_tier_preference" : "data_content"
            }
          }
        }
      }
    },
    "mappings" : {                 
      "properties" : {
        "@timestamp" : {
          "type" : "date"
        }
      }
    },
    "aliases" : { }
  },
  "overlapping" : [ ]
}

	来自 `ct1` 的分片数量
	来自 `ct2` 的副本数量
	从 `ct1` 的映射

模拟任意模板配置

edit

要在将模板添加到集群之前查看将应用哪些设置，您可以在请求正文中传递模板配置。如果指定的模板的优先级高于现有模板，则将使用该模板进行模拟。

POST /_index_template/_simulate
{
  "index_patterns": ["my-index-*"],
  "composed_of": ["ct2"],
  "priority": 10,
  "template": {
    "settings": {
      "index.number_of_replicas": 1
    }
  }
}

响应显示任何优先级较低的重叠模板。

{
  "template" : {
    "settings" : {
      "index" : {
        "number_of_replicas" : "1",
        "routing" : {
          "allocation" : {
            "include" : {
              "_tier_preference" : "data_content"
            }
          }
        }
      }
    },
    "mappings" : {
      "properties" : {
        "@timestamp" : {
          "type" : "date"
        }
      }
    },
    "aliases" : { }
  },
  "overlapping" : [
    {
      "name" : "final-template",
      "index_patterns" : [
        "my-index-*"
      ]
    }
  ]
}

拆分索引 API

edit

将现有索引拆分为一个具有更多主分片的新索引。

POST /my-index-000001/_split/split-my-index-000001
{
  "settings": {
    "index.number_of_shards": 2
  }
}

请求

edit

POST //_split/

PUT //_split/

先决条件

edit

如果启用了Elasticsearch安全功能，您必须对该索引具有manage 索引权限。
在你能够拆分一个索引之前：
- 索引必须是只读的。
- 集群健康状态必须是绿色。

您可以使用以下请求通过添加索引块 API将索引设置为只读：

PUT /my_source_index/_block/write

数据流上的当前写入索引无法拆分。为了拆分当前写入索引，必须首先将数据流滚动更新，以便创建新的写入索引，然后才能拆分之前的写入索引。

描述

edit

拆分索引 API 允许您将现有索引拆分为一个新索引，其中每个原始主分片在新索引中被拆分为两个或更多主分片。

索引可以被分割的次数（以及每个原始分片可以被分割成的分片数量）由index.number_of_routing_shards设置决定。路由分片数量指定了内部用于通过一致性哈希在分片之间分发文档的哈希空间。例如，一个5分片的索引，如果number_of_routing_shards设置为30（5 x 2 x 3），则可以按2或3的因子进行分割。换句话说，它可以按如下方式分割：

5 → 10 → 30 (按2分割，然后按3分割)
5 → 15 → 30 (按3分割，然后按2分割)
5 → 30 (按6分割)

index.number_of_routing_shards 是一个静态索引设置。你只能在索引创建时或在一个关闭的索引上设置 index.number_of_routing_shards。

索引创建示例

以下创建索引 API创建了索引my-index-000001，并设置了index.number_of_routing_shards为30。

PUT /my-index-000001
{
  "settings": {
    "index": {
      "number_of_routing_shards": 30
    }
  }
}

设置 index.number_of_routing_shards 的默认值取决于原始索引中的主分片数量。默认值旨在允许您通过 2 的倍数进行拆分，最多可达 1024 个分片。然而，必须考虑原始主分片的数量。例如，一个创建时带有 5 个主分片的索引可以被拆分为 10、20、40、80、160、320 或最多 640 个分片（通过单次拆分操作或多步拆分操作）。

如果原始索引包含一个主分片（或者一个多分片索引已经被缩小到一个主分片），那么该索引可以被拆分成任意数量的分片，且数量大于1。默认的路由分片属性将适用于新拆分的索引。

拆分的工作原理

edit

一个分割操作：

创建一个与源索引定义相同的新目标索引，但具有更多的主分片。
将段从源索引硬链接到目标索引。（如果文件系统不支持硬链接，则所有段都会被复制到新索引中，这是一个更加耗时的过程。）
在创建低级文件后，再次对所有文档进行哈希处理，以删除属于不同分片的文档。
将目标索引恢复，就像它是一个刚刚重新打开的已关闭索引一样。

为什么Elasticsearch不支持增量重新分片？

edit

从 N 个分片到 N+1 个分片，即增量重新分片，确实是许多键值存储支持的功能。仅向新分片添加新分片并将新数据推送到新分片并不是一个选项：这可能会成为索引瓶颈，并且在给定其 _id 的情况下，确定文档属于哪个分片（这对于获取、删除和更新请求是必要的）将变得相当复杂。这意味着我们需要使用不同的哈希方案重新平衡现有数据。

键值存储实现这一点的最常见方式是使用一致性哈希。一致性哈希在将分片数量从 N 扩展到 N+1 时，只需要重新定位 1/N 的键。然而，Elasticsearch 的存储单元——分片，是 Lucene 索引。由于其面向搜索的数据结构，即使只删除 5% 的文档并将其重新索引到另一个分片上，通常也会比键值存储带来更高的成本。当通过乘法因子增加分片数量时，这种成本可以保持在合理范围内，如上节所述：这允许 Elasticsearch 在本地执行拆分，从而允许在索引级别执行拆分，而不是重新索引需要移动的文档，同时使用硬链接进行高效的文件复制。

在仅追加数据的情况下，通过创建一个新索引并将新数据推送到该索引，同时添加一个涵盖旧索引和新索引的别名以进行读操作，可以获得更大的灵活性。假设旧索引和新索引分别有M和N个分片，这与搜索一个具有M+N个分片的索引相比，没有任何开销。

拆分索引

edit

要将 my_source_index 拆分为名为 my_target_index 的新索引，请发出以下请求：

POST /my_source_index/_split/my_target_index
{
  "settings": {
    "index.number_of_shards": 2
  }
}

上述请求在目标索引被添加到集群状态后立即返回——它不会等待拆分操作开始。

索引只有在满足以下要求时才能被拆分：

目标索引必须不存在
源索引的主分片数量必须少于目标索引。
目标索引中的主分片数量必须是源索引中主分片数量的倍数。
处理拆分过程的节点必须有足够的可用磁盘空间来容纳现有索引的第二个副本。

The _split API 类似于 create index API 并且接受目标索引的 settings 和 aliases 参数：

POST /my_source_index/_split/my_target_index
{
  "settings": {
    "index.number_of_shards": 5 
  },
  "aliases": {
    "my_search_indices": {}
  }
}

目标索引中的分片数量。这必须是源索引中分片数量的倍数。

映射不能在 _split 请求中指定。

监控分割过程

edit

拆分过程可以通过_cat recovery API进行监控，或者可以使用cluster health API来等待，直到所有主分片都被分配，方法是将wait_for_status 参数设置为yellow。

The _split API 在目标索引被添加到集群状态后立即返回，此时还没有任何分片被分配。在这个阶段，所有分片都处于 unassigned 状态。如果由于任何原因，目标索引无法被分配，其主分片将保持 unassigned 状态，直到它可以在该节点上被分配。

一旦主分片被分配，它将进入状态 initializing，并且拆分过程开始。当拆分操作完成时，分片将变为 active。此时，Elasticsearch 将尝试分配任何副本，并可能决定将主分片重新定位到另一个节点。

等待活动分片

edit

因为拆分操作会创建一个新的索引来拆分分片，所以在索引创建时的等待活动分片设置也适用于拆分索引操作。

路径参数

edit

<index>

(必需，字符串) 要拆分的源索引的名称。

<target-index>

(必需，字符串) 要创建的目标索引的名称。

索引名称必须满足以下条件：

仅限小写
不能包含 \, /, *, ?, ", <, >, |, ` ` (空格字符), ,, #
7.0 之前的索引可以包含冒号 (:)，但已被弃用，7.0 及以上版本将不再支持
不能以 -, _, + 开头
不能是 . 或 ..
不能超过 255 字节（注意是字节，因此多字节字符会更快达到 255 字节的限制）
以 . 开头的名称已被弃用，除了隐藏索引和插件管理的内部索引

查询参数

edit

wait_for_active_shards

(可选，字符串) 在继续操作之前，必须处于活动状态的每个分片的副本数量。设置为 all 或任何非负整数，最大不超过索引中每个分片的副本总数（number_of_replicas+1）。默认为 1，表示仅等待每个主分片处于活动状态。

请参阅Active shards。

master_timeout

(可选，时间单位) 等待主节点的时间段。如果在超时到期之前主节点不可用，请求将失败并返回错误。默认为30s。也可以设置为-1，表示请求不应超时。

timeout

(可选，时间单位) 在更新集群元数据后，等待集群中所有相关节点响应的时间段。如果在超时到期之前未收到响应，集群元数据更新仍然适用，但响应将表明它未被完全确认。默认为 30s。也可以设置为 -1 以指示请求不应超时。

请求体

edit

aliases

(可选，对象的对象) 结果索引的别名。

Properties of aliases objects

(必需，对象) 键是别名名称。索引别名名称支持日期数学。

对象体包含别名的选项。支持空对象。

Properties of

filter: (可选，Query DSL 对象) 用于限制别名可以访问的文档的查询。
index_routing: (可选，字符串) 用于将索引操作路由到特定分片的值。如果指定，这将覆盖索引操作的 routing 值。
is_hidden: (可选，布尔值) 如果为 true，则别名是隐藏的。默认为 false。别名的所有索引必须具有相同的 is_hidden 值。
is_write_index: (可选，布尔值) 如果为 true，则索引是别名的写入索引。默认为 false。
routing: (可选，字符串) 用于将索引和搜索操作路由到特定分片的值。
search_routing: (可选，字符串) 用于将搜索操作路由到特定分片的值。如果指定，这将覆盖搜索操作的 routing 值。

settings

(可选, 索引设置对象) 目标索引的配置选项。参见索引设置。

解冻索引 API

edit

在7.14中已弃用

在8.0版本中，我们移除了冻结索引的功能。在之前的版本中，冻结索引可以减少其内存开销。然而，由于堆内存使用的最新改进，冻结索引不再有用。您可以使用此API来解冻在7.x版本中冻结的索引。冻结索引与冻结数据层无关。

解冻一个索引。

请求

edit

POST //_unfreeze

先决条件

edit

如果启用了Elasticsearch安全功能，您必须拥有目标索引或索引别名的manage 索引权限。

描述

edit

当一个冻结的索引被解冻时，该索引会经历正常的恢复过程，并再次变为可写状态。

路径参数

edit

<index>: （必需，字符串）索引的标识符。

示例

edit

以下示例解冻一个索引：

POST /my-index-000001/_unfreeze

更新索引设置 API

edit

实时更改动态索引设置。

对于数据流，索引设置更改默认会应用于所有后备索引。

PUT /my-index-000001/_settings
{
  "index" : {
    "number_of_replicas" : 2
  }
}

请求

edit

PUT //_settings

前提条件

edit

如果启用了Elasticsearch安全功能，您必须拥有目标数据流、索引或别名的manage 索引权限。

路径参数

edit

<target>: (可选，字符串) 用于限制请求的逗号分隔的数据流、索引和别名列表。支持通配符 (*)。要针对所有数据流和索引，请省略此参数或使用 * 或 _all。

查询参数

edit

allow_no_indices

(可选, 布尔值) 如果为false，当任何通配符表达式、索引别名或_all值仅针对缺失或关闭的索引时，请求将返回错误。即使请求针对其他打开的索引，此行为也适用。例如，如果一个请求针对foo*,bar*，但没有任何索引以bar开头，即使存在以foo开头的索引，请求也会返回错误。

默认为 false。

expand_wildcards

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

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

默认为 open。

flat_settings

(可选，布尔值) 如果 true，返回设置为扁平格式。默认为 false。

ignore_unavailable

(可选，布尔值) 如果为false，则当请求目标是一个缺失或关闭的索引时，请求将返回错误。默认为false。

preserve_existing

(可选，布尔值) 如果 true，则现有的索引设置保持不变。默认为 false。

reopen

(可选，布尔值) 如果为true，则通常仅在关闭的索引上更新的任何静态设置将通过自动关闭和重新打开受影响的索引来更新。如果为false，尝试在打开的索引上更新静态设置将失败。默认为false。

使用reopen参数在自动关闭的索引上更改索引设置将导致索引在重新打开过程中暂时不可用。

master_timeout: (可选，时间单位) 等待主节点的时间段。如果在超时到期之前主节点不可用，请求将失败并返回错误。默认为30s。也可以设置为-1，表示请求不应超时。
timeout: (可选，时间单位) 在更新集群元数据后，等待集群中所有相关节点响应的时间段。如果在超时到期之前未收到响应，集群元数据更新仍然适用，但响应将表明它未被完全确认。默认为 30s。也可以设置为 -1 以指示请求不应超时。

请求体

edit

settings: (可选, 索引设置对象) 索引的配置选项。参见索引设置。

示例

edit

重置索引设置

edit

要将设置恢复为默认值，请使用 null。例如：

PUT /my-index-000001/_settings
{
  "index" : {
    "refresh_interval" : null
  }
}

可以在索引模块中找到可以在活动索引上动态更新的每个索引设置列表。为了保留现有的设置不被更新，可以将preserve_existing请求参数设置为true。

批量索引使用

edit

例如，更新设置 API 可以用于动态改变索引，使其在批量索引时更具性能，然后将其切换到更实时的索引状态。在开始批量索引之前，使用：

PUT /my-index-000001/_settings
{
  "index" : {
    "refresh_interval" : "-1"
  }
}

（另一个优化选项是开始时索引没有任何副本，只在之后添加它们，但这确实取决于使用情况）。

然后，一旦批量索引完成，可以更新设置（例如，恢复为默认值）：

PUT /my-index-000001/_settings
{
  "index" : {
    "refresh_interval" : "1s"
  }
}

并且，应该调用强制合并：

POST /my-index-000001/_forcemerge?max_num_segments=5

更新索引分析

edit

您只能在已关闭的索引上定义新的分析器。

要添加分析器，您必须关闭索引，定义分析器，然后重新打开索引。

您无法关闭数据流的写入索引。

要更新数据流的写入索引和未来支持索引的分析器，请在数据流使用的索引模板中更新分析器。然后滚动数据流以将新分析器应用于数据流的写入索引和未来支持索引。这会影响搜索和滚动后添加到数据流中的任何新数据。但是，它不会影响数据流的支持索引或其现有数据。

要更改现有后备索引的分析器，您必须创建一个新的数据流并将数据重新索引到其中。请参阅使用重新索引更改映射或设置。

例如，以下命令将 content 分析器添加到 my-index-000001 索引中：

POST /my-index-000001/_close

PUT /my-index-000001/_settings
{
  "analysis" : {
    "analyzer":{
      "content":{
        "type":"custom",
        "tokenizer":"whitespace"
      }
    }
  }
}

POST /my-index-000001/_open

更新映射 API

edit

向现有数据流或索引添加新字段。您还可以使用此API更改现有字段的搜索设置。

对于数据流，这些更改默认会应用于所有后备索引。

PUT /my-index-000001/_mapping
{
  "properties": {
    "email": {
      "type": "keyword"
    }
  }
}

请求

edit

PUT //_mapping

先决条件

edit

如果启用了Elasticsearch的安全功能，您必须对目标数据流、索引或别名拥有manage 索引权限。

[7.9] 在7.9中已弃用。如果请求针对的是索引或索引别名，您还可以使用create、create_doc、index或write索引权限来更新其映射。

路径参数

edit

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

查询参数

edit

allow_no_indices

(可选, 布尔值) 如果为false，当任何通配符表达式、索引别名或_all值仅针对缺失或关闭的索引时，请求将返回错误。即使请求针对其他打开的索引，此行为也适用。例如，如果一个请求针对foo*,bar*，但没有任何索引以bar开头，即使存在以foo开头的索引，请求也会返回错误。

默认为 false。

expand_wildcards

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

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

默认为 open。

ignore_unavailable

(可选，布尔值) 如果为false，则当请求目标是一个缺失或关闭的索引时，请求将返回错误。默认为false。

master_timeout

(可选，时间单位) 等待主节点的时间段。如果在超时到期之前主节点不可用，请求将失败并返回错误。默认为30s。也可以设置为-1，表示请求不应超时。

timeout

(可选，时间单位) 在更新集群元数据后，等待集群中所有相关节点响应的时间段。如果在超时到期之前未收到响应，集群元数据更新仍然适用，但响应将表明它未被完全确认。默认为 30s。也可以设置为 -1 以指示请求不应超时。

write_index_only

(可选, 布尔值) 如果为true，映射仅应用于目标的当前写入索引。默认为false。

请求体

edit

properties

(必需，映射对象) 字段的映射。对于新字段，此映射可以包括：

对于现有字段，请参阅更改现有字段的映射。

示例

edit

单个目标的示例

edit

更新映射 API 需要一个现有的数据流或索引。以下创建索引 API 请求创建了没有映射的 publications 索引。

PUT /publications

以下更新映射 API 请求添加了 title，这是一个新的 text 字段，到 publications 索引中。

PUT /publications/_mapping
{
  "properties": {
    "title":  { "type": "text"}
  }
}

多个目标

edit

更新映射 API 可以应用于多个数据流或索引，只需一个请求。例如，您可以同时更新 my-index-000001 和 my-index-000002 索引的映射：

# Create the two indices
PUT /my-index-000001
PUT /my-index-000002

# Update both mappings
PUT /my-index-000001,my-index-000002/_mapping
{
  "properties": {
    "user": {
      "properties": {
        "name": {
          "type": "keyword"
        }
      }
    }
  }
}

向现有对象字段添加新属性

edit

您可以使用更新映射 API 向现有 对象字段添加新属性。要查看其工作原理，请尝试以下示例。

使用创建索引 API 来创建一个包含 name 对象字段和内部 first 文本字段的索引。

PUT /my-index-000001
{
  "mappings": {
    "properties": {
      "name": {
        "properties": {
          "first": {
            "type": "text"
          }
        }
      }
    }
  }
}

使用更新映射 API 在 name 字段中添加一个新的内部 last 文本字段。

PUT /my-index-000001/_mapping
{
  "properties": {
    "name": {
      "properties": {
        "last": {
          "type": "text"
        }
      }
    }
  }
}

向现有字段添加多字段

edit

多字段允许你以不同的方式索引同一个字段。你可以使用更新映射API来更新fields映射参数，并为现有字段启用多字段。

如果在添加多字段时索引（或数据流）中已包含文档，这些文档将不会包含新多字段的值。您可以使用通过查询更新API来填充新多字段。

要查看此操作的工作原理，请尝试以下示例。

使用创建索引 API 来创建一个包含 city 文本字段的索引。

PUT /my-index-000001
{
  "mappings": {
    "properties": {
      "city": {
        "type": "text"
      }
    }
  }
}

虽然文本字段适用于全文搜索，但关键词字段未经过分析，可能更适合用于排序或聚合。

使用更新映射 API 为 city 字段启用多字段。此请求添加了 city.raw 关键字多字段，可用于排序。

PUT /my-index-000001/_mapping
{
  "properties": {
    "city": {
      "type": "text",
      "fields": {
        "raw": {
          "type": "keyword"
        }
      }
    }
  }
}

更改现有字段的支持映射参数

edit

每个映射参数的文档都指明了是否可以使用更新映射API为现有字段更新它。例如，您可以使用更新映射API来更新ignore_above参数。

要查看此操作的工作原理，请尝试以下示例。

使用创建索引 API 来创建一个包含 user_id 关键词字段的索引。user_id 字段有一个 ignore_above 参数值为 20。

PUT /my-index-000001
{
  "mappings": {
    "properties": {
      "user_id": {
        "type": "keyword",
        "ignore_above": 20
      }
    }
  }
}

使用更新映射 API 将 ignore_above 参数值更改为 100。

PUT /my-index-000001/_mapping
{
  "properties": {
    "user_id": {
      "type": "keyword",
      "ignore_above": 100
    }
  }
}

更改现有字段的映射

edit

除了支持的映射参数，您不能更改现有字段的映射或字段类型。更改现有字段可能会使已索引的数据无效。

如果您需要更改数据流支持索引中某个字段的映射，请参阅更改数据流的映射和设置。

如果您需要更改其他索引中字段的映射，请创建一个具有正确映射的新索引并将您的数据重新索引到该索引中。

要查看如何更改索引中现有字段的映射，请尝试以下示例。

使用创建索引 API 来创建一个包含user_id字段的索引，并使用long字段类型。

PUT /my-index-000001
{
  "mappings" : {
    "properties": {
      "user_id": {
        "type": "long"
      }
    }
  }
}

使用索引 API 来索引多个文档，并设置user_id字段值。

POST /my-index-000001/_doc?refresh=wait_for
{
  "user_id" : 12345
}

POST /my-index-000001/_doc?refresh=wait_for
{
  "user_id" : 12346
}

要将user_id字段更改为keyword字段类型，请使用创建索引API 创建一个具有正确映射的新索引。

PUT /my-new-index-000001
{
  "mappings" : {
    "properties": {
      "user_id": {
        "type": "keyword"
      }
    }
  }
}

使用reindex API 将文档从旧索引复制到新索引。

POST /_reindex
{
  "source": {
    "index": "my-index-000001"
  },
  "dest": {
    "index": "my-new-index-000001"
  }
}

重命名字段

edit

重命名一个字段会使已经使用旧字段名称索引的数据失效。相反，添加一个alias字段来创建一个备用字段名称。

例如，使用创建索引 API 来创建一个包含user_identifier字段的索引。

PUT /my-index-000001
{
  "mappings": {
    "properties": {
      "user_identifier": {
        "type": "keyword"
      }
    }
  }
}

使用更新映射 API 为现有的 user_identifier 字段添加 user_id 字段别名。

PUT /my-index-000001/_mapping
{
  "properties": {
    "user_id": {
      "type": "alias",
      "path": "user_identifier"
    }
  }
}

索引 API

索引 API

索引管理：

映射管理：

别名管理：

索引设置：

索引模板：

监控：

状态管理：

悬空索引：

别名存在 API

请求

先决条件

路径参数

查询参数

响应代码

别名 API

请求

先决条件

查询参数

请求体

响应体

分析 API

请求

前提条件

路径参数

查询参数

示例

未指定索引

文本字符串数组

自定义分析器

特定索引

从字段映射派生分析器

规范化器

解释分析

设置令牌限制

分析索引磁盘使用情况 API

请求

前提条件

路径参数

查询参数

示例

清除缓存 API

请求

先决条件

路径参数

查询参数

示例

清除特定缓存

清除特定字段的缓存

清除多个数据流和索引的缓存

清除所有数据流和索引的缓存

克隆索引 API

请求

先决条件

描述

克隆的工作原理

克隆一个索引

监控克隆过程

等待活动分片

路径参数

查询参数

请求体

关闭索引 API

请求

前提条件

描述

路径参数

查询参数

示例

创建索引 API

请求

先决条件

描述

路径参数

查询参数

请求体

示例

索引设置

映射