lookup command: Examples

The following are examples for using the SPL2 lookup command. To learn more about the lookup command, see How the SPL2 lookup command works.

1. Put corresponding information from a lookup dataset into your events

This example appends the data returned from your search results with the data in the users lookup dataset using the uid field.

The users lookup dataset contains this data:


uid	username	department
1066	Claudia Garcia	Engineering
1690	Rutherford Sullivan	Engineering
1815	Vanya Patel	IT
1862	Wei Zhang	Engineering
1916	Alex Martin	Personnel

The events look something like this:


_time	host	action	department	uid
1:02:45 PM 13 Apr 2025	mailsv2	Failed password	Engineering	1066
10:52:41 AM 13 Apr 2025	mailsv1	Failed password	IT	1815
6:23:48 AM 13 Apr 2025	mailsv3	Session closed		1916
6:23:48 AM 13 Apr 2025	mailsv3	Failed password
8:18:36 PM 12 Apr 2025	mailsv1	Session closed	Engineering	1690

The third event is missing the department. The fourth event is missing the department and the uid.

When you run the following search, for search results that contains a uid field, the value in that field are matched with the uid field in the users lookup dataset.

... | lookup users uid OUTPUTNEW username, department

The username and department fields from the users lookup dataset are appended to each search result. If the search results already have the username and department fields, the OUTPUTNEW argument only fills in missing values in those fields.


_time	host	action	department	uid	username
1:02:45 PM 13 Apr 2025	mailsv2	Failed password	Engineering	1066	Claudia Garcia
10:52:41 AM 13 Apr 2025	mailsv1	Failed password	IT	1815	Vanya Patel
6:23:48 AM 13 Apr 2025	mailsv3	Session closed	Personnel	1916	Alex Martin
6:23:48 AM 13 Apr 2025	mailsv3	Failed password
8:18:36 PM 12 Apr 2025	mailsv1	Session closed	Engineering	1690	Rutherford Sullivan

Because the third event was missing the department, the department name is added to the search results. The fourth event was missing the department and the uid. Because there is no uid to match on, there are no changes to the search results for that event.

2. Replace data in your events with data from a lookup dataset

This example replaces the data returned from the search results with data in the addresses lookup dataset. It maps each value in the CustID field in the lookup dataset with the matching value in the cid field in the search results. Find the corresponding CustAddress value and use the address in the lookup dataset to replace the cAddress in the search results.

...| lookup addresses CustID AS cid OUTPUT CustAddress AS cAddress

3. Lookup users and return the corresponding group the user belongs to

There is a KV store lookup dataset called usertogroup. The dataset contains multiple fields, including user and group. The values in the user field in the lookup dataset are mapped to the corresponding value of the field local_user in the search results. For any entries that match, the value of the group field in the lookup dataset is written to the field user_group in the search results.

... | lookup usertogroup user AS local_user OUTPUTNEW group

4. Pipeline examples

These examples show how to use the lookup command in a pipeline.

To use a lookup in a pipeline, you must add an import statement before the $pipeline statement.

The syntax you use is:

import <lookup_dataset_name> from <namespace>

$pipeline = | from $source 
| lookup <lookup_dataset_name> <lookup_field> AS <event_field> 
| into $destination

Enrich a pipeline with lookup data

The following example imports the prices lookup dataset and references the lookup field productId, which is equivalent to the event field product_id . The product_name field in the lookup is added to the pipeline events, using the product ID field values to determine the corresponding product name values.

import 'prices.csv' from /envs.splunk.buttercup.lookups 

$pipeline = | from $source 
| lookup 'prices.csv' productId AS product_id OUTPUTNEW product_name 
| into $destination;

Replace pipeline values with lookup data

The following example imports the API_clients lookup dataset and references the lookup field apiclientID, which is equivalent to the event field APIClientID . The values in theeventtype field in the lookup replace the corresponding values in the eventtype field in the incoming pipeline events.

import 'API_clients.csv' from /envs.splunk.<tenant>.lookups 

$pipeline = | from $source 
| lookup 'API_clients.csv' apiclientID AS APIClientID OUTPUT eventtype
| into $destination

Documentation