# Lookups: Introduction and Configuration

> Chapter 6 of the Courseiva SPLUNK-CORE-CERTIFIED-POWER-USER curriculum — https://courseiva.com/learn/splunk-core-certified-power-user/lookups-introduction-and-configuration

**Official objective:** 2.3 — Configure and use lookups to enrich search results.

## Introduction

A lookup is a way to add extra, meaningful information to your Splunk search results by matching a field in your data against a reference table. It matters for SPLK-1003 because the exam tests your ability to create, configure, and use lookups to turn raw machine data into reports that business people can actually understand.

## The Restaurant Menu Analogy

Because you don't have a menu, you can't order your favourite dish. A Splunk lookup is like that restaurant menu. When a waiter brings you a plate of food, you see a short code on the plate — say "STK-42" — but you have no idea what that code means. The menu is a separate card that lists every code next to its full description: "STK-42" is "Ribeye steak, medium-rare, with peppercorn sauce." Without the menu, the code tells you nothing useful. With the menu, you instantly know what you're about to eat.

In Splunk, a lookup works the same way. Your search results often contain a code or an ID — like a user ID (e.g., "U342") or a status number (e.g., "403"). Splunk doesn't automatically know that "U342" means "Jane Doe, Marketing Department" or that "403" means "Forbidden — no permission." You create a lookup file — a simple table stored in Splunk — that acts as your menu. When Splunk runs a search and finds "U342," it looks up that code in the lookup table and pulls back "Jane Doe, Marketing Department" to enrich the search results.

This is everyday life. You have a loyalty card with a number, and the shop's system looks up that number in their database to show your name and points balance. Splunk does the exact same thing with machine data. The lookup transforms a meaningless ID into rich, readable information that helps you understand what's happening in your systems.

## Core explanation

A lookup in Splunk is a process that takes a value from your search results — for example, an IP address like "192.168.1.10" — and uses it to find related information in a separate file or table. That separate file is called a lookup table. Once Splunk finds a match, it adds the new information from the lookup table to your search results. This process is called enriching your data.

Let's start with the simplest form: a CSV file as a lookup table. CSV stands for comma-separated values. It is like a spreadsheet saved as plain text, where each line is a row and commas separate the columns. Imagine you have a CSV file called "employees.csv" with two columns: "user_id" and "full_name." Inside the file, it would look like this:

user_id,full_name
U001,Alice Smith
U002,Bob Jones
U003,Carol Lee

Now, your Splunk search returns events that contain a field called "user_id" with values like "U002." Without a lookup, you only see the code. With a lookup, Splunk reads the CSV, finds "U002" in the first column, and adds the value "Bob Jones" into a new field called "full_name." Your event now shows both the user ID and the person's real name.

Why is this useful? Because machine data is often full of codes, IDs, and numbers that mean nothing to a human. A web server might log a status code "500" but your manager wants to see "Internal Server Error." A firewall might log a source IP like "10.0.0.45" but the security team needs to see "HR Database Server." Lookups bridge the gap between what machines log and what people understand.

The lookup file does not have to be a CSV. You can also use: a static lookup table stored on the Splunk server, a KV store (a key-value store inside Splunk that acts like a small database), a geospatial lookup that maps coordinates to location names, an external lookup that queries an external system such as an SQL database or an API. But for the SPLK-1003 exam, you mainly need to know about file-based CSV lookups and the KV store.

To configure a lookup, you follow these steps:

- Upload the lookup file (usually a CSV) to Splunk through Settings -> Lookups -> Lookup table files, or place it in the correct directory on the Splunk server.
- Define the lookup, which tells Splunk which file to use and which fields to match. This is done under Settings -> Lookups -> Lookup definitions. You give the lookup a name, point it to the file, and specify the matching field (for example, the "user_id" column in your file must be named exactly as the field appears in your events).
- Optionally, you can configure an automatic lookup that runs every time a search happens without the user typing anything extra. You do this under Settings -> Lookups -> Automatic lookups.
- Alternatively, you can use the lookup command in a search, like: | lookup employees.csv user_id OUTPUT full_name. This tells Splunk to run the lookup only during that search.

A key concept is the difference between an input field and an output field. The input field is the value in your search results that you want to match — for example, the "user_id" field. The output field is the new information you want to add — for example, the "full_name" field. In some configurations, you can also use an OUTPUTNEW option, which only adds the value if it doesn't already exist in the event.

Another important concept is the default lookup. If you configure a lookup as an automatic lookup, Splunk runs it on every search by default. This can slow searches down if the table is large, so it's wise to only enable automatic lookups for small tables. For larger tables, use the lookup command explicitly in your search.

Finally, learn the difference between a lookup and a subsearch. A subsearch runs a separate search and returns results that are then used by the main search. A lookup simply looks up a value in a pre-built table. Subsearches are slower and more complex. Lookups are fast and simple. For exam questions that ask you to enrich data with a static reference, the answer is always a lookup, not a subsearch.

## Real-world context

You work as a SOC (Security Operations Centre) analyst at a mid-sized company. Your job is to monitor firewall logs for suspicious activity. The firewall logs contain the source IP address of every connection attempt. Without enrichments, an entry might look like this: "2025-04-01 14:32:10, src_ip=203.0.113.45, dest_port=443, action=deny." You see an IP address, but you have no idea who or what that IP belongs to.

Your organisation maintains a CSV file called "asset_inventory.csv" with three columns: "ip_address," "hostname," and "department." The contents look like:

ip_address,hostname,department
203.0.113.45,web-server-01,IT
198.51.100.22,hr-database,HR
192.0.2.77,ceo-laptop,Executive

You upload this file to Splunk as a lookup table. Then you create a lookup definition called "asset_info" that maps the "ip_address" column to the "src_ip" field in your events. You configure it to output the "hostname" and "department" fields. Now, every time you run a search that includes the source IP, Splunk automatically enriches each event with the hostname and department of the device. A typical step-by-step would be:

- Step 1: Log into Splunk and go to Settings > Lookups > Lookup table files > Add New. Upload the "asset_inventory.csv" file.
- Step 2: Go to Settings > Lookups > Lookup definitions > Add New. Name it "asset_info." Select the CSV file you just uploaded. Set the input field as "src_ip" and the output fields as "hostname" and "department."
- Step 3: Go to Settings > Lookups > Automatic lookups > Add New. Choose a specific data source (e.g., any firewall sourcetype) and apply the "asset_info" lookup. This makes the enrichment automatic for all searches against that data.
- Step 4: Run a search like index=firewall | stats count by src_ip. The results now also show hostname and department for each IP.
- Step 5: You spot that the CEO's laptop is attempting connections to a known malicious domain. Because the lookup revealed the department, you escalate the incident immediately to the executive team.

Without the lookup, you would have had to manually cross-reference every IP against a spreadsheet — a tedious, error-prone process that could take hours. With the lookup, enrichment happens in milliseconds.

Another real-world use is in IT operations. Your monitoring system records error codes like "E1001." By creating a lookup that maps each code to a human-readable description—for example, "E1001 = Disk full on drive C:"—you can turn a cryptic log into an actionable alert in seconds.

The ability to write a search like:
index=windows_events EventCode=4625 | lookup account_lookup Account_Name OUTPUT Full_Name Department
and instantly see which employee's account is failing to log in is exactly why lookups are essential. For SPLK-1003, you must be able to configure all three stages: upload the file, define the lookup, and apply it in a search.

## Exam focus

The SPLK-1003 exam tests your ability to configure and use lookups in three main ways: multiple-choice questions about definitions and syntax, hands-on simulation questions where you must upload and define a lookup, and scenario-based questions where you choose the correct command to enrich results. Expect about 5 to 8 questions on lookups and KV store lookups combined.

Key exam topics you must know cold:

- The exact steps to upload a lookup table file: Navigate to Settings > Lookups > Lookup table files > Add new.
- The exact steps to define a lookup: Settings > Lookups > Lookup definitions > Add new. You must know the difference between a lookup table file and a lookup definition. A table file is the data (CSV). A definition is the configuration that tells Splunk how to use that file.
- The difference between OUTPUT and OUTPUTNEW. OUTPUT always overwrites any existing field with the same name. OUTPUTNEW only adds the field if it does not already exist.
- The difference between an automatic lookup and an explicit lookup command. Automatic lookups run on every search against the specified source type. Explicit lookups are run only when you type | lookup in a search.
- The syntax of the lookup command: | lookup <lookup_name> <input_field> OUTPUT <output_field>.
- The concept of a default lookup and that it applies automatically to all searches.
- The KV store: a specialised type of lookup that is stored in memory and can be updated by search commands. It is useful for dynamic data.

Common traps the exam sets:

- They give you a scenario where you need to enrich data but also deduplicate it. They might ask which command comes first — always do the enrichment first, then deduplicate, otherwise you lose the enriched data.
- They ask you to choose between a lookup and a subsearch. If the reference data is static and small, a lookup is correct. If you need to run a separate query on the same data, a subsearch is needed.
- They specify a field name that does not match between the CSV column and the event field. You must select the answer that maps the CSV column name to the event field name correctly, or rename the column in the CSV.
- They test whether you know that a lookup can return multiple output fields from a single input match.
- They test whether you know that automatic lookups can degrade performance, so for large lookups you should use the lookup command instead.

