› › ›

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

Устарело в 8.11.0.

Функциональность агрегаций будет удалена в будущей версии. Используйте downsampling вместо этого.

Начиная с 8.15.0, вызов этого API в кластере без использования агрегаций завершится ошибкой с сообщением о устаревании и запланированном удалении агрегаций. Для выполнения этого API в кластере должна быть либо задача агрегации, либо индекс агрегации.

Создает задачу агрегации.

Запрос

PUT _rollup/job/<job_id>

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

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

Описание

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

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

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

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

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

Тело запроса

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

groups

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

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

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

Свойства groups

date_histogram

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

Свойства date_histogram

calendar_interval или fixed_interval

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

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

delay

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

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

field

(Обязательный параметр, строка) Дата-поле, которое будет проходить rollup.

time_zone

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

histogram

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

Свойства histogram

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

terms

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

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

Свойства terms

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

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

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

metrics

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

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

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

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

page_size

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

rollup_index

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

timeout

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

Пример

В следующем примере создается задание сводки (rollup) с именем sensor, нацеленное на шаблон индекса sensor-*:

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

	Эта конфигурация позволяет использовать гистограммы дат для поля `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/8.17/rollup-put-job.html