<job_id>: (必需，字符串) 汇总任务的标识符。这可以是任何字母数字字符串，并唯一标识与汇总任务关联的数据。该ID是持久的；它与汇总数据一起存储。如果您创建了一个任务，让它运行一段时间，然后删除该任务，该任务汇总的数据显示仍将与该任务ID关联。您不能创建具有相同ID的新任务，因为这可能会导致任务配置不匹配的问题。

请求体

edit

cron: (必需，字符串) 一个定义滚动任务执行间隔的 cron 字符串。当间隔触发时，索引器尝试对索引模式中的数据进行滚动。cron 模式与正在滚动的数据的时间间隔无关。例如，您可能希望每小时创建一次文档的滚动，但只希望在每天午夜按 cron 定义的每日基础上运行索引器。cron 模式定义与 Watcher cron 计划相同。

groups

(必需，对象) 定义了为此汇总作业定义的分组字段和聚合。这些字段将在之后用于聚合到桶中。

这些聚合和字段可以以任何组合方式使用。将groups配置视为定义了一组工具，这些工具可以在后续的聚合中用于划分数据。与原始数据不同，我们必须提前考虑哪些字段和聚合可能会被使用。汇总提供了足够的灵活性，您只需要确定哪些字段是必需的，而不需要考虑它们的顺序。

目前有三种类型的分组可用：date_histogram、histogram 和 terms。

Properties of groups

date_histogram

(必需, 对象) 日期直方图组将一个 日期 字段聚合到基于时间的桶中。此组是 强制性的; 您目前无法在没有时间戳和 date_histogram 组的情况下汇总文档。date_histogram 组有几个参数:

Properties of date_histogram

calendar_interval or fixed_interval

(必需的, 时间单位) 生成滚动时的时间桶间隔。例如，60m 生成60分钟（每小时）的滚动。这遵循Elasticsearch中其他地方使用的时间格式化语法。间隔定义了最小间隔，只能聚合此间隔。如果配置了每小时（60m）间隔，滚动搜索可以执行60分钟或更长时间（每周、每月等）间隔的聚合。因此，将间隔定义为您希望稍后查询的最小单位。有关日历和固定时间间隔之间差异的更多信息，请参阅日历和固定间隔。

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

delay

(可选,时间单位) 在滚动新文档之前等待多长时间。默认情况下，索引器会尝试滚动所有可用数据。然而，数据无序到达，有时甚至会延迟几天，这种情况并不少见。索引器无法处理在时间跨度已经滚动之后到达的数据。也就是说，没有提供更新已经存在的汇总的功能。

相反，您应该指定一个与您预期乱序数据到达的最长时间段相匹配的delay。例如，delay为1d会指示索引器将文档汇总到now - 1d，这为乱序文档的到达提供了1天的缓冲时间。

field

(必需, 字符串) 要汇总的日期字段。

time_zone

(可选, 字符串) 定义汇总文档存储的时区。与原始数据不同，原始数据可以动态更改时区，汇总文档必须存储在特定的时区。默认情况下，汇总文档存储在UTC。

histogram

（可选，对象）直方图组将一个或多个数值字段聚合到数值直方图区间中。

Properties of histogram

fields: (必需, 数组) 您希望为其构建直方图的字段集。所有指定的字段必须是某种数字类型。顺序无关紧要。
interval: (必需, 整数) 滚动时生成的直方图桶的间隔。例如，值为5会创建宽度为五个单位的桶（0-5，5-10等）。请注意，在histogram组中只能指定一个间隔，这意味着通过直方图分组的所有字段必须共享相同的间隔。

terms

(可选, 对象) terms组可以在keyword或数字字段上使用，以便在稍后通过terms聚合进行分组。索引器枚举并存储每个时间段字段的所有值。对于高基数的组（如IP地址），这可能会非常昂贵，特别是在时间桶特别稀疏的情况下。

