About lookups
Lookups enrich your event data by adding field-value combinations from lookup tables. Splunk software uses lookups to match field-value combinations in your event data with field-value combinations in external lookup tables. If Splunk software finds those field-value combinations in your lookup table, Splunk software will append the corresponding field-value combinations from the table to the events in your search.
Types of lookups
There are four types of lookups:
- CSV lookups
- External lookups
- KV Store lookups
- Geospatial lookups
You can create lookups in Splunk Web through the Settings pages for lookups.
If you have Splunk Enterprise or Splunk Light and have access to the configuration files for your Splunk deployment, you can configure lookups by editing configuration files.
Lookup type | Data source | Description | Create in Splunk Web | Configure in .conf files |
---|---|---|---|---|
CSV | A CSV file | Populates your events with fields pulled from CSV files. Also referred to as a static lookup because CSV files represent static tables of data. Each column in a CSV table is interpreted as the potential values of a field. Use CSV lookups when you have small sets of data that is relatively static.
|
Link | Link |
External | An external source, such as a DNS server. | Uses Python scripts or binary executables to populate your events with field values from an external source. Also referred to as a scripted lookup.
|
Link | Link |
KV Store | A KV Store collection | Matches fields in your events to fields in a KV Store collection and outputs corresponding fields in that collection to your events. Use a KV Store lookup when you have a large lookup table or a table that is updated often.
|
Link | Link |
Geospatial | A Keyhole Markup Zipped (KMZ) or Keyhole Markup Language (KML), used to define boundaries of mapped regions such as countries, US states, and US counties. | A geospatial lookup matches location coordinates in your events to geographic feature collections in a KMZ or KML file and outputs fields to your events that provide corresponding geographic feature information encoded in the KMZ or KML, like country, state, or county names. Use a geospatial lookup to create a query that Splunk software uses to configure a choropleth map.
|
Link | Link |
Lookup table files
Lookup table files are files that contain a lookup table. A standard lookup pulls fields out of this table and adds them to your events when corresponding fields in the table are matched in your events.
All lookup types use lookup tables, but only two lookup types require that you upload a lookup table file: CSV lookups and geospatial lookups. A single lookup table file can be used by multiple lookup definitions.
For example, say you have a CSV lookup table file that provides the definitions of http_status
fields. If you have events that include http_status = 503
you can have a lookup that finds the value of 503
in the lookup table column for the http_status
field and pulls out the corresponding value for status_description
in that lookup table. The lookup then adds status_description = Service Unavailable, Server Error
to every event with http_status = 503
.
Lookup definitions
A lookup definition provides a lookup name and a path to find the lookup table. Lookup definitions can include extra settings such as matching rules, or restrictions on the fields that the lookup is allowed to match. One lookup table can have multiple lookup definitions.
All lookup types require a lookup definition. After you create a lookup definition you can invoke the lookup in a search with the lookup
command.
Automatic lookups
Use automatic lookups to apply a lookup to all searches at search time. After you define an automatic lookup for a lookup definition, you do not need to manually invoke it in searches with the lookup
command.
See Define an automatic lookup.
Search commands and lookups
After you define your lookups and share them with apps, you can interact with them through search commands:
lookup
: Use to add fields to the events in the results of the search.inputlookup
: Use to search the contents of a lookup table.outputlookup
: Use to write fields in search results to a static lookup table file or KV store collection that you specify. You cannot use theoutputlookup
command with external lookups.
Lookups and the search-time operations sequence
Search-time operation order
Lookups are seventh in the search-time operations sequence and are processed after calculated fields but before event types.
Restrictions
The Splunk software processes lookups belonging to a specific host, source, or source type in ASCII sort order.
Lookup configurations can reference fields that are added to events by field extractions, field aliases, and calculated fields. They cannot reference event types and tags.
For more information
Configure transaction types | Define a CSV lookup in Splunk Web |
This documentation applies to the following versions of Splunk Cloud Platform™: 9.2.2406, 8.2.2201, 8.2.2202, 8.2.2203, 9.0.2205, 9.0.2208, 9.0.2209, 9.0.2303, 9.0.2305, 9.1.2308, 9.1.2312, 9.2.2403 (latest FedRAMP release)
Feedback submitted, thanks!