aggs
Описание
Выполняет статистические операции над данными с помощью внутренних механизмов хранилища.
Использование aggs
в запросе допустимо в случае, если перед ней находятся только команды, также работающие с внутренними механизмами хранилища. К ним относятся source
, search
и peval
. Это условие должно выполняться и для всех подзапросов в запросе.
Синтаксис
| aggs [composite=<bool>] <functions-expression> ["," <functions-expression>] [<by_expression>]
Обязательные аргументы
Обязательно использование хотя бы одной из функций:
Параметр | Синтаксис | Описание |
---|---|---|
count | count | count(<field>) | Вычисляет количество событий, содержащих поле. Если поле не указано, рассчитывает общее количество событий. |
values | values(<field>) | Вычисляет массив уникальных значений по заданному полю. |
avg | avg(<field>) | Вычисляет среднее значение по заданному полю. |
dc | dc(<field>) | Вычисляет количество уникальных значений в заданном поле. |
earliest | earliest(<field>) | Вычисляет значение поля для самого раннего события. В качестве второго (опционального) параметра передается имя поля с временной меткой. По умолчанию @timestamp . |
latest | latest(<field>) | Вычисляет значение поля для самого позднего события. В качестве второго (опционального) параметра передается имя поля с временной меткой. По умолчанию @timestamp . |
max | max(<field>) | Вычисляет максимальное значение по заданному полю. |
min | min(<field>) | Вычисляет минимальное значение по заданному полю. |
sum | sum(<field>) | Вычисляет сумму значений по заданному полю. |
perc | perc(<field>, <percent>) | Вычисляет персентиль по заданному полю и проценту. |
median | median(<field>) | Вычисляет медиану по заданному полю. |
Опциональные аргументы
Параметр | Синтаксис | По умолчанию | Описание |
---|---|---|---|
composite | composite=<boolean> | false | Дает возможность использования скроллинга в агрегациях и получить все возможные сегменты (buckets) с помощью нескольких запросов (аналогично scroll в stats ). Может быть применен только при наличии группировки (by полей). Количеством сегментов (buckets), которые будут возвращены в ответе имеет фиксированное значение — 1000. |
<by_expression> | <by_field> ["," <by_field> ...] | Имя поля (или полей) для группировки значений. |
Аргумент composite
доступен при запросе к OpenSearch.
Aggregations в OpenSearch выполняют статистическую обработку по числовым типам полей или же keyword
, если поле текстовое. В соответствии с этим для текстовых полей нужно дописывать <название поля>.keyword
, это необходимо делать как в заданных, так и в by полях. Исключением являются заданные поля в функциях earliest и latest. Пример:
... | aggs avg(user.keyword), earliest(user) by event.keyword, user_count
Примеры запросов
В примерах ниже используются наборы данных для маппинга поля .keyword
. Если индексация настроена по умолчанию, необходимо указывать .keyword
.
Поле text
разбивается на отдельные слова при индексации, что позволяет искать даже частичные совпадения (например, найти "кот" в слове "котенок"). Это удобно для полнотекстового поиска, но требует больше ресурсов.
Поле keyword
не разбивается — оно хранится и ищется целиком. Подходит для точного совпадения (например, поиск "Москва" только как полного значения). Работает быстрее.
Базовые примеры
Пример 1
Расчет количества событий для каждой комбинации кода состояния DNS и названия хоста.
source winlogbeat_dns
| aggs count by event.code, host.keyword
| sort - count
Так как поле host
является текстовым, к нему необходимо обращаться через .keyword
.
При использовании by
полей в запросе возвращается строка для каждого уникального значения by
-поля, содержащая это значение и значение статистических функций. Так как в данном примере используется три by
-поля, каждая уникальная комбинация event.code
, status
и host
будет на отдельной строке. Команда sort
сортирует по умолчанию поле count
.
Результатом выполнения запроса может быть следующая таблица:
count | event.code | status | host.keyword |
---|---|---|---|
1595 | 3 | Info | VLG-DC-01 |
1498 | 5504 | Info | MSK-DC-02 |
356 | 4015 | Error | SPB-DC-03 |
254 | 4013 | Warning | VLG-DC-01 |
123 | 4007 | Error | SPB-DC-03 |
98 | 4013 | Warning | MSK-DC-02 |
79 | 5504 | Info | SPB-DC-03 |
Пример 2
Расчет списка хостов и количества действий для каждого пользователя и его действия на хостах.
source wineventlog
| aggs count, values(host.name.keyword) as hosts by user.name.keyword, event.action.keyword
Для каждой уникальной пары event.action
и user.name
вычисляется количество событий и список уникальных хостов, которые записываются в поля count
и hosts
соответственно.
Результатом выполнения запроса может быть следующая таблица:
user.name.keyword | event.action.keyword | count | hosts |
---|---|---|---|
IvanovMG | credential-validated | 41 | MSK-WS-01 SPB-WS-02 |
IvanovMG | logged-in | 26 | SPB-WS-02 VLG-WS-03 KZN-WS-05 |
IvanovMG | logged-out | 25 | SPB-WS-02 VLG-WS-03 KZN-WS-05 |
PetrovSI | logged-out | 33 | SPB-WS-02 KZN-WS-05 |
PetrovSI | added-member-to-group | 6 | MSK-WS-01 |
AndreevAE | added-member-to-group | 14 | SPB-WS-02 VLG-WS-03 |
Расширенные примеры
Пример 1
Получение списка уникальных значений поля user
:
... | aggs values(user.keyword)
Возвращает массив уникальных значений поля user.keyword
из всех документов, соответствующих запросу.
Пример входных данных:
user | source.address | event |
---|---|---|
IvanovMG | 192.168.1.10 | login |
PetrovSI | 192.168.1.15 | logout |
IvanovMG | 192.168.1.20 | login |
AndreevAE | 10.0.0.1 | password_reset |
SidorovVA | 10.0.0.5 | password_reset |
Результатом выполнения запроса может быть следующая таблица:
values (user.keyword) |
---|
IvanovMG PetrovSI AndreevAE SidorovVA |
Пример 2
Получение списка уникальных значений поля user
для каждого уникального значения поля event
.
В примере поле event
в данных принимает значения start
и end
. После выполнения команды, система вернет пары результатов: start
и список уникальных значений user
(у которых event = "start"
), и end
и список уникальных значений user
(у которых event = "end"
):
... | aggs values(user.keyword) by event.keyword
Результатом выполнения запроса может быть следующая таблица:
event.keyword | values (user.keyword) |
---|---|
start | Ivanov Petrov |
end | Andreev |
Пример 2.2
В примере поле response.status
в данных принимает значения HTTP-состояний. После выполнения команды, система вернет пары: 200
и список уникальных значений source.address.keyword
(у которых response.status = 200
), и 403
и список уникальных значений source.address.keyword
(у которых response.status = 403
), для response.status = 401
аналогичный случай:
... | aggs values(source.address.keyword) by response.status
Пример входных данных:
user.keyword | response.status | source.address.keyword | request.referrer.keyword | network.bytes |
---|---|---|---|---|
IvanovMG | 200 | 192.168.1.10 | /data | 2048 |
PetrovSI | 200 | 192.168.1.15 | /login | 1024 |
IvanovMG | 403 | 175.100.1.20 | /data | 512 |
AndreevAE | 401 | 10.0.0.1 | /config | 128 |
Результатом выполнения запроса может быть следующая таблица:
response.status | values (source.address.keyword) |
---|---|
200 | 192.168.1.10 192.168.1.15 |
403 | 175.100.1.20 |
401 | 10.0.0.1 |
Пример 3
Для последующих примеров будет использоваться входные данные аудита действий пользователей, часть которых представлена ниже. Для набора данных используемых в примерах не установлен маппинг индекса.
l_time | host | user | target | action | outcome |
---|---|---|---|---|---|
2025-05-30 13:47:08 | ws-01 | denisov | sokolova | locked-out-user-account changed-password added-member-to-group | success |
2025-05-30 13:47:08 | ws-01 | avdeev | sokolova | reset-password changed-password | failure |
2025-05-30 13:47:08 | ws-01 | abramova | morozov | enabled-user-account | success |
2025-05-30 13:47:08 | ws-02 | popov | kirillova | changed-password | failure |
2025-05-30 13:47:08 | ws-01 | abramova | jakovleva | removed-member-from-group | success |
2025-05-30 13:47:08 | ws-01 | denisov | popov | added-member-to-group | failure |
2025-05-30 13:47:08 | ws-02 | shishkin | nikolaev | removed-member-from-group | failure |
Пример 3.1
Список всех уникальных значений полей user
и action
:
... | aggs values(user.keyword), values(action.keyword)
Возвращает массивы уникальных значений для user.keyword
и action.keyword
независимо друг от друга.
Результатом выполнения запроса может быть следующая таблица:
values (user.keyword) | values (action.keyword) |
---|---|
denisov avdeev abramova popov shishkin | locked-out-user-account reset-password enabled-user-account changed-password removed-member-from-group added-member-to-group |
Пример 3.2
Список уникальных значений user.keyword
и action.keyword
, у которых одинаковое сочетание значений полей user.keyword
и action.keyword
:
... | aggs values(user.keyword), values(action.keyword) by user.keyword, action.keyword
Группирует документы по уникальным комбинациям user.keyword
и action.keyword
, возвращая значения этих полей для каждой группы.
Результатом выполнения запроса может быть следующая таблица:
user.keyword | action.keyword | values (user.keyword) | values (action.keyword) |
---|---|---|---|
denisov | locked-out-user-account | denisov | locked-out-user-account changed-password added-member-to-group |
denisov | changed-password | denisov | locked-out-user-account changed-password added-member-to-group |
denisov | added-member-to-group | denisov | locked-out-user-account changed-password added-member-to-group |
avdeev | reset-password | avdeev | reset-password changed-password |
avdeev | changed-password | avdeev | reset-password changed-password |
abramova | enabled-user-account | abramova | ["enabled-user-account"] |
popov | changed-password | popov | changed-password |
abramova | removed-member-from-group | abramova | removed-member-from-group |
denisov | added-member-to-group | denisov | added-member-to-group |
shishkin | removed-member-from-group | shishkin | removed-member-from-group |
Пример 3.3
Количество документов, содержащих поле user.keyword
:
... | aggs count(user.keyword)
Результатом выполнения запроса может быть следующая таблица:
count (user.keyword) |
---|
5 |
Пример 3.4
Количество документов, содержащих поле action.keyword
для каждого уникального значения поля user.keyword
:
... | aggs count(action.keyword) by user.keyword
Результатом выполнения запроса может быть следующая таблица:
user.keyword | count (user.keyword) |
---|---|
denisov | 955 |
avdeev | 34 |
abramova | 1007 |
popov | 1022 |
shishkin | 873 |
Пример 3.5
Количество документов, содержащих поле user.keyword
и количество документов, содержащих поле action.keyword
:
... | aggs count(user.keyword), count(action.keyword)
Результатом выполнения запроса может быть следующая таблица:
count (user.keyword) | count (action.keyword) |
---|---|
5 | 3891 |
Пример 3.6
Количество документов, содержащих поле user.keyword
для каждого уникального сочетания значений полей user.keyword
и action.keyword
:
... | aggs count(user.keyword) by user.keyword, action.keyword
Результатом выполнения запроса может быть следующая таблица из первых 7 записей:
user.keyword | action.keyword | count (user.keyword) |
---|---|---|
denisov | locked-out-user-account | 201 |
denisov | changed-password | 40 |
denisov | added-member-to-group | 46 |
shishkin | locked-out-user-account | 271 |
popov | locked-out-user-account | 511 |
denisov | disabled-user-account | 23 |
abramova | added-user-account | 51 |
avdeev | reset-password | 1 |
avdeev | changed-password | 2 |
popov | added-user-account | 59 |
Пример 3.7
В примере система вернет содержимое поля action.keyword
для первой записи в выборке, содержимое поля action.keyword
для последней записи в выборке, среднее значение поля action_count
, который рассчитывается командой из предыдущего примера, для каждого уникального user.keyword
:
... | aggs count(user.keyword) as action_count by user.keyword, event.keyword
| aggs first(action.keyword), last(action.keyword), avg(action_count.keyword) by user.keyword
Результатом выполнения запроса может быть следующая таблица:
user.keyword | first (action.keyword) | last (action.keyword) | avg (action_count.keyword) |
---|---|---|---|
denisov | locked-out-user-account | changed-password | 95.8 |
abramova | locked-out-user-account | changed-password | 100.1 |
shishkin | removed-member-from-group | reset-password | 102.2 |
popov | removed-member-from-group | reset-password | 113.22 |
avdeev | changed-password | reset-password | 1.5 |
Пример 3.8
В примере система вернет содержимое поля action.keyword
для самой ранней записи в выборке, содержимое поля user
для самой поздней записи в выборке:
... | aggs earliest(action.keyword), latest(user.keyword) by @timestamp
Результатом выполнения запроса может быть следующая таблица из первых 7 записей:
@timestamp | earliest (action.keyword) | latest (user.keyword) |
---|---|---|
2025-05-30T10:20:00.000000+0000 | removed-member-from-group | abramova |
2025-05-30T10:21:00.000000+0000 | added-member-to-group | abramova |
2025-05-30T10:22:00.000000+0000 | removed-member-from-group | denisov |
2025-05-30T10:23:00.000000+0000 | deleted-user-account | popov |
2025-05-30T10:24:00.000000+0000 | enabled-user-account | abramova |
2025-05-30T10:25:00.000000+0000 | locked-out-user-account | abramova |
2025-05-30T10:26:00.000000+0000 | unlocked-user-account | shishkin |
Пример 4
Количество уникальных значений поля user
:
... | aggs dc(user)
Пример входных данных:
user |
---|
Ivanov |
Petrov |
Andreev |
Ivanov |
Результатом выполнения запроса может быть следующая таблица:
dc(user) |
---|
3 |
Пример 5
В примере система вернет значение поля user
, которое встречается в 50 процентах случаев:
... | aggs perc(user, 50)
В примере система группирует данные по статусу доставки status
и для каждой группы возвращает массив уникальных идентификаторов транспортных средств vehicle
, вычисляет суммарное расстояние distance
и определяет времени доставки delivery_time
, которое встречается в 90 процентах случаев:
... | aggs values(vehicle.keyword), sum(distance), perc(delivery_time, 90) by status.keyword
Пример входных данных:
vehicle | status | distance | delivery_time | @timestamp |
---|---|---|---|---|
MTL Pounder | delivered | 100 | 24 | 2025-04-30T10:00:00Z |
Maibatsu Mule | delivered | 150 | 30 | 2025-04-30T10:10:00Z |
MTL Pounder | in_transit | 200 | 48 | 2025-04-30T10:20:00Z |
Jobiult Hauler | in_transit | 120 | 36 | 2025-04-30T10:30:00Z |
Maibatsu Mule | delivered | 80 | 28 | 2025-04-30T10:40:00Z |
Vapid Benson | pending | 50 | 12 | 2025-04-30T10:50:00Z |
Результатом выполнения запроса может быть следующая таблица:
status.keyword | values (vehicle_id.keyword) | sum (distance) | perc (delivery_time, 90) |
---|---|---|---|
delivered | MTL Pounder Maibatsu Mule | 330 | 29.6 |
in_transit | MTL Pounder Jobiult Hauler | 320 | 46.8 |
pending | Vapid Benson | 50 | 12 |
Пример 6
В примере система группирует данные по комбинациям типа транзакции transaction_type
и валюты currency
и для каждой группы подсчитывает количество уникальных клиентов client
, общую сумму транзакций amount
и возвращает идентификатор самой ранней транзакции transaction_id
:
... | aggs dc(client.keyword), sum(amount), earliest(transaction_id) by transaction_type.keyword, currency.keyword
Пример входных данных:
client | transaction_type | currency | amount | transaction_id | @timestamp |
---|---|---|---|---|---|
Ivanov | deposit | USD | 1000 | 1 | 2025-04-30T10:00:00Z |
Petrov | deposit | USD | 500 | 2 | 2025-04-30T10:10:00Z |
Ivanov | withdrawal | EUR | 200 | 3 | 2025-04-30T10:20:00Z |
Andreev | deposit | EUR | 400 | 4 | 2025-04-30T10:30:00Z |
Petrov | withdrawal | USD | 300 | 5 | 2025-04-30T10:40:00Z |
Ivanov | deposit | USD | 600 | 6 | 2025-04-30T09:50:00Z |
Результатом выполнения запроса может быть следующая таблица:
transaction_type.keyword | currency.keyword | dc (client.keyword) | sum (amount) | earliest (transaction_id) |
---|---|---|---|---|
deposit | USD | 2 | 1500 | 6 |
deposit | EUR | 1 | 400 | 4 |
withdrawal | EUR | 1 | 200 | 3 |
withdrawal | USD | 1 | 300 | 5 |