› ›

数据流API

edit

数据流API

edit

以下API可用于管理数据流：

以下API可用于管理数据流的内置生命周期：

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

更新数据流生命周期 [预览] 此功能处于技术预览阶段，可能会在未来的版本中更改或删除。Elastic 将努力修复任何问题，但技术预览中的功能不受官方 GA 功能支持 SLA 的约束。
获取数据流生命周期 [预览] 此功能处于技术预览阶段，可能会在未来的版本中更改或删除。Elastic 将努力修复任何问题，但技术预览中的功能不受官方 GA 功能支持 SLA 的约束。
删除数据流生命周期 [预览] 此功能处于技术预览阶段，可能会在未来的版本中更改或删除。Elastic 将努力修复任何问题，但技术预览中的功能不受官方 GA 功能支持 SLA 的约束。
解释数据流生命周期 [预览] 此功能处于技术预览阶段，可能会在未来的版本中更改或删除。Elastic 将努力修复任何问题，但技术预览中的功能不受官方 GA 功能支持 SLA 的约束。
获取数据流生命周期统计信息 [预览] 此功能处于技术预览阶段，可能会在未来的版本中更改或删除。Elastic 将努力修复任何问题，但技术预览中的功能不受官方 GA 功能支持 SLA 的约束。

以下 API 适用于时间序列数据流：

下采样

有关概念和教程，请参阅数据流。

创建数据流 API

edit

创建一个新的数据流。

PUT /_data_stream/my-data-stream

请求

edit

PUT /_data_stream/

先决条件

edit

如果启用了Elasticsearch安全功能，您必须拥有create_index或manage 索引权限才能访问数据流。
一个启用了数据流的匹配索引模板。请参阅设置数据流。

路径参数

edit

<data-stream>

（必需，字符串）要创建的数据流的名称。数据流名称必须满足以下条件：

仅小写
不能包含 \, /, *, ?, ", <, >, |, ,, #, :, 或空格字符
不能以 -, _, +, 或 .ds- 开头
不能是 . 或 ..
不能超过 255 字节。多字节字符会更快地达到此限制。

删除数据流 API

edit

删除一个或多个数据流及其支持的索引。请参阅删除数据流。

DELETE /_data_stream/my-data-stream

请求

edit

DELETE /_data_stream/

前提条件

edit

如果启用了Elasticsearch安全功能，您必须拥有delete_index或manage 索引权限才能操作数据流。

路径参数

edit

<data-stream>: (必需，字符串) 要删除的数据流的逗号分隔列表。支持通配符 (*) 表达式。

查询参数

edit

expand_wildcards

(可选，字符串) 通配符模式可以匹配的数据流类型。支持逗号分隔的值，例如 open,hidden。有效值包括：

all, hidden: 匹配任何数据流，包括隐藏的数据流。
open, closed: 匹配任何非隐藏的数据流。数据流不能被关闭。
none: 不接受通配符模式。

默认为 open。

获取数据流 API

edit

检索有关一个或多个数据流的信息。请参阅获取数据流信息。

GET /_data_stream/my-data-stream

请求

edit

GET /_data_stream/

先决条件

edit

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

路径参数

edit

<data-stream>: (可选，字符串) 用于限制请求的逗号分隔的数据流名称列表。支持通配符 (*) 表达式。如果省略，将返回所有数据流。

查询参数

edit

expand_wildcards

(可选，字符串) 通配符模式可以匹配的数据流类型。支持逗号分隔的值，例如 open,hidden。有效值包括：

all, hidden: 匹配任何数据流，包括隐藏的数据流。
open, closed: 匹配任何非隐藏的数据流。数据流不能被关闭。
none: 不接受通配符模式。

默认为 open。

include_defaults

(可选, 布尔值) 功能处于 [技术预览] 此功能处于技术预览阶段，可能会在未来的版本中更改或移除。Elastic 将努力修复任何问题，但技术预览中的功能不受正式 GA 功能支持 SLA 的约束。。如果 true，则在响应中返回所有默认设置。默认为 false。

