Percentile ranks aggregation #

A multi-value metrics aggregation that answers the inverse of percentiles: for each value you provide, what percentage of documents is at or below it.

How it works #

The engine collects every value of the field and sorts it once. For each requested value v, the rank is the fraction of collected values that are less than or equal to v:

rank(v) = count(value <= v) / n * 100

The comparison is inclusive — a document exactly at v counts toward its own rank, so the rank of the maximum value is 100, not 100 − 1/n. With no values at all (empty result set, or every document missing the field) each rank is null.

This engine computes ranks exactly over the collected values — there is no hdr option to configure. When a query fans out, the raw sorted values travel to the coordinator and the ranks are recomputed there, so the result is exact regardless of parallelism.

Examples #

Where do the prices 30 and 45 sit in the distribution?

30 is at rank 75 (75% of documents cost 30 or less), 45 at ≈91.7.

POST /sales/_search
{
  "aggs": {
    "price_ranks": {
      "percentile_ranks": {
        "field": "price",
        "values": [30, 45]
      }
    }
  }
}

Response — keyed by the requested values:

{
  ...
  "aggregations": {
    "price_ranks": {
      "values": {
        "30.0": 75.0,
        "45.0": 91.66666666666667
      }
    }
  }
}

The count behind each number: 90 of the 120 sale prices are <= 30 (every 15 and every 30), and 110 are <= 45.

Use cases #

• SLA / SLO dashboards. “What fraction of requests finished within 500ms?” is a percentile rank, evaluated at one threshold. Feed it the latency cutoff and read the compliance percentage straight out.
• Threshold tuning. Evaluating ranks at several candidate thresholds ([100, 200, 500, 1000]) shows how the population distributes across cutoffs — often clearer than a histogram for decision-making.
• Grading and scoring. “A score of 45 beats 91.7% of the entries” — any leaderboard or test-score question is a rank at a value.
• Sharing numbers safely. Percentiles leak the values of individuals (the p99 is a real observation); a percentile rank discloses only the value you already chose, which is often all an external report needs.

Parameters for percentile_ranks #

• field
  (Required, string) Numeric field you wish to aggregate.
• values
  (Required, number array) Values whose ranks you want. Each becomes one key in the response.
• missing
  (Optional, number) Value substituted for documents without the field.

Related #

• percentiles — the forward direction: which value is at the p-th percentage. These two are inverse functions of each other.
• boxplot — the quartile ranks (25/50/75) materialized as values.
• extended_stats — parametric alternatives (mean, standard deviation) for the same distribution questions.