percentiles_array

This page explains how to use the percentiles_array function in APL.

Use the percentiles_array aggregation function in APL to calculate multiple percentile values over a numeric expression in one pass. This function is useful when you want to understand the distribution of numeric data points, such as response times or durations, by summarizing them at several key percentiles like the 25th, 50th, and 95th.

You can use percentiles_array to:

• Analyze latency or duration metrics across requests or operations.
• Identify performance outliers.
• Visualize percentile distributions in dashboards.

For users of other query languages

If you come from other query languages, this section explains how to adjust your existing queries to achieve the same results in APL.

Splunk SPL users

In Splunk, you typically calculate percentiles one at a time using the perc function. To get multiple percentiles, you repeat the function with different percentile values. In APL, percentiles_array lets you specify multiple percentiles in a single function call and returns them as an array.

Splunk example

... | stats perc95(duration), perc50(duration), perc25(duration) by service

ANSI SQL users

Standard SQL typically lacks a built-in function to calculate multiple percentiles in a single operation. Instead, you use PERCENTILE_CONT or PERCENTILE_DISC with WITHIN GROUP, repeated for each desired percentile. In APL, percentiles_array simplifies this with a single function call that returns all requested percentiles as an array.

SQL example

SELECT
  service,
  PERCENTILE_CONT(0.25) WITHIN GROUP (ORDER BY duration) AS p25,
  PERCENTILE_CONT(0.50) WITHIN GROUP (ORDER BY duration) AS p50,
  PERCENTILE_CONT(0.95) WITHIN GROUP (ORDER BY duration) AS p95
FROM traces
GROUP BY service

Usage

Syntax

percentiles_array(Field, Percentile1, Percentile2, ...)

Parameters

• Field is the name of the field for which you want to compute percentile values.
• Percentile1, Percentile2, … are numeric percentile values between 0 and 100.

Returns

An array of numbers where each element is the value at the corresponding percentile.

Use case examples

Log analysis

Use percentiles_array to understand the spread of request durations per HTTP method, highlighting performance variability.

Query

['sample-http-logs']
| summarize percentiles_array(req_duration_ms, 25, 50, 95) by method

Run in Playground

Output

method	P25	P50	P95
GET	0.3981 ms	0.7352 ms	1.981 ms
POST	0.3261 ms	0.7162 ms	2.341 ms
PUT	0.3324 ms	0.7772 ms	1.341 ms
DELETE	0.2332 ms	0.4652 ms	1.121 ms

This query calculates the 25th, 50th, and 95th percentiles of request durations for each HTTP method. It helps identify performance differences between different methods.

List of related functions

• avg: Returns the average value. Use it when a single central tendency is sufficient.
• percentile: Returns a single percentile value. Use it when you only need one percentile.
• percentile_if: Returns a single percentile value for the records that satisfy a condition.
• percentiles_arrayif: Returns an array of percentile values for the records that satisfy a condition.
• sum: Returns the sum of a numeric column.