Splunk® Enterprise

Search Reference

Download manual as PDF

Splunk Enterprise version 7.0 is no longer supported as of October 23, 2019. See the Splunk Software Support Policy for details. For information about upgrading to a supported version, see How to upgrade Splunk Enterprise.
Download topic as PDF

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 the keeplast argument. Controls whether the last result in the result set is retained. The last result returned is the result that caused the eval-expression to evaluate to false or NULL. Set keeplast to true to retain the last result in the result set. Set keeplast to false 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 the head command include events for which <eval-expression> evaluates to NULL in the output. The head command continues to process the remaining events.
  • If null=false, the head command treats the <eval-expression> that evaluates to NULL as if the <eval-expression> evaluated to false. The head command stops processing events. If keeplast=true, the event for which the <eval-expression> evaluated to NULL is also included in the output.
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

Commands
reverse
tail
Last modified on 20 May, 2020
PREVIOUS
geostats
  NEXT
highlight

This documentation applies to the following versions of Splunk® Enterprise: 6.0, 6.0.2, 6.0.3, 6.0.4, 6.0.5, 6.0.6, 6.0.7, 6.0.8, 6.0.9, 6.0.10, 6.0.11, 6.0.12, 6.0.13, 6.0.14, 6.0.15, 6.1, 6.1.1, 6.1.2, 6.1.3, 6.1.4, 6.1.5, 6.1.6, 6.1.7, 6.1.8, 6.1.9, 6.1.10, 6.1.11, 6.1.12, 6.1.13, 6.1.14, 6.2.0, 6.2.1, 6.2.2, 6.2.3, 6.2.4, 6.2.5, 6.2.6, 6.2.7, 6.2.8, 6.2.9, 6.2.10, 6.2.11, 6.2.12, 6.2.13, 6.2.14, 6.2.15, 6.3.0, 6.3.1, 6.3.2, 6.3.3, 6.3.4, 6.3.5, 6.3.6, 6.3.7, 6.3.8, 6.3.9, 6.3.10, 6.3.11, 6.3.12, 6.3.13, 6.3.14, 6.4.0, 6.4.1, 6.4.2, 6.4.3, 6.4.4, 6.4.5, 6.4.6, 6.4.7, 6.4.8, 6.4.10, 6.4.11, 6.5.0, 6.5.1, 6.0.1, 6.4.9, 6.5.4, 6.5.5, 6.5.6, 6.5.7, 6.5.8, 6.5.9, 6.6.0, 6.6.1, 6.6.2, 6.6.3, 6.6.4, 6.6.5, 6.6.6, 6.6.7, 6.6.8, 6.6.9, 6.6.10, 6.6.11, 6.6.12, 7.0.0, 7.0.1, 7.0.2, 7.0.3, 7.0.4, 7.0.5, 7.0.6, 7.0.7, 7.0.8, 7.0.9, 7.0.10, 7.0.11, 7.0.13, 7.1.0, 7.1.1, 7.1.2, 7.1.3, 7.1.4, 7.1.5, 7.1.6, 7.1.7, 7.1.8, 7.1.9, 7.1.10, 7.2.0, 7.2.1, 7.2.2, 7.2.3, 7.2.4, 7.2.5, 7.2.6, 7.2.7, 7.2.8, 7.2.9, 7.2.10, 7.3.0, 7.3.1, 7.3.2, 7.3.3, 7.3.4, 7.3.5, 8.0.0, 8.0.1, 8.0.2, 8.0.3, 8.0.4, 6.5.10, 6.5.2, 6.5.3


Was this documentation topic helpful?

Enter your email address, and someone from the documentation team will respond to you:

Please provide your comments here. Ask a question or make a suggestion.

You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters