return
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> ...]| Argument | Default | Description |
|---|---|---|
count | 1 | Maximum number of distinct rows to return. |
field | Fields to return. A leading $ ($user.name, as other SIEM query languages write it) is accepted and stripped. |
How it works
returnoutputs the distinct combinations of the listed fields, up tocountrows. Without a count it returns one row.- The rows are not sorted. If you need "the top N", don't rely on
sortbeforereturn; filter withwhereor 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
returnof one field. Any other command insideIN [...]is rejected with "IN subsearch supports only a search and optional return field". - Inside
IN [...]the subsearch supplies up to 10,000 distinct values. Thecountonreturnis 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.hostnameTwenty distinct host and user pairs seen running PowerShell:
class_uid=1007 process.name=powershell.exe | return 20 device.hostname, actor.user.nameWhat's next
- join: combine searches, including on aggregated output
- Syntax: subsearches
- dedup: one full event per key