head
Description
Returns the first N number of specified results in search order. This means the most recent N events for a historical search, or the first N captured events for a real-time search. The search results are limited to the first results in search order.
There are two types of limits that can be applied: an absolute number of results, or an expression where all results are returned until the expression becomes false.
Syntax
The required syntax is in bold.
- head
- [<N> | (<eval-expression>)]
- [limit=<int>]
- [null=<bool>]
- [keeplast=<bool>]
Required arguments
None.
If no options or limits are specified, the head
command returns the first 10 results.
Optional arguments
- <N>
- Syntax: <int>
- Description: The number of results to return.
- Default: 10
- limit
- Syntax: limit=<int>
- Description: Another way to specify the number of results to return.
- Default: 10
- eval-expression
- Syntax: <eval-compare-exp> | <eval-bool-exp>
- Description: A valid
<eval-expression>
that evaluates to a Boolean. The search returns results until this expression evaluates to false. For more information, see the evaluation functions in the Search Reference.
- keeplast
- Syntax: keeplast=<bool>
- Description: You must specify a
eval-expression
to use thekeeplast
argument. Controls whether the last result in the result set is retained. The last result returned is the result that caused theeval-expression
to evaluate tofalse
orNULL
. Setkeeplast
totrue
to retain the last result in the result set. Setkeeplast
tofalse
to discard the last result. - Default: false
- null
- Syntax: null=<bool>
- Description: You must specify an <eval-expression> for the
null
argument to have any effect. Controls how an <eval-expression> that evaluates to NULL is handled. For example, if the <eval-expression> is(x > 10)
and a value in field x does not exist, the <eval-expression> evaluates to NULL instead of true or false.- If
null=true
, the results of thehead
command include events for which <eval-expression> evaluates to NULL in the output. Thehead
command continues to process the remaining events. - If
null=false
, thehead
command treats the <eval-expression> that evaluates to NULL as if the <eval-expression> evaluated tofalse
. Thehead
command stops processing events. Ifkeeplast=true
, the event for which the <eval-expression> evaluated to NULL is also included in the output.
- If
- Default: false
Usage
The head
command is a centralized streaming command. See Command types.
Setting limits
If a numeric limit such as a numeric literal or the argument limit=<int>
is used, the head
command returns the first N results where N is the selected number. Using both the numeric limit and limit=<int>
results in an error.
Using an <eval-expression>
If an <eval-expression> is used, all initial results are returned until the first result where the expression evaluates to false. The result where the <eval-expression> evaluates to false is kept or dropped based on the keeplast
argument.
If both a numeric limit and an <eval-expression> are used, the smaller of the two constraints applies. For example, the following search returns up to the first 10 results, because the <eval-expression> is always true.
... |head limit=10 (1==1)
However, this search returns no results because the <eval-expression> is always false.
... |head limit=10 (0==1)
Basic examples
1. Return a specific number of results
Return the first 20 results.
... | head 20
2. Return results based on a specified limit
Return events until the time span of the data is >= 100 seconds
... | streamstats range(_time) as timerange | head (timerange<100)
Extended example
1. Using the keeplast and null arguments
The following example shows the search results when an <eval-expression> evaluates to NULL, and the impact of the keeplast
and null
arguments on those results.
Let's start with creating a set of events. The eval
command replaces the value 3 with NULL in the count field.
| makeresults count=7
| streamstats count
| eval count=if(count=3,null(), count)
The results look something like this:
_time | count |
---|---|
2020-05-18 12:46:51 | 1 |
2020-05-18 12:46:51 | 2 |
2020-05-18 12:46:51 | |
2020-05-18 12:46:51 | 4 |
2020-05-18 12:46:51 | 5 |
2020-05-18 12:46:51 | 6 |
2020-05-18 12:46:51 | 7 |
When null
is set to true
, the head
command continues to process the results. In this example the command processes the results, ignoring NULL values, as long as the count is less than 5. Because keeplast=true
the event that stopped the processing, count 5, is also included in the output.
| makeresults count=7
| streamstats count
| eval count=if(count=3,null(), count)
| head count<5 keeplast=true null=true
The results look something like this:
_time | count |
---|---|
2020-05-18 12:46:51 | 1 |
2020-05-18 12:46:51 | 2 |
2020-05-18 12:46:51 | |
2020-05-18 12:46:51 | 4 |
2020-05-18 12:46:51 | 5 |
When null
is set to false
, the head
command stops processing the results when it encounters a NULL value. The events with count 1 and 2 are returned. Because keeplast=true
the event with the NULL value that stopped the processing, the third event, is also included in the output.
| makeresults count=7
| streamstats count
| eval count=if(count=3,null(), count)
| head count<5 keeplast=true null=false
The results look something like this:
_time | count |
---|---|
2020-05-18 12:46:51 | 1 |
2020-05-18 12:46:51 | 2 |
2020-05-18 12:46:51 |
See also
geostats | highlight |
This documentation applies to the following versions of Splunk Cloud Platform™: 8.2.2112, 8.2.2201, 8.2.2202, 8.2.2203, 9.0.2205, 9.0.2208, 9.0.2209, 9.0.2303, 9.0.2305, 9.1.2308, 9.1.2312, 9.2.2403 (latest FedRAMP release), 9.2.2406
Feedback submitted, thanks!