Percentile Ranks Aggregation

edit

Percentile Ranks Aggregation

edit

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.

This functionality is in technical preview and may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features.

Please see Percentiles are (usually) approximate and 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:

{
    "aggs" : {
        "load_time_outlier" : {
            "percentile_ranks" : {
                "field" : "load_time", 
                "values" : [15, 30]
            }
        }
    }
}

The field load_time must be a numeric field

The response will look like this:

{
    ...

   "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

edit

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:

{
    "aggs" : {
        "load_time_outlier" : {
            "percentile_ranks" : {
                "values" : [3, 5],
                "script" : "doc['load_time'].value / timeUnit", 
                "params" : {
                    "timeUnit" : 1000   
                }
            }
        }
    }
}

The field parameter is replaced with a script parameter, which uses the script to generate values which percentile ranks are calculated on

Scripting supports parameterized input just like any other script

The script parameter expects an inline script. Use script_id for indexed scripts and script_file for scripts in the config/scripts/ directory.