verbose

(可选，布尔值)。如果为true，返回数据流中文档的@timestamp字段对应的maximum_timestamp。默认为false。

响应体

edit

data_streams

(对象数组) 包含有关检索到的数据流的信息。

对象在 data_streams 中的属性

name

(字符串) 数据流的名称。

timestamp_field

(对象) 包含有关数据流的 @timestamp 字段的信息。

timestamp_field 的属性

name: (字符串) 数据流的时间戳字段的名称，必须是 @timestamp。@timestamp 字段必须包含在索引到数据流的每个文档中。

indices

(对象数组) 包含有关数据流支持索引信息的数组对象。

这个数组中的最后一项包含了关于流的当前写索引的信息。

indices 对象的属性

index_name: (字符串) 支持索引的名称。有关命名约定，请参阅生成。
index_uuid: (字符串) 索引的通用唯一标识符 (UUID)。
prefer_ilm: (布尔值) [预览] 此功能处于技术预览阶段，可能会在未来的版本中进行更改或移除。Elastic 将努力修复任何问题，但技术预览中的功能不受官方 GA 功能支持 SLA 的约束。。指示此索引是否配置为在同时配置了索引生命周期管理和数据流生命周期时，优先使用索引生命周期管理。
managed_by: (字符串) [预览] 此功能处于技术预览阶段，可能会在未来的版本中进行更改或移除。Elastic 将努力修复任何问题，但技术预览中的功能不受官方 GA 功能支持 SLA 的约束。。指示管理此索引的系统。

generation

(整数) 数据流的当前生成。此数字作为流的翻转的累积计数，从 1 开始。

_meta

(对象) 流的定制元数据，从流的匹配索引模板的 _meta 对象复制。如果为空，则响应中省略此属性。

status

(字符串) 数据流的运行状况。

此健康状态基于流的备份索引的主分片和副本分片的状态。

status 的值

GREEN: 所有分片都已分配。
YELLOW: 所有主分片都已分配，但一个或多个副本分片未分配。
RED: 一个或多个主分片未分配，因此某些数据不可用。

template

(字符串) 用于创建数据流支持索引的索引模板名称。

模板的索引模式必须与该数据流的名称匹配。请参阅创建索引模板。

ilm_policy

(字符串) 当前 ILM 生命周期策略的名称，该策略设置在流匹配索引模板中。此生命周期策略在 index.lifecycle.name 设置中定义。

如果模板不包含生命周期策略，则此属性不会包含在响应中。

数据流的备份索引可能被分配不同的生命周期策略。要检索单个备份索引的生命周期策略，请使用获取索引设置 API。

next_generation_managed_by

(字符串) [预览] 此功能处于技术预览阶段，可能会在未来的版本中进行更改或移除。Elastic 将努力修复任何问题，但技术预览中的功能不受官方 GA 功能支持 SLA 的约束。。指示将管理下一个生成索引（即下一个数据流写索引）的系统。

prefer_ilm

(布尔值) [预览] 此功能处于技术预览阶段，可能会在未来的版本中进行更改或移除。Elastic 将努力修复任何问题，但技术预览中的功能不受官方 GA 功能支持 SLA 的约束。。指示用于创建数据流支持索引的索引模板是否配置为在同时配置了索引生命周期管理和数据流生命周期时，优先使用索引生命周期管理。

hidden

(布尔值) 如果为 true，则数据流是隐藏的。

system

(布尔值) 如果为 true，则数据流是由 Elastic 堆栈组件创建和管理的，不能通过正常的用户交互进行修改。

allow_custom_routing

(布尔值) 如果为 true，则此数据流允许在写请求上进行自定义路由。

replicated

(布尔值) 如果为 true，则数据流是由跨集群复制创建和管理的，本地集群不能写入此数据流或更改其映射。

lifecycle

(对象) [预览] 此功能处于技术预览阶段，可能会在未来的版本中进行更改或移除。Elastic 将努力修复任何问题，但技术预览中的功能不受官方 GA 功能支持 SLA 的约束。。包含此数据流的生命周期管理配置。

