outputlookup
Description
Writes search results to a static lookup table, or KV store collection, that you specify.
Syntax
| outputlookup [append=<bool>] [create_empty=<bool>] [max=<int>] [key_field=<field_name>] [createinapp=<bool>] (<filename> | <tablename>)
Required arguments
- <filename>
- Syntax: <string>
- Description: The name of the lookup file. The file must end with
.csv
or.csv.gz
.
- <tablename>
- Syntax: <string>
- Description: The name of the lookup table as specified by a stanza name in
transforms.conf
. The lookup table can be configured for any lookup type (CSV, external, or KV store).
Optional arguments
- append
- Syntax: append=<bool>
- Description: The default,
append=false
setting, writes the search results to the.csv
file or KV store collection. Columns that are not in the current search results are removed from the file. If set to true, attempts to append search results to an existing.csv
file or KV store collection. Otherwise it creates a file. If there is an existing .csv file, theoutputlookup
command writes only the fields that are present in the previously existing.csv
file. Anoutputlookup
search that is run withappend=true
might result in a situation where the lookup table or collection is only partially updated. This means that a subsequentlookup
orinputlookup
search on that lookup table or collection might return stale data along with new data. Theoutputlookup
command cannot append to.gz
files. - Default: false
- create_empty
- Syntax: create_empty=<bool>
- Description: If set to
true
and there are no results, a zero-length file is created. When set tofalse
and there are no results, no file is created. If the file previously existed, the file is deleted. - Default: true
- createinapp
- Syntax: createinapp=<bool>
- Description: If set to
false
, or if there is no current application context, the command creates the file in the system lookups directory. - Default: true
- key_field
- Syntax: key_field=<field_name>
- Description: For KV store-based lookups, uses the specified field name as the key to a value and replaces that value. An
outputlookup
search using thekey_field
argument might result in a situation where the lookup table or collection is only partially updated. A subsequentlookup
orinputlookup
search on that collection might return stale data along with new data. A partial update only occurs with concurrent searches, one with theoutputlookup
command and a search with theinputlookup
command. It is possible that theinputlookup
occurs when theoutputlookup
is still updating some of the records.
- max
- Syntax: max=<int>
- Description: The number of rows to output.
- Default: no limit
Usage
The lookup table must be a CSV or GZ file, or a table name specified with a lookup table configuration in transforms.conf
. The lookup table can refer to a KV store collection or a CSV lookup. The outputlookup command cannot be used with external lookups.
For CSV lookups, if the lookup file does not exist, it is created in the lookups directory of the current application. If the lookup file already exists, it is overwritten with the results of the outputlookup
command. If the createinapp
option is set to false
or if there is no current application context, then the file is created in the system lookups directory.
For permissions in CSV lookups, use the check_permission
field in transforms.conf
and outputlookup_check_permission
in limits.conf
to restrict write access to users with the appropriate permissions when using the outputlookup
command. Both check_permission
and outputlookup_check_permission
default to false. Set to true for Splunk software to verify permission settings for lookups for users. You can change lookup table file permissions in the .meta
file for each lookup file, or Settings > Lookups > Lookup table files. By default, only users who have the admin or power role can write to a shared CSV lookup file.
For more information about creating lookups, see About lookups in the Knowledge Manager Manual.
For more information about App Key Value Store collections, see About KV store in the Admin Manual.
Appending results
Suppose you have an existing CSV file which contains columns A, D, and J. The results of your search are columns A, C, and J. If you run a search with outputlookup append=false
, then columns A, C, and J are written to the CSV file. Column D is not retained.
If you run a search with outputlookup append=true
, then only the columns that are currently in the file are preserved. In this example columns A and J are written to the CSV file. Column C is lost because it does not already exist in the CSV file. Column D is retained.
You can work around this issue by using the eval
command to add a column to your CSV file before you run the search. For example, if your CSV file is named foo you would do something like this:
| inputlookup foo | eval c=null | outputlookup foo append=false ....
Then run your search and pipe the results to the fields
command for the columns you want to preserve.
... | fields A C J | outputlookup append=true foo
Multivalued fields
When you output to a static lookup table, the outputlookup
command merges values in a multivalued field into single space-delimited value. This does not apply to a KV store collection.
Examples
Example 1: Write to usertogroup
lookup table as specified in transforms.conf
.
| outputlookup usertogroup
Example 2: Write to users.csv
lookup file under $SPLUNK_HOME/etc/system/lookups
or $SPLUNK_HOME/etc/apps/*/lookups
.
| outputlookup users.csv
Example 3: Write food inspection events for Shalimar Restaurant to a KV store collection called kvstorecoll
. This collection is referenced in a lookup table called kvstorecoll_lookup
.
index=sf_food_health sourcetype=sf_food_inspections name="SHALIMAR RESTAURANT" | outputlookup kvstorecoll_lookup
Example 4: 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
Example 5: Update field values for a single KV store collection record. This requires usage of inputlookup
, outputlookup
, and eval
. The 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="Marge Simpson" | eval CustCity="Springfield" | outputlookup kvstorecoll_lookup append=True key_field=_key
To learn how to obtain the internal key ID values of the records in a KV store collection, see Example 5 for the inputlookup
command.
See also
inputlookup, lookup, inputcsv, outputcsv
Answers
Have questions? Visit Splunk Answers and see what questions and answers the Splunk community has using the outputlookup command.
outputcsv | outputtext |
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
Feedback submitted, thanks!