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. CSV inline lookup table files and inline lookup definitions that use CSV files are both dataset types. See About datasets.	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. Not a dataset type.	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. Not a dataset type.	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. Not a dataset type.	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 the outputlookup command with external lookups.

Lookups and the search-time operations sequence

Search-time operation order

In the search-time operations sequence, lookups 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 lexicographical 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

See The sequence of search-time operations.