lifecycle 的属性

data_retention: (字符串) 如果定义，添加到此数据流的每个文档将至少存储在此时间框架内。在此持续时间之后，文档可能会被删除。如果为空，则此数据流中的每个文档将无限期存储。
rollover: (对象) 将触发备份索引翻转的条件，如集群设置 cluster.lifecycle.default.rollover 所配置。此属性是实现细节，只有在查询参数 include_defaults 设置为 true 时才会检索。此字段的内容可能会发生变化。

rollover_on_write

(布尔值) 如果为 true，则对此数据流的下一个写操作将首先触发翻转，文档将被索引到新的备份索引中。如果翻转失败，索引请求也将失败。

示例

edit

GET _data_stream/my-data-stream*

API返回以下响应：

{
  "data_streams": [
    {
      "name": "my-data-stream",
      "timestamp_field": {
        "name": "@timestamp"
      },
      "indices": [
        {
          "index_name": ".ds-my-data-stream-2099.03.07-000001",
          "index_uuid": "xCEhwsp8Tey0-FLNFYVwSg",
          "prefer_ilm": true,
          "ilm_policy": "my-lifecycle-policy",
          "managed_by": "Index Lifecycle Management"
        },
        {
          "index_name": ".ds-my-data-stream-2099.03.08-000002",
          "index_uuid": "PA_JquKGSiKcAKBA8DJ5gw",
          "prefer_ilm": true,
          "ilm_policy": "my-lifecycle-policy",
          "managed_by": "Index Lifecycle Management"
        }
      ],
      "generation": 2,
      "_meta": {
        "my-meta-field": "foo"
      },
      "status": "GREEN",
      "next_generation_managed_by": "Index Lifecycle Management",
      "prefer_ilm": true,
      "template": "my-index-template",
      "ilm_policy": "my-lifecycle-policy",
      "hidden": false,
      "system": false,
      "allow_custom_routing": false,
      "replicated": false,
      "rollover_on_write": false
    },
    {
      "name": "my-data-stream-two",
      "timestamp_field": {
        "name": "@timestamp"
      },
      "indices": [
        {
          "index_name": ".ds-my-data-stream-two-2099.03.08-000001",
          "index_uuid": "3liBu2SYS5axasRt6fUIpA",
          "prefer_ilm": true,
          "ilm_policy": "my-lifecycle-policy",
          "managed_by": "Index Lifecycle Management"
        }
      ],
      "generation": 1,
      "_meta": {
        "my-meta-field": "foo"
      },
      "status": "YELLOW",
      "next_generation_managed_by": "Index Lifecycle Management",
      "prefer_ilm": true,
      "template": "my-index-template",
      "ilm_policy": "my-lifecycle-policy",
      "hidden": false,
      "system": false,
      "allow_custom_routing": false,
      "replicated": false,
      "rollover_on_write": false
    }
  ]
}

迁移到数据流API

edit

将一个索引别名转换为数据流。

POST /_data_stream/_migrate/my-logs

请求

edit

POST /_data_stream/_migrate/

先决条件

edit

如果启用了Elasticsearch安全功能，您必须拥有索引别名的manage 索引权限。
启用了数据流的匹配索引模板。请参阅设置数据流。

路径参数

edit

<alias>

(必需，字符串) 要转换为数据流的索引别名的名称。该别名必须满足以下条件：

别名必须有一个写入索引。
别名的所有索引都有一个@timestamp字段映射，该字段类型为date或date_nanos。
别名不能有任何过滤器。
别名不能使用自定义路由。

如果成功，请求将移除别名并创建一个与别名同名的数据流。别名的索引成为流的隐藏后备索引。别名的写入索引成为流的写入索引。

数据流统计 API

edit

检索一个或多个数据流的统计信息。

GET /_data_stream/my-data-stream/_stats

先决条件

edit

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

请求

edit

GET /_data_stream//_stats

路径参数

edit

<data-stream>

(可选，字符串) 用于限制请求的逗号分隔的数据流列表。支持通配符表达式 (*)。

要定位集群中的所有数据流，请省略此参数或使用 *。

查询参数

edit

expand_wildcards

(可选，字符串) 通配符模式可以匹配的数据流类型。支持逗号分隔的值，例如 open,hidden。有效值包括：

all, hidden: 匹配任何数据流，包括隐藏的数据流。
open, closed: 匹配任何非隐藏的数据流。数据流不能被关闭。
none: 不接受通配符模式。

默认为 open。

human

(可选，布尔值) 如果为true，响应将包含以人类可读的字节值表示的统计信息。默认为false。

响应体

edit

_shards

(对象) 包含有关尝试执行请求的分片的信息。

Properties of _shards

total: (整数) 尝试执行请求的分片总数。
successful: (整数) 成功执行请求的分片数量。
failed: (整数) 未能执行请求的分片数量。

data_stream_count

(整数) 所选数据流的总数。

backing_indices

(整数) 所选数据流的备份索引总数。

total_store_size

(字节值) 所选数据流的全部分片的总大小。仅当human查询参数为true时，才会包含此属性。

total_store_size_bytes

(整数) 所选数据流的全部分片总大小，以字节为单位。

data_streams

(对象数组) 包含所选数据流的统计信息。

对象在 data_streams 中的属性

data_stream

(字符串) 数据流的名称。

backing_indices

(整数) 数据流当前的备份索引数量。

store_size

(字节值) 数据流备份索引的所有分片的总大小。仅当 human 查询参数为 true 时返回此参数。

store_size_bytes

(整数) 数据流备份索引的所有分片的总大小，以字节为单位。

maximum_timestamp

(整数) 数据流的最高 @timestamp 值，转换为自 Unix 纪元以来的毫秒数。

如果满足以下一个或多个条件，数据流可能包含高于此值的 @timestamp：

数据流包含已关闭的备份索引。
具有较低代数的备份索引包含更高的 @timestamp 值。

示例

edit

GET /_data_stream/my-data-stream*/_stats?human=true

API返回以下响应。

{
  "_shards": {
    "total": 10,
    "successful": 5,
    "failed": 0
  },
  "data_stream_count": 2,
  "backing_indices": 5,
  "total_store_size": "7kb",
  "total_store_size_bytes": 7268,
  "data_streams": [
    {
      "data_stream": "my-data-stream",
      "backing_indices": 3,
      "store_size": "3.7kb",
      "store_size_bytes": 3772,
      "maximum_timestamp": 1607512028000
    },
    {
      "data_stream": "my-data-stream-two",
      "backing_indices": 2,
      "store_size": "3.4kb",
      "store_size_bytes": 3496,
      "maximum_timestamp": 1607425567000
    }
  ]
}

提升数据流API

edit

推广数据流 API 的目的是将由 CCR 复制的数据流转换为常规数据流。

通过CCR自动跟随，可以将远程集群的数据流复制到本地集群。这些数据流在本地集群中无法滚动。只有当上游数据流滚动时，这些复制的数据流才会滚动。如果远程集群不再可用，本地集群中的数据流可以提升为常规数据流，从而允许这些数据流在本地集群中滚动。

在提升数据流时，确保本地集群有一个启用了数据流功能的索引模板与数据流匹配。如果缺少这个模板，数据流将无法进行滚动更新，直到创建了匹配的索引模板。这会影响数据流的生命周期管理，并干扰数据流的大小和保留策略。

POST /_data_stream/_promote/my-data-stream

请求

edit

POST /_data_stream/_promote/

前提条件

edit

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

路径参数

edit

<data-stream>: (必需，字符串) 要提升的数据流的名称。

修改数据流 API

edit

在一个单一的原子操作中执行一个或多个数据流修改操作。

POST _data_stream/_modify
{
  "actions": [
    {
      "remove_backing_index": {
        "data_stream": "my-logs",
        "index": ".ds-my-logs-2099.01.01-000001"
      }
    },
    {
      "add_backing_index": {
        "data_stream": "my-logs",
        "index": "index-to-add"
      }
    }
  ]
}

