› › ›

API создания задач агрегирования

Создаёт задачу агрегирования.

Данная функция находится в техническом предварительном просмотре и может быть изменена или удалена в будущих версиях. Elastic будет работать над устранением любых проблем, но функции в техническом предварительном просмотре не подпадают под SLA поддержки официальных функций в общем доступе.

Запрос

PUT _rollup/job/<job_id>

Предварительные условия

Если в Elasticsearch включены функции безопасности, вам необходимо иметь manage или manage_rollup привилегии кластера для использования этого API. Дополнительную информацию см. в разделе Привилегии безопасности.

Описание

Конфигурация задачи агрегирования содержит все детали о том, как должна выполняться задача, когда она индексирует документы и какие будущие запросы смогут выполняться на индексе агрегирования.

Конфигурация задачи состоит из трёх основных разделов: логистические детали задачи (расписание cron и т.д.), поля, используемые для группировки, и метрики, которые нужно собирать для каждой группы.

Задачи создаются в состоянии STOPPED. Вы можете запустить их с помощью API запуска задач агрегирования.

Параметры пути

<job_id>: (Обязательно, строка) Идентификатор задачи агрегирования. Это может быть любая буквенно-цифровая строка, уникально определяющая данные, связанные с задачей агрегирования. ID сохраняется; он хранится вместе с агрегированными данными. Если вы создадите задачу, дадите ей поработать некоторое время, а затем удалите задачу, данные, которые агрегировала задача, всё ещё будут связаны с этим идентификатором задачи. Вы не можете создать новую задачу с тем же идентификатором, так как это может привести к проблемам с несовместимыми конфигурациями задач.

Тело запроса

cron: (Обязательно, строка) Строка cron, определяющая интервалы, когда задача сворачивания должна выполняться. При срабатывании интервала индексатор пытается выполнить сворачивание данных в шаблоне индекса. Шаблон cron не связан со временным интервалом сворачиваемых данных. Например, вы можете создать ежечасные сворачивания ваших документов, но запустить индексатор только ежедневно в полночь, как определено в cron. Шаблон cron определяется так же, как и расписание cron в Watcher.

groups

(Обязательно, объект) Определяет поля группировки и агрегации, определённые для этой задачи сворачивания. Эти поля затем будут доступны для агрегирования в корзины.

Эти агрегации и поля могут использоваться в любой комбинации. Представьте себе конфигурацию groups как определение набора инструментов, которые позже могут быть использованы в агрегациях для разделения данных. В отличие от исходных данных, мы должны заранее определить, какие поля и агрегации могут быть использованы. Сворачивание предоставляет достаточную гибкость, поэтому вам просто нужно определить, какие поля необходимы, а не в каком порядке они необходимы.

В настоящее время доступны три типа группировки: date_histogram, histogram и terms.

Свойства groups

date_histogram

(Обязательно, объект) Группа агрегации по дате (date histogram) агрегирует поле date в временные корзины. Эта группа обязательна; в настоящее время вы не можете выполнить сворачивание документов без отметки времени и группы date_histogram. У группы date_histogram есть несколько параметров:

Свойства date_histogram

calendar_interval или fixed_interval

(Обязательно, единицы времени) Интервал временных корзин, которые будут созданы при сворачивании. Например, 60m создаёт 60-минутные (почасовые) сворачивания. Это соответствует стандартному синтаксису форматирования времени, используемому в Elasticsearch. Интервал определяет минимальный интервал, который может быть агрегирован только. Если настроены почасовые (60m) интервалы, поиск сворачивания может выполнять агрегации с интервалами 60м или более (еженедельно, ежемесячно и т. д.). Поэтому определите интервал как наименьший возможный, который вы хотите использовать позже для запросов. Дополнительную информацию о различии между календарными и фиксированными временными интервалами см. в Календарные и фиксированные интервалы.

Меньшие, более подробные интервалы занимают пропорционально больше места.

delay

(Необязательно, единицы времени) Сколько времени ждать, прежде чем сворачивать новые документы. По умолчанию индексатор пытается сворачивать все доступные данные. Однако нередко данные поступают не в порядке, иногда с опозданием на несколько дней. Индексатор не может обрабатывать данные, поступающие после того, как временной интервал был свёрнут. То есть нет возможности обновлять уже существующие сворачивания.

Вместо этого вы должны указать delay, соответствующий самому большому ожидаемому интервалу времени задержки данных. Например, delay значение 1d указывает индексатору на сворачивание документов до now - 1d, что даёт суточный буфер времени для поступления документов с задержкой.

field

(Обязательно, строка) Поле даты, которое должно быть свёрнуто.

time_zone

