Lookups do for IT data what a recipe conversion card does for baking ingredients: they translate cryptic codes and numbers into names and descriptions humans understand. For the SPLK-1002 exam, understanding lookups is essential because they are one of the most common ways to enrich raw machine data with context, making searches far more useful and reports far clearer.
Jump to a section
A simple way to picture Lookups: Basics and Creation
You have a handwritten recipe card for your grandmother's famous chocolate cake, but it's a mess. It says '1 stick of butter' and '1 cup of flour' and '1 teaspoon of baking soda.' Now imagine your friend hands you a different recipe card that says '113 grams of butter,' '120 grams of flour,' and '5 grams of baking soda.' These two cards describe different numbers for the same ingredients. When you bake, you need to convert the numbers from one system to the other. So you buy a small plastic 'conversion card' that lists every ingredient on one side in 'stick/cup/teaspoon' amounts and on the other side in 'grams' amounts. Every time you look at your grandmother's card, you slide the conversion card next to it. Against '1 stick of butter,' the conversion card shows '113 g — use 113 g.' Against '1 cup of flour,' it shows '120 g — use 120 g.' You never change the original card; you just overlay the conversion card to translate those raw numbers into meaningful values your digital scale understands.
In IT, your 'grandmother's card' is raw machine data (e.g., user IDs like '1003'). Your 'digital scale' is a Splunk search that needs human-readable information (e.g., employee names). A 'lookup' is the conversion card: a separate file or table that maps raw codes to meaningful labels without altering the original data. You load the lookup, and Splunk automatically translates each code into its descriptive equivalent during a search.
A lookup is a static table — like a spreadsheet or a CSV file — that you load into Splunk to add extra information to your search results. Think of it as a reference book. When your raw data contains a short code (for example, a three-digit department ID like '101'), you can use a lookup to replace that code with the full department name ('Marketing'). This process is called 'enrichment.' Enrichment means giving your data more meaning without changing the original events.
Why does enrichment matter? Raw machine data is often compact and cryptic. Servers log user IDs, IP addresses, and status codes because those are efficient for machines. But humans need names, locations, and descriptions. Without lookups, you would have to memorise every code or manually cross-reference a list. With lookups, Splunk does the translating automatically during a search.
Every lookup has two essential parts: the lookup table (the data file itself) and the lookup definition (the rule that tells Splunk which fields to match and which to add). The lookup table is typically a CSV file containing at least two columns: one column that matches a field in your search data (the 'match' or 'key' field) and one or more columns containing the new information you want to bring in (the 'output' fields). For example, a CSV file could have columns 'user_id' (the key) and 'full_name' and 'email' (the outputs).
To use a lookup, you first upload the CSV file into Splunk (or create a KV Store lookup, which is a lookup stored in a database table inside Splunk). Then you create a lookup definition: you specify the CSV file, name the lookup, and tell Splunk which field(s) in the file should match fields in your events. Optionally, you can set the lookup to 'automatic' — meaning it runs on every search that involves the matching field — or you can call it manually in a search command like | lookup username_lookup user_id OUTPUT full_name.
There are three main types of lookups in Splunk:
File-based lookups: these are CSV files or other static files stored on the Splunk server. They are simple to create and ideal for reference data that does not change often, like a list of office locations.
KV Store lookups: these are stored in a built-in database called the Key-Value Store. Unlike a CSV file, a KV Store lookup can be updated dynamically by Splunk itself (for example, by a search that adds new entries from incoming data). KV Store lookups are good for data that changes frequently, such as a list of active user sessions.
External lookups: these connect Splunk to an external system (like a database or an API) to fetch real-time data. External lookups are more complex and are rarely tested on the SPLK-1002 exam.
When you create a lookup, you must consider the 'match type.' The default match type is EXACT, meaning Splunk will only match if the key field in the event exactly equals the key field in the lookup table. There is also WILDCARD matching, where you can use asterisks (*) to match partial strings. For example, you could match 'john.*' to find all variations of a username prefix.
A critical concept to understand is the 'default' field for lookups. If a lookup has no match for a given value in the event (for example, a user ID that does not exist in the lookup table), Splunk returns no additional fields for that event by default. You can change this behaviour using the | lookup command's DEFAULT option to supply a fallback value.
Finally, be aware of lookup performance. Every lookup adds processing time to your search. If you have a very large lookup table (millions of rows), Splunk may need to use memory to cache it, which can slow down your searches. For the exam, you should know that file-based lookups are cached in memory by default, but you can change caching settings.
Prepare the data file
Create a CSV file with column headers that exactly match the field names in your Splunk events. For example, if your events have a field called 'user_id', your CSV must have a column called 'user_id' (case-sensitive). Save the file with a .csv extension.
Upload the CSV as a lookup table file
In Splunk Web, go to Settings -> Lookups -> Lookup table files -> New. Click 'Choose File' and select your CSV. Give the file a name (usually the same as the filename). This step makes the data available to Splunk but does not yet create a usable lookup.
Create the lookup definition
Go to Settings -> Lookups -> Lookup definitions -> New. Choose 'File-based' as the type. Select the uploaded CSV file from the dropdown. Name your lookup (e.g., 'user_lookup'). Specify which field in the CSV is the match field (the key) and which fields are output fields. Save the definition.
Test the lookup with a manual search
Run a simple search that includes the match field, e.g., `index=main | lookup user_lookup user_id OUTPUT full_name, email`. Check that events now contain the new fields. If they do not, verify the field name spelling and that the CSV file is correctly formatted.
Optionally configure an automatic lookup
If you want the lookup to run on every search that uses the match field, go to Settings -> Lookups -> Automatic lookups -> New. Select the lookup definition and the field that triggers it. Be cautious: automatic lookups run on all relevant searches, which can slow performance.
Maintain and update the lookup data
If the source data changes (e.g., new employees are added), upload a new version of the CSV file with the same filename and header structure. Splunk automatically uses the new file for future searches. For KV Store lookups, you can update data using Splunk searches.
Consider a real IT helpdesk scenario at a medium-sized company called 'GlobalMart.' GlobalMart has 10,000 employees, each with a numeric employee ID (e.g., 'EID-45321'). Whenever an employee calls the helpdesk, the ticketing system records only the employee ID. The IT team wants to see, in Splunk, who called most often and from which department, so they can identify if a specific team is having recurring issues.
Here is how they use a lookup:
First, the IT team creates a CSV file called 'employee_directory.csv' that contains three columns: 'employee_id', 'full_name', and 'department'. They obtain this file from the HR system. They upload the CSV to Splunk by going to Settings -> Lookups -> Lookup table files -> New. They give it the name 'employee_directory.csv' and point it to the uploaded file.
Second, they create a lookup definition: Settings -> Lookups -> Lookup definitions -> New. They name it 'employee_lookup', select 'File-based' as the type, and choose the uploaded CSV file. They specify that the field to match is 'employee_id' (the field in the search events) and that Splunk should output the 'full_name' and 'department' fields from the CSV.
Third, they test the lookup manually. They run a search over the helpdesk ticket data:
index=helpdesk_tickets | lookup employee_lookup employee_id OUTPUT full_name, department | stats count by full_name, department
Now Splunk automatically translates every 'employee_id' in the raw tickets into a 'full_name' and a 'department.' The helpdesk team can instantly see that 'Jane Smith' from 'Finance' has called 47 times in the last month, which suggests a problem with the accounting software. Without the lookup, they would see only a list of numeric IDs like 'EID-45321' and have no idea who those employees were.
This simple enrichment has practical business value: the IT manager can prioritise fixing the accounting software instead of asking 'Who is EID-45321?' every time. The lookup also saves time because the CSV file can be updated weekly when HR adds new employees — the lookup always uses the latest file, so no manual changes are needed in Splunk queries.
Beyond helpdesk tickets, lookups are used for:
Enriching firewall logs: mapping IP addresses to geographic locations or hostnames.
Enriching web server logs: matching short product codes to full product names and prices.
Enriching system event codes: translating numeric Windows Event IDs (like '4624') into descriptive text ('Successful logon').
In every case, the lookup acts as a bridge between machine-oriented data and human understanding. The IT professional's job becomes simpler: they no longer need to remember codes or create complex search-time calculations to decode values. They create the lookup once, and every search thereafter automatically benefits from the enrichment.
The SPLK-1002 exam tests lookups in a very specific and predictable way. Expect 3–5 questions related to lookups, split roughly evenly between theory and hands-on commands.
What they test:
- The purpose of a lookup: You will see questions like 'Which of the following best describes the purpose of a lookup in Splunk?' The correct answer will say 'to enrich events with additional fields from an external source.' Traps include answers about 'changing fields in raw events' (which is incorrect) or 'filtering events' (lookups do not filter; they add fields).
- How to create a lookup: You will be asked to identify the correct sequence of steps: first upload the CSV as a lookup table file, then create the lookup definition. A common trap reverses these steps. Memorise the order: table file first, definition second.
- Lookup command syntax: They will ask you to complete a search command. For example:
... | lookup employee_lookup employee_id OUTPUT full_name
The trap is that sometimes they omit the OUTPUT clause, expecting you to know that OUTPUT is optional but specific. Another trap is using OUTPUTNEW (which only populates if the field does not already exist) versus OUTPUT (which overwrites existing values). You must know the difference.
- Match types: EXACT vs WILDCARD. They will describe a scenario (e.g., matching IP addresses with subnet wildcards) and ask which match type to use. The answer is usually WILDCARD for partial matches.
- Automatic lookups: You must know that you can configure a lookup to run automatically on all searches that involve a specific field. The trap is that automatic lookups can slow down searches because they run even when not needed.
- Lookup types: You must distinguish between file-based, KV Store, and external. File-based is the most tested. KV Store appears once or twice, typically in questions about dynamic updates. External lookups are rarely tested.
Common traps:
- 'Lookups modify raw events.' False. Lookups add fields to search results only; the original data in the index remains untouched.
- 'A lookup definition is the same as a lookup table file.' False. A definition is a configuration that references a table file.
- 'The order of columns in the CSV does not matter.' False. The column headers must exactly match the field names you use in the lookup definition.
- 'You can use a lookup to replace field values in the raw data.' False. Lookups do not replace; they append. To replace, you would need to use the | lookup ... | eval command combination.
Key definitions to memorise: - Lookup table file: the actual CSV or data file containing the mapping. - Lookup definition: the configuration that tells Splunk which file to use and how to match fields. - Automatic lookup: a lookup that runs on every search involving a specific field without being called explicitly. - KV Store lookup: a lookup stored in a database that can be updated by searches. - Match field: the field in the lookup table that corresponds to a field in the events. - Output field: a field from the lookup table that is added to events.
A lookup enriches search results by adding extra fields from an external data source without changing raw events.
The two-step creation process is: first upload the CSV file as a lookup table file, then create a lookup definition referencing that file.
Use the `| lookup` command in a search to manually apply a lookup, specifying the lookup name, match field, and output fields.
EXACT matching requires the field value to be identical; WILDCARD matching allows partial strings using asterisks.
Automatic lookups run on every search involving a designated field but can slow down performance.
KV Store lookups can be updated dynamically by Splunk searches, making them ideal for frequently changing data.
The `OUTPUT` clause overrides an existing field, while `OUTPUTNEW` only populates if the field does not already exist.
These come up on the exam all the time. Here's how to tell them apart.
Lookup Table File
The actual data file (e.g., CSV) containing rows of information.
Uploaded separately under Settings > Lookups > Lookup table files.
Exists independently of any definition and can be reused in multiple definitions.
Lookup Definition
A configuration that tells Splunk how to use the table file.
Created under Settings > Lookups > Lookup definitions.
Includes match fields, output fields, and a reference to the table file.
File-based Lookup
Data is stored in a static CSV file on the Splunk server.
Cannot be updated by searches; must replace the file manually.
Best for reference data that changes infrequently.
KV Store Lookup
Data is stored in Splunk's built-in database (Key-Value Store).
Can be updated dynamically using Splunk search commands like `| outputlookup`.
Ideal for data that changes frequently or needs to be modified by searches.
OUTPUT
Overwrites any existing field in the event with the lookup value.
Syntax: `OUTPUT field1`
Use when you want to replace current values with lookup data.
OUTPUTNEW
Only populates the field if it does NOT already exist in the event.
Syntax: `OUTPUTNEW field1`
Use when you want to preserve existing values and only add missing ones.
EXACT Matching
Requires the field value to be an exact match to a lookup key.
Default match type; no special configuration needed.
Fastest in performance because it does not need pattern evaluation.
WILDCARD Matching
Allows partial matches using asterisks (*) as wildcards.
Configured by selecting 'WILDCARD' in the lookup definition.
Slower than EXACT matching because it evaluates patterns.
Manual Lookup
Must be called explicitly in a search via `| lookup` command.
Does not run unless the search includes the lookup command.
Gives the user full control over when the lookup is applied.
Automatic Lookup
Runs automatically on every search that involves the specified field.
Configured once under Settings > Lookups > Automatic lookups.
Can impact search performance because it runs even when not needed.
Mistake
A lookup permanently changes the raw machine data stored in Splunk.
Correct
Lookups only add information to the results of a search. The raw events in the index remain untouched and unchanged.
Beginners confuse 'search-time field extraction' with 'index-time field modification.' Splunk never alters raw data at index time; all lookups operate at search time.
Mistake
Creating a lookup definition is the same as uploading the CSV file.
Correct
Uploading the CSV file is only step one. After the file is uploaded, you must create a separate lookup definition that tells Splunk how to use that file, including which fields to match and which to output.
The interface has two separate menus (Lookup table files and Lookup definitions). Many learners miss the second step because they think the file alone is sufficient.
Mistake
Lookups can be used to filter out events from search results.
Correct
Lookups only add fields to existing events. They do not remove events. To filter events, you use commands like `search` or `where` or `| spath`.
The word 'lookup' implies 'looking something up,' which sounds like you can 'look up and then exclude.' This is a mental model mismatch.
Mistake
If a value in the event does not exist in the lookup table, Splunk will create a default value automatically.
Correct
By default, Splunk returns no additional fields for unmatched values. You must explicitly use the `DEFAULT` option in the lookup command to supply a fallback value.
Many beginners assume Splunk is 'smart' enough to handle missing data gracefully, but it is explicit by design.
Mistake
Lookups only work with CSV files.
Correct
While CSV file-based lookups are the most common, Splunk also supports KV Store lookups (dynamic database tables) and external lookups (API or database connections).
CSVs are the default example in documentation and training, leading learners to think they are the only option.
Mistake
The order of columns in the CSV file matters for the lookup to work.
Correct
The column headers (field names) must match exactly, but the physical order of columns does not matter. Splunk reads the headers to know which field is which.
People familiar with Excel workflows often think position is important, but Splunk uses header names.
Reveal each answer, then mark whether you got it right. Score 60%+ to unlock the next chapter.
A lookup table file is the actual data source (e.g., a CSV file). A lookup definition is a configuration that tells Splunk which file to use and how to match fields. You need both.
No. Lookups only add fields to the search results; they never modify the raw events stored in Splunk. The original data remains unchanged.
By default, if a value in your event does not match any row in the lookup table, Splunk returns no new fields for that event. You can use the `DEFAULT` option in the lookup command to supply a fallback value.
A KV Store lookup stores data in Splunk's built-in database and can be updated dynamically by searches. Use it when your reference data changes frequently and you need Splunk to automatically add or modify entries.
Yes. In the lookup definition, you can specify multiple match fields. Splunk will only add the output fields when all match conditions are satisfied simultaneously.
No. Splunk reads the column headers (field names) to determine which data is which. The physical order of columns is irrelevant as long as the headers match the expected field names.
OUTPUT overwrites an existing field in an event with the lookup value. OUTPUTNEW only populates the field if it does not already exist in the event; otherwise, the existing value is kept.
You've finished Lookups: Basics and Creation. Continue through the SPLK-1002 study guide to build a complete picture of the exam.
Done with this chapter?