请求

edit

POST /_data_stream/_modify

请求体

edit

actions

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

Properties of actions objects

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

Valid keys

add_backing_index: 将现有索引添加为数据流的备份索引。该索引在此操作中被隐藏。

使用 add_backing_index 操作添加索引可能会导致数据流行为不正确。这应被视为专家级 API。

remove_backing_index: 从数据流中移除备份索引。该索引在此操作中被取消隐藏。数据流的写入索引不能被移除。

对象体包含操作的选项。

Properties of

data_stream: (Required*, string) 操作目标的数据流。
index: (Required*, string) 操作的索引。

设置数据流的生命周期

edit

配置目标数据流的生命周期。

先决条件

edit

如果启用了Elasticsearch安全功能，您必须拥有manage_data_stream_lifecycle索引权限或更高权限才能使用此API。有关更多信息，请参阅安全权限。

请求

edit

PUT _data_stream//_lifecycle

描述

edit

配置目标数据流的生命周期。如果提供了多个数据流，但其中至少有一个不存在，那么所有数据流的生命周期更新都将失败，API将返回404。

路径参数

edit

<data-stream>: (必需，字符串) 用于限制请求的逗号分隔的数据流列表。支持通配符 (*)。要针对所有数据流，请使用 * 或 _all。

查询参数

edit

expand_wildcards

(可选，字符串) 通配符模式可以匹配的数据流类型。支持逗号分隔的值，例如 open,hidden。有效值包括：

all, hidden: 匹配任何数据流，包括隐藏的数据流。
open, closed: 匹配任何非隐藏的数据流。数据流不能被关闭。
none: 不接受通配符模式。

默认为 open。

请求体

edit

lifecycle

（必需，对象）

属性 lifecycle

data_retention: (可选，字符串) 如果定义了，添加到此数据流的每个文档将至少存储在此时间范围内。在此持续时间之后的任何时间，文档都可能被删除。如果为空，此数据流中的每个文档将无限期存储。
enabled: (可选，布尔值) 如果定义了，它将为此数据流打开/关闭数据流生命周期（true/false）。一个被禁用的数据流生命周期（enabled: false）将对此数据流没有任何影响。默认为 true。
downsampling: (可选，数组) 一个可选的降采样配置对象数组，每个对象定义一个 after 间隔，表示后备索引应在何时进行降采样（时间范围是从索引滚动更新时计算的，即生成时间），以及一个 fixed_interval 表示降采样间隔（最小 fixed_interval 值为 5m）。最多可以配置10轮降采样。请参见下面的配置示例。

示例

edit

以下示例设置了 my-data-stream 的生命周期：

PUT _data_stream/my-data-stream/_lifecycle
{
  "data_retention": "7d"
}

当生命周期在所有数据流中成功更新时，您将收到以下结果：

{
  "acknowledged": true
}

示例

edit

以下示例配置了两个降采样轮次，第一个轮次在后备索引滚动更新后一天开始（或者更晚，如果索引仍在其写入接受时间界限内），间隔为10m，第二个轮次在滚动更新后7天开始，间隔为1d：

PUT _data_stream/my-weather-sensor-data-stream/_lifecycle
{
    "downsampling": [
      {
        "after": "1d",
        "fixed_interval": "10m"
      },
      {
        "after": "7d",
        "fixed_interval": "1d"
      }
    ]
}

获取数据流的生命周期

edit

获取一组数据流的生命周期。

先决条件

edit

如果启用了Elasticsearch安全功能，您必须至少拥有以下权限之一：manage 索引权限、manage_data_stream_lifecycle索引权限或 view_index_metadata权限才能使用此API。有关更多信息，请参阅安全权限。

请求

edit

GET _data_stream//_lifecycle

描述

edit