虽然汇总数据的大小不太可能超过原始数据，但在多个高基数字段上定义terms分组可以有效地将汇总的压缩率大幅降低。因此，您应该谨慎选择包含哪些高基数字段。

Properties of terms

fields: (必需, 字符串) 您希望为其收集术语的字段集。此数组可以包含keyword和数字字段。顺序无关紧要。

index_pattern

(必需，字符串) 要汇总的目标索引或索引模式。支持通配符风格的模式 (logstash-*)。该作业尝试汇总整个索引或索引模式。

The index_pattern 不能是也会匹配目标 rollup_index 的模式。例如，模式 foo-* 会匹配汇总索引 foo-rollup。这种情况会导致问题，因为汇总作业会在运行时尝试汇总其自身的数据。如果您尝试配置一个匹配 rollup_index 的模式，将会发生异常以防止这种行为。

metrics

(可选, 对象) 定义每个分组元组的收集指标。默认情况下，仅收集每个组的文档计数。为了使汇总功能有用，您通常会添加平均值、最小值、最大值等指标。指标是按字段定义的，对于每个字段，您可以配置应收集的指标。

配置metrics接受一个对象数组，其中每个对象有两个参数。

metric对象的属性

field: (必需, 字符串) 要收集指标的字段。这必须是一个某种类型的数值。
metrics: (必需, 数组) 为该字段收集的指标数组。至少必须配置一个指标。可接受的指标有min,max,sum,avg, 和value_count。

page_size

(必需，整数) 每次滚动索引器迭代时处理的存储桶结果的数量。较大的值通常执行速度更快，但在处理过程中需要更多的内存。此值对数据的汇总方式没有影响；它仅用于调整索引器的速度或内存成本。

rollup_index

(必需，字符串) 包含汇总结果的索引。该索引可以与其他汇总作业共享。数据存储时不会干扰不相关的作业。

timeout

(可选，时间值) 等待请求完成的时间。默认为20s（20秒）。

示例

edit

以下示例创建一个名为 sensor 的汇总作业，目标为 sensor-* 索引模式：

PUT _rollup/job/sensor
{
  "index_pattern": "sensor-*",
  "rollup_index": "sensor_rollup",
  "cron": "*/30 * * * * ?",
  "page_size": 1000,
  "groups": { 
    "date_histogram": {
      "field": "timestamp",
      "fixed_interval": "1h",
      "delay": "7d"
    },
    "terms": {
      "fields": [ "node" ]
    }
  },
  "metrics": [ 
      {
      "field": "temperature",
      "metrics": [ "min", "max", "sum" ]
    },
    {
      "field": "voltage",
      "metrics": [ "avg" ]
    }
  ]
}

	此配置允许在 `timestamp` 字段上使用日期直方图，并在 `node` 字段上使用 `terms` 聚合。
	此配置定义了两个字段的指标：`temperature` 和 `voltage`。对于 `temperature` 字段，我们正在收集温度的最小值、最大值和总和。对于 `voltage`，我们正在收集平均值。

当作业创建时，您会收到以下结果：

{
  "acknowledged": true
}

删除汇总作业 API

edit

在8.11.0中已弃用。

Rollups 将在未来的版本中被移除。请改用降采样。

删除现有的汇总作业。

请求

edit

DELETE _rollup/job/

先决条件

edit

如果启用了Elasticsearch安全功能，您必须拥有manage或manage_rollup集群权限才能使用此API。更多信息，请参阅安全权限。

描述

edit

在删除作业之前，必须先将其停止。如果您尝试删除一个已启动的作业，将会发生错误。同样，如果您尝试删除一个不存在的作业，将会发生异常。

当一个任务被删除时，这只会移除正在主动监控和汇总数据的进程。它不会删除任何之前汇总的数据。这是设计使然；用户可能希望汇总一个静态数据集。由于数据集是静态的，一旦它被完全汇总，就没有必要保留索引汇总任务（因为没有新数据）。因此，可以删除该任务，留下汇总的数据以供分析。

