Writes search results to a static lookup table, or KV store collection, that you specify.
The required syntax is in bold.
- | outputlookup
- <filename> | <tablename>
You must specify one of the following required arguments, either
- Syntax: <string>
- Description: The name of the lookup file. The file must end with
- 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).
- Syntax: append=<bool>
- Description: The default,
append=falsesetting, writes the search results to the
.csvfile 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
.csvfile or KV store collection. Otherwise it creates a file. If there is an existing .csv file, the
outputlookupcommand writes only the fields that are present in the previously existing
outputlookupsearch that is run with
append=truemight result in a situation where the lookup table or collection is only partially updated. This means that a subsequent
inputlookupsearch on that lookup table or collection might return stale data along with new data. The
outputlookupcommand cannot append to
- Default: false
- Syntax: create_empty=<bool>
- Description: If set to
trueand there are no results, a zero-length file is created. When set to
falseand there are no results, no file is created. If the file previously existed, the file is deleted.
- For example, suppose there is a system-level lookup called "test" with the lookup defined in "test.csv". There is also an app-level lookup with the same name. If an app overrides that "test.csv" in it's own app directory with an empty file
create_empty=true, the app-level lookup behaves as if the lookup is empty. However, if there's no file at all
create_empty=falseat the app level, then the lookup file in the system-level is used.
- Default: false
- 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
- Syntax: key_field=<field>
- Description: For KV store-based lookups, uses the specified field name as the key to a value and replaces that value. An
outputlookupsearch using the
key_fieldargument might result in a situation where the lookup table or collection is only partially updated. A subsequent
inputlookupsearch on that collection might return stale data along with new data. A partial update only occurs with concurrent searches, one with the
outputlookupcommand and a search with the
inputlookupcommand. It is possible that the
inputlookupoccurs when the
outputlookupis still updating some of the records.
- Syntax: max=<int>
- Description: The number of rows to output.
- Default: no limit
- Syntax: output_format=splunk_sv_csv | splunk_mv_csv
- Description: Controls the output data format of the lookup. Use
output_format=splunk_mv_csvwhen you want to output multivalued fields to a lookup table file, and then read the fields back into Splunk using the
inputlookupcommand. The default,
splunk_sv_csvoutputs a CSV file which excludes the
- Default: splunk_sv_csv
- Syntax: override_if_empty=<bool>
- Description: If
override_if_empty=trueand no results are passed to the output file, the existing output file is deleted, If
override_if_empty=falseand no results are passed to the output file, the command does not delete the existing output file.
- Default: true
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
limits.conf to restrict write access to users with the appropriate permissions when using the
outputlookup command. Both
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.
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
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.
1. Write to a lookup table using settings in the transforms.conf file
usertogroup lookup table as specified in the
| outputlookup usertogroup
2. Write to a lookup file in a specific system or app directory
users.csv lookup file under
| outputlookup users.csv
3. Specify not to override the lookup file if no results are returned
users.csv lookup file, if results are returned, under
$SPLUNK_HOME/etc/apps/*/lookups. Do not delete the
users.csv file if no results are returned.
| outputlookup users.csv override_if_empty=false
4. Write to a KV store collection
Write food inspection events for Shalimar Restaurant to a KV store collection called
kvstorecoll. This collection is referenced in a lookup table called
index=sf_food_health sourcetype=sf_food_inspections name="SHALIMAR RESTAURANT" | outputlookup kvstorecoll_lookup
5. Write from 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. This requires usage of both
| inputlookup customers.csv | outputlookup kvstorecoll_lookup
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 "Return the internal key ID values for the KV store collection" in the Examples section of the inputlookup command.
You must use the
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
| inputlookup kvstorecoll_lookup
| search _key=544948df3ec32d7a4c1d9755
| eval CustName="Vanya Patel"
| eval CustCity="Springfield"
| outputlookup kvstorecoll_lookup append=True key_field=_key
The outputlookup command appends the search results to the specified lookup file,
key_field argument identifies the field in the collection that contains the key ID for the values that you want to append.
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, 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, 8.0.5, 8.0.6, 8.0.7, 8.0.8