获取指定数据流的声明周期。如果请求了多个数据流，但其中至少有一个不存在，则API将响应404，因为至少有一个请求的资源无法检索。如果请求的数据流没有配置声明周期，它们仍然会包含在API响应中，但lifecycle键将缺失。

路径参数

edit

<data-stream>: (必需，字符串) 用于限制请求的逗号分隔的数据流列表。支持通配符 (*)。要针对所有数据流，请使用 * 或 _all。

查询参数

edit

expand_wildcards

(可选，字符串) 通配符模式可以匹配的数据流类型。支持逗号分隔的值，例如 open,hidden。有效值包括：

all, hidden: 匹配任何数据流，包括隐藏的数据流。
open, closed: 匹配任何非隐藏的数据流。数据流不能被关闭。
none: 不接受通配符模式。

默认为 open。

include_defaults

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

响应体

edit

data_streams

(对象数组) 包含有关检索到的数据流生命周期的信息。

对象在 data_streams 中的属性

name

(字符串) 数据流的名称。

lifecycle

（可选，对象）

lifecycle 的属性

data_retention: (可选，字符串) 如果定义了，它表示数据流所有者为此数据流请求的保留期。
effective_retention: (可选，字符串) 如果定义了，添加到此数据流的每个文档将至少存储此时间段。在此时间段之后的任何时间，文档都可能被删除。如果为空，此数据流中的每个文档将无限期存储。有效保留期的计算方法如教程中所述。
retention_determined_by: (可选，字符串) 保留期的来源，可以是以下三个值之一：data_stream_configuration、default_retention 或 max_retention。
rollover: (可选，对象) 将触发后备索引滚动更新的条件，如集群设置 cluster.lifecycle.default.rollover 所配置。此属性是实现细节，只有在查询参数 include_defaults 设置为 true 时才会检索。此字段的内容可能会发生变化。

global_retention

(对象) 包含全局最大值和默认保留值。当未配置全局保留时，这将是一个空对象。

Properties of global_retention

max_retention: (可选, 字符串) 由数据流生命周期管理的数据流的有效保留不能超过此值。
default_retention: (可选, 字符串) 这将是未指定data_retention的数据流的有效保留。

示例

edit

让我们检索生命周期：

GET _data_stream/my-data-stream*/_lifecycle

响应将如下所示：

{
  "data_streams": [
    {
      "name": "my-data-stream-1",
      "lifecycle": {
        "enabled": true,
        "data_retention": "7d",
        "effective_retention": "7d",
        "retention_determined_by": "data_stream_configuration"
      }
    },
    {
      "name": "my-data-stream-2",
      "lifecycle": {
        "enabled": true,
        "data_retention": "7d",
        "effective_retention": "7d",
        "retention_determined_by": "data_stream_configuration"
      }
    }
  ],
  "global_retention": {}
}

删除数据流的生命周期

edit

从一组数据流中删除生命周期。

前提条件

edit

如果启用了Elasticsearch的安全功能，您必须拥有manage_data_stream_lifecycle索引权限或更高权限才能使用此API。更多信息，请参阅安全权限。

请求

edit

DELETE _data_stream//_lifecycle

描述

edit

删除指定数据流的生存时间。如果提供了多个数据流，但其中至少有一个不存在，则所有数据流的生存时间删除操作都将失败，API将返回404。

路径参数

edit

<data-stream>: (必需，字符串) 用于限制请求的逗号分隔的数据流列表。支持通配符 (*)。要针对所有数据流，请使用 * 或 _all。

查询参数

edit

expand_wildcards

(可选，字符串) 通配符模式可以匹配的数据流类型。支持逗号分隔的值，例如 open,hidden。有效值包括：

all, hidden: 匹配任何数据流，包括隐藏的数据流。
open, closed: 匹配任何非隐藏的数据流。数据流不能被关闭。
none: 不接受通配符模式。

默认为 open。

示例

edit

以下示例删除了 my-data-stream 的生命周期：

DELETE _data_stream/my-data-stream/_lifecycle

当策略成功从所有选定的数据流中删除时，您将收到以下结果：

