## `percentile()`

Calculates percentiles over a given collection of numbers.

ParameterTypeRequiredDefaultDescription
`accuracy`doubleoptional[a]`0.01` Provided as a relative error threshold. Can be between >0 and <1: values closer to 1 means lower accuracy, values closer to 0 means higher accuracy.
`as`stringoptional[a]  Prefix of output fields.
`field`[b]stringrequired  Specifies the field for which to calculate percentiles. The field must contain numbers.
`percentiles`Array of numbersoptional[a]`[50, 75, 99]` Specifies which percentiles to calculate.

[a] Optional parameters use their default value unless explicitly set

[b] The argument name `field` can be omitted.

Omitted Argument Names

The argument name for `field` can be omitted; the following forms of this function are equivalent:

logscale
``percentile("field")``

and:

logscale
``percentile(field="field")``

These examples show basic structure only; full examples are provided below.

A percentile is a comparison value between a particular value and the values of the rest of a group. This enables the identification of scores that a particular score surpassed. For example, with a value of 75 ranked in the 85th percentile, it means that the score 75 is higher than 85% of the values of the entire group. This can be used to determine threshold and limits for triggering events or scoring probabilities and threats.

For example, given the values 12, 25, 50 and 99, the 50th percentile would be 25.79. That is, a value above 25.79 would be higher than 50% of the values.

The function returns one event with a field for each of the percentiles specified in the `percentiles` parameter. Fields are named like by prepending _ to the values specified in the `percentiles` parameter. For example the event could contain the fields _50, _75 and _99.

The following conditions apply when using this function:

• The function only works on non-negative input values.

• The `accuracy` argument specifies the accuracy of the percentile relative to the number estimated and is intended as a relative error tolerance (lower values implies a better accuracy). Some examples:

• An `accuracy` of `0.001` means that the percentiles are accurate to 0.1% of the actual value.

For example, with an original value of 1000 the value would be betwen 999 and 1001 (`1000-1000/1000` and (`1000+1000/1000`)).

• An `accuracy` of `0.01` means accuracy to 1/100 of the original value.

For example, with an original value of 1000 the value between 990 and 1010 ((`1000-1000/100` and (`1000+1000/100`)).

With an original value of 500 the value would be between 495 and 505 ((`500-500/100` and `500+500/100`)).

### Important

Higher `accuracy` implies a high memory usage. Be careful to choose the accuracy for the kind of precision they need from the expected output value. Lower percentiles are discarded if the memory usage becomes too high. If your percentiles seems off, try reducing the accuracy.

### `percentile()` Examples

Calculate the 50th,75th,99th and 99.9th percentiles for events with the field responsetime:

logscale
``percentile(field=responsetime, percentiles=[50, 75, 99, 99.9])``

In a timechart, calculate percentiles for both of the fields r1 and r2.

logscale
``timechart(function=[percentile(field=r1,as=r1),percentile(field=r2,as=r2)])``

To calculate the median for a given value, use `percentile()` with `percentiles` set to `50`:

logscale
``percentile(field=allocBytes,percentiles=[50],as=median)``

This creates the field median_50 with the 50th percentile value.