Related Answers
Download topic as PDF
return
Description
Returns values from a subsearch.
The return command is used to pass values up from a subsearch. The command replaces the incoming events with one event, with one attribute: "search". To improve performance, the return command automatically limits the number of incoming results with the head command and the resulting fields with the fields command.
By default, the return command uses only the first row of results. Use the count argument to specify the number of results to use.
Syntax
return [<count>] [<alias>=<field>...] [<field>...] [$<field>...]
Required arguments
None.
Optional arguments
- <count>
- Syntax: <int>
- Description: Specify the number of rows.
- Default: 1, which is the first row of results passed into the command.
- <alias>
- Syntax: <alias>=<field>...
- Description: Specify the field alias and value to return. You can specify multiple pairs of aliases and values, separated by spaces.
- <field>
- Syntax: <field>...
- Description: Specify one or more fields to return, separated by spaces.
- <$field>
- Syntax: <$field>
- Description: Specify one or more field values to return, separated by spaces.
Usage
The command is convenient for outputting a field name, a alias-value pair, or just a field value.
| Output | Example |
|---|---|
| Field name | return source
|
| Alias=value | return ip=srcip
|
| Value | return $srcip
|
By default, the return command uses only the first row of results. You can specify multiple rows, for example 'return 2 ip'. Each row is viewed as an OR clause, that is, output might be '(ip=10.1.11.2) OR (ip=10.2.12.3)'. Multiple values can be specified and are placed within OR clauses. So, 'return 2 user ip' might output '(user=bob ip=10.1.11.2) OR (user=fred ip=10.2.12.3)'.
In most cases, using the return command at the end of a subsearch removes the need for head, fields, rename, format, and dedup.
Duplicate values
Suppose you have the following search:
sourcetype=WinEventLog:Security | return 2 user
You might logically expect the command to return the first two distinct users. Instead the command looks at the first two events, based on the ordering from the implied head command. The return command returns the users within those two events. The command does not determine if the user value is unique. If the same user is listed in these events, the command returns only the one user.
To return unique values, you need to include the dedup command in your search. For example:
sourcetype=WinEventLog:Security | dedup user | return 2 user
Quotations in returned fields
The return command does not escape quotation marks that are in the fields that are returned. You must use an eval command to escape the quotation marks before you use the return command. For example:
...[search eval field2=replace(field1,"\"","\\\"") | return field2]
Examples
Example 1:
Search for 'error ip=<someip>', where <someip> is the most recent ip used by user 'boss'.
error [ search user=boss | return ip ]
Example 2:
Search for 'error (user=user1 ip=ip1) OR (user=user2 ip=ip2)', where the users and IPs come from the two most-recent logins.
error [ search login | return 2 user ip ]
Example 3:
Return to eval the userid of the last user, and increment it by 1.
... | eval nextid = 1 + [ search user=* | return $id ] | ...
See also
Answers
Have questions? Visit Splunk Answers and see what questions and answers the Splunk community has using the return command.
|
PREVIOUS rest |
NEXT reverse |
This documentation applies to the following versions of Splunk® Enterprise: 4.3, 4.3.2, 4.3.3, 4.3.4, 4.3.5, 4.3.6, 4.3.7, 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, 6.2.0, 6.2.1, 6.2.2, 6.2.3, 6.2.4, 6.2.5, 6.2.6, 6.2.7, 6.2.8, 6.2.9, 6.2.10, 6.2.11, 6.2.12, 6.2.13, 6.2.14, 6.2.15, 6.3.0, 6.3.1, 6.3.10, 6.3.11, 6.3.12, 6.3.14, 4.3.1, 6.3.3, 6.3.6, 6.3.7, 6.3.8, 6.3.9, 6.4.0, 6.4.1, 6.3.13, 6.4.2, 6.4.3, 6.4.4, 6.4.5, 6.4.6, 6.4.7, 6.4.8, 6.4.9, 6.4.10, 6.4.11, 6.5.0, 6.5.1, 6.5.1612 (Splunk Cloud only), 6.5.2, 6.5.3, 6.5.4, 6.5.5, 6.5.6, 6.5.7, 6.5.8, 6.5.9, 6.5.10, 6.6.0, 6.6.1, 6.6.2, 6.6.3, 6.6.4, 6.6.5, 6.6.6, 6.6.7, 6.6.8, 6.6.9, 6.6.10, 6.6.11, 6.6.12, 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.1.0, 7.1.1, 7.1.2, 7.1.3, 7.1.4, 7.1.5, 7.1.6, 7.1.7, 7.1.8, 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.3.0, 7.3.1, 6.3.2, 6.3.4, 6.3.5
Comments
As an example, add: eval field=REPLACE(field,"\"","\\\"")
As a general warning - return doesn't correctly escape quotes in the returned fields so you have to do it yourself using eval before the return.
Hi Fairje
Thanks for this explanation and example. I added it to the "Usage" section under "Duplicate values".
The documentation doesn't appear to be clear enough on which field values are expected to be returned. With the way this works:
e.g.: sourcetype=WinEventLog:Security | return 2 user
You would logically expect it to return the first two distinct users. Instead it looks at the first two events (based on the ordering from the implied "head" command) and returns the users within those two events (two based on the example search above). This might be one user who occupied the first two results and therefore it would only "return" one actual user value. To work around this I was forced to do the following command:
sourcetype=WinEventLog:Security | dedup user | return 2 user
It would be helpful if this was clarified in some fashion in the description.
JeToJedno
Thank you for your comment.
I have added it to the Usage section along with the example.