> ## Documentation Index
> Fetch the complete documentation index at: https://axiom.co/docs/llms.txt
> Use this file to discover all available pages before exploring further.

<AgentInstructions>

## Submitting Feedback

If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:

POST https://axiom.co/docs/feedback

```json
{
  "path": "/apl/aggregation-function/percentiles-arrayif",
  "feedback": "Description of the issue"
}
```

Only submit feedback when you have something specific and actionable to report.

</AgentInstructions>

# percentiles_arrayif

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

Use `percentiles_arrayif` to calculate approximate percentile values for a numeric expression when a certain condition evaluates to true. This function is useful when you want an array of percentiles instead of a single percentile. You can use it to understand data distributions in scenarios such as request durations, event processing times, or security alert severities, while filtering on specific criteria.

## 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.

<AccordionGroup>
  <Accordion title="Splunk SPL users">
    In Splunk SPL, you often use statistical functions such as `perc<percent>` or `percN()` to compute percentile estimates. In APL, you use `percentiles_arrayif` and provide a predicate to define which records to include in the computation.

    <CodeGroup>
      ```sql Splunk example theme={null}
      index=main sourcetype=access_combined
      | stats perc90(req_duration_ms) AS p90, perc99(req_duration_ms) AS p99
      ```

      ```kusto APL equivalent theme={null}
      ['sample-http-logs']
      | summarize Dist=percentiles_arrayif(req_duration_ms, dynamic([90, 99]), status == '200')
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="ANSI SQL users">
    In ANSI SQL, you often use window functions like `PERCENTILE_DISC` or `PERCENTILE_CONT` or write multiple `CASE` expressions for conditional aggregation. In APL, you can achieve similar functionality with `percentiles_arrayif` by passing the numeric field and condition to the function.

    <CodeGroup>
      ```sql SQL example theme={null}
      SELECT
        PERCENTILE_DISC(0.90) WITHIN GROUP (ORDER BY req_duration_ms) AS p90,
        PERCENTILE_DISC(0.99) WITHIN GROUP (ORDER BY req_duration_ms) AS p99
      FROM sample_http_logs
      WHERE status = '200';
      ```

      ```kusto APL equivalent theme={null}
      ['sample-http-logs']
      | summarize Dist=percentiles_arrayif(req_duration_ms, dynamic([90, 99]), status == '200')
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

# Usage

## Syntax

```kusto theme={null}
percentiles_arrayif(Field, Array, Condition)
```

## Parameters

* `Field` is the name of the field for which you want to compute percentile values.
* `Array` is a dynamic array of one or more numeric percentile values (between 0 and 100).
* `Condition` is a Boolean expression that indicates which records to include in the calculation.

## Returns

The function returns an array of percentile values for the records that satisfy the condition. The position of each returned percentile in the array matches the order in which it appears in the function call.

## Use case examples

<Tabs>
  <Tab title="Log analysis">
    You can use `percentiles_arrayif` to analyze request durations in HTTP logs while filtering for specific criteria, such as certain HTTP statuses or geographic locations.

    **Query**

    ```kusto theme={null}
    ['sample-http-logs']
    | summarize percentiles_arrayif(req_duration_ms, dynamic([50, 90, 95, 99]), status == '200') by bin_auto(_time)
    ```

    [Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B'sample-http-logs'%5D%20%7C%20summarize%20percentiles_arrayif\(req_duration_ms%2C%20dynamic\(%5B50%2C%2090%2C%2095%2C%2099%5D\)%2C%20status%20%3D%3D%20'200'\)%20by%20bin_auto\(_time\)%22%7D)

    **Output**

    | percentiles\_req\_duration\_ms |
    | ------------------------------ |
    | 0.7352 ms                      |
    | 1.691 ms                       |
    | 1.981 ms                       |
    | 2.612 ms                       |

    This query filters records to those with a status of 200 and returns the percentile values for the request durations.
  </Tab>

  <Tab title="OpenTelemetry traces">
    Use `percentiles_arrayif` to track performance of spans and filter on a specific service operation. This lets you quickly gauge how request durations differ for incoming traffic.

    **Query**

    ```kusto theme={null}
    ['otel-demo-traces']
    | summarize percentiles_arrayif(duration, dynamic([50, 90, 99, 99]), ['method'] == "POST") by bin_auto(_time)
    ```

    [Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B'otel-demo-traces'%5D%20%7C%20summarize%20percentiles_arrayif\(duration%2C%20dynamic\(%5B50%2C%2090%2C%2099%2C%2099%5D\)%2C%20%5B'method'%5D%20%3D%3D%20'POST'\)%20by%20bin_auto\(_time\)%22%7D)

    **Output**

    | percentiles\_duration |
    | --------------------- |
    | 5.166 ms              |
    | 25.18 ms              |
    | 71.996 ms             |

    This query returns the percentile values for span durations for requests with the POST method.
  </Tab>

  <Tab title="Security logs">
    You can focus on server issues by filtering for specific status codes, then see how request durations are distributed in those scenarios.

    **Query**

    ```kusto theme={null}
    ['sample-http-logs']
    | summarize percentiles_arrayif(req_duration_ms, dynamic([50, 90, 95, 99]), status startswith '5') by bin_auto(_time)
    ```

    [Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B'sample-http-logs'%5D%20%7C%20summarize%20percentiles_arrayif\(req_duration_ms%2C%20dynamic\(%5B50%2C%2090%2C%2095%2C%2099%5D\)%2C%20status%20startswith%20'5'\)%20by%20bin_auto\(_time\)%22%7D)

    **Output**

    | percentiles\_req\_duration\_ms |
    | ------------------------------ |
    | 0.7352 ms                      |
    | 1.691 ms                       |
    | 1.981 ms                       |
    | 2.612 ms                       |

    This query calculates percentile values for request durations that return a status code starting with 5 which means server error.
  </Tab>
</Tabs>

## List of related functions

* [avg](/apl/aggregation-function/avg): Returns the average of a numeric column.
* [percentile](/apl/aggregation-function/percentile): Returns a single percentile value.
* [percentile\_if](/apl/aggregation-function/percentileif): Returns a single percentile value for the records that satisfy a condition.
* [percentiles\_array](/apl/aggregation-function/percentiles-array): Returns an array of percentile values for all rows.
* [sum](/apl/aggregation-function/sum): Returns the sum of a numeric column.