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.

Syntax

The required syntax is in bold.

head

[keeplast = (true | false)]

[while "("<boolean-expression>")"]

[<limit>]

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 3

You 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) 5

Here 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 head command syntax details.

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

head command examples