如果你希望同时删除汇总数据，并且汇总索引仅包含单个作业的数据，你可以简单地删除整个汇总索引。如果汇总索引存储了来自多个作业的数据，你必须发出一个针对汇总作业ID的按查询删除操作。

POST my_rollup_index/_delete_by_query
{
  "query": {
    "term": {
      "_rollup.id": "the_rollup_job_id"
    }
  }
}

路径参数

edit

<job_id>: （必需，字符串）作业的标识符。

响应代码

edit

404 (Missing resources): 此代码表示没有与请求匹配的资源。如果您尝试删除不存在的作业，则会发生这种情况。

示例

edit

如果我们有一个名为 sensor 的汇总作业，可以使用以下命令删除它：

DELETE _rollup/job/sensor

这将返回响应：

{
  "acknowledged": true
}

获取汇总作业 API

edit

在8.11.0中已弃用。

Rollups 将在未来的版本中被移除。请改用降采样。

检索汇总作业的配置、统计信息和状态。

请求

edit

GET _rollup/job/

先决条件

edit

如果启用了Elasticsearch安全功能，您必须拥有monitor、 monitor_rollup、manage或manage_rollup集群权限才能使用此API。有关更多信息，请参阅安全权限。

描述

edit

API 可以返回单个汇总作业或所有汇总作业的详细信息。

此API仅返回活动（包括STARTED和STOPPED）的任务。如果一个任务被创建、运行了一段时间然后被删除，此API不会返回该任务的任何详细信息。

有关历史汇总作业的详细信息，汇总功能 API可能更有用。

路径参数

edit

<job_id>: (可选，字符串) 滚动任务的标识符。如果它是 _all 或省略， API 返回所有滚动任务。

响应体

edit

jobs

(数组) 一个汇总作业资源的数组。

汇总作业资源的属性

config

(对象) 包含汇总作业的配置。此信息与通过创建作业 API创建作业时提供的配置相同。

stats

(对象) 包含有关汇总作业的瞬时统计信息，例如已处理的文档数量和已索引的汇总摘要文档数量。这些统计信息不会持久化。如果节点重新启动，这些统计信息将被重置。

status

(对象) 包含当前汇总作业索引器的状态。可能的值及其含义如下：

stopped 表示索引器已暂停，即使其 cron 间隔触发也不会处理数据。
started 表示索引器正在运行，但未主动索引数据。当 cron 间隔触发时，作业的索引器将开始处理数据。
indexing 表示索引器正在主动处理数据并创建新的汇总文档。在此状态下，任何后续的 cron 间隔触发都将被忽略，因为作业已经在前一次触发时处于活动状态。
abort 是一个瞬态状态，通常不会被用户看到。如果任务由于某种原因需要关闭（作业已被删除，遇到无法恢复的错误等），则会使用此状态。在设置 abort 状态后不久，作业将从集群中移除。

示例

edit

如果我们已经创建了一个名为 sensor 的汇总作业，可以使用以下命令检索该作业的详细信息：

GET _rollup/job/sensor

API 返回以下响应：

{
  "jobs": [
    {
      "config": {
        "id": "sensor",
        "index_pattern": "sensor-*",
        "rollup_index": "sensor_rollup",
        "cron": "*/30 * * * * ?",
        "groups": {
          "date_histogram": {
            "fixed_interval": "1h",
            "delay": "7d",
            "field": "timestamp",
            "time_zone": "UTC"
          },
          "terms": {
            "fields": [
              "node"
            ]
          }
        },
        "metrics": [
          {
            "field": "temperature",
            "metrics": [
              "min",
              "max",
              "sum"
            ]
          },
          {
            "field": "voltage",
            "metrics": [
              "avg"
            ]
          }
        ],
        "timeout": "20s",
        "page_size": 1000
      },
      "status": {
        "job_state": "stopped"
      },
      "stats": {
        "pages_processed": 0,
        "documents_processed": 0,
        "rollups_indexed": 0,
        "trigger_count": 0,
        "index_failures": 0,
        "index_time_in_ms": 0,
        "index_total": 0,
        "search_failures": 0,
        "search_time_in_ms": 0,
        "search_total": 0,
        "processing_time_in_ms": 0,
        "processing_total": 0
      }
    }
  ]
}

