return
return
Synopsis
Returns values from a subsearch.
Syntax
return [<count>] [<alias>=<field>] [<field>] [$<field>]
Arguments
- <count>
- Syntax: <int>
- Description: Specify the number of rows. Defaults to 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.
- <field>
- Syntax: <field>
- Description: Specify the field to return.
- <$field>
- Syntax: <$field>
- Description: Specify the field values to return.
Description
The return command is for passing values up from a subsearch. 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 head and the resulting fields with the fields.
The command also allows convenient outputting of field=value, 'return source', alias=value, 'return ip=srcip', and value, 'return $srcip'.
The return command defaults to using as input just the first row of results that are passed to it. Multiple rows can be specified with count, for example 'return 2 ip'; and each row is ORed, 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.
Examples
Example 1: Search for 'error ip=<someip>', where someip is the most recent ip used by Boss.
error [ search user=boss | return ip ]Example 2: Search for 'error (user=user1 ip=ip1) OR (user=user2 ip=ip2)', where 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.
This documentation applies to the following versions of Splunk: 4.2 , 4.2.1 , 4.2.2 , 4.2.3 , 4.2.4 , 4.3 , 4.3.1 , 4.3.2 , 4.3.3 , 4.3.4 , 4.3.5 , 4.3.6 , 5.0 , 5.0.1 , 5.0.2 View the Article History for its revisions.