(Необязательно, строка) Определяет часовой пояс, в котором хранятся свёрнутые документы. В отличие от исходных данных, которые могут динамически менять часовой пояс, свёрнутые документы должны храниться в определённом часовом поясе. По умолчанию свёрнутые документы хранятся в UTC.

histogram

(Необязательно, объект) Группа гистограмм (histogram) агрегирует одно или несколько числовых полей в числовые интервалы гистограммы.

Свойства histogram

fields: (Обязательно, массив) Набор полей, для которых вы хотите создать гистограммы. Все указанные поля должны быть числовыми. Порядок не имеет значения.
interval: (Обязательно, целое число) Интервал корзин гистограммы, которые будут созданы при сворачивании. Например, значение 5 создаёт корзины шириной в пять единиц (0-5, 5-10 и т. д.). Обратите внимание, что в группе histogram может быть указан только один интервал, что означает, что все поля, сгруппированные с помощью гистограммы, должны иметь одинаковый интервал.

terms

(Необязательно, объект) Группа терминов (terms) может быть использована с keyword или числовыми полями, чтобы разрешить группировку с помощью агрегации terms в более позднее время. Индексатор перечисляет и сохраняет все значения поля для каждого временного периода. Это может быть дорогостоящим для полей с высокой кардинальностью, таких как IP-адреса, особенно если временная корзина имеет малый интервал.

Хотя маловероятно, что сворачивание когда-либо будет больше по размеру, чем исходные данные, определение групп terms на нескольких полях с высокой кардинальностью может эффективно уменьшить сжатие сворачивания в большой степени. Следует разумно выбирать, какие поля с высокой кардинальностью включать.

Свойства terms

fields: (Обязательно, строка) Набор полей, для которых необходимо собрать термины. Этот массив может содержать поля, которые являются как keyword, так и числовыми. Порядок не имеет значения.

index_pattern: (Обязательно, строка) Индекс или шаблон индекса для сворачивания. Поддерживает шаблоны с подстановкой (logstash-*). Задача пытается свёрнуть весь индекс или шаблон индекса.

Индекс index_pattern не может быть шаблоном, который также соответствовал бы целевому индексу rollup_index. Например, шаблон foo-* соответствовал бы индексу сворачивания foo-rollup. Такая ситуация привела бы к проблемам, поскольку задача сворачивания пыталась бы сворачивать свои собственные данные во время выполнения. Если вы попытаетесь настроить шаблон, который соответствует индексу rollup_index, произойдёт исключение для предотвращения этого поведения.

metrics

(Необязательно, объект) Определяет метрики, которые нужно собирать для каждой пары группировки. По умолчанию собираются только doc_counts для каждой группы. Чтобы сворачивание было полезным, вы часто будете добавлять метрики, такие как средние значения, минимумы, максимумы и т. д. Метрики определяются на основе каждого поля, и для каждого поля вы настраиваете, какие метрики нужно собирать.

Конфигурация metrics принимает массив объектов, где каждый объект имеет два параметра.

Свойства метрических объектов

field: (Обязательно, строка) Поле для сбора метрик. Это должно быть числовое поле.
metrics: (Обязательно, массив) Массив метрик для сбора по полю. Должна быть настроена хотя бы одна метрика. Допустимые метрики — min, max, sum, avg и value_count.

page_size

(Обязательно, целое число) Количество результатов корзин, обрабатываемых на каждой итерации индексатора сворачивания. Большее значение, как правило, выполняется быстрее, но требует больше памяти во время обработки. Это значение никак не влияет на то, как сворачиваются данные; оно используется только для настройки скорости или стоимости памяти индексатора.

rollup_index

(Обязательно, строка) Индекс, содержащий результаты сворачивания. Индекс может быть использован другими задачами сворачивания. Данные хранятся так, чтобы они не мешали не связанным задачам.

timeout

(Необязательно, временная величина) Время ожидания завершения запроса. По умолчанию 20s (20 секунд).

Пример

В следующем примере создается задание сводки, названное 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` и агрегации `terms` для поля `node`.
	Эта конфигурация определяет метрики по двум полям: `temperature` и `voltage`. Для поля `temperature` мы собираем минимальное, максимальное значение и сумму температуры. Для `voltage` мы собираем среднее значение.

При создании задания вы получите следующие результаты:

{
  "acknowledged": true
}

© 2023-2025 Elasticsearch
As of September 2024, Elasticsearch is available under a choice of three licenses: the Server Side Public License (SSPL), the Elastic License, or the AGPLv3 (OSI approved).
Elasticsearch and the Elasticsearch logo are trademarks of Elasticsearch B.V., registered in the U.S. and in other countries.
https://www.elastic.co/guide/en/elasticsearch/reference/7.17/rollup-put-job.html