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
• OpenTelemetry traces
• Security logs

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.

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.

Use percentiles_array to analyze the distribution of span durations by service to detect potential bottlenecks.

Query

['otel-demo-traces']
| summarize percentiles_array(duration, 50, 90, 99) by ['service.name']

Run in Playground

Output

service.name	P50	P90	P99	P99
recommendationservice	1.96 ms	2.965 ms	3.477 ms	3.477 ms
frontendproxy	3.767 ms	13.101 ms	39.735 ms	39.735 ms
shippingservice	2.119 ms	3.085 ms	9.739 ms	9.739 ms
checkoutservice	1.454 ms	12.342 ms	29.542 ms	29.542 ms

This query shows latency patterns across services by computing the median, 90th, and 99th percentile of span durations.

Use percentiles_array to assess outlier response times per status code, which can reveal abnormal activity or service issues.

Query

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

Run in Playground

Output

status	P50	P95	P99
200	0.7352 ms	1.981 ms	2.612 ms
201	0.7856 ms	1.356 ms	2.234 ms
301	0.8956 ms	1.547 ms	2.546 ms
500	0.6587 ms	1.856 ms	2.856 ms

This query helps identify whether requests resulting in errors (like 500) are significantly slower than successful ones.

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.