Search Reference

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

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

Required arguments

<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.

Additional information

For more information about lookup table configuration, see Configure CSV and external lookups and Configure KV store lookups in the Knowledge Manager Manual.

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

Examples

Example 1: Read in a usertogroup lookup table that is defined in transforms.conf.

| inputlookup usertogroup

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

| inputlookup append=t usertogroup

Example 3: Search the users.csv lookup file (under $SPLUNK_HOME/etc/system/lookups or $SPLUNK_HOME/etc/apps/<app_name>/lookups).

| inputlookup users.csv

Example 4: 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

Example 5: View internal key ID values for the KV store collection kvstorecoll, using the lookup table kvstorecoll_lookup. The internal key ID is a unique identifier for each record in the collection. This requires usage of the eval and table commands.

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

Example 6: Update field values for a single KV store collection record. This requires usage of inputlookup, outputlookup, and eval. The record is indicated by the its internal key ID (the _key field) and this search updates the record 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="Marge Simpson" | eval CustCity="Springfield" | outputlookup kvstorecoll_lookup append=True key_field=_key

Example 7: Write the contents of a CSV file to the KV store collection kvstorecoll using the lookup table kvstorecoll_lookup. This requires usage of both inputlookup and outputlookup.

| inputlookup customers.csv | outputlookup kvstorecoll_lookup

See also

inputcsv, join, lookup, outputlookup

Answers

Have questions? Visit Splunk Answers and see what questions and answers the Splunk community has using the inputlookup command.