Перейти к основному содержимому
Версия: 5.1

aggs

Описание

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

осторожно

Использование aggs в запросе допустимо в случае, если перед ней находятся только команды, также работающие с внутренними механизмами хранилища. К ним относятся source, search и peval. Это условие должно выполняться и для всех подзапросов в запросе.

Синтаксис

| aggs [composite=<bool>] <functions-expression> ["," <functions-expression>]  [<by_expression>]

Обязательные аргументы

Обязательно использование хотя бы одной из функций:

ПараметрСинтаксисОписание
countcount | count(<field>)Вычисляет количество событий, содержащих поле. Если поле не указано, рассчитывает общее количество событий.
valuesvalues(<field>)Вычисляет массив уникальных значений по заданному полю.
avgavg(<field>)Вычисляет среднее значение по заданному полю.
dcdc(<field>)Вычисляет количество уникальных значений в заданном поле.
earliestearliest(<field>)Вычисляет значение поля для самого раннего события. В качестве второго (опционального) параметра передается имя поля с временной меткой. По умолчанию @timestamp.
latestlatest(<field>)Вычисляет значение поля для самого позднего события. В качестве второго (опционального) параметра передается имя поля с временной меткой. По умолчанию @timestamp.
maxmax(<field>)Вычисляет максимальное значение по заданному полю.
minmin(<field>)Вычисляет минимальное значение по заданному полю.
sumsum(<field>)Вычисляет сумму значений по заданному полю.
percperc(<field>, <percent>)Вычисляет персентиль по заданному полю и проценту.
medianmedian(<field>)Вычисляет медиану по заданному полю.

Опциональные аргументы

ПараметрСинтаксисПо умолчаниюОписание
compositecomposite=<boolean>falseДает возможность использования скроллинга в агрегациях и получить все возможные сегменты (buckets) с помощью нескольких запросов (аналогично scroll в stats). Может быть применен только при наличии группировки (by полей). Количеством сегментов (buckets), которые будут возвращены в ответе имеет фиксированное значение — 1000.
<by_expression><by_field> ["," <by_field> ...]Имя поля (или полей) для группировки значений.
Использование composite

Аргумент composite доступен при запросе к OpenSearch.

Использование keyword в 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.

Результатом выполнения запроса может быть следующая таблица:

countevent.codestatushost.keyword
15953InfoVLG-DC-01
14985504InfoMSK-DC-02
3564015ErrorSPB-DC-03
2544013WarningVLG-DC-01
1234007ErrorSPB-DC-03
984013WarningMSK-DC-02
795504InfoSPB-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.keywordevent.action.keywordcounthosts
IvanovMGcredential-validated41MSK-WS-01
SPB-WS-02
IvanovMGlogged-in26SPB-WS-02
VLG-WS-03
KZN-WS-05
IvanovMGlogged-out25SPB-WS-02
VLG-WS-03
KZN-WS-05
PetrovSIlogged-out33SPB-WS-02
KZN-WS-05
PetrovSIadded-member-to-group6MSK-WS-01
AndreevAEadded-member-to-group14SPB-WS-02
VLG-WS-03

Расширенные примеры

Пример 1

Получение списка уникальных значений поля user:

... | aggs values(user.keyword)

Возвращает массив уникальных значений поля user.keyword из всех документов, соответствующих запросу.

Пример входных данных:

usersource.addressevent
IvanovMG192.168.1.10login
PetrovSI192.168.1.15logout
IvanovMG192.168.1.20login
AndreevAE10.0.0.1password_reset
SidorovVA10.0.0.5password_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.keywordvalues (user.keyword)
startIvanov
Petrov
endAndreev

Пример 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.keywordresponse.statussource.address.keywordrequest.referrer.keywordnetwork.bytes
IvanovMG200192.168.1.10/data2048
PetrovSI200192.168.1.15/login1024
IvanovMG403175.100.1.20/data512
AndreevAE40110.0.0.1/config128

Результатом выполнения запроса может быть следующая таблица:

response.statusvalues (source.address.keyword)
200192.168.1.10
192.168.1.15
403175.100.1.20
40110.0.0.1

Пример 3

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

l_timehostusertargetactionoutcome
2025-05-30 13:47:08ws-01denisovsokolovalocked-out-user-account
changed-password
added-member-to-group
success
2025-05-30 13:47:08ws-01avdeevsokolovareset-password
changed-password
failure
2025-05-30 13:47:08ws-01abramovamorozovenabled-user-accountsuccess
2025-05-30 13:47:08ws-02popovkirillovachanged-passwordfailure
2025-05-30 13:47:08ws-01abramovajakovlevaremoved-member-from-groupsuccess
2025-05-30 13:47:08ws-01denisovpopovadded-member-to-groupfailure
2025-05-30 13:47:08ws-02shishkinnikolaevremoved-member-from-groupfailure

Пример 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.keywordaction.keywordvalues (user.keyword)values (action.keyword)
denisovlocked-out-user-accountdenisovlocked-out-user-account
changed-password
added-member-to-group
denisovchanged-passworddenisovlocked-out-user-account
changed-password
added-member-to-group
denisovadded-member-to-groupdenisovlocked-out-user-account
changed-password
added-member-to-group
avdeevreset-passwordavdeevreset-password
changed-password
avdeevchanged-passwordavdeevreset-password
changed-password
abramovaenabled-user-accountabramova["enabled-user-account"]
popovchanged-passwordpopovchanged-password
abramovaremoved-member-from-groupabramovaremoved-member-from-group
denisovadded-member-to-groupdenisovadded-member-to-group
shishkinremoved-member-from-groupshishkinremoved-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.keywordcount (user.keyword)
denisov955
avdeev34
abramova1007
popov1022
shishkin873

