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 as when 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 non-key columns are included. Key columns are only output when explicitly listed after >.

See Lookups for where lookup files are stored and how they are loaded.

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.

Explicit key output:

| lookup csv("people.csv") name as name_alias > name

Uses the event’s name_alias field to match against the name column, then outputs the lookup table’s name column. If the event already has a name field, it is replaced by the lookup value.

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. Implicit output excludes lookup key columns, but explicitly selected key columns will be output and overwrite exising values.
• Field replacement: Output fields replace existing event fields with the same name.
• Multiple matches: When multiple rows match, the resulting fields contain arrays of all matching values.
• Typed output values: Lookup values are parsed using the same value conversion as search fields. A CSV value containing a JSON object or array can be accessed by later commands using dot notation.
• Nested output access: The > output list selects lookup columns, not nested paths. Select the parent column, then access nested values in a later command.

For example, if a lookup outputs a profile column containing {"age":30}, a later command can read the nested value:

| lookup csv("people.csv") name
| eval age=profile.age

To limit output to a nested object, select the parent lookup column:

| lookup csv("people.csv") name > profile
| eval country=profile.country