Search Reference

 


lookup

This documentation does not apply to the most recent version of Splunk. Click here for the latest version.

lookup

Use the lookup command to manually invoke field lookups from a lookup table that you've defined in transforms.conf. For more information, see "Lookup fields from external data sources," in the Knowledge Manager manual.

Synopsis

Explicitly invokes field value lookups.

Syntax

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

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

Optional arguments

local
Syntax: local=<bool>
Description: If local=true, forces the lookup to run locally and not on any remote peers.
update
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. Defaults to false.
<local-destfield>
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.
<local-field>
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.
<lookup-destfield>
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.
<lookup-field>
Syntax: <string>
Description: Refers to a field in the lookup table to match to the local event. Multiple <lookup-destfield> values can be specified.

Description

Use the lookup command to invoke field value lookups manually.

If an OUTPUT clause is not specified, all fields in the lookup table that are not specified as a lookup 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.

Examples

Example 1: There is a lookup table specified in a stanza name 'usertogroup' in transform.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 matches, the value of the 'group' field in the lookup table will be 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 reporting command, do the lookup after the reporting command. For example, run:

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

instead of:

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

Answers

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

This documentation applies to the following versions of Splunk: 4.1 , 4.1.1 , 4.1.2 , 4.1.3 , 4.1.4 , 4.1.5 , 4.1.6 , 4.1.7 , 4.1.8 , 4.2 , 4.2.1 , 4.2.2 , 4.2.3 , 4.2.4 , 4.2.5 , 4.3 , 4.3.1 , 4.3.2 , 4.3.3 , 4.3.4 , 4.3.5 , 4.3.6 , 4.3.7 , 5.0 , 5.0.1 , 5.0.2 , 5.0.3 , 5.0.4 , 5.0.5 , 5.0.6 , 5.0.7 , 5.0.8 , 5.0.9 View the Article History for its revisions.


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

Was this documentation topic helpful?

If you'd like to hear back from us, please provide your email address:

We'd love to hear what you think about this topic or the documentation as a whole. Feedback you enter here will be delivered to the documentation team.

Feedback submitted, thanks!