To pass, memorise the settings path exactly: Settings > Lookups > Lookup table files (to upload) and Settings > Lookups > Lookup definitions (to configure). Know the difference between a lookup table file, a lookup definition, and an automatic lookup. Practise writing the | lookup command in your head: the pipe, the word lookup, the lookup name, the input field, the word OUTPUT, and the output fields. This pattern appears in at least one exam question.

## Step by step

1. **Upload the lookup table file** — Go to Settings > Lookups > Lookup table files and click 'Add new'. Upload a CSV file that contains your reference data. The file must have a header row with column names. This file is now stored on the Splunk server. Without this step, Splunk has no data to look up.
2. **Create a lookup definition** — Go to Settings > Lookups > Lookup definitions and click 'Add new'. Give the definition a name (e.g., 'user_info'). Select the file you just uploaded. Set the input field as the field from your events you want to match (e.g., 'user_id'), and the output fields as the columns from the file you want to add (e.g., 'full_name'). This step tells Splunk how to use the file.
3. **Apply the lookup automatically (optional)** — Go to Settings > Lookups > Automatic lookups and click 'Add new'. Choose the source type or host for which the lookup should automatically run. Select the lookup definition you created. Now, every search against that data will automatically include the enrichment. Only do this for small files to avoid performance issues.
4. **Use the lookup in a search command** — In your search, after the initial search terms, add a pipe and the lookup command. Example: | lookup user_info user_id OUTPUT full_name. This runs the lookup only for that specific search. This is the most common method for larger lookups and gives you full control.
5. **Verify the enrichment** — Run a search that includes the output fields. For example: index=main | lookup user_info user_id OUTPUT full_name | table user_id full_name. Check that the new fields appear correctly. If not, verify that the field names match exactly, including case sensitivity, and that the input field exists in your events.

## Comparisons

### Lookup vs Subsearch

**Lookup:**
- Uses a pre-built static table on disk or in memory.
- Runs quickly — microseconds per match.
- Best for enriching with reference data that does not change often.

**Subsearch:**
- Runs a separate full search inside the main search.
- Slower — can take seconds or minutes depending on the data volume.
- Best for querying the same data source for related events.

### CSV Lookup vs KV Store Lookup

**CSV Lookup:**
- Data is static — cannot be changed from inside a search.
- Requires you to upload a new file to update the data.
- Simplicity: just a CSV file with headers.

**KV Store Lookup:**
- Data is dynamic — can be edited by search commands like outputlookup.
- Automatically persists changes without manual re-uploads.
- Supported by collection-based features and built-in APIs.

### Automatic Lookup vs Explicit Lookup Command

**Automatic Lookup:**
- Runs on every search against the configured source type.
- Can slow down all searches if the lookup table is large.
- Configured once in Settings and forgotten.

**Explicit Lookup Command:**
- Runs only when you type | lookup in the search.
- Gives you control over which searches use the lookup.
- Preferred for large lookup tables to avoid performance issues.

### OUTPUT in Lookup vs OUTPUTNEW in Lookup

**OUTPUT in Lookup:**
- Overwrites any existing field with the same output name.
- Use when you want to replace stale data.
- Commonly used in standard enrichment scenarios.

**OUTPUTNEW in Lookup:**
- Only adds the field if no field with that name exists.
- Preserves original values that may be more recent.
- Commonly used to avoid overwriting manually entered data.

## Diagram

_How a lookup enriches a single search result by matching a field against a CSV file and adding new fields._

```mermaid
flowchart TD
    A[Search Results] --> B[Has field: user_id = U002]
    B --> C[Lookup Command or Automatic Lookup]
    C --> D[Lookup Definition points to CSV file]
    D --> E[CSV file: user_id,full_name,department]
    E --> F[Match on user_id = U002]
    F --> G[Output: full_name = Bob Jones, department = Sales]
    G --> H[Enriched Search Result]
```

## Common misconceptions

