Splunk® Enterprise

Search Reference

Download manual as PDF

Splunk Enterprise version 6.x is no longer supported as of October 23, 2019. See the Splunk Software Support Policy for details. For information about upgrading to a supported version, see How to upgrade Splunk Enterprise.
This documentation does not apply to the most recent version of Splunk. Click here for the latest version.
Download topic as PDF



Use the lookup command to invoke field value lookups. The lookup does not need to be defined in props.conf or transforms.conf for you to use this command, but lookup table you reference must be uploaded to Splunk Enterprise.

You can also use this command to manually invoke lookup definitions that exist in transforms.conf. If you have automatic lookups configured in the props.conf file, the lookup command does not use any of those settings. See "Lookup fields from external data sources," in the Knowledge Manager Manual.


Explicitly invokes field value lookups.


lookup [local=<bool>] [update=<bool>] <lookup-table-name> ( <lookup-field> [AS <local-field>] ) ( OUTPUT | OUTPUTNEW <lookup-destfield> [AS <local-destfield>] )

Note: The lookup command can accept multiple lookup and local fields and destfields. For example:

lookup <lookup-table-name> <lookup-field1> AS <local-field1>, <lookup-field2> AS <local-field2> OUTPUTNEW <lookup-destfield1> AS <local-destfield1>, <lookup-destfield2> AS <local-destfield2>

Required arguments

Syntax: <string>
Description: Refers to a stanza name in transforms.conf. This stanza specifies the location of the lookup table file.

Optional arguments

Syntax: local=<bool>
Description: If local=true, forces the lookup to run locally and not on any remote peers.
Default: false
Syntax: update=<bool>
Description: If the lookup table is modified on disk while the search is running, real-time searches will not automatically reflect the update. To do this, specify update=true. This does not apply to non-real-time searches. This implies that local=true.
Default: false
Syntax: <string>
Description: Refers to the field in the local event, defaults to the value of <lookup-destfield>. Multiple <local-destfield> values can be specified.
Syntax: <string>
Description: Refers to the field in the local event, defaults to the value of <lookup-field>. Multiple <local-field> values can be specified.
Syntax: <string>
Description: Refers to a field in the lookup table to be copied to the local event. Multiple <lookup-destfield> values can be specified.
Syntax: <string>
Description: Refers to a field in the lookup table to match to the local event. Multiple <lookup-field> values can be specified.


When using the lookup command, if an OUTPUT or OUTPUTNEW clause is not specified, all fields in the lookup table that are not the match field will be used as output fields. If OUTPUT is specified, the output lookup fields will overwrite existing fields. If OUTPUTNEW is specified, the lookup will not be performed for events in which the output fields already exist.


Example 1: There is a lookup table specified in a stanza named usertogroup in transforms.conf. This lookup table contains (at least) two fields, user and group. For each event, we look up the value of the field local_user in the table and for any entries that match, the value of the group field in the lookup table is written to the field user_group in the event.

... | lookup usertogroup user as local_user OUTPUT group as user_group

Optimizing your lookup search

If you're using the lookup command in the same pipeline as a transforming command, do the lookup after the transforming command. For example, run:

sourcetype=access_* | stats count by status | lookup status_desc status OUTPUT description

and not:

sourcetype=access_* | lookup status_desc status OUTPUT description | stats count by description

The lookup in the first search is faster because it only needs to match the results of the stats command and not all the Web access events.

See also

appendcols, inputlookup, outputlookup


Have questions? Visit Splunk Answers and see what questions and answers the Splunk community has using the lookup command.

Last modified on 28 January, 2016

This documentation applies to the following versions of Splunk® Enterprise: 6.0, 6.0.1, 6.0.2, 6.0.3, 6.0.4, 6.0.5, 6.0.6, 6.0.7, 6.0.8, 6.0.9, 6.0.10, 6.0.11, 6.0.12, 6.0.13, 6.0.14, 6.0.15, 6.1, 6.1.1, 6.1.2, 6.1.3, 6.1.4, 6.1.5, 6.1.6, 6.1.7, 6.1.8, 6.1.9, 6.1.10, 6.1.11, 6.1.12, 6.1.13, 6.1.14, 6.2.13, 6.2.14, 6.2.15

Was this documentation topic helpful?

Enter your email address, and someone from the documentation team will respond to you:

Please provide your comments here. Ask a question or make a suggestion.

You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters