head command: Overview, syntax, and usage
The SPL2 head command returns the first search results, in search order, based on the <limit> specified. For historical searches, returns the most recent events. For real-time searches, searches the first captured events.
If no options are explicitly specified, the head command returns the first 10 results.
Use these links to quickly navigate to the main sections in this topic:
Use these links to quickly navigate to the main sections in this topic:
How the SPL2 head command works
The SPL2 head command returns the top <limit> results. If your search returns events, the most recent events are returned first.
Here is an example of some search results:
| Time | Event |
|---|---|
| 00:15:07 AM 17 Sep 2024 | Thu Sep 17 2024 00:15:07 mailsv1 sshd[5276]: Failed password for invalid user zhang from 194.8.74.23 port 3351 ssh2 |
| 11:59:07 PM 16 Sep 2024 | Wed Sep 16 2024 23:59:07 mailsv1 sshd[5258]: Failed password for invalid user garcia from 194.8.74.23 port 3626 ssh2 |
| 11:12:33 PM 16 Sep 2024 | Wed Sep 16 2024 23:12:33 mailsv1 sshd[21881]: pam_unix(sshd:session): session closed for user sullivan by (uid=0) |
| 10:19:07 PM 16 Sep 2024 | Wed Sep 16 2024 22:19:07 mailsv1 sshd[3760]: Failed password for invalid user dubois from 194.8.74.23 port 2472 ssh2 |
| 8:59:24 PM 16 Sep 2024 | Wed Sep 16 2024 20:59:24 mailsv1 sshd[5801]: Failed password for invalid user patel from 194.8.74.23 port 2285 ssh2 |
| 8:42:07 PM 16 Sep 2024 | Wed Sep 16 2024 20:42:07 mailsv1 sshd[3759]: Failed password for martin from 194.8.74.23 port 3769 ssh2 |
| 7:49:13 PM 16 Sep 2024 | Wed Sep 16 2024 19:49:13 mailsv1 sshd[5979]: Failed password for invalid user garcia from 194.8.74.23 port 3417 ssh2 |
To see the first 3 events, you specify this:
... | head 3You would see this set of events:
| Time | Event |
|---|---|
| 00:15:07 AM 17 Sep 2024 | Thu Sep 17 2024 00:15:07 mailsv1 sshd[5276]: Failed password for invalid user zhang from 194.8.74.23 port 3351 ssh2 |
| 11:59:07 PM 16 Sep 2024 | Wed Sep 16 2024 23:59:07 mailsv1 sshd[5258]: Failed password for invalid user garcia from 194.8.74.23 port 3626 ssh2 |
| 11:12:33 PM 16 Sep 2024 | Wed Sep 16 2024 23:12:33 mailsv1 sshd[21881]: pam_unix(sshd:session): session closed for user sullivan by (uid=0) |
Specifying a filter with the head command
Instead of returning just the top <limit> events, you can filter which events are returned by using the while argument. In this example is looking for events where the user is garcia and returns at most 5 events. The while argument is a <boolean-expression> that must be enclosed in parenthesis.
...| head while (user=garcia) 5Here are the results:
| Time | Event |
|---|---|
| 11:59:07 PM 16 Sep 2024 | Wed Sep 16 2024 23:59:07 mailsv1 sshd[5258]: Failed password for invalid user garcia from 194.8.74.23 port 3626 ssh2 |
| 7:49:13 PM 16 Sep 2024 | Wed Sep 16 2024 19:49:13 mailsv1 sshd[5979]: Failed password for invalid user garcia from 194.8.74.23 port 3417 ssh2 |
To learn about the other arguments you can specify with the head command, see the Syntax section.
Using the command on transformed data
In the previous examples we show examples with search results that are events. You can also use the head command after the events have been summarized using a transforming command like stats.
Consider these results:
| status | host | count |
|---|---|---|
| 200 | www1 | 11835 |
| 200 | www2 | 11186 |
| 200 | www3 | 11261 |
| 400 | www1 | 233 |
| 400 | www2 | 257 |
| 400 | www3 | 211 |
| 403 | www2 | 228 |
| 404 | www1 | 244 |
| 404 | www2 | 209 |
These results are sorted by the status field. If you specify something like ...| head 4 the first 4 results are returned:
| status | host | count |
|---|---|---|
| 200 | www1 | 11835 |
| 200 | www2 | 11186 |
| 200 | www3 | 11261 |
| 400 | www1 | 233 |
If you want return the top 4 results based on the count field, you must first sort the results by that field before you run the head command. For example:
...| sort count | head 4
| status | host | count |
|---|---|---|
| 200 | www1 | 11835 |
| 200 | www2 | 11186 |
| 200 | www3 | 11261 |
| 400 | www2 | 257 |
Compare the last result (257) with the last result in previous example (233) to see the difference.
Here is another example.
You want to group the results by host. When you sort on the host field and return the top 4 results, you get this:
| status | host | count |
|---|---|---|
| 200 | www1 | 11835 |
| 400 | www1 | 233 |
| 404 | www1 | 244 |
| 200 | www2 | 11186 |
Syntax
The required syntax is in bold.
head
[keeplast = (true | false)]
[while "("<boolean-expression>")"]
[<limit>]
Required arguments
None. If no options are specified, the head command returns the first 10 results.
Optional arguments
keeplast
Syntax: keeplast=<boolean>
Description: Use in conjunction with the while argument to determine whether the last result in the result set is retained. The last result returned is the result that caused the <boolean-expression> to evaluate to false or NULL. Set keeplast=true to retain the last result in the result set. Set keeplast=false to discard the last result.
Default: true
limit
Syntax: <integer>
Description: The number of results to return.
Default: 10
while
Syntax: while "("<boolean-expression>")"
Description: A expression that evaluates to either true or false, such as <field>=<value>. You cannot use statistical functions in the expression.
Default: false
Usage
The following sections contain information to help you understand and use the SPL2 head command.
Differences between SPL and SPL2
The differences between the SPL and SPL2 head command are described in these sections.
Command options must be specified before command arguments
| Version | Example |
|---|---|
| SPL | ...head limit=10 (x>10) keeplast=true |
| SPL2 | ...head keeplast=true while (x>10) 10 |
New while keyword
SPL2 uses the while keyword to indicate that the head command accumulates events until the while condition is not met.
| Version | Example |
|---|---|
| SPL | ...head limit=20 (x>10) |
| SPL2 | ...head while (x>10) 20 |
The limit keyword is not supported in SPL2
The syntax has been simplified and the limit keyword is no longer necessary.
| Version | Example |
|---|---|
| SPL | ...head limit=10 |
| SPL2 | ...head 10 |
The null argument is not supported in SPL2
The null=<boolean> argument is not supported. To handle fields with null values, you must use the isnull() or isnotnull() function.
| Version | Example | Example |
|---|---|---|
| SPL | ...head null=true | ...head null=false |
| SPL2 | ...head while (isnotnull(host)) | ...head while (isnull(host) OR host="localhost") |
See also
head command