Splunk® Enterprise

Search Tutorial

Acrobat logo Download manual as PDF

Splunk Enterprise version 6.x is no longer supported as of October 23, 2019. See the Splunk Software Support Policy for details. For information about upgrading to a supported version, see How to upgrade Splunk Enterprise.
This documentation does not apply to the most recent version of Splunk. Click here for the latest version.
Acrobat logo Download topic as PDF

Use field lookups

This topic takes you through using field lookups to add new fields to your events. Field lookups let you reference fields in an external CSV file that match fields in your event data. Using this match, you can enrich your event data by adding more meaningful information and searchable fields to each event.

Download and uncompress the following file:

Important: To complete the rest of the tutorial, you have to follow the procedures in this topic. If you do not configure the field lookup, the searches in the following topics will not produce the correct results.

Find the Lookups manager

1. In the Splunk bar, on the upper right, click Settings.

2. Under Knowledge, click Lookups.

6.2tutorial settings lookups.png

This opens the Lookups editor where you can create new lookups or edit existing ones.

6.1 tutorial lookupsmanager.png

You can view and edit existing lookups by clicking on the links in the table for Lookup table files, Lookup definitions, and Automatic lookups.

Upload the lookup table file

1. In the Lookups manager under "Actions" for Lookup table files, click Add new.

This takes you to the Add new' lookup table files view where you upload CSV files to use in your definitions for field lookups.

6.1 tutorial addnewlookuptable.png

2. To save your lookup table file in the Search app, leave the Destination app as search.

3. Under Upload a lookup file, browse for the CSV file (prices.csv) to upload.

4. Under Destination filename, name the file prices.csv.

This is the name you use to refer to the file in a lookup definition.

5. Click Save.

This uploads your lookup file to the Search app and returns to the lookup table files list.

6.1 tutorial lookuptablefiles.png

Note: If Splunk does not recognize or cannot upload the file, check that it was uncompressed before you attempt to upload it again.

Share the lookup table file globally

If the lookup file is not shared, you can not select it when you define the lookup.

1. Go to the Lookup table files list.

2. Under Sharing for the prices.csv lookup table's Path, click Permissions.

This opens the Permission dialog box for the prices.csv lookup file.

3. Under Object should appear in, select All apps.

6.1 tutorial lookuptablepermissions.png

4. Click Save.

6.1 tutorial lookuptableglobal.png

Now, the lookup table should be shared with Global permissions.

Add the field lookup definition

1. Return to the Lookups manager.

2. Under Actions for Lookup definitions, click Add New.

This takes you to the Add new lookups definitions view where you define your field lookup.

6.1 tutorial newlookupdefinition.png

3. There is no need to change the Destination app. It is already set to search, referring to the Search app.

4. Name your lookup prices_lookup.

5. Under Type, select File-based.

File-based lookups add fields from a static table, usually a CSV file.

6. Under Lookup file, select prices.csv (the name of your lookup table).

7. Keep Configure time-based lookup and Advanced options unselected.

8. Click Save.

This defines prices_lookup as a file-based lookup.

6.2tutorial lookupdefinitionsaved.png

Share the lookup definition with all apps

1. Return to the Lookup definitions list.

2. Under Sharing for prices_lookup, click Permissions.

The Permission dialog box for the prices.lookup opens.

3. Under Object should appear in, select All apps.

6.1 tutorial lookupdefinitionspermissions.png

4. Click Save.

The prices_lookup definition has Global permissions.

Now you can use this field lookup to add information from the lookup table file to your events. You use the field lookup by specifying the lookup command in a search string.

Make the lookup automatic

1. In the Lookups manager, under Actions for Automatic lookups, click Add New.

This takes you to the Add New automatic lookups view where you configure the lookup to run automatically.

6.1 tutorial newautomaticlookups.png

2. Leave the Destination app as search.

3. Name your automatic lookup price_lookup.

4. Under Lookup table, select prices_lookup.

6.1 tutorial automaticlookup namefile.png

5. Under Apply to and named, select sourcetype and type in access_combined_wcookie.

6.1 tutorial automaticlookup sourcetype.png

6. Under Lookup input fields type in productId in both text areas under Lookup input fields.

6.1 tutorial lookupinputfields.png

Splunk Enterprise matches the field in the lookup table (which is the one specified on the left) with the field on the right (which is the field in your events). In this case the field names match.

7. Under Lookup output fields, type in the name of the fields that you want to add to your event data based on the input field matching and rename the fields.

6.1 tutorial lookupoutputfields.png

7.1 In the first text area, type product_name. This is the field in the prices.csv file that contains the descriptive name for each productId .

7.2. In the second text area, after the equal sign, type productName. This renames the field to productName.

7.3. Click Add another field to add another field after the first one.

7.4. Add the field price. This is the field in the prices.csv file that contains the price for each productId. Do not rename this field. Type price in the second text area.

8. Leave Overwrite field values unchecked.

9. Click Save.

This returns you to the list of automatic lookups and you should see your configured lookup.

6.1 tutorial automaticlookupssaved.png

Show the new fields in your search results

1. Click Search in the app menu to return to the Search view.

2. Run the search for web access activity.


3. Scroll through the list of Interesting Fields in the fields sidebar, and find the price field.

4. Click price to open its field summary dialog box.

6.1 tutorial price fieldsummary.png

5. Next to Selected, click Yes.

6. Close the dialog box.

The price field appears under Selected Fields in the fields sidebar.

6. Repeat Steps 3 to 5 for the productName field.

6.1 tutorial selected lookupfields.png

Search with the new lookup fields

1. Copy and paste or type in the previous subsearch example to see what the VIP customer bought. This time, replace the productId field with productName.

sourcetype=access_* status=200 action=purchase [search sourcetype=access_* status=200 action=purchase | top limit=1 clientip | table clientip] | stats count AS "Total Purchased", dc(productId) AS "Total Products", values(productName) AS "Product Names" by clientip | rename clientip AS "VIP Customer"

The result is the same as in the previous subsearch example, except that the VIP customer's purchases are more meaningful with the added descriptive product names.

6.2tutorial lookup subsearch.png

The next section takes you through saving this search as a report called "VIP Customer".

Next steps

As you run more searches, you want to be able to save to reuse or share them with other people. Go to "About saving and sharing reports" to learn about saving and sharing reports.

Last modified on 07 March, 2016
Use a subsearch
About saving and sharing reports

This documentation applies to the following versions of Splunk® Enterprise: 6.3.0, 6.3.1, 6.3.2, 6.3.3, 6.3.4, 6.3.5, 6.3.6, 6.3.7, 6.3.8, 6.3.9, 6.3.10, 6.3.11, 6.3.12, 6.3.13, 6.3.14

Was this documentation topic helpful?

You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters