Splunk® Enterprise

Search Reference

Splunk Enterprise version 8.0 is no longer supported as of October 22, 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.

inputlookup

Description

Use the inputlookup command to search the contents of a lookup table. The lookup table can be a CSV lookup or a KV store lookup.

Syntax

The required syntax is in bold.

| inputlookup
[append=<bool>]
[start=<int>]
[max=<int>]
[<filename> | <tablename>]
[WHERE <search-query>]

Required arguments

You must specify either a <filename> or a <tablename>.

<filename>
Syntax: <string>
Description: The name of the lookup file must end with .csv or .csv.gz. If the lookup does not exist, a warning message is displayed (but no syntax error is generated).
<tablename>
Syntax: <string>
Description: The name of the lookup table as specified by a stanza name in the transforms.conf file. The lookup table can be configured for any lookup type (CSV, external, or KV store).

Optional arguments

append
Syntax: append=<bool>
Description: If set to true, the data returned from the lookup file is appended to the current set of results rather than replacing it. Defaults to false.
max
Syntax max=<int>
Description: Specify the maximum number of events to be read from the file. Defaults to 1000000000.
start
Syntax: start=<int>
Description: Specify the 0-based offset of the first event to read. If start=0, it begins with the first event. If start=4, it begins with the fifth event. Defaults to 0.
WHERE clause
Syntax: WHERE <search-query>
Description: Use this clause to improve search performance by prefiltering data returned from the lookup table. Supports a limited set of search query operators: =, !=, <, >, <=, >=, AND, OR, NOT. Any combination of these operators is permitted. Also supports wildcard string searches.

Usage

The inputlookup command is an event-generating command. See Command types.

Generating commands use a leading pipe character and should be the first command in a search.

The lookup can be a file name that ends with .csv or .csv.gz, or a lookup table configuration in the transforms.conf file.

Appending or replacing results

If append=true, data from the lookup file or KV store collection is appended to the current set of results. By default, append=false which means that the current result set is replaced with the results from the lookup search.

Working with large CSV lookup tables

The WHERE clause allows you to narrow the scope of the query that inputlookup makes against the lookup table. It restricts inputlookup to a smaller number of lookup table rows, which can improve search efficiency when you are working with significantly large lookup tables.

Testing geometric lookup files

You can use the inputlookup command to verify that the geometric features on the map are correct. The syntax is | inputlookup <your_lookup>.

  1. For example, to verify that the geometric features in built-in geo_us_states lookup appear correctly on the choropleth map, run the following search:

    | inputlookup geo_us_states

  2. On the Visualizations tab, zoom in to see the geometric features. In this example, the states in the United States.

Additional information

For more information about creating lookups, see About lookups in the Knowledge Manager Manual.

For more information about the App Key Value store, see About KV store in the Admin Manual.

Examples

1. Read in a lookup table

Read in a usertogroup lookup table that is defined in the transforms.conf file.

| inputlookup usertogroup

2. Append lookup table fields to the current search results

Read in a usertogroup lookup table that is defined by a stanza in the transforms.conf file. Append the fields to any current results.

| inputlookup append=t usertogroup

3. Read in a lookup table in a CSV file

Search the users.csv lookup file, which is in the $SPLUNK_HOME/etc/system/lookups or $SPLUNK_HOME/etc/apps/<app_name>/lookups directory.

| inputlookup users.csv

4. Read in a lookup table from a KV store collection

Search the contents of the KV store collection kvstorecoll that have a CustID value greater than 500 and a CustName value that begins with the letter P. The collection is referenced in a lookup table called kvstorecoll_lookup. Provide a count of the events received from the table.

| inputlookup kvstorecoll_lookup where (CustID>500) AND (CustName="P*") | stats count

In this example, the lookup definition explicitly defines the CustID field as a type of "number". If the field type is not explicitly defined, the where clause does not work. Defining field types is optional.

5. Return the internal key ID values for the KV store collection

The internal key ID is a unique identifier for each record in the collection, and is a hidden field.

To return the values in the_key field, you must create a new field to display those values. In this example, the eval command is used to create the CustKey field and the _key field is used as the source for the CustKey field values.

The following example returns the internal key ID values for the KV store collection kvstorecoll, using the lookup table kvstorecoll_lookup.

| inputlookup kvstorecoll_lookup | eval CustKey = _key | table CustKey, CustName, CustStreet, CustCity, CustState, CustZip

6. Update field values for a single KV store collection record

To update field values for a single KV store collection record you must specify the internal key ID for the record.

To learn how to obtain the internal key ID values of the records in a KV store collection, see the previous example "Return the internal key ID values for the KV store collection".

You must use the inputlookup, outputlookup, and eval commands to update field values for a single KV store collection record.

In the following example, the KV store collection record is indicated by the value of its internal key ID, the _key field, and is updated with a new customer name and customer city. The record belongs to the KV store collection kvstorecoll, which is accessed through the lookup table kvstorecoll_lookup.

| inputlookup kvstorecoll_lookup | search _key=544948df3ec32d7a4c1d9755 | eval CustName="Claudia Garcia" | eval CustCity="San Francisco" | outputlookup kvstorecoll_lookup append=true key_field=_key

The outputlookup command appends the CustName and CustCity for the specified key ID in the kvstorecoll_lookup lookup file. The key_field argument identifies the field in the collection that contains the key ID for the values that you want to append.

7. Write the contents of a CSV file to a KV store collection

Write the contents of a CSV file to the KV store collection kvstorecoll using the lookup table kvstorecoll_lookup. The CSV file is in the $SPLUNK_HOME/etc/system/lookups or $SPLUNK_HOME/etc/apps/<app_name>/lookups directory.

| inputlookup customers.csv | outputlookup kvstorecoll_lookup

See also

Commands
inputcsv
join
lookup
outputlookup
Last modified on 05 February, 2021
 

This documentation applies to the following versions of Splunk® Enterprise: 7.0.0, 7.0.1, 7.0.2, 7.0.3, 7.0.4, 7.0.5, 7.0.6, 7.0.7, 7.0.8, 7.0.9, 7.0.10, 7.0.11, 7.0.13, 7.1.0, 7.1.1, 7.1.2, 7.1.3, 7.1.4, 7.1.5, 7.1.6, 7.1.7, 7.1.8, 7.1.9, 7.1.10, 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, 7.3.0, 7.3.1, 7.3.2, 7.3.3, 7.3.4, 7.3.5, 7.3.6, 7.3.7, 7.3.8, 7.3.9, 8.0.0, 8.0.1, 8.0.2, 8.0.3, 8.0.4

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