数组包含一个作业（id: sensor），因为我们请求了端点 URL 中的单个作业。如果我们添加另一个作业，我们可以看到如何处理多作业响应：

PUT _rollup/job/sensor2 
{
  "index_pattern": "sensor-*",
  "rollup_index": "sensor_rollup",
  "cron": "*/30 * * * * ?",
  "page_size": 1000,
  "groups": {
    "date_histogram": {
      "field": "timestamp",
      "fixed_interval": "1h",
      "delay": "7d"
    },
    "terms": {
      "fields": [ "node" ]
    }
  },
  "metrics": [
    {
      "field": "temperature",
      "metrics": [ "min", "max", "sum" ]
    },
    {
      "field": "voltage",
      "metrics": [ "avg" ]
    }
  ]
}

GET _rollup/job/_all

	我们创建一个名为 `sensor2` 的第二个作业
	然后使用 GetJobs API 中的 `_all` 请求所有作业

这将产生以下响应：

{
  "jobs": [
    {
      "config": {
        "id": "sensor2",
        "index_pattern": "sensor-*",
        "rollup_index": "sensor_rollup",
        "cron": "*/30 * * * * ?",
        "groups": {
          "date_histogram": {
            "fixed_interval": "1h",
            "delay": "7d",
            "field": "timestamp",
            "time_zone": "UTC"
          },
          "terms": {
            "fields": [
              "node"
            ]
          }
        },
        "metrics": [
          {
            "field": "temperature",
            "metrics": [
              "min",
              "max",
              "sum"
            ]
          },
          {
            "field": "voltage",
            "metrics": [
              "avg"
            ]
          }
        ],
        "timeout": "20s",
        "page_size": 1000
      },
      "status": {
        "job_state": "stopped"
      },
      "stats": {
        "pages_processed": 0,
        "documents_processed": 0,
        "rollups_indexed": 0,
        "trigger_count": 0,
        "index_failures": 0,
        "index_time_in_ms": 0,
        "index_total": 0,
        "search_failures": 0,
        "search_time_in_ms": 0,
        "search_total": 0,
        "processing_time_in_ms": 0,
        "processing_total": 0
      }
    },
    {
      "config": {
        "id": "sensor",
        "index_pattern": "sensor-*",
        "rollup_index": "sensor_rollup",
        "cron": "*/30 * * * * ?",
        "groups": {
          "date_histogram": {
            "fixed_interval": "1h",
            "delay": "7d",
            "field": "timestamp",
            "time_zone": "UTC"
          },
          "terms": {
            "fields": [
              "node"
            ]
          }
        },
        "metrics": [
          {
            "field": "temperature",
            "metrics": [
              "min",
              "max",
              "sum"
            ]
          },
          {
            "field": "voltage",
            "metrics": [
              "avg"
            ]
          }
        ],
        "timeout": "20s",
        "page_size": 1000
      },
      "status": {
        "job_state": "stopped"
      },
      "stats": {
        "pages_processed": 0,
        "documents_processed": 0,
        "rollups_indexed": 0,
        "trigger_count": 0,
        "index_failures": 0,
        "index_time_in_ms": 0,
        "index_total": 0,
        "search_failures": 0,
        "search_time_in_ms": 0,
        "search_total": 0,
        "processing_time_in_ms": 0,
        "processing_total": 0
      }
    }
  ]
}

获取汇总作业能力 API

edit

在8.11.0中已弃用。

Rollups 将在未来的版本中被移除。请改用降采样。

返回为特定索引或索引模式配置的任何汇总作业的功能。

请求

edit

GET _rollup/data/

先决条件

edit

如果启用了Elasticsearch安全功能，您必须拥有monitor、 monitor_rollup、manage或manage_rollup集群权限才能使用此API。有关更多信息，请参阅安全权限。

描述

edit

这个API很有用，因为汇总作业通常配置为仅从源索引中汇总一部分字段。此外，只有某些聚合可以为各个字段配置，从而根据该配置导致功能受限的子集。

此API使您能够检查索引并确定：

这个索引在集群中的某个地方是否有相关的汇总数据？
如果第一个问题的答案是肯定的，那么汇总了哪些字段，可以执行哪些聚合操作，数据存放在哪里？

路径参数

edit

<index>: (字符串) 要返回汇总功能的索引、索引或索引模式。 _all 可用于从所有作业中获取汇总功能。

示例

edit

假设我们有一个名为 sensor-1 的索引，里面充满了原始数据。我们知道数据会随着时间的推移而增长，因此会有 sensor-2、sensor-3 等。让我们创建一个针对索引模式 sensor-* 的汇总任务，以适应未来的扩展：

PUT _rollup/job/sensor
{
  "index_pattern": "sensor-*",
  "rollup_index": "sensor_rollup",
  "cron": "*/30 * * * * ?",
  "page_size": 1000,
  "groups": {
    "date_histogram": {
      "field": "timestamp",
      "fixed_interval": "1h",
      "delay": "7d"
    },
    "terms": {
      "fields": [ "node" ]
    }
  },
  "metrics": [
    {
      "field": "temperature",
      "metrics": [ "min", "max", "sum" ]
    },
    {
      "field": "voltage",
      "metrics": [ "avg" ]
    }
  ]
}

然后，我们可以通过以下命令检索该索引模式（sensor-*）的汇总功能：

GET _rollup/data/sensor-*

这将产生以下响应：

{
  "sensor-*" : {
    "rollup_jobs" : [
      {
        "job_id" : "sensor",
        "rollup_index" : "sensor_rollup",
        "index_pattern" : "sensor-*",
        "fields" : {
          "node" : [
            {
              "agg" : "terms"
            }
          ],
          "temperature" : [
            {
              "agg" : "min"
            },
            {
              "agg" : "max"
            },
            {
              "agg" : "sum"
            }
          ],
          "timestamp" : [
            {
              "agg" : "date_histogram",
              "time_zone" : "UTC",
              "fixed_interval" : "1h",
              "delay": "7d"
            }
          ],
          "voltage" : [
            {
              "agg" : "avg"
            }
          ]
        }
      }
    ]
  }
}

返回的响应包含与原始汇总配置相似的信息，但格式不同。首先，有一些内部管理细节：汇总作业ID、存储汇总数据的索引以及作业所针对的索引模式。

接下来，它显示了一个包含可用于汇总搜索的数据的字段列表。这里我们看到四个字段：node、temperature、timestamp 和 voltage。每个字段都列出了可能的聚合方式。例如，你可以在 temperature 字段上使用最小值、最大值或总和聚合，但在 timestamp 字段上只能使用 date_histogram。

请注意，rollup_jobs 元素是一个数组；可以为单个索引或索引模式配置多个独立的作业。每个作业可能具有不同的配置，因此 API 返回所有可用配置的列表。

我们也可以通过请求_all来获取相同的信息：

GET _rollup/data/_all

但请注意，如果我们使用具体的索引名称（sensor-1），我们将无法检索到汇总功能：

GET _rollup/data/sensor-1

{

}

为什么会这样？原始的汇总作业是针对特定的索引模式（sensor-*）而不是具体的索引（sensor-1）配置的。因此，虽然该索引属于该模式，但汇总作业仅在整个模式范围内有效，而不仅仅是在其包含的某个索引上有效。因此，出于这个原因，获取汇总功能 API 仅返回基于最初配置的索引名称或模式的信息。

