nano SIEM
Search Commands

return

Supported in:Self-hosted

Return the distinct values of one or more fields, most often to feed an IN [...] subsearch.

Use return to select distinct values of your chosen fields. At the end of an IN [...] subsearch, it supplies values for the outer search to match.

Syntax

... | return [<count>] <field> [, <field> ...]
ArgumentDefaultDescription
count1Maximum number of distinct rows to return.
fieldFields to return. A leading $ ($user.name, as other SIEM query languages write it) is accepted and stripped.

How it works

  • return outputs the distinct combinations of the listed fields, up to count rows. Without a count it returns one row.
  • The rows are not sorted. If you need "the top N", don't rely on sort before return; filter with where or use head on aggregated output instead.

In an IN [...] subsearch

class_uid=1007 device.hostname IN [search class_uid=3002 status_id=2 | return device.hostname]
  • The subsearch may contain only a search expression and an optional return of one field. Any other command inside IN [...] is rejected with "IN subsearch supports only a search and optional return field".
  • Inside IN [...] the subsearch supplies up to 10,000 distinct values. The count on return is ignored there.
  • To filter on aggregates (for example, hosts with more than 50 failures), use join.

Examples

Process activity on every host that had a failed logon:

class_uid=1007 device.hostname IN [search class_uid=3002 status_id=2 | return device.hostname]

Proxy traffic from addresses that also show up in failed logons:

metadata.log_source=conduit_proxy src_endpoint.ip IN [search class_uid=3002 status_id=2 | return src_endpoint.ip] | stats count by src_endpoint.ip, http_request.url.hostname

Twenty distinct host and user pairs seen running PowerShell:

class_uid=1007 process.name=powershell.exe | return 20 device.hostname, actor.user.name

What's next

On this page