- **Misconception:** A lookup automatically adds fields to every search result without any configuration beyond uploading the file. **Reality:** After uploading a lookup table file, you must create a lookup definition and then either apply it as an automatic lookup or use the lookup command in your search. (Beginners see 'upload file' and assume it's like a database import that instantly works everywhere. They miss the configuration steps needed to tell Splunk which field to match and what to return.)
- **Misconception:** The lookup file must have the same column names as the fields in your events, or Splunk won't match them. **Reality:** The column names in the lookup file can be different from the event field names, as long as you correctly map them when you define the lookup definition or specify them in the lookup command. (New users naturally assume the names must match because that's how most 'match' functions work in everyday software. Splunk's flexibility with field mapping is not obvious from the user interface.)
- **Misconception:** You cannot use a lookup to add data if the lookup file has more than one matching row for the same input value. **Reality:** If the lookup file has duplicate input values, Splunk will return only the first matching row it finds. You can control this by deduplicating the file beforehand or using KV store where you can update the data. (People expect a lookup to behave like a database with unique keys, but a CSV file can have duplicates. Splunk does not warn you about duplicates — it just silently returns the first match.)
- **Misconception:** Once you set up an automatic lookup, it applies to all searches in all indexes. **Reality:** An automatic lookup can be restricted to specific source types, hosts, or indexes. By default, it applies to the selected source type only, not globally. (The word 'automatic' suggests it works everywhere. Beginners overlook the configuration step where you choose which data the lookup applies to.)
- **Misconception:** A KV store lookup works exactly the same as a CSV lookup, just stored differently. **Reality:** A KV store lookup is dynamic — data can be added, updated, or deleted by Splunk search commands. A CSV lookup is static and cannot be modified from within a search without re-uploading the file. (‘Key-value store’ sounds similar to ‘lookup table’, so beginners assume they are interchangeable. They miss that KV store is writable and ideal for data that changes frequently.)
- **Misconception:** The lookup command must be the first command in a search pipeline. **Reality:** You can place the lookup command anywhere in the pipeline after the initial search, as long as the input field is already present in the results at that point in the search. (New users often think of lookups as a step that happens before any other filtering, but the lookup command only needs the input field to exist — which field might come from an earlier eval or rex command.)

## Key takeaways

- A lookup enriches your search results by matching a field in your data against a reference table and adding new fields from that table.
- The three steps to use a lookup are: upload the lookup table file, create a lookup definition, and either apply it automatically or use the lookup command.
- The lookup command syntax is: | lookup <lookup_name> <input_field> OUTPUT <output_field>.
- OUTPUT overwrites an existing field of the same name; OUTPUTNEW only adds the field if it does not already exist.
- Automatic lookups apply to every search against the configured source type, but they can slow down performance if the lookup table is large.
- A KV store lookup differs from a CSV lookup because a KV store can be updated dynamically by search commands, while a CSV is static.
- The lookup must be defined before you can use it; uploading the file alone is insufficient.
- When using the lookup command, the input field must already exist in the search results at the point the command runs.

## FAQ

**What is the difference between a lookup table file and a lookup definition?**

The lookup table file is the actual data (like a CSV file) stored on the Splunk server. The lookup definition is the configuration that tells Splunk which file to use, which fields to match, and what to output. You need both.

**Can I use a lookup to add more than one field?**

Yes. You can list multiple output fields in the lookup definition or in the lookup command, separated by spaces. For example: | lookup employees.csv user_id OUTPUT first_name last_name department.

**What happens if the lookup file has multiple rows with the same input value?**

Splunk will return only the first matching row it encounters. To avoid unexpected results, either deduplicate your lookup file or use a data source that guarantees unique values for the input field.

**How do I update a CSV lookup without re-uploading it?**

You cannot update a CSV lookup dynamically; you must upload a new version of the file. If you need to update data frequently, use a KV store lookup instead, which supports write operations from within Splunk searches.

**Can I use a lookup with a field from a subsearch?**

Yes, but the field must be present in the main search results at the point where the lookup command runs. You can pipe the subsearch results into the main pipeline and then apply the lookup.

**What does OUTPUTNEW do that OUTPUT does not?**

OUTPUT overwrites any existing field with the same name in the event. OUTPUTNEW only adds the field if it is not already present, preserving the original value if it exists.

## Check your understanding

1. **What is the correct order of steps to configure a file-based CSV lookup in Splunk?**

   Answer: Upload the lookup table file, then create a lookup definition, then optionally create an automatic lookup.

2. **When using the | lookup command, what keyword do you use to add fields that replace existing fields of the same name?**

   Answer: OUTPUT overwrites existing fields; use OUTPUTNEW to only add fields that do not already exist.

3. **If your lookup file contains duplicate input values, how does Splunk handle them?**

   Answer: Splunk returns only the first matching row from the lookup file.

4. **What is the main advantage of a KV store lookup over a CSV lookup?**

   Answer: A KV store lookup can be updated dynamically by search commands, while a CSV lookup is static.

5. **What is a common pitfall of using automatic lookups with large lookup tables?**

   Answer: They can slow down all searches because they run on every search against the configured source type.

---

Interactive version with quiz and diagrams: https://courseiva.com/learn/splunk-core-certified-power-user/lookups-introduction-and-configuration