lookup
The lookup command enriches events by joining them against an external data source, typically a CSV file. It matches fields from incoming events against keys in the lookup table and appends matching values as new fields.
Syntax
The lookup command takes a lookup type identifier specifying the source, followed by filter field specifications, and optionally output field specifications:
| lookup csv("path/to/file.csv") <field1> [as <alias1>] [<field2> [as <alias2>] ...] [> <output1> [<output2> ...]]
csv("path"): Specifies the CSV file to use as the lookup source. The filename is provided as a quoted string argument.- Filter Fields: One or more field names from your event that will be matched against columns in the lookup table. Optionally aliased using
aswhen the event field name differs from the lookup table column name. - Output Fields (optional): After
>, specifies which columns from the lookup table should be added to the event. If omitted, all remaining columns are included.
Examples
Basic lookup with all outputs:
| lookup csv("people.csv") name
Matches the name field from the event against the name column in people.csv, adding all other columns (age, country, etc.) to the event.
Lookup with alias:
| lookup csv("people.csv") name as user_name_alias
Uses the event’s user_name_alias field to match against the name column in the lookup table.
Limited output:
| lookup csv("people.csv") name > age country
Only adds the age and country columns to the event, excluding others.
Multi-key lookup:
| lookup csv("data.csv") id name
Performs a composite key lookup using both id and name fields together.
Key Behaviors
- Multi-key support: You can specify multiple fields to create composite keys for more precise matching.
- Alias flexibility: Event fields can be aliased to match different column names in the lookup table.
- Output filtering: Use
>to explicitly select which columns to add, reducing payload size. - Multiple matches: When multiple rows match, the resulting fields contain arrays of all matching values.