{
  "acknowledged": true
}

解释数据流生命周期

edit

检索一个或多个数据流支持索引的当前数据流生命周期状态。

先决条件

edit

如果启用了Elasticsearch的安全功能，您必须至少拥有manage_data_stream_lifecycle索引权限或view_index_metadata索引权限才能使用此API。更多信息，请参阅安全权限。

请求

edit

GET /_lifecycle/explain

描述

edit

检索有关索引或数据流的当前数据流生命周期状态的信息，例如索引创建后的时间、翻转后的时间、管理索引的生命周期配置，或Elasticsearch在生命周期执行过程中可能遇到的任何错误。

路径参数

edit

<target>: (必需，字符串) 逗号分隔的索引或数据流列表。

查询参数

edit

include_defaults: (可选，布尔值) 包含与目标生命周期相关的默认配置。默认为 false。
master_timeout: (可选，时间单位) 等待主节点的时间段。如果在超时到期之前主节点不可用，请求将失败并返回错误。默认为30s。也可以设置为-1，表示请求不应超时。

示例

edit

如果你想检索数据流的所有后备索引的生命周期状态，你可以使用数据流名称。为了简单起见，以下示例检索一个后备索引 .ds-metrics-2023.03.22-000001 的生命周期状态：

GET .ds-metrics-2023.03.22-000001/_lifecycle/explain

如果索引由数据流生命周期管理，explain 将显示 managed_by_lifecycle 字段设置为 true，并且响应的其余部分将包含有关此索引的生命周期执行状态的信息：

