« 获取汇总索引能力 API 启动汇总任务 API »
Elastic 文档 ›Elasticsearch 指南 [8.17] ›REST APIs ›汇总 APIs

汇总搜索

编辑

汇总搜索

编辑

在 8.11.0 版本中已弃用。

汇总功能将在未来版本中移除。请改用降采样。

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

请求

编辑

GET <目标>/_rollup_search

描述

编辑

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

路径参数

编辑
<目标>

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

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

<目标>参数的规则

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

请求体

编辑

请求体支持常规搜索 API 的部分功能。它支持：

不可用的功能

  • size：由于汇总处理的是预聚合数据，因此无法返回搜索命中，所以 size 必须设置为零或完全省略。
  • highlighter、suggestors、post_filter、profile、explain：这些同样是被禁止的。

示例

编辑

仅限历史记录的搜索示例

编辑

假设我们有一个名为 sensor-1 的索引，其中包含原始数据，并且我们创建了一个具有以下配置的汇总任务

resp = client.rollup.put_job(
    id="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"
            ]
        }
    ],
)
print(resp)
const response = await client.rollup.putJob({
  id: "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"],
    },
  ],
});
console.log(response);
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 来搜索汇总数据

resp = client.rollup.rollup_search(
    index="sensor_rollup",
    size=0,
    aggregations={
        "max_temperature": {
            "max": {
                "field": "temperature"
            }
        }
    },
)
print(resp)
response = client.rollup.rollup_search(
  index: 'sensor_rollup',
  body: {
    size: 0,
    aggregations: {
      max_temperature: {
        max: {
          field: 'temperature'
        }
      }
    }
  }
)
puts response
const response = await client.rollup.rollupSearch({
  index: "sensor_rollup",
  size: 0,
  aggregations: {
    max_temperature: {
      max: {
        field: "temperature",
      },
    },
  },
});
console.log(response);
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 字段的配置指标之一。如果我们尝试执行该搜索

resp = client.rollup.rollup_search(
    index="sensor_rollup",
    size=0,
    aggregations={
        "avg_temperature": {
            "avg": {
                "field": "temperature"
            }
        }
    },
)
print(resp)
response = client.rollup.rollup_search(
  index: 'sensor_rollup',
  body: {
    size: 0,
    aggregations: {
      avg_temperature: {
        avg: {
          field: 'temperature'
        }
      }
    }
  }
)
puts response
const response = await client.rollup.rollupSearch({
  index: "sensor_rollup",
  size: 0,
  aggregations: {
    avg_temperature: {
      avg: {
        field: "temperature",
      },
    },
  },
});
console.log(response);
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
}

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

编辑

汇总搜索 API 具有跨“实时”非汇总数据和聚合汇总数据进行搜索的能力。这可以通过简单地将实时索引添加到 URI 来完成

resp = client.rollup.rollup_search(
    index="sensor-1,sensor_rollup",
    size=0,
    aggregations={
        "max_temperature": {
            "max": {
                "field": "temperature"
            }
        }
    },
)
print(resp)
response = client.rollup.rollup_search(
  index: 'sensor-1,sensor_rollup',
  body: {
    size: 0,
    aggregations: {
      max_temperature: {
        max: {
          field: 'temperature'
        }
      }
    }
  }
)
puts response
const response = await client.rollup.rollupSearch({
  index: "sensor-1,sensor_rollup",
  size: 0,
  aggregations: {
    max_temperature: {
      max: {
        field: "temperature",
      },
    },
  },
});
console.log(response);
GET sensor-1,sensor_rollup/_rollup_search 
{
  "size": 0,
  "aggregations": {
    "max_temperature": {
      "max": {
        "field": "temperature"
      }
    }
  }
}

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

执行搜索时，汇总搜索端点会执行两项操作

  1. 原始请求会被发送到非汇总索引，不做任何更改。
  2. 原始请求的重写版本会被发送到汇总索引。

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

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

{
  "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 启动汇总任务 API »