获取汇总索引能力 API

edit

在8.11.0中已弃用。

Rollups 将在未来的版本中被移除。请改用降采样。

返回汇总索引中所有作业的汇总功能（例如，存储汇总数据的索引）。

请求

edit

GET /_rollup/data

先决条件

edit

如果启用了Elasticsearch的安全功能，您必须拥有存储汇总结果的索引上的任何读取、 查看索引元数据或管理 索引权限。有关更多信息，请参阅安全权限。

描述

edit

单个汇总索引可能存储多个汇总作业的数据，并且可能根据这些作业具有多种功能。

此API将允许您确定：

索引（或通过模式指定的索引）中存储了哪些作业？
哪些目标索引被汇总了，在这些汇总中使用了哪些字段，以及可以在每个作业上执行哪些聚合？

路径参数

edit

<target>: (必需，字符串) 要检查是否具备滚动功能的数据流或索引。通配符 (*) 表达式是支持的。

示例

edit

假设我们有一个名为 sensor-1 的索引，里面充满了原始数据。我们知道数据会随着时间的推移而增长，因此会有 sensor-2、sensor-3 等。让我们创建一个汇总作业，将其数据存储在 sensor_rollup 中：

PUT _rollup/job/sensor
{
  "index_pattern": "sensor-*",
  "rollup_index": "sensor_rollup",
  "cron": "*/30 * * * * ?",
  "page_size": 1000,
  "groups": {
    "date_histogram": {
      "field": "timestamp",
      "fixed_interval": "1h",
      "delay": "7d"
    },
    "terms": {
      "fields": [ "node" ]
    }
  },
  "metrics": [
    {
      "field": "temperature",
      "metrics": [ "min", "max", "sum" ]
    },
    {
      "field": "voltage",
      "metrics": [ "avg" ]
    }
  ]
}

如果在以后的日期，我们想确定存储在sensor_rollup索引中的作业和功能，我们可以使用获取汇总索引API：

GET /sensor_rollup/_rollup/data

注意我们是如何在URL的第一部分请求具体的汇总索引名称（sensor_rollup）的。这将产生以下响应：

{
  "sensor_rollup" : {
    "rollup_jobs" : [
      {
        "job_id" : "sensor",
        "rollup_index" : "sensor_rollup",
        "index_pattern" : "sensor-*",
        "fields" : {
          "node" : [
            {
              "agg" : "terms"
            }
          ],
          "temperature" : [
            {
              "agg" : "min"
            },
            {
              "agg" : "max"
            },
            {
              "agg" : "sum"
            }
          ],
          "timestamp" : [
            {
              "agg" : "date_histogram",
              "time_zone" : "UTC",
              "fixed_interval" : "1h",
              "delay": "7d"
            }
          ],
          "voltage" : [
            {
              "agg" : "avg"
            }
          ]
        }
      }
    ]
  }
}

返回的响应包含与原始汇总配置相似的信息，但格式不同。首先，有一些内部管理细节：汇总作业ID、存储汇总数据的索引、作业所针对的索引模式。

与其他与索引交互的API类似，您可以指定索引模式而不是明确的索引：

