Search Reference

lookup

Description

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.

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.

Default: false

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.

Default: 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-field> values can be specified.

Description

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.

Examples

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

Answers

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