Change the format of subsearch results
When you use a subsearch, the
format command is implicitly applied to your subsearch results. The format command changes your subsearch results into a single linear search string. This is used when you want to pass the returned values in the returned fields into the primary search.
If your subsearch returned a table, such as:
| field1 | field2 | ------------------- event/row1 | val1_1 | val1_2 | event/row2 | val2_1 | val2_2 |
The format command returns:
(field1=val1_1 AND field2=val1_2) OR (field1=val2_1 AND field2=val2_2)
For more information, see the format search command reference.
The search and query fields
There are a couple of exceptions to this. First, all internal fields (fields that begin with a leading underscore "_*") are ignored and not reformatted in this way. Second, the "search" and "query" fields have their values rendered directly in the reformatted search string.
Generally, "search" can be useful when you need to append some static data or do some
eval on the data in your subsearch and then pass it to the primary search. When you use "search", the first value of the field is used as the actual search term. For example, if field2 was "search" (in the table above), the format command returns:
(field1=val1_1 AND val1_2) OR (field1=val2_1 AND val2_2)
You can also use "search" to modify the actual search string that gets passed to the primary search.
"Query" is useful when you are looking for the values in the fields returned from the subsearch, but not in these exact fields. The "query" field behaves similarly to format. Instead of passing the field/value pairs, as you see with
format, it passes the values:
(val1_1 AND val1_2) OR (val2_1 AND val2_2)
The following searches for a
clID associated with a specific
Name. This value is then used to search for several sources.
index="myindex" [search index="myindex" host="myhost" <Name> | top limit=1 clID | fields + clID ]
The subsearch returns the field and value in the format:
( (clID="0050834ja") )
If you want to return only the value,
0050834ja, rename the clID field to "search" in the subsearch:
index=myindex [search index=myindex host=myhost MyName | top limit=1 clID | fields + clID | rename clID as search ]
If the field is named search (or query) the field name (in this case, clID) is dropped and the subsearch (technically, the implicit
| format command at the end of the subsearch) returns only the value ( ( 0050834ja ) ). If you have multiple values (in the previous search, the top command limits the search result to 1), the subsearch returns each of the values ORed together. For example, the result for three values is
( ( value1 ) OR ( value2 ) OR ( value3 ) ).
This is a special case only when the field is named either "search" or "query". Renaming your fields to anything else will make the subsearch use the new field names.
Use subsearch to correlate events
About transforming commands and searches
This documentation applies to the following versions of Splunk® Enterprise: 5.0, 5.0.1, 5.0.2, 5.0.3, 5.0.4, 5.0.5, 5.0.6, 5.0.7, 5.0.8, 5.0.9, 5.0.10, 5.0.11, 5.0.12, 5.0.13, 5.0.14, 5.0.15, 5.0.16, 5.0.17, 5.0.18, 6.0, 6.0.1, 6.0.2, 6.0.3, 6.0.4, 6.0.5, 6.0.6, 6.0.7, 6.0.8, 6.0.9, 6.0.10, 6.0.11, 6.0.12, 6.0.13, 6.0.14, 6.0.15, 6.1, 6.1.1, 6.1.2, 6.1.3, 6.1.4, 6.1.5, 6.1.6, 6.1.7, 6.1.8, 6.1.9, 6.1.10, 6.1.11, 6.1.12, 6.1.13, 6.1.14