GET /*_rollup/_rollup/data

汇总搜索

edit

在8.11.0中已弃用。

Rollups 将在未来的版本中被移除。请改用降采样。

启用使用标准查询DSL搜索汇总数据。

请求

edit

GET /_rollup_search

描述

edit

汇总搜索端点是必需的，因为内部汇总文档使用与原始数据不同的文档结构。汇总搜索端点将标准查询DSL重写为与汇总文档匹配的格式，然后获取响应并将其重写回客户端在原始查询下所期望的格式。

路径参数

edit

<target>

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

此目标可以包括汇总和非汇总索引。

关于参数的规则：

至少必须指定一个数据流、索引或通配符表达式。此目标可以包括一个汇总或非汇总索引。对于数据流，流的备份索引只能作为非汇总索引。省略参数或使用_all是不允许的。
可以指定多个非汇总索引。
只能指定一个汇总索引。如果提供了多个，则会发生异常。
可以使用通配符表达式，但如果它们匹配多个汇总索引，则会发生异常。但是，您可以使用表达式来匹配多个非汇总索引或数据流。

请求体

edit

请求体支持常规搜索API功能的一个子集。它支持：

query 参数用于指定DSL查询，受某些限制 (参见 Rollup搜索限制和 Rollup聚合限制
aggregations 参数用于指定聚合

不可用的功能：

size: 因为汇总操作是在预聚合数据上进行的，所以无法返回搜索命中结果，因此必须将size设置为零或完全省略。
highlighter, suggestors, post_filter, profile, explain: 这些同样是被禁止的。

示例

edit

仅历史搜索示例

edit

假设我们有一个名为 sensor-1 的索引，里面充满了原始数据，并且我们创建了一个滚动任务，配置如下：

PUT _rollup/job/sensor
{
  "index_pattern": "sensor-*",
  "rollup_index": "sensor_rollup",
  "cron": "*/30 * * * * ?",
  "page_size": 1000,
  "groups": {
    "date_histogram": {
      "field": "timestamp",
      "fixed_interval": "1h",
      "delay": "7d"
    },
    "terms": {
      "fields": [ "node" ]
    }
  },
  "metrics": [
    {
      "field": "temperature",
      "metrics": [ "min", "max", "sum" ]
    },
    {
      "field": "voltage",
      "metrics": [ "avg" ]
    }
  ]
}

这将汇总 sensor-* 模式并将结果存储在 sensor_rollup 中。要搜索这些汇总数据，我们需要使用 _rollup_search 端点。然而，你会注意到我们可以使用常规的查询DSL来搜索汇总数据：

GET /sensor_rollup/_rollup_search
{
  "size": 0,
  "aggregations": {
    "max_temperature": {
      "max": {
        "field": "temperature"
      }
    }
  }
}

查询的目标是 sensor_rollup 数据，因为这包含了在作业中配置的汇总数据。在 temperature 字段上使用了 max 聚合，得到了以下响应：

{
  "took" : 102,
  "timed_out" : false,
  "terminated_early" : false,
  "_shards" : ... ,
  "hits" : {
    "total" : {
        "value": 0,
        "relation": "eq"
    },
    "max_score" : 0.0,
    "hits" : [ ]
  },
  "aggregations" : {
    "max_temperature" : {
      "value" : 202.0
    }
  }
}

响应与常规查询 + 聚合的结果完全一致；它提供了一些关于请求的元数据（took、_shards 等）、搜索命中（对于汇总搜索来说总是空的）以及聚合响应。

汇总搜索仅限于在汇总作业中配置的功能。例如，我们无法计算平均温度，因为 avg 不是为 temperature 字段配置的指标之一。如果我们尝试执行该搜索：

GET sensor_rollup/_rollup_search
{
  "size": 0,
  "aggregations": {
    "avg_temperature": {
      "avg": {
        "field": "temperature"
      }
    }
  }
}

{
  "error": {
    "root_cause": [
      {
        "type": "illegal_argument_exception",
        "reason": "There is not a rollup job that has a [avg] agg with name [avg_temperature] which also satisfies all requirements of query.",
        "stack_trace": ...
      }
    ],
    "type": "illegal_argument_exception",
    "reason": "There is not a rollup job that has a [avg] agg with name [avg_temperature] which also satisfies all requirements of query.",
    "stack_trace": ...
  },
  "status": 400
}

同时搜索历史汇总和非汇总数据

edit

rollup 搜索 API 具有在“实时”非汇总数据和聚合的汇总数据之间进行搜索的能力。只需将实时索引添加到 URI 中即可实现：

