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

Аргумент 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.

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

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