head

import { Aside } from ‘@astrojs/starlight/components’;

The head command returns the first N results from a search result. The default number of results is 10. An optional offset skips a specified number of results before returning, enabling simple pagination.

head is commonly placed at the end of a pipeline after sort to implement top-N queries (for example, “show the 10 slowest traces”). During exploration, always use head to limit the volume of data scanned and returned.

The `head` command is not rewritten to query DSL. It is executed on the coordinating node.

Syntax

head [<size>] [from <offset>]

Arguments

Argument	Required	Type	Default	Description
<size>	No	Integer	10	The number of results to return. Must be a positive integer.
<offset>	No	Integer	0	The number of results to skip before returning. Used with the from keyword. Must be a non-negative integer.

Usage notes

• Always use during exploration. Adding head at the end of a query prevents scanning the entire result set when you only need a sample.
• Combine with sort for top-N patterns. The idiomatic way to get “top N by some metric” in PPL is sort - <field> | head N.
• Offset enables simple pagination. Use head <size> from <offset> to page through results. For example, head 10 from 20 returns results 21 through 30.
• Order matters. head operates on whatever the pipeline has produced up to that point. Placing it before sort limits the rows that get sorted; placing it after sort limits the sorted output.

Examples

Return the default number of results

Return the first 10 log entries (the default):

| head

Try in playground →

Return a specific number of results

Return the first 50 results:

| head 50

Try in playground →

Skip results with an offset

Return 10 results starting from the 21st result (skip the first 20):

| head 10 from 20

Try in playground →

Top-N pattern: slowest traces

Combine sort and head to find the 10 slowest spans:

source = otel-v1-apm-span-*
| sort - durationInNanos
| head 10

Try in Playground

Top-N pattern: services with the most errors (OTel logs)

Count error logs per service, sort descending, and return the top 5:

| where severityText = 'ERROR'
| stats count() as error_count by `resource.attributes.service.name`
| sort - error_count
| head 5

Try in playground →

Extended examples

Paginate through recent error logs

Page through error logs 20 at a time. This query returns the second page (results 21-40):

| where severityText = 'ERROR'
| sort - time
| head 20 from 20

Try in playground →

Sample logs from each OTel service

Get a quick sample of 5 logs per service by combining dedup and head:

source = logs-otel-v1*
| dedup 5 `resource.attributes.service.name`
| sort - time

Try in playground →

This is useful for initial exploration of what data each service is producing, without scanning the entire index.

See also

• sort - Sort results before applying head for top-N queries
• dedup - Deduplicate results for unique combinations
• PPL Command Reference - All PPL commands
• Observability Examples - Real-world OTel queries