match
These innovations work starting from version 5.3.1.
Description
Filters events from the source by field values from an external index. If OUTPUT or OUTPUTNEW is specified, the event will be enriched with the specified fields from the match-index.
The command performs comparison of a specified field in the event and match-index. Wildcard characters * and ? are supported in match-index values — if an entry in the index contains such a pattern, it will be matched against values from events.
You should avoid duplicate entries in the match-index for the comparison field. When multiple matching entries exist, the enriched fields in the result will take the form of a multivalue array.
Syntax
...| match <match-index-name> <match-field> [as <source-field>] [match-options] [ OUTPUT | OUTPUTNEW (<match-destfield> [as <event-destfield>] )... ]
Required arguments
| Parameter | Syntax | Description |
|---|---|---|
match-index-name | <string> | Index name for building match. |
match-field | <string> | The name of the field in the match-index for comparison. |
Optional arguments match-options
| Parameter | Syntax | Default | Description |
|---|---|---|---|
packsize | packsize=<int> | 500 | Size of data block for processing. |
workers | workers=<int> | 8 | Number of threads for data processing. |
timefield | timefield=<field> | @timestamp | Name of the field storing the timestamp. |
earliest | earliest=<string> | Start timestamp for search. | |
latest | latest=<string> | End timestamp for search. |
Other Optional Arguments
| Parameter | Syntax | Default | Description |
|---|---|---|---|
source-field | <string> | The name of the field in the event to compare with match-field. Used when the field name in the event and in the match-index do not match. | |
| `OUTPUT | OUTPUTNEW` | `OUTPUT | OUTPUTNEW` |
match-destfield | <string> | The name of the field in the match-index whose value is added to the event. | |
event-destfield | <string> | The name of the field in the result. Used when you need to save the value from the match-index under a different name. Specified after as in the construct OUTPUT <match-destfield> as <event-destfield>. |
Query Examples
The following examples use two indexes.
Event index 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-index ad_users (user directory):
| username | category | risk_level | description |
|---|---|---|---|
| admin | administrator | low | System administrator |
| svc_* | service_account | medium | Service account |
| guest | external | high | Guest user |
| john.doe | employee | low | HR department employee |
Example 1
In this example, match is used as a filter without enrichment. From the event stream, only those events remain where the value of the user_login field matches the username field in the ad_users match-index. The keyword as user_login indicates that the comparable field in the event is called user_login, not username.
source auth_events
| match ad_users username as user_login
User unknown_user is absent in ad_users, so their event is excluded from the result:
| @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 |
Example 2
In this example, events are enriched with category, risk_level, and description fields from the match-index. OUTPUT overwrites the values of these fields in the event, even if they are already filled.
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 | System administrator |
| 2026-06-24T10:05:00Z | svc_backup | srv-02 | logged-in | success | service_account | medium | Service account |
| 2026-06-24T10:10:00Z | svc_monitor | srv-03 | logged-in | success | service_account | medium | Service account |
| 2026-06-24T10:15:00Z | guest | workstation-05 | logged-in | failure | external | high | Guest user |
| 2026-06-24T10:20:00Z | john.doe | workstation-12 | logged-out | success | employee | low | HR department employee |
Example 3
In this example, OUTPUTNEW is used — fields are added only if they are absent in the event. Unlike OUTPUT, already filled values are not overwritten.
Suppose that in auth_events the user admin already has the field category filled with the value 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
For admin, the field category retains the original value sysadmin. For svc_backup, whose field is empty, the value will be added from the match-index:
| @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 |
Example 4
In this example, the work of wildcard patterns in the match-index is demonstrated. The entry svc_* in the username field of the ad_users index is matched against all values starting with svc_. Events of users svc_backup and svc_monitor receive the category field from this entry.
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 |
Example 5
In this example, performance parameters packsize and workers are used, as well as renaming the resulting field through as. The category field from the match-index is saved in the event under the name user_category.
source auth_events
| match ad_users username as user_login packsize=1000 workers=4 OUTPUT category as user_category, risk_level
Example 6
In this example, parameters earliest and latest limit the time range of records in the match-index that participate in matching. This is useful when the match-index contains versioned data — for example, a user directory that is updated over time, and you need to match events only with records that were actual for a specific period.
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 |