Пример 3.5

Количество документов, содержащих поле user.keyword и количество документов, содержащих поле action.keyword:

... | aggs count(user.keyword), count(action.keyword)

Результатом выполнения запроса может быть следующая таблица:

count (user.keyword)count (action.keyword)
53891

Пример 3.6

Количество документов, содержащих поле user.keyword для каждого уникального сочетания значений полей user.keyword и action.keyword:

... | aggs count(user.keyword) by user.keyword, action.keyword

Результатом выполнения запроса может быть следующая таблица из первых 7 записей:

user.keywordaction.keywordcount (user.keyword)
denisovlocked-out-user-account201
denisovchanged-password40
denisovadded-member-to-group46
shishkinlocked-out-user-account271
popovlocked-out-user-account511
denisovdisabled-user-account23
abramovaadded-user-account51
avdeevreset-password1
avdeevchanged-password2
popovadded-user-account59

Пример 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.keywordfirst (action.keyword)last (action.keyword)avg (action_count.keyword)
denisovlocked-out-user-accountchanged-password95.8
abramovalocked-out-user-accountchanged-password100.1
shishkinremoved-member-from-groupreset-password102.2
popovremoved-member-from-groupreset-password113.22
avdeevchanged-passwordreset-password1.5

Пример 3.8

В примере система вернет содержимое поля action.keyword для самой ранней записи в выборке, содержимое поля user для самой поздней записи в выборке:

... | aggs earliest(action.keyword), latest(user.keyword) by @timestamp

Результатом выполнения запроса может быть следующая таблица из первых 7 записей:

@timestampearliest (action.keyword)latest (user.keyword)
2025-05-30T10:20:00.000000+0000removed-member-from-groupabramova
2025-05-30T10:21:00.000000+0000added-member-to-groupabramova
2025-05-30T10:22:00.000000+0000removed-member-from-groupdenisov
2025-05-30T10:23:00.000000+0000deleted-user-accountpopov
2025-05-30T10:24:00.000000+0000enabled-user-accountabramova
2025-05-30T10:25:00.000000+0000locked-out-user-accountabramova
2025-05-30T10:26:00.000000+0000unlocked-user-accountshishkin

Пример 4

Количество уникальных значений поля user:

Пример №10
... | aggs dc(user)

Пример входных данных:

user
Ivanov
Petrov
Andreev
Ivanov

Результатом выполнения запроса может быть следующая таблица:

dc(user)
3

Пример 5

В примере система вернет значение поля user, которое встречается в 50 процентах случаев:

Пример №11
... | aggs perc(user, 50)

В примере система группирует данные по статусу доставки status и для каждой группы возвращает массив уникальных идентификаторов транспортных средств vehicle, вычисляет суммарное расстояние distance и определяет времени доставки delivery_time, которое встречается в 90 процентах случаев:

Пример №11
... | aggs values(vehicle.keyword), sum(distance), perc(delivery_time, 90) by status.keyword

Пример входных данных:

vehiclestatusdistancedelivery_time@timestamp
MTL Pounderdelivered100242025-04-30T10:00:00Z
Maibatsu Muledelivered150302025-04-30T10:10:00Z
MTL Pounderin_transit200482025-04-30T10:20:00Z
Jobiult Haulerin_transit120362025-04-30T10:30:00Z
Maibatsu Muledelivered80282025-04-30T10:40:00Z
Vapid Bensonpending50122025-04-30T10:50:00Z

Результатом выполнения запроса может быть следующая таблица:

status.keywordvalues (vehicle_id.keyword)sum (distance)perc (delivery_time, 90)
deliveredMTL Pounder
Maibatsu Mule
33029.6
in_transitMTL Pounder
Jobiult Hauler
32046.8
pendingVapid Benson5012

Пример 6

В примере система группирует данные по комбинациям типа транзакции transaction_type и валюты currency и для каждой группы подсчитывает количество уникальных клиентов client, общую сумму транзакций amount и возвращает идентификатор самой ранней транзакции transaction_id:

Пример №12
... | aggs dc(client.keyword), sum(amount), earliest(transaction_id) by transaction_type.keyword, currency.keyword

Пример входных данных:

clienttransaction_typecurrencyamounttransaction_id@timestamp
IvanovdepositUSD100012025-04-30T10:00:00Z
PetrovdepositUSD50022025-04-30T10:10:00Z
IvanovwithdrawalEUR20032025-04-30T10:20:00Z
AndreevdepositEUR40042025-04-30T10:30:00Z
PetrovwithdrawalUSD30052025-04-30T10:40:00Z
IvanovdepositUSD60062025-04-30T09:50:00Z

Результатом выполнения запроса может быть следующая таблица:

transaction_type.keywordcurrency.keyworddc (client.keyword)sum (amount)earliest (transaction_id)
depositUSD215006
depositEUR14004
withdrawalEUR12003
withdrawalUSD13005