{
  "indices": {
    ".ds-metrics-2023.03.22-000001": {
      "index" : ".ds-metrics-2023.03.22-000001",
      "managed_by_lifecycle" : true,                        
      "index_creation_date_millis" : 1679475563571,   
      "time_since_index_creation" : "843ms",          
      "rollover_date_millis" : 1679475564293,         
      "time_since_rollover" : "121ms",                
      "lifecycle" : { },                              
      "generation_time" : "121ms"                     
  }
}

	显示索引是否由数据流生命周期管理。如果索引不由数据流生命周期管理，则不会显示其他字段
	当索引被创建时，这个时间戳用于确定何时进行滚动更新
	自索引创建以来的时间（用于通过`max_age`计算何时滚动更新索引）
	当索引被滚动更新时。如果索引没有被滚动更新，则不会显示此信息。
	自上次滚动以来的时间。如果索引未滚动，则不会显示此信息。
	应用于该索引的生命周期配置（在父数据流上配置）
	索引的生成时间表示自索引开始向用户可配置/业务特定的生命周期部分（例如保留）进展以来的时间。 `generation_time` 是从起源日期（如果存在）计算的，或者从滚动日期（如果存在）计算的，或者从创建日期（如果其他两个都不存在）计算的。如果索引是写入索引，则不会报告 `generation_time`，因为它不符合保留或其他生命周期部分的条件。

The explain 还将报告与目标索引的生命周期执行相关的任何错误：

{
  "indices": {
    ".ds-metrics-2023.03.22-000001": {
      "index" : ".ds-metrics-2023.03.22-000001",
      "managed_by_lifecycle" : true,
      "index_creation_date_millis" : 1679475563571,
      "time_since_index_creation" : "843ms",
      "lifecycle" : {
        "enabled": true
      },
      "error": "{\"type\":\"validation_exception\",\"reason\":\"Validation Failed: 1: this action would add [2] shards, but this cluster
currently has [4]/[3] maximum normal shards open;\"}"        
  }
}

由于集群中允许的分片数量限制，目标索引无法进行滚动更新。

获取数据流生命周期统计信息

edit

获取有关数据流生命周期执行的统计信息。

先决条件

edit

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

请求

edit

GET _lifecycle/stats

描述

edit

获取有关数据流生命周期执行的统计信息。数据流级别的统计信息仅包括有关由数据流生命周期管理的数据流的统计信息。

响应体

edit

last_run_duration_in_millis

(可选, 长整型) 上次数据流生命周期执行的持续时间。

time_between_starts_in_millis

(可选, 长整型) 上两次数据流生命周期执行开始之间经过的时间。这应该大约等于 data_streams.lifecycle.poll_interval。

data_stream_count

(整数) 数据流生命周期当前正在管理的数据流数量。

data_streams

(对象数组) 包含有关检索到的数据流生命周期的信息。

对象在 data_streams 中的属性

name: (字符串) 数据流的名称。
backing_indices_in_total: (整数) 由数据流生命周期管理的后备索引的数量。
backing_indices_in_error: (整数) 由数据流生命周期管理并遇到错误的备份索引的数量。

示例

edit

让我们检索一个已经执行过多次生命周期的集群的数据流生命周期统计信息：

GET _lifecycle/stats?human&pretty

响应将如下所示：

{
  "last_run_duration_in_millis": 2,
  "last_run_duration": "2ms",
  "time_between_starts_in_millis": 9998,
  "time_between_starts": "9.99s",
  "data_streams_count": 2,
  "data_streams": [
    {
      "name": "my-data-stream",
      "backing_indices_in_total": 2,
      "backing_indices_in_error": 0
    },
    {
      "name": "my-other-stream",
      "backing_indices_in_total": 2,
      "backing_indices_in_error": 1
    }
  ]
}

降采样索引 API

edit

聚合一个时间序列（TSDS）索引并存储预先计算的统计摘要（最小值、最大值、总和、值计数 和 平均值），这些摘要按配置的时间间隔对每个指标字段进行分组。例如，一个包含每10秒采样一次指标的TSDS索引可以被降采样到一个每小时索引。在一个小时间隔内的所有文档被汇总并存储为降采样索引中的单个文档。

POST /my-time-series-index/_downsample/my-downsampled-time-series-index
{
    "fixed_interval": "1d"
}

请求

edit

POST //_downsample/

先决条件

edit

仅支持在时间序列数据流中的索引。
如果启用了Elasticsearch安全功能，您必须拥有all或manage 索引权限。
源索引上不能定义字段或文档级安全。
源索引必须是只读的（index.blocks.write: true）。

路径参数

edit

<source-index>

(可选，字符串) 要降采样的时间序列索引的名称。

<output-downsampled_index>

（必需，字符串）要创建的索引名称。

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

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

查询参数

edit

fixed_interval: (必需的, 时间单位) 用于聚合原始时间序列索引的时间间隔。例如，60m 会为每60分钟（每小时）生成一个文档。这遵循了Elasticsearch中其他地方使用的时间格式化语法。

更小、更细粒度的区间占用比例更多的空间。

下采样过程

edit

下采样操作遍历源TSDS索引并执行以下步骤：

为每个_tsid字段的值和每个@timestamp值（四舍五入到降采样配置中定义的fixed_interval）创建一个新文档。
对于每个新文档，将源索引中的所有时间序列维度复制到目标索引。TSDS中的维度是常量，因此每个桶只需执行一次。
对于每个时间序列指标字段，计算桶中所有文档的聚合。根据每个指标字段的指标类型，存储一组不同的预聚合结果：
- gauge: 存储min、max、sum和value_count；value_count存储为类型aggregate_metric_double。
- counter: 存储last_value。
对于所有其他字段，将最新值复制到目标索引。

源索引和目标索引字段映射

edit

目标下采样索引中的字段是根据原始源索引中的字段创建的，如下所示：

所有使用time-series-dimension参数映射的字段在目标降采样索引中以与源索引相同的映射创建。
所有使用time_series_metric参数映射的字段在目标降采样索引中以与源索引相同的映射创建。一个例外是，对于映射为time_series_metric: gauge的字段，字段类型更改为aggregate_metric_double。
所有既不是维度也不是度量（即标签字段）的其他字段，在目标降采样索引中以它们在源索引中具有的相同映射创建。

查看降采样文档，了解手动运行降采样和作为ILM策略一部分运行的概述和示例。

« Connector APIs Document APIs »