
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.
PREVIOUS localop |
NEXT makecontinuous |
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
Feedback submitted, thanks!