A subsearch is a search with a search pipeline as an argument. Subsearches are contained in square brackets and evaluated first. The result of the subsearch is then used as an argument in the primary or outer search. Subsearches are mainly used for two purposes:
- Parameterize one search, using the output of another search (for example, find every record from IP addresses that visited some specific URL).
- Run a separate search, but stitch the output to the first search using the
A subsearch can only be used where the explicit action/what you're trying to do deals with search and not a transformation of the data. For example, you cannot use a subsearch with "
sourcetype=top | multikv", because the
multikv command doesn't expect a subsearch as an argument. Certain commands, such as
join can take a subsearch as an argument.
A subsearch example
The following is an example of using a subsearch to parameterize one search. You're interested in finding all events from the most active host in the last hour; but, you can't search for a specific host because it might not be the same host every hour. First, you need to identify which host is most active.
sourcetype=syslog earliest=-1h | top limit=1 host | fields + host
This search will only return one host value. In this example, the result is the host named "crashy". Now, you can search for all the events coming from "crashy":
But, instead of running two searches each time you want this information, you can use a subsearch to give you the hostname and pass it to the outer search:
sourcetype=syslog [search sourcetype=syslog earliest=-1h | top limit=1 host | fields + host]
Performance of subsearches
If your subsearch returns a large table of results, it will impact the performance of your search. You can change the number of results that the format command operates over inline with your search by appending the following to the end of your subsearch:
| format maxresults = <integer> . For more information, see the format command in the Search Reference.
You can also control the subsearch with settings in
limits.conf for the runtime and maximum number of results returned:
maxout = <integer>
- Maximum number of results to return from a subsearch.
- This number cannot be greater than or equal to 10500.
- Defaults to 100.
maxtime = <integer>
- Maximum number of seconds to run a subsearch before finalizing
- Defaults to 60.
ttl = <integer>
- Time to cache a given subsearch's results.
- Defaults to 300.
After running a search you can click the Job menu and select Inspect Job to open the Search Job Inspector. Scroll down to the
remoteSearch component, and you can see what the actual query that resulted from your subsearch. For more information, see Using the Search Job Inspector in this manual.
Result output settings for subsearch commands
Limits.conf.spec indicates that subsearches return a maximum of 100 results by default. You will see variations in the actual number of output results because every command can change what the default
maxout is when it invokes a subsearch. Additionally, the default
maxout only applies to subsearches that are intended to be expanded into a search expression, which is not the case for some commands such as join, append, and appendcols.
- For example, the append command overrides that default to be the value of
maxresultrows, unless the user has specified a
maxoutas an argument to append.
- The output limit of the join command is controlled by
subsearch_maxoutin limits.conf. This defaults to 50000 events.
Have questions? Visit Splunk Answers and see what questions and answers the Splunk community has about using subsearches.
Specify real-time time range windows in your search
Use subsearch to correlate events
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