Return Command in Splunk

Return Command in Splunk

“Return” command basically returns the result from the sub search to your main search.
“Sub search” in Splunk – A sub search is a search within a primary search. A sub search looks for a single piece of information that is then added as a criteria, to the main search. Generally it’s a procedure of adding condition dynamically to your main search.
The return command automatically limits the number of incoming events with the “head” command and the resulting fields with the “fields” command.

Syntax:

…|return [<count>] [<alias>=<field>...] [<field>...] [$<field>...]

<count> – Number of results you want to return (default is 1)
<alias>=<field> – Mention field alias and field name of values to be returned, you can mention more than one <alias>=<field> pair separated by spaces.
<field> – Name of the fields to return, you can mention more than one field name separated by spaces.
$<field> – Name of the fields to return with “$” sign, you can mention more than one field name separated by spaces.
At first we will see how the “return” command returns the result, then we will use that query as a sub search within a primary search and will try to understand the function.

Example 1:

index="sample_set" sourcetype=access_combined_wcookie action=view status=200
|top ip
|return ip

Result:

Explanation:
Here we took data from the “sample_set” index and “access_combined_wcookie” sourcetype,which consist of data related to an online merchant site. Then we have added two filters  “action=view” and “status=200” (i.e. we want to see who viewed our product most), and then using top command we bring the most viewed ip’s and last we used return command to return our result. By default return command use “|head 1” to return the 1st value. As we can see that it brings the result in the form of a field value pair (i.e. ip=”87.194.216.51”) and results in a field called “search” . By using the return command it only brings one column, which consists of the “ip” value.

Example 2:

index="sample_set" sourcetype=access_combined_wcookie action=view status=200
|top ip
|return 10 ip

Result :

Explanation:
Here we took data from the “sample_set” index and “access_combined_wcookie” sourcetype,which consist of data related to an online merchant site. Then we have added two filters  “action=view” and “status=200” (i.e. we want to see who viewed our product most), and then using top command we bring the most viewed ip’s and last we used return command to return our result. Now this time we are using |return 10 , to get 10 ip values in the search field.

Example 3:

index="sample_set" sourcetype=access_combined_wcookie action=purchase status=200
| top ip
| return client_ip=ip

Result:

Explanation:
As you can see everything is the same as earlier but the only change is with “return” command. Here we have used  <alias>=<field> argument i.e. we return the value of ‘ip’ field in an alias named as “client_ip”. You can alter as per the requirement of your primary search.

Example 4:

index="sample_set" sourcetype=access_combined_wcookie action=view status=200
| top ip
| return $ip

Result:

Explanation:
Here also as you can see everything’s the same as earlier but the only change is with the “return” command. Here we have used the  “$<field>” argument i.e. we return the value of ‘ip’ field only in the search field.

Example 5:

index="sample_set" sourcetype=access_combined_wcookie action=view status=200
| return 3 ip JSESSIONID

Result:

Explanation:
Here we took data from “sample_set” index and “access_combined_wcookie” sourcetype, then “action=view” and “status=200” (i.e. we want to see the who viewed our product most recently), Then we have used “return” command to return the ip and JSESSIONID of those user and also we have used count=3, i.e. it will bring the “|head 3” value of our result. As one can see it brings the result like this, where the result of one event is bounded in a bracket and every event is separated by “OR”.

Use Case:

index="sample_set" sourcetype=access_combined_wcookie action=purchase status=200
 [ search index="sample_set" sourcetype=access_combined_wcookie action=view status=200
 | top ip
 | return ip]
| stats count(productId) as Product_Count values(productId) as Product_ID by ip

Result:

Explanation:
Here in the “sample_set” index and “access_combined_wcookie” sourcetype, we have data related to online merchant site “www.buttercupgames.com”, which gives us information related to product purchasing, add to cart, view etc actions. Now we want to see the ip-address of that user who purchased most products from our site with all purchased product id. Now if you see the above query we have two portions of our search query (Blue underlined portion is main or primary search and red underlined portion is sub search). Through sub search we return the top occurred ip address in the “action=purchase” category from the same index and sourcetype.
If you run that sub search separately then you will find result like this,

That is the whole sub search is replaced by ip=”87.194.216.51” in the main query. Now if you want to crosscheck then replace it and notice.

It will return the same result as early. That is how we use the “return” command in sub search to return the result based on predefined criteria dynamically.
I hope you have understood the concepts of “sub search” and most importantly “Return Command in Splunk”.