OpenSearch/docs/reference/aggregations/metrics/percentile-rank-aggregation.asciidoc

[[search-aggregations-metrics-percentile-rank-aggregation]]
=== Percentile Ranks Aggregation

A `multi-value` metrics aggregation that calculates one or more percentile ranks
over numeric values extracted from the aggregated documents.  These values
can be extracted either from specific numeric fields in the documents, or
be generated by a provided script.

[NOTE]
==================================================
Please see <<search-aggregations-metrics-percentile-aggregation-approximation>>
and <<search-aggregations-metrics-percentile-aggregation-compression>> for advice
regarding approximation and memory use of the percentile ranks aggregation
==================================================

Percentile rank show the percentage of observed values which are below certain
value.  For example, if a value is greater than or equal to 95% of the observed values
it is said to be at the 95th percentile rank.

Assume your data consists of website load times.  You may have a service agreement that
95% of page loads completely within 15ms and 99% of page loads complete within 30ms.

Let's look at a range of percentiles representing load time:

[source,js]
--------------------------------------------------
{
    "aggs" : {
        "load_time_outlier" : {
            "percentile_ranks" : {
                "field" : "load_time", <1>
                "values" : [15, 30]
            }
        }
    }
}
--------------------------------------------------
<1> The field `load_time` must be a numeric field

The response will look like this:

[source,js]
--------------------------------------------------
{
    ...

   "aggregations": {
      "load_time_outlier": {
         "values" : {
            "15": 92,
            "30": 100
         }
      }
   }
}
--------------------------------------------------

From this information you can determine you are hitting the 99% load time target but not quite
hitting the 95% load time target


==== Script

The percentile rank metric supports scripting.  For example, if our load times
are in milliseconds but we want to specify values in seconds, we could use
a script to convert them on-the-fly:

[source,js]
--------------------------------------------------
{
    "aggs" : {
        "load_time_outlier" : {
            "percentile_ranks" : {
                "values" : [3, 5],
                "script" : {
                    "inline": "doc['load_time'].value / timeUnit", <1>
                    "params" : {
                        "timeUnit" : 1000   <2>
                    }
                }
            }
        }
    }
}
--------------------------------------------------
<1> The `field` parameter is replaced with a `script` parameter, which uses the
script to generate values which percentile ranks are calculated on
<2> Scripting supports parameterized input just like any other script

This will interpret the `script` parameter as an `inline` script with the default script language and no script parameters. To use a file script use the following syntax:

[source,js]
--------------------------------------------------
{
    "aggs" : {
        "load_time_outlier" : {
            "percentile_ranks" : {
                "values" : [3, 5],
                "script" : {
                    "file": "my_script",
                    "params" : {
                        "timeUnit" : 1000
                    }
                }
            }
        }
    }
}
--------------------------------------------------

TIP: for indexed scripts replace the `file` parameter with an `id` parameter.

==== HDR Histogram

experimental[]

https://github.com/HdrHistogram/HdrHistogram[HDR Histogram] (High Dynamic Range Histogram) is an alternative implementation 
that can be useful when calculating percentile ranks for latency measurements as it can be faster than the t-digest implementation 
with the trade-off of a larger memory footprint. This implementation maintains a fixed worse-case percentage error (specified as a 
number of significant digits). This means that if data is recorded with values from 1 microsecond up to 1 hour (3,600,000,000 
microseconds) in a histogram set to 3 significant digits, it will maintain a value resolution of 1 microsecond for values up to 
1 millisecond and 3.6 seconds (or better) for the maximum tracked value (1 hour).

The HDR Histogram can be used by specifying the `method` parameter in the request:

[source,js]
--------------------------------------------------
{
    "aggs" : {
        "load_time_outlier" : {
            "percentile_ranks" : {
                "field" : "load_time",
                "values" : [15, 30],
                "method" : "hdr", <1>
                "number_of_significant_value_digits" : 3 <2>
            }
        }
    }
}
--------------------------------------------------
<1> The `method` parameter is set to `hdr` to indicate that HDR Histogram should be used to calculate the percentile_ranks
<2> `number_of_significant_value_digits` specifies the resolution of values for the histogram in number of significant digits

The HDRHistogram only supports positive values and will error if it is passed a negative value. It is also not a good idea to use 
the HDRHistogram if the range of values is unknown as this could lead to high memory usage.

==== Missing value

The `missing` parameter defines how documents that are missing a value should be treated.
By default they will be ignored but it is also possible to treat them as if they
had a value.

[source,js]
--------------------------------------------------
{
    "aggs" : {
        "grade_ranks" : {
            "percentile_ranks" : {
                "field" : "grade",
                "missing": 10 <1>
            }
        }
    }
}
--------------------------------------------------

<1> Documents without a value in the `grade` field will fall into the same bucket as documents that have the value `10`.