Splunk® Enterprise

Search Tutorial

Splunk Enterprise version 7.2 is no longer supported as of April 30, 2021. 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® Enterprise. For documentation on the most recent version, go to the latest release.

Enabling field lookups

The events used in this tutorial data contain fields with the product codes and product IDs. Those codes and IDs do not tell you much about the products themselves, such as the product names. Being able to display the actual product names in reports and dashboards is useful to anyone who reads those reports or dashboards. That is where lookup files come in.

Lookup files contain data that does not change very often. This can include information about customers, products, employees, equipment, and so forth. For this tutorial, you will use a CSV lookup file that contains product IDs, product names, regular prices, sales prices, and product codes.

There are five key steps to enabling field lookups:

  1. Upload the lookup file
  2. Share the uploaded file with the applications
  3. Create a lookup definition
  4. Share the lookup definition with the applications
  5. Optional. Make the lookup definition automatic

The remaining Parts in this tutorial depend on you completing the steps in this section.
If you do not configure the field lookups, the searches will not produce the correct results.

Download and uncompress the tutorial lookup file

With the tutorial lookup file, you can match the codes or IDs in the Buttercup Games store events with the codes or IDs in a lookup file. This matching is referred to as field lookups. After the field lookups are configured, you can add any of the fields from the lookup file to your searches. The lookup files are sometimes referred to as lookup tables or lookup table files.

  1. Download the Prices.csv.zip file.
  2. Uncompress the Prices.csv.zip file. There is only one file in the ZIP file, prices.csv.
The prices.csv file contains the product names, price, and code. For example:
productId product_name price sale_price Code
DB-SG-G01 Mediocre Kingdoms 24.99 19.99 A
DC-SG-G02 Dream Crusher 39.99 24.99 B
FS-SG-G03 Final Sequel 24.99 16.99 C
WC-SH-G04 World of Cheese 24.99 19.99 D

Find the Lookups manager

  1. In the Splunk bar, click Settings.
  2. In the Knowledge section, click Lookups.

    This image shows the Settings drop-down. The Lookups option is circled.

    The Lookups manager opens, where you can create new lookups or edit existing lookups.

    This image shows the Lookups manager page.


You can view and edit existing lookups by clicking on the links in the Lookups manager. In the next few sections of this tutorial, you will upload a lookup table file, create a lookup definition, and create an automatic lookup.

Upload the lookup table file

To use a lookup table file, you must upload the file to your Splunk platform.

  1. In the Lookups manager, locate Lookup table files and click Add new.
    You use the Add new view to upload the CSV file that you want to as a lookup table.

    This image shows the Add new view with the prices.csv file specified as the file to upload and the destination name.

  2. The Destination app field specifies which app you want to upload the lookup table file to. To upload the file in the Search app, you do not need to change anything. The default value is search.
  3. Under Upload a lookup file, click Choose File and browse for the prices.csv file.
  4. Under Destination filename, type prices.csv.
    This is the name that you will use when you create a lookup definition.
  5. Click Save.
    This uploads your lookup file to the Search app and displays the lookup table files list.

If the Splunk software does not recognize or cannot upload the file, you can take the following actions.

  • Check that the file is uncompressed.
  • If an error message indicates that the file does not have line breaks, the file has become corrupted. This can happen if the file is opened in Microsoft Excel before it is uploaded. You should delete the Prices.csv.zip and prices.csv files. Then download the ZIP file again, and uncompress the file.

The image shows that the prices.csv file was uploaded successfully.

The other lookup table files in the list are included with the Splunk software.

Share the lookup table file

When you upload a lookup table file, the default sharing setting is Private. To use the file with other applications or with specific roles, you need to change the permissions to the file. For this tutorial, you are going to share the lookup table file with all applications.

  1. In the Lookup table files list, locate the prices.csv file at the bottom of the Path list.
  2. In the Sharing column, notice that prices.csv is listed as Private.
  3. To share the lookup table file, click Permissions.
  4. In the Permissions dialog box, under Object should appear in, select All apps.

    This image shows the upper part of the Permissions dialog box with the "All apps" radio button selected.

  5. Click Save.
    The Sharing setting for the prices.csv lookup table is set to Global.

    This image shows the list of lookups in the Lookup table file dialog box. For the prices.csv lookup, the Global value In the Sharing column is circled.

Add the field lookup definition

It is not sufficient to share the lookup table file with an application. You must define the information in the lookup table file and how that information relates to the fields in your events. This is called a lookup definition.

  1. In the Lookup table file dialog box, select Lookups in the breadcrumbs to return to the Lookups manager.

    This image shows the Lookup table file dialog box. There is a circle around the first link in the breadcrumbs "Lookups". You can also open the Lookups manager from the Settings menu and selecting "Lookups".

  2. For Lookup definitions, click Add New.
    The Add new lookups definitions page opens, where you define the field lookup.
  3. There is no need to change the Destination app setting. It is already set to search, referring to the Search app.
  4. For Name, type prices_lookup.
  5. For Type, select File-based.
    A file-based lookup is typically a static table, such as a CSV file.
  6. For Lookup file, select prices.csv, which is the name of the lookup table file that you created.

    This image shows the Add new page.

  7. Leave the check boxes for Configure time-based lookup and Advanced options unchecked.
  8. Click Save.
    The prices_lookup is now defined as a file-based lookup.

    This image shows the Lookup Definitions page. There are several pre-defined built in lookup definitions. The prices_lookup is at the bottom of the list.

    Notice the Supported fields column in the Lookup Definitions page. The Splunk software automatically interprets the first row in a CSV lookup table file as the field names, or column headings, for the lookup table.

Share the lookup definition with all apps

Now that you have created the lookup definition, you need to specify in which apps you want to use the lookup table.

  1. In the Lookup definitions list, for the prices_lookup, click Permissions.
  2. In the Permissions dialog box, under Object should appear in, select All apps.

    This image shows the Permissions page with "All apps" selected.

  3. Click Save.
    In the Lookup definitions page, prices_lookup now has Global permissions.

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. Or, you can set the field lookup to run automatically.

Make the lookup automatic

Instead of using the lookup command in your search when you want to apply a field lookup to your events, you can set the lookup to run automatically.

  1. In the Lookup table file dialog box, select Lookups in the breadcrumbs to return to the Lookups manager.
  2. In the Lookups manager, for Automatic lookups, click Add New.
    This takes you to the Add new automatic lookups view, where you configure the lookup to run automatically.

    This image shows the Add New view for automatic lookups. None of the fields have been changed.

  3. There is no need to change the Destination app setting. It is already set to search, referring to the Search app.
  4. For Name, type autolookup_prices.
  5. For Lookup table, select prices_lookup.
    The other options are lookup table files that come with the product.
  6. For Apply to, the value sourcetype is already selected. For named, type access_combined_wcookie.

    This image shows the Add New Automatic lookups page. The fields are filled in as described in the steps up to this point.

  7. For Lookup input fields, type productId in both text boxes.

    The lookup input fields are the fields that the lookup table and the events have in common. The lookup input fields are used to associate, or link, the fields from the lookup table file with fields in your events.
    • The first text box specifies the field name in the lookup table file.
    • The second text box specifies the field name in your events.

    The lookup table file has a productId column that contains values that match the values in the productId field in the events.

    This image shows the Add New Automatic lookups page. The fields are filled in as described in the steps up to this point.

  8. For Lookup output fields, specify the names of the fields from the lookup table file that you want to add to your event data. You can specify different names.
    The lookup table file has several fields. You will specify two of the fields in the lookup table to appear in your events.
    1. In the first text box, type product_name. This is the field in the prices.csv file that contains the descriptive name for each productId.
    2. In the second text box, after the equal sign, type productName. This is the name of the field that will appear in your events for the descriptive name of the product.
    3. Click Add another field to add another field after the first one.
    4. Type price in the first text box. This is the field in the prices.csv file that contains the price for each productId. Let's use the same name for the field that will appear in your events. Type price in the second text box.

      This image shows the Add New Automatic lookups page. The fields are filled in as described in these steps.

  9. Keep Overwrite field values unchecked.
  10. Click Save.
    The Automatic lookup view appears and the lookup that you configured, autolookup_prices, is in the list. The full name is access_combined_wcookie : LOOKUP-autolookup_prices.

    This image shows the Automatic lookups view. The format of the lookup name is "sourcetype : LOOKUP-name". This displays as "access_combined_wcookie : LOOKUP-autolookup_prices" in the screen image. The list in this view contains seven columns: Name, Lookup, Owner, App, Sharing, Status, and Action.

Next step

You have setup the Search app to automatically retrieve information from your lookup table definition.
Now, you will search using those lookup definitions.

Last modified on 19 April, 2019
Use a subsearch   Search with field lookups

This documentation applies to the following versions of Splunk® Enterprise: 7.2.0, 7.2.1, 7.2.2, 7.2.3, 7.2.4, 7.2.5, 7.2.6, 7.2.7, 7.2.8, 7.2.9, 7.2.10

Acrobat logo Download manual
Acrobat logo Download this page

Was this topic useful?







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