match
Данные нововведения работают начиная с версии 5.3.1.
Описание
Фильтрует события из источника по значениям поля из стороннего индекса. Если указать OUTPUT или OUTPUTNEW, событие будет обогащено указанными полями из match-индекса.
Команда выполняет сравнение заданного поля в событии и match-индексе. В значениях match-индекса поддерживаются wildcard-символы * и ? — если запись в индексе содержит такой паттерн, он будет сопоставлен со значениями из событий.
Следует избегать дублирующих записей в match-индексе по полю сравнения. При наличии нескольких совпадающих записей обогащенные поля в результате примут вид multivalue-массива.
Синтаксис
...| match <match-index-name> <match-field> [as <source-field>] [match-options] [ OUTPUT | OUTPUTNEW (<match-destfield> [as <event-destfield>] )... ]
Обязательные аргументы
| Параметр | Синтаксис | Описание |
|---|---|---|
match-index-name | <string> | Имя индекса для построения match. |
match-field | <string> | Имя поля в match-индексе для сравнения. |
Опциональные аргументы match-options
| Параметр | Синтаксис | По умолчанию | Описание |
|---|---|---|---|
packsize | packsize=<int> | 500 | Размер блока данных для обработки. |
workers | workers=<int> | 8 | Количество потоков для обработки данных. |
timefield | timefield=<field> | @timestamp | Имя поля, в котором хранится временная метка. |
earliest | earliest=<string> | Начальная временная метка поиска. | |
latest | latest=<string> | Конечная временная метка поиска. |
Остальные опциональные аргументы
| Параметр | Синтаксис | По умолчанию | Описание |
|---|---|---|---|
source-field | <string> | Имя поля в событии для сравнения с match-field. Используется, если названия поля в событии и в match-индексе не совпадают. | |
OUTPUT | OUTPUTNEW | OUTPUT | OUTPUTNEW | OUTPUT | OUTPUT — добавляет или перезаписывает поля в событии данными из match-индекса. OUTPUTNEW — добавляет поля только если они отсутствуют в событии, не перезаписывая уже существующие значения. |
match-destfield | <string> | Имя поля в match-индексе, значение которого добавляется в событие. | |
event-destfield | <string> | Имя поля в результате. Используется, если нужно сохранить значение из match-индекса под другим именем. Указывается после as в конструкции OUTPUT <match-destfield> as <event-destfield>. |
Примеры запросов
В следующих примерах используются два индекса.
Индекс событий auth_events:
| @timestamp | user_login | host.name | event.action | event.outcome |
|---|---|---|---|---|
| 2026-06-24T10:00:00Z | admin | dc-01 | logged-in | success |
| 2026-06-24T10:05:00Z | svc_backup | srv-02 | logged-in | success |
| 2026-06-24T10:10:00Z | svc_monitor | srv-03 | logged-in | success |
| 2026-06-24T10:15:00Z | guest | workstation-05 | logged-in | failure |
| 2026-06-24T10:20:00Z | john.doe | workstation-12 | logged-out | success |
| 2026-06-24T10:25:00Z | unknown_user | workstation-99 | logged-in | failure |
Match-индекс ad_users (справочник пользователей):
| username | category | risk_level | description |
|---|---|---|---|
| admin | administrator | low | Системный администратор |
| svc_* | service_account | medium | Сервисная учетная запись |
| guest | external | high | Гостевой пользователь |
| john.doe | employee | low | Сотрудник отдела HR |
Пример 1
В данном примере match используется как фильтр без обогащения. Из потока событий остаются только те, у которых значение поля user_login совпадает с полем username в match-индексе ad_users. Ключевое слово as user_login указывает, что в событии сравниваемое поле называется user_login, а не username.
source auth_events
| match ad_users username as user_login
Пользователь unknown_user отсутствует в ad_users, поэтому его событие исключается из результата:
| @timestamp | user_login | host.name | event.action | event.outcome |
|---|---|---|---|---|
| 2026-06-24T10:00:00Z | admin | dc-01 | logged-in | success |
| 2026-06-24T10:05:00Z | svc_backup | srv-02 | logged-in | success |
| 2026-06-24T10:10:00Z | svc_monitor | srv-03 | logged-in | success |
| 2026-06-24T10:15:00Z | guest | workstation-05 | logged-in | failure |
| 2026-06-24T10:20:00Z | john.doe | workstation-12 | logged-out | success |
Пример 2
В данном примере события обогащаются полями category, risk_level и description из match-индекса. OUTPUT перезаписывает значения этих полей в событии, даже если они уже заполнены.
source auth_events
| match ad_users username as user_login OUTPUT category, risk_level, description
| @timestamp | user_login | host.name | event.action | event.outcome | category | risk_level | description |
|---|---|---|---|---|---|---|---|
| 2026-06-24T10:00:00Z | admin | dc-01 | logged-in | success | administrator | low | Системный администратор |
| 2026-06-24T10:05:00Z | svc_backup | srv-02 | logged-in | success | service_account | medium | Сервисная учетная запись |
| 2026-06-24T10:10:00Z | svc_monitor | srv-03 | logged-in | success | service_account | medium | Сервисная учетная запись |
| 2026-06-24T10:15:00Z | guest | workstation-05 | logged-in | failure | external | high | Гостевой пользователь |
| 2026-06-24T10:20:00Z | john.doe | workstation-12 | logged-out | success | employee | low | Сотрудник отдела HR |
Пример 3
В данном примере используется OUTPUTNEW — поля добавляются только если они отсутствуют в событии. В отличие от OUTPUT, уже заполненные значения не перезаписываются.
Предположим, что в auth_events у пользователя admin поле category уже заполнено значением sysadmin:
| @timestamp | user_login | host.name | category |
|---|---|---|---|
| 2026-06-24T10:00:00Z | admin | dc-01 | sysadmin |
| 2026-06-24T10:05:00Z | svc_backup | srv-02 |
source auth_events
| match ad_users username as user_login OUTPUTNEW category, risk_level
Для admin поле category сохранит исходное значение sysadmin. Для svc_backup, у которого поле пустое, значение будет добавлено из match-индекса:
| @timestamp | user_login | host.name | category | risk_level |
|---|---|---|---|---|
| 2026-06-24T10:00:00Z | admin | dc-01 | sysadmin | low |
| 2026-06-24T10:05:00Z | svc_backup | srv-02 | service_account | medium |
Пример 4
В данном примере демонстрируется работа wildcard-паттернов в match-индексе. Запись svc_* в поле username индекса ad_users сопоставляется со всеми значениями, начинающимися на svc_. События пользователей svc_backup и svc_monitor получают поле category из этой записи.
source auth_events
| search user_login="svc_*"
| match ad_users username as user_login OUTPUT category
| @timestamp | user_login | host.name | event.action | event.outcome | category |
|---|---|---|---|---|---|
| 2026-06-24T10:05:00Z | svc_backup | srv-02 | logged-in | success | service_account |
| 2026-06-24T10:10:00Z | svc_monitor | srv-03 | logged-in | success | service_account |
Пример 5
В данном примере используются параметры производительности packsize и workers, а также переименование результирующего поля через as. Поле category из match-индекса сохраняется в событии под именем user_category.
source auth_events
| match ad_users username as user_login packsize=1000 workers=4 OUTPUT category as user_category, risk_level
Пример 6
В данном примере параметры earliest и latest ограничивают временной диапазон записей в match-индексе, которые участвуют в сопоставлении. Это полезно, если match-индекс содержит версионированные данные — например, справочник пользователей, который обновляется со временем, и нужно сопоставить события только с актуальными на конкретный период записями.
source auth_events
| match ad_users username as user_login earliest="2026-06-24T00:00:00Z" latest="2026-06-26T00:00:00Z" OUTPUT category
| @timestamp | user_login | host.name | event.action | event.outcome | category |
|---|---|---|---|---|---|
| 2026-06-24T10:00:00Z | admin | dc-01 | logged-in | success | administrator |
| 2026-06-24T10:05:00Z | svc_backup | srv-02 | logged-in | success | service_account |
| 2026-06-24T10:10:00Z | svc_monitor | srv-03 | logged-in | success | service_account |
| 2026-06-24T10:15:00Z | guest | workstation-05 | logged-in | failure | external |
| 2026-06-24T10:20:00Z | john.doe | workstation-12 | logged-out | success | employee |
| 2026-06-24T10:35:00Z | oleg.ivanov | workstation-100 | logged-in | success | employee |
| 2026-06-24T10:45:00Z | ivan.ivanov | workstation-101 | logged-in | failure | employee |