GET sensor-1,sensor_rollup/_rollup_search 
{
  "size": 0,
  "aggregations": {
    "max_temperature": {
      "max": {
        "field": "temperature"
      }
    }
  }
}

注意，URI现在同时搜索sensor-1和sensor_rollup

当搜索执行时，汇总搜索端点会做两件事：

原始请求被原封不动地发送到非汇总索引。
原始请求的重写版本被发送到汇总索引。

当接收到两个响应时，端点会重写汇总响应并将两者合并。在合并过程中，如果两个响应之间存在桶的重叠，则使用非汇总索引的桶。

尽管跨越了汇总和非汇总索引，上述查询的响应看起来如预期：

{
  "took" : 102,
  "timed_out" : false,
  "terminated_early" : false,
  "_shards" : ... ,
  "hits" : {
    "total" : {
        "value": 0,
        "relation": "eq"
    },
    "max_score" : 0.0,
    "hits" : [ ]
  },
  "aggregations" : {
    "max_temperature" : {
      "value" : 202.0
    }
  }
}

启动汇总作业 API

edit

在8.11.0中已弃用。

Rollups 将在未来的版本中被移除。请改用降采样。

启动一个已停止的卷积作业。

请求

edit

POST _rollup/job//_start

先决条件

edit

如果启用了Elasticsearch安全功能，您必须拥有manage或manage_rollup集群权限才能使用此API。更多信息，请参阅安全权限。

描述

edit

如果你尝试启动一个不存在的作业，会发生异常。如果你尝试启动一个已经启动的作业，则不会有任何反应。

路径参数

edit

<job_id>: （必需，字符串）用于汇总作业的标识符。

响应代码

edit

404 (Missing resources): 此代码表示没有与请求匹配的资源。如果您尝试启动一个不存在的作业，就会发生这种情况。

示例

edit

如果我们已经创建了一个名为 sensor 的汇总作业，可以使用以下命令启动它：

POST _rollup/job/sensor/_start

这将返回响应：

{
  "started": true
}

停止汇总作业 API

edit

在8.11.0中已弃用。

Rollups 将在未来的版本中被移除。请改用降采样。

停止一个已启动的汇总作业。

请求

edit

POST _rollup/job//_stop

先决条件

edit

如果启用了Elasticsearch安全功能，您必须拥有manage或manage_rollup集群权限才能使用此API。更多信息，请参阅安全权限。

描述

edit

如果你尝试停止一个不存在的作业，会发生异常。如果你尝试停止一个已经停止的作业，什么也不会发生。

路径参数

edit

<job_id>: （必需，字符串）用于汇总任务的标识符。

查询参数

edit

timeout: (可选，时间值) 如果 wait_for_completion 是 true，API 会阻塞（最多）指定的时间，等待作业停止。如果超过 timeout 时间，API 会抛出一个超时异常。默认为 30s。

即使抛出了超时异常，停止请求仍在处理中，并最终将作业移动到已停止状态。超时仅仅意味着API调用本身在等待状态变化时超时。
wait_for_completion: (可选，布尔值) 如果设置为 true，将导致 API 阻塞，直到索引器状态完全停止。如果设置为 false，API 将立即返回，索引器将在后台异步停止。默认为 false。

响应代码

edit

404 (Missing resources): 此代码表示没有与请求匹配的资源。如果您尝试停止一个不存在的作业，就会发生这种情况。

示例

edit

由于只有已停止的任务才能被删除，因此在索引器完全停止之前阻塞API可能会很有用。这可以通过wait_for_completion查询参数以及可选的timeout来实现：

POST _rollup/job/sensor/_stop?wait_for_completion=true&timeout=10s

该参数阻止 API 调用返回，直到作业已移动到 STOPPED 或指定的时间已过去。如果指定的时间过去而作业未移动到 STOPPED，则会抛出超时异常。

« Repositories metering APIs Root API »