Search Manual

About subsearches

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

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 append and 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":

sourcetype=syslog host=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:

[subsearch]
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 maxout as an argument to append.
• The output limit of the join command is controlled by subsearch_maxout in limits.conf. This defaults to 50000 events.

Answers

Have questions? Visit Splunk Answers and see what questions and answers the Splunk community has about using subsearches.