ClickHouse/docs/en/sql-reference/aggregate-functions/reference/quantiles.md

slug	sidebar_position
/en/sql-reference/aggregate-functions/reference/quantiles	201

quantiles Functions

quantiles

Syntax: quantiles(level1, level2, …)(x)

All the quantile functions also have corresponding quantiles functions: quantiles, quantilesDeterministic, quantilesTiming, quantilesTimingWeighted, quantilesExact, quantilesExactWeighted, quantileInterpolatedWeighted, quantilesTDigest, quantilesBFloat16. These functions calculate all the quantiles of the listed levels in one pass, and return an array of the resulting values.

quantilesExactExclusive

Exactly computes the quantiles of a numeric data sequence.

To get exact value, all the passed values ​​are combined into an array, which is then partially sorted. Therefore, the function consumes O(n) memory, where n is a number of values that were passed. However, for a small number of values, the function is very effective.

This function is equivalent to PERCENTILE.EXC Excel function, (type R6).

Works more efficiently with sets of levels than quantileExactExclusive.

Syntax

quantilesExactExclusive(level1, level2, ...)(expr)

Arguments

• expr — Expression over the column values resulting in numeric data types, Date or DateTime.

Parameters

• level — Levels of quantiles. Possible values: (0, 1) — bounds not included. Float.

Returned value

• Array of quantiles of the specified levels.

Type of array values:

• Float64 for numeric data type input.
• Date if input values have the Date type.
• DateTime if input values have the DateTime type.

Example

Query:

CREATE TABLE num AS numbers(1000);

SELECT quantilesExactExclusive(0.25, 0.5, 0.75, 0.9, 0.95, 0.99, 0.999)(x) FROM (SELECT number AS x FROM num);

Result:

┌─quantilesExactExclusive(0.25, 0.5, 0.75, 0.9, 0.95, 0.99, 0.999)(x)─┐
│ [249.25,499.5,749.75,899.9,949.9499999999999,989.99,998.999]        │
└─────────────────────────────────────────────────────────────────────┘

quantilesExactInclusive

Exactly computes the quantiles of a numeric data sequence.

To get exact value, all the passed values ​​are combined into an array, which is then partially sorted. Therefore, the function consumes O(n) memory, where n is a number of values that were passed. However, for a small number of values, the function is very effective.

This function is equivalent to PERCENTILE.INC Excel function, (type R7).

Works more efficiently with sets of levels than quantileExactInclusive.

Syntax

quantilesExactInclusive(level1, level2, ...)(expr)

Arguments

• expr — Expression over the column values resulting in numeric data types, Date or DateTime.

Parameters

• level — Levels of quantiles. Possible values: [0, 1] — bounds included. Float.

Returned value

• Array of quantiles of the specified levels.

Type of array values:

• Float64 for numeric data type input.
• Date if input values have the Date type.
• DateTime if input values have the DateTime type.

Example

Query:

CREATE TABLE num AS numbers(1000);

SELECT quantilesExactInclusive(0.25, 0.5, 0.75, 0.9, 0.95, 0.99, 0.999)(x) FROM (SELECT number AS x FROM num);

Result:

┌─quantilesExactInclusive(0.25, 0.5, 0.75, 0.9, 0.95, 0.99, 0.999)(x)─┐
│ [249.75,499.5,749.25,899.1,949.05,989.01,998.001]                   │
└─────────────────────────────────────────────────────────────────────┘

quantilesApprox

quantilesApprox works similarly with quantileApprox but allows us to calculate quantities at different levels simultaneously and returns an array.

Syntax

quantilesApprox(accuracy, level1, level2, ...)(expr)

Returned value

• Array of quantiles of the specified levels.

Type of array values:

• Float64 for numeric data type input.
• Date if input values have the Date type.
• DateTime if input values have the DateTime type.

Example

Query:

SELECT quantilesApprox(1, 0.25, 0.5, 0.75)(number + 1)
FROM numbers(1000)

┌─quantilesApprox(1, 0.25, 0.5, 0.75)(plus(number, 1))─┐
│ [1,1,1]                                              │
└──────────────────────────────────────────────────────┘

SELECT quantilesApprox(10, 0.25, 0.5, 0.75)(number + 1)
FROM numbers(1000)

┌─quantilesApprox(10, 0.25, 0.5, 0.75)(plus(number, 1))─┐
│ [156,413,659]                                         │
└───────────────────────────────────────────────────────┘


SELECT quantilesApprox(100, 0.25, 0.5, 0.75)(number + 1)
FROM numbers(1000)

┌─quantilesApprox(100, 0.25, 0.5, 0.75)(plus(number, 1))─┐
│ [251,498,741]                                          │
└────────────────────────────────────────────────────────┘

SELECT quantilesApprox(1000, 0.25, 0.5, 0.75)(number + 1)
FROM numbers(1000)

┌─quantilesApprox(1000, 0.25, 0.5, 0.75)(plus(number, 1))─┐
│ [249,499,749]                                           │
└─────────────────────────────────────────────────────────┘