From ddf3839306081bb1aba24b9c42ee43ef9d7a50d1 Mon Sep 17 00:00:00 2001
From: coderashed <coderashed@gmail.com>
Date: Mon, 29 Jun 2026 22:26:34 +0000
Subject: [PATCH 1/3] feat(aggregate-functions): add quantileReq for
 relative-error quantiles
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add `quantileReq`, `quantilesReq`, and the `medianReq` alias: a streaming
quantile based on the Relative Error Quantiles (REQ) sketch from the bundled
DataSketches library.

Unlike `quantileTDigest` (no formal error bound) and `quantileGK` (flat
rank-error bound), REQ guarantees a relative rank error, so it stays accurate
at extreme quantiles such as p99.9. The sketch is fully mergeable, so it works
under partial and distributed aggregation.

Reference: Cormode, Karnin, Liberty, Thaler, Veselý, "Relative Error Streaming
Quantiles" (JACM 2023, https://dl.acm.org/doi/10.1145/3617891).
---
 contrib/datasketches-cpp-cmake/CMakeLists.txt |   1 +
 .../reference/quantileReq.md                  |  14 ++
 .../AggregateFunctionQuantile.h               |   4 +
 .../AggregateFunctionQuantileReq.cpp          | 114 +++++++++++++
 src/AggregateFunctions/QuantileReq.h          | 154 ++++++++++++++++++
 .../registerAggregateFunctions.cpp            |   2 +
 .../GatherFunctionQuantileVisitor.cpp         |   1 +
 .../0_stateless/04489_quantile_req.reference  |   9 +
 .../0_stateless/04489_quantile_req.sql        |  57 +++++++
 9 files changed, 356 insertions(+)
 create mode 100644 docs/en/sql-reference/aggregate-functions/reference/quantileReq.md
 create mode 100644 src/AggregateFunctions/AggregateFunctionQuantileReq.cpp
 create mode 100644 src/AggregateFunctions/QuantileReq.h
 create mode 100644 tests/queries/0_stateless/04489_quantile_req.reference
 create mode 100644 tests/queries/0_stateless/04489_quantile_req.sql

diff --git a/contrib/datasketches-cpp-cmake/CMakeLists.txt b/contrib/datasketches-cpp-cmake/CMakeLists.txt
index 497d6956d0ef..72327b56f8a9 100644
--- a/contrib/datasketches-cpp-cmake/CMakeLists.txt
+++ b/contrib/datasketches-cpp-cmake/CMakeLists.txt
@@ -10,6 +10,7 @@ add_library(_datasketches INTERFACE)
 target_include_directories(_datasketches SYSTEM BEFORE INTERFACE
     "${ClickHouse_SOURCE_DIR}/contrib/datasketches-cpp/common/include"
     "${ClickHouse_SOURCE_DIR}/contrib/datasketches-cpp/count/include"
+    "${ClickHouse_SOURCE_DIR}/contrib/datasketches-cpp/req/include"
     "${ClickHouse_SOURCE_DIR}/contrib/datasketches-cpp/theta/include")
 
 add_library(ch_contrib::datasketches ALIAS _datasketches)
diff --git a/docs/en/sql-reference/aggregate-functions/reference/quantileReq.md b/docs/en/sql-reference/aggregate-functions/reference/quantileReq.md
new file mode 100644
index 000000000000..e9aaa5e9e464
--- /dev/null
+++ b/docs/en/sql-reference/aggregate-functions/reference/quantileReq.md
@@ -0,0 +1,14 @@
+---
+description: 'Computes an approximate quantile of a sample using the Relative Error Quantiles (REQ) sketch, with a relative rank-error guarantee that stays accurate at extreme quantiles.'
+slug: /sql-reference/aggregate-functions/reference/quantilereq
+title: 'quantileReq'
+doc_type: 'reference'
+---
+
+<!--AUTOGENERATED_START-->
+<!--AUTOGENERATED_END-->
+
+**See Also**
+
+- [median](/sql-reference/aggregate-functions/reference/median)
+- [quantiles](../../../sql-reference/aggregate-functions/reference/quantiles.md)
diff --git a/src/AggregateFunctions/AggregateFunctionQuantile.h b/src/AggregateFunctions/AggregateFunctionQuantile.h
index d143211b60cb..ae40eb002417 100644
--- a/src/AggregateFunctions/AggregateFunctionQuantile.h
+++ b/src/AggregateFunctions/AggregateFunctionQuantile.h
@@ -29,6 +29,7 @@ namespace ErrorCodes
 template <typename> class QuantileTiming;
 template <typename> class QuantileGK;
 template <typename> class QuantileDD;
+template <typename> class QuantileReq;
 
 /** Generic aggregate function for calculation of quantiles.
   * It depends on quantile calculation data structure. Look at Quantile*.h for various implementations.
@@ -346,6 +347,9 @@ struct NameQuantilesGK { static constexpr auto name = "quantilesGK"; };
 struct NameQuantileDD { static constexpr auto name = "quantileDD"; };
 struct NameQuantilesDD { static constexpr auto name = "quantilesDD"; };
 
+struct NameQuantileReq { static constexpr auto name = "quantileReq"; };
+struct NameQuantilesReq { static constexpr auto name = "quantilesReq"; };
+
 struct NameQuantilePrometheusHistogram { static constexpr auto name = "quantilePrometheusHistogram"; };
 struct NameQuantilesPrometheusHistogram { static constexpr auto name = "quantilesPrometheusHistogram"; };
 
diff --git a/src/AggregateFunctions/AggregateFunctionQuantileReq.cpp b/src/AggregateFunctions/AggregateFunctionQuantileReq.cpp
new file mode 100644
index 000000000000..e468ad460a5a
--- /dev/null
+++ b/src/AggregateFunctions/AggregateFunctionQuantileReq.cpp
@@ -0,0 +1,114 @@
+#include "config.h"
+
+#include <AggregateFunctions/AggregateFunctionFactory.h>
+#include <AggregateFunctions/AggregateFunctionQuantile.h>
+
+#if USE_DATASKETCHES
+#include <AggregateFunctions/QuantileReq.h>
+#include <AggregateFunctions/Helpers.h>
+#include <DataTypes/DataTypeDate.h>
+#include <DataTypes/DataTypeDateTime.h>
+#include <Core/Field.h>
+#endif
+
+
+namespace DB
+{
+struct Settings;
+
+#if USE_DATASKETCHES
+
+namespace ErrorCodes
+{
+    extern const int TOO_FEW_ARGUMENTS_FOR_FUNCTION;
+    extern const int ILLEGAL_TYPE_OF_ARGUMENT;
+}
+
+namespace
+{
+
+template <typename Value, bool float_return> using FuncQuantileReq = AggregateFunctionQuantile<Value, QuantileReq<Value>, NameQuantileReq, void, std::conditional_t<float_return, Float64, void>, false, true>;
+template <typename Value, bool float_return> using FuncQuantilesReq = AggregateFunctionQuantile<Value, QuantileReq<Value>, NameQuantilesReq, void, std::conditional_t<float_return, Float64, void>, true, true>;
+
+
+template <template <typename, bool> class Function>
+AggregateFunctionPtr createAggregateFunctionQuantile(
+    const std::string & name, const DataTypes & argument_types, const Array & params, const Settings *)
+{
+    if (argument_types.empty())
+        throw Exception(ErrorCodes::TOO_FEW_ARGUMENTS_FOR_FUNCTION, "Aggregate function {} requires at least one argument", name);
+
+    const DataTypePtr & argument_type = argument_types[0];
+    WhichDataType which(argument_type);
+
+#define DISPATCH(TYPE) \
+    if (which.idx == TypeIndex::TYPE) return std::make_shared<Function<TYPE, true>>(argument_types, params);
+    FOR_BASIC_NUMERIC_TYPES(DISPATCH)
+#undef DISPATCH
+    if (which.idx == TypeIndex::Date) return std::make_shared<Function<DataTypeDate::FieldType, false>>(argument_types, params);
+    if (which.idx == TypeIndex::DateTime) return std::make_shared<Function<DataTypeDateTime::FieldType, false>>(argument_types, params);
+
+    throw Exception(ErrorCodes::ILLEGAL_TYPE_OF_ARGUMENT, "Illegal type {} of argument for aggregate function {}",
+                    argument_type->getName(), name);
+}
+
+}
+
+#endif
+
+void registerAggregateFunctionsQuantileReq(AggregateFunctionFactory & factory);
+void registerAggregateFunctionsQuantileReq(AggregateFunctionFactory & factory)
+{
+#if USE_DATASKETCHES
+    /// For aggregate functions returning array we cannot return NULL on empty set.
+    AggregateFunctionProperties properties = { .returns_default_when_only_null = true };
+
+    FunctionDocumentation::Description description = R"(
+Computes an approximate [quantile](https://en.wikipedia.org/wiki/Quantile) of a sample using the
+Relative Error Quantiles (REQ) sketch. Unlike `quantileTDigest` (no formal error bound) and
+`quantileGK` (flat rank-error bound), REQ guarantees a *relative* rank error, so it stays accurate
+at extreme quantiles such as p99.9. The sketch is fully mergeable, so it works under partial and
+distributed aggregation.
+
+Reference: "Relative Error Streaming Quantiles", Cormode, Karnin, Liberty, Thaler, Veselý
+(JACM 2023, https://dl.acm.org/doi/10.1145/3617891).
+    )";
+    FunctionDocumentation::Syntax syntax = R"(
+quantileReq(accuracy, [level])(expr)
+    )";
+    FunctionDocumentation::Arguments arguments = {
+        {"expr", "Column with numeric data.", {"(U)Int*", "Float*", "Date", "DateTime"}}
+    };
+    FunctionDocumentation::Parameters parameters = {
+        {"accuracy", "Accuracy of the sketch (the `k` parameter). A constant positive even integer; larger values mean less error and more memory. Odd values are rounded up. The recommended value is 12.", {"UInt*"}},
+        {"level", "Optional. Level of quantile. A constant floating-point number in the range from 0 to 1. Default value: 0.5.", {"Float*"}}
+    };
+    FunctionDocumentation::ReturnedValue returned_value = {"Approximate quantile of the specified level.", {"Float64"}};
+    FunctionDocumentation::Examples examples = {
+    {
+        "Computing a tail quantile with the REQ sketch",
+        R"(
+SELECT quantileReq(12, 0.999)(number) FROM numbers(1000000);
+        )",
+        R"(
+┌─quantileReq(12, 0.999)(number)─┐
+│                         999000 │
+└────────────────────────────────┘
+        )"
+    }
+    };
+    FunctionDocumentation::IntroducedIn introduced_in = {25, 7};
+    FunctionDocumentation::Category category = FunctionDocumentation::Category::AggregateFunction;
+    FunctionDocumentation documentation = {description, syntax, arguments, parameters, returned_value, examples, introduced_in, category};
+
+    factory.registerFunction(NameQuantileReq::name, {createAggregateFunctionQuantile<FuncQuantileReq>, documentation});
+    factory.registerFunction(NameQuantilesReq::name, { createAggregateFunctionQuantile<FuncQuantilesReq>, {}, properties });
+
+    /// 'median' is an alias for 'quantile'
+    factory.registerAlias("medianReq", NameQuantileReq::name);
+#else
+    (void)factory;
+#endif
+}
+
+}
diff --git a/src/AggregateFunctions/QuantileReq.h b/src/AggregateFunctions/QuantileReq.h
new file mode 100644
index 000000000000..6c0377aa0c18
--- /dev/null
+++ b/src/AggregateFunctions/QuantileReq.h
@@ -0,0 +1,154 @@
+#pragma once
+
+#include "config.h"
+
+#if USE_DATASKETCHES
+
+#include <base/types.h>
+#include <req_sketch.hpp>
+
+#include <IO/ReadBuffer.h>
+#include <IO/WriteBuffer.h>
+#include <IO/ReadHelpers.h>
+#include <IO/WriteHelpers.h>
+#include <Common/Exception.h>
+
+namespace DB
+{
+
+namespace ErrorCodes
+{
+    extern const int CORRUPTED_DATA;
+}
+
+/** Relative Error Quantiles (REQ) sketch — a fully-mergeable streaming quantile sketch with a
+  * *relative* rank-error guarantee, i.e. the rank error is proportional to the distance from the
+  * nearer tail rather than a flat fraction of the stream size. This makes it accurate at extreme
+  * quantiles (e.g. p99.9), where `QuantileTDigest` has no formal bound and `QuantileGK` only
+  * guarantees a flat rank error.
+  *
+  * Reference: "Relative Error Streaming Quantiles", Graham Cormode, Zohar Karnin, Edo Liberty,
+  * Justin Thaler, Pavel Veselý (PODS 2021; JACM 2023, https://dl.acm.org/doi/10.1145/3617891).
+  *
+  * Wraps `datasketches::req_sketch` from the bundled DataSketches library. The sketch is built in
+  * high-rank-accuracy (HRA) mode, which favours accuracy near rank 1.0 — the tail that matters for
+  * latency SLOs.
+  */
+template <typename Value>
+class QuantileReq
+{
+public:
+    using Item = Float64;
+    using Sketch = datasketches::req_sketch<Item>;
+
+    /// `k` controls accuracy and memory: larger means more accurate and larger. Must be even and
+    /// at least 4; DataSketches enforces this. Default mirrors the DataSketches default of 12.
+    QuantileReq() : sketch(default_k, /* hra */ true) { }
+
+    explicit QuantileReq(ssize_t k) : sketch(toK(k), /* hra */ true) { }
+
+    void add(const Value & x)
+    {
+        if (!isNaN(x))
+            sketch.update(static_cast<Item>(x));
+    }
+
+    void merge(const QuantileReq & other)
+    {
+        sketch.merge(other.sketch);
+    }
+
+    void serialize(WriteBuffer & buf) const
+    {
+        auto bytes = sketch.serialize();
+        writeVectorBinary(bytes, buf);
+    }
+
+    /// You can only call this for a freshly created object.
+    void deserialize(ReadBuffer & buf)
+    {
+        typename Sketch::vector_bytes bytes;
+        readVectorBinary(bytes, buf);
+        if (bytes.empty())
+            return;
+
+        try
+        {
+            sketch = Sketch::deserialize(bytes.data(), bytes.size());
+        }
+        catch (const DB::Exception &)
+        {
+            throw;
+        }
+        catch (const std::bad_alloc &)
+        {
+            /// Memory pressure is not data corruption; let it propagate.
+            throw;
+        }
+        catch (const std::exception & e)
+        {
+            /// `datasketches` throws `std::invalid_argument` / `std::out_of_range` on malformed
+            /// input. These are not `DB::Exception`, so without translation they escape
+            /// `SerializationAggregateFunction`'s `catch (...)`, reach the top level as
+            /// `LOGICAL_ERROR` (code 1001), and abort the process. Translate to `CORRUPTED_DATA`
+            /// so the bad input is rejected cleanly.
+            throw Exception(ErrorCodes::CORRUPTED_DATA, "Cannot deserialize REQ sketch state: {}", e.what());
+        }
+    }
+
+    Value get(Float64 level)
+    {
+        return getImpl<Value>(level);
+    }
+
+    void getMany(const Float64 * levels, const size_t * indices, size_t size, Value * result)
+    {
+        getManyImpl(levels, indices, size, result);
+    }
+
+    Float64 getFloat(Float64 level)
+    {
+        return getImpl<Float64>(level);
+    }
+
+    void getManyFloat(const Float64 * levels, const size_t * indices, size_t size, Float64 * result)
+    {
+        getManyImpl(levels, indices, size, result);
+    }
+
+private:
+    static constexpr uint16_t default_k = 12;
+
+    Sketch sketch;
+
+    static uint16_t toK(ssize_t k)
+    {
+        /// The aggregate-function layer only guarantees `k > 0`. Round up to an even value and
+        /// clamp to the range DataSketches accepts, so a user-supplied odd or tiny `k` does not
+        /// throw deep inside the sketch constructor.
+        if (k < 4)
+            return 4;
+        if (k > 65534)
+            return 65534;
+        return static_cast<uint16_t>(k % 2 == 0 ? k : k + 1);
+    }
+
+    template <typename T>
+    T getImpl(Float64 level)
+    {
+        if (sketch.is_empty())
+            return std::numeric_limits<T>::quiet_NaN();
+        return static_cast<T>(sketch.get_quantile(level));
+    }
+
+    template <typename T>
+    void getManyImpl(const Float64 * levels, const size_t *, size_t num_levels, T * result)
+    {
+        for (size_t i = 0; i < num_levels; ++i)
+            result[i] = getImpl<T>(levels[i]);
+    }
+};
+
+}
+
+#endif
diff --git a/src/AggregateFunctions/registerAggregateFunctions.cpp b/src/AggregateFunctions/registerAggregateFunctions.cpp
index a09eaa20461b..be076354acd4 100644
--- a/src/AggregateFunctions/registerAggregateFunctions.cpp
+++ b/src/AggregateFunctions/registerAggregateFunctions.cpp
@@ -38,6 +38,7 @@ void registerAggregateFunctionsQuantileTDigest(AggregateFunctionFactory &);
 void registerAggregateFunctionsQuantileTDigestWeighted(AggregateFunctionFactory &);
 void registerAggregateFunctionsQuantileBFloat16(AggregateFunctionFactory &);
 void registerAggregateFunctionsQuantileDD(AggregateFunctionFactory &);
+void registerAggregateFunctionsQuantileReq(AggregateFunctionFactory &);
 void registerAggregateFunctionsQuantileBFloat16Weighted(AggregateFunctionFactory &);
 void registerAggregateFunctionsQuantileApprox(AggregateFunctionFactory &);
 void registerAggregateFunctionsQuantilePrometheusHistogram(AggregateFunctionFactory &);
@@ -152,6 +153,7 @@ void registerAggregateFunctions()
         registerAggregateFunctionsQuantileTDigestWeighted(factory);
         registerAggregateFunctionsQuantileBFloat16(factory);
         registerAggregateFunctionsQuantileDD(factory);
+        registerAggregateFunctionsQuantileReq(factory);
         registerAggregateFunctionsQuantileBFloat16Weighted(factory);
         registerAggregateFunctionsQuantileApprox(factory);
         registerAggregateFunctionsQuantilePrometheusHistogram(factory);
diff --git a/src/Interpreters/GatherFunctionQuantileVisitor.cpp b/src/Interpreters/GatherFunctionQuantileVisitor.cpp
index c61298d07261..19c39ec31b93 100644
--- a/src/Interpreters/GatherFunctionQuantileVisitor.cpp
+++ b/src/Interpreters/GatherFunctionQuantileVisitor.cpp
@@ -39,6 +39,7 @@ static const std::unordered_map<String, String> quantile_fuse_name_mapping =
     {"quantileTiming", "quantilesTiming"},
     {"quantileTimingWeighted", "quantilesTimingWeighted"},
     {"quantileGK", "quantilesGK"},
+    {"quantileReq", "quantilesReq"},
 };
 
 String GatherFunctionQuantileData::toFusedNameOrSelf(const String & func_name)
diff --git a/tests/queries/0_stateless/04489_quantile_req.reference b/tests/queries/0_stateless/04489_quantile_req.reference
new file mode 100644
index 000000000000..329a4902de7f
--- /dev/null
+++ b/tests/queries/0_stateless/04489_quantile_req.reference
@@ -0,0 +1,9 @@
+1
+1	1	1	1
+1	1
+1
+1
+1
+1
+1
+1
diff --git a/tests/queries/0_stateless/04489_quantile_req.sql b/tests/queries/0_stateless/04489_quantile_req.sql
new file mode 100644
index 000000000000..88b5a5c57022
--- /dev/null
+++ b/tests/queries/0_stateless/04489_quantile_req.sql
@@ -0,0 +1,57 @@
+-- Tags: no-fasttest
+-- no-fasttest: quantileReq requires the DataSketches library, which is disabled in the fast test build.
+
+-- The Relative Error Quantiles (REQ) sketch: a fully-mergeable streaming quantile with a relative
+-- rank-error guarantee, accurate at extreme quantiles. See QuantileReq.h.
+-- Reference: Cormode, Karnin, Liberty, Thaler, Veselý, "Relative Error Streaming Quantiles"
+-- (JACM 2023, https://dl.acm.org/doi/10.1145/3617891).
+
+-- 1. Median sanity on a uniform stream 0..999.
+SELECT quantileReq(100, 0.5)(number) BETWEEN 470 AND 530 FROM numbers(1000);
+
+-- 2. Accuracy across several levels on a uniform stream 0..999999.
+--    For this distribution the true quantile at level p is p * 999999. REQ must land within a
+--    small relative error of the truth at each level.
+SELECT
+    abs(quantileReq(1000, 0.25)(number)  - 0.25 * 999999) / 999999 < 0.01,
+    abs(quantileReq(1000, 0.50)(number)  - 0.50 * 999999) / 999999 < 0.01,
+    abs(quantileReq(1000, 0.75)(number)  - 0.75 * 999999) / 999999 < 0.01,
+    abs(quantileReq(1000, 0.90)(number)  - 0.90 * 999999) / 999999 < 0.01
+FROM numbers(1000000);
+
+-- 3. Extreme-tail accuracy — the regime REQ exists for. p99.9 and p99.99 of 0..999999.
+SELECT
+    abs(quantileReq(1000, 0.999)(number)  - 0.999  * 999999) / 999999 < 0.01,
+    abs(quantileReq(1000, 0.9999)(number) - 0.9999 * 999999) / 999999 < 0.01
+FROM numbers(1000000);
+
+-- 4. Mergeability: the same tail quantile computed by merging many partial states (one per
+--    partition) must still honour the relative-error guarantee. Exercises serialize/deserialize
+--    + merge, i.e. the distributed-aggregation path.
+SELECT abs(quantileReqMerge(1000, 0.999)(s) - 0.999 * 999999) / 999999 < 0.01
+FROM
+(
+    SELECT quantileReqState(1000, 0.999)(number) AS s
+    FROM numbers(1000000)
+    GROUP BY number % 13
+);
+
+-- 5. Multiple levels in one call are returned in level order and are monotonically non-decreasing.
+SELECT arraySort(x -> x, q) = q
+FROM (SELECT quantilesReq(1000, 0.1, 0.5, 0.9, 0.99, 0.999)(number) AS q FROM numbers(1000000));
+
+-- 6. Edge cases — empty input yields NaN (not a logical error), a single value is returned exactly.
+SELECT isNaN(quantileReq(12, 0.5)(number)) FROM numbers(0);
+SELECT quantileReq(12, 0.5)(number) = 5 FROM numbers(5, 1);
+
+-- 7. Type coverage: DateTime arguments return a DateTime quantile.
+--    Median of [start .. start+999] seconds is ~ start + 500s = 00:08:20; allow a generous window.
+SELECT quantileReq(100, 0.5)(toDateTime('2020-01-01 00:00:00', 'UTC') + number)
+    BETWEEN toDateTime('2020-01-01 00:07:00', 'UTC') AND toDateTime('2020-01-01 00:09:40', 'UTC')
+FROM numbers(1000);
+
+-- 8. The 'median' alias is registered.
+SELECT medianReq(100, 0.5)(number) BETWEEN 470 AND 530 FROM numbers(1000);
+
+-- 9. The accuracy parameter is mandatory.
+SELECT quantileReq(number) FROM numbers(10); -- { serverError NUMBER_OF_ARGUMENTS_DOESNT_MATCH }

From 4aa81f0bdcac6af7aed0c084c85e8476e3be8405 Mon Sep 17 00:00:00 2001
From: coderashed <coderashed@gmail.com>
Date: Mon, 29 Jun 2026 23:39:19 +0000
Subject: [PATCH 2/3] test(aggregate-functions): expand quantileReq coverage

Extend the stateless test for `quantileReq` with small-input exactness
(no compaction yields exact order statistics), asymmetric and three-way
merge topologies, alongside the existing accuracy, extreme-tail,
mergeability, monotonicity, edge-case, type, and parameter-validation
checks.

Add `04490_quantile_req_corrupted_state.sh`: feeding a malformed
`AggregateFunction(quantileReq, ...)` state must be rejected as
`CORRUPTED_DATA` rather than aborting the process. Mirrors the existing
`04307_uniqTheta_corrupted_state_106259.sh`, covering both the RowBinary
and query-parameter deserialization paths.
---
 .../0_stateless/04489_quantile_req.reference  |  4 +++
 .../0_stateless/04489_quantile_req.sql        | 27 +++++++++++++++-
 ...490_quantile_req_corrupted_state.reference |  2 ++
 .../04490_quantile_req_corrupted_state.sh     | 31 +++++++++++++++++++
 4 files changed, 63 insertions(+), 1 deletion(-)
 create mode 100644 tests/queries/0_stateless/04490_quantile_req_corrupted_state.reference
 create mode 100755 tests/queries/0_stateless/04490_quantile_req_corrupted_state.sh

diff --git a/tests/queries/0_stateless/04489_quantile_req.reference b/tests/queries/0_stateless/04489_quantile_req.reference
index 329a4902de7f..46af8e8d3595 100644
--- a/tests/queries/0_stateless/04489_quantile_req.reference
+++ b/tests/queries/0_stateless/04489_quantile_req.reference
@@ -7,3 +7,7 @@
 1
 1
 1
+1
+1
+1
+1
diff --git a/tests/queries/0_stateless/04489_quantile_req.sql b/tests/queries/0_stateless/04489_quantile_req.sql
index 88b5a5c57022..7c2cb2f85188 100644
--- a/tests/queries/0_stateless/04489_quantile_req.sql
+++ b/tests/queries/0_stateless/04489_quantile_req.sql
@@ -53,5 +53,30 @@ FROM numbers(1000);
 -- 8. The 'median' alias is registered.
 SELECT medianReq(100, 0.5)(number) BETWEEN 470 AND 530 FROM numbers(1000);
 
--- 9. The accuracy parameter is mandatory.
+-- 9. Small inputs: when the data fits within the sketch's accuracy budget no compaction happens,
+--    so REQ returns exact order statistics. Median of 0..10 is 5, of 0..100 is 50.
+SELECT quantileReq(1000, 0.5)(number) = 5 FROM numbers(11);
+SELECT quantileReq(1000, 0.5)(number) = 50 FROM numbers(101);
+
+-- 10. Asymmetric merge (1 row vs 999999 rows) — the merged tail quantile still honours the bound.
+SELECT abs(quantileReqMerge(1000, 0.999)(s) - 0.999 * 999999) / 999999 < 0.01
+FROM
+(
+    SELECT quantileReqState(1000, 0.999)(number) AS s FROM numbers(1)
+    UNION ALL
+    SELECT quantileReqState(1000, 0.999)(number) AS s FROM numbers(1, 999999)
+);
+
+-- 11. Three-way merge of disjoint partitions covering 0..999999 — still honours the bound.
+SELECT abs(quantileReqMerge(1000, 0.999)(s) - 0.999 * 999999) / 999999 < 0.01
+FROM
+(
+    SELECT quantileReqState(1000, 0.999)(number) AS s FROM numbers(400000)
+    UNION ALL
+    SELECT quantileReqState(1000, 0.999)(number) AS s FROM numbers(400000, 400000)
+    UNION ALL
+    SELECT quantileReqState(1000, 0.999)(number) AS s FROM numbers(800000, 200000)
+);
+
+-- 12. The accuracy parameter is mandatory.
 SELECT quantileReq(number) FROM numbers(10); -- { serverError NUMBER_OF_ARGUMENTS_DOESNT_MATCH }
diff --git a/tests/queries/0_stateless/04490_quantile_req_corrupted_state.reference b/tests/queries/0_stateless/04490_quantile_req_corrupted_state.reference
new file mode 100644
index 000000000000..42eb14998cba
--- /dev/null
+++ b/tests/queries/0_stateless/04490_quantile_req_corrupted_state.reference
@@ -0,0 +1,2 @@
+OK rowbinary
+OK param
diff --git a/tests/queries/0_stateless/04490_quantile_req_corrupted_state.sh b/tests/queries/0_stateless/04490_quantile_req_corrupted_state.sh
new file mode 100755
index 000000000000..e54fb77fa0a3
--- /dev/null
+++ b/tests/queries/0_stateless/04490_quantile_req_corrupted_state.sh
@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+# Tags: no-fasttest
+# no-fasttest -- compiled w/o datasketches
+
+# Deserializing a malformed `AggregateFunction(quantileReq, ...)` state must not abort the
+# process. The `datasketches` REQ sketch throws a bare `std::out_of_range` / `std::invalid_argument`
+# on bad input; those are not `DB::Exception`, so without translation they escape
+# `SerializationAggregateFunction`'s `catch (...)`, reach the top level as `LOGICAL_ERROR`
+# (code 1001) and abort via `abortOnFailedAssertion`. `QuantileReq::deserialize` translates the
+# bare `std::exception` into `DB::Exception(CORRUPTED_DATA)` so the bad input is rejected cleanly.
+
+CUR_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+# shellcheck source=../shell_config.sh
+. "$CUR_DIR"/../shell_config.sh
+
+# RowBinary path. First byte 0x03 is a varint saying the sketch payload is 3 bytes long, which is
+# shorter than the REQ sketch preamble (8 bytes), so `datasketches::req_sketch::deserialize` throws.
+# Before the translation this aborted with SIGABRT (exit 134); now it must produce CORRUPTED_DATA.
+printf '\x03\x01\x02\x03' \
+    | $CLICKHOUSE_LOCAL --input-format=RowBinary \
+        --structure='x AggregateFunction(quantileReq(100, 0.5), UInt64)' \
+        --query='SELECT x FROM table' 2>&1 \
+    | grep -q -F 'CORRUPTED_DATA' && echo 'OK rowbinary' || echo 'FAIL rowbinary'
+
+# Query-parameter path: deserialised via `deserializeTextEscaped` rather than `deserializeBinary`,
+# but the eventual call into `QuantileReq::deserialize` is the same.
+$CLICKHOUSE_LOCAL \
+    --param_p=$'\x03\x01\x02\x03' \
+    --query='SELECT count() FROM numbers(1) WHERE {p:AggregateFunction(quantileReq(100, 0.5), UInt64)} IS NOT NULL' \
+    2>&1 \
+    | grep -q -F 'CORRUPTED_DATA' && echo 'OK param' || echo 'FAIL param'

From c03d0633d804a9e2a6e4f214be5e35e234820258 Mon Sep 17 00:00:00 2001
From: coderashed <coderashed@gmail.com>
Date: Mon, 29 Jun 2026 23:56:50 +0000
Subject: [PATCH 3/3] docs(aggregate-functions): document quantilesReq

Add inline `FunctionDocumentation` for `quantilesReq` and the standalone
`quantilesReq.md` reference page, mirroring `quantilesGK`. Previously the
plural was registered without documentation, so its autogenerated doc page
would have rendered empty. Also correct the `quantileReq` / `quantilesReq`
examples to show representative approximate output, since the REQ sketch is
randomized and does not return exact values.
---
 .../reference/quantilesReq.md                 |  9 ++++
 .../AggregateFunctionQuantileReq.cpp          | 47 +++++++++++++++++--
 2 files changed, 53 insertions(+), 3 deletions(-)
 create mode 100644 docs/en/sql-reference/aggregate-functions/reference/quantilesReq.md

diff --git a/docs/en/sql-reference/aggregate-functions/reference/quantilesReq.md b/docs/en/sql-reference/aggregate-functions/reference/quantilesReq.md
new file mode 100644
index 000000000000..a7efc33b100d
--- /dev/null
+++ b/docs/en/sql-reference/aggregate-functions/reference/quantilesReq.md
@@ -0,0 +1,9 @@
+---
+description: 'quantilesReq works similarly to quantileReq but allows us to calculate quantiles at different levels simultaneously and returns an array.'
+slug: /sql-reference/aggregate-functions/reference/quantilesReq
+title: 'quantilesReq'
+doc_type: 'reference'
+---
+
+<!--AUTOGENERATED_START-->
+<!--AUTOGENERATED_END-->
diff --git a/src/AggregateFunctions/AggregateFunctionQuantileReq.cpp b/src/AggregateFunctions/AggregateFunctionQuantileReq.cpp
index e468ad460a5a..bfbed58bd65a 100644
--- a/src/AggregateFunctions/AggregateFunctionQuantileReq.cpp
+++ b/src/AggregateFunctions/AggregateFunctionQuantileReq.cpp
@@ -86,13 +86,13 @@ quantileReq(accuracy, [level])(expr)
     FunctionDocumentation::ReturnedValue returned_value = {"Approximate quantile of the specified level.", {"Float64"}};
     FunctionDocumentation::Examples examples = {
     {
-        "Computing a tail quantile with the REQ sketch",
+        "Computing a tail quantile with the REQ sketch (result is approximate)",
         R"(
 SELECT quantileReq(12, 0.999)(number) FROM numbers(1000000);
         )",
         R"(
 ┌─quantileReq(12, 0.999)(number)─┐
-│                         999000 │
+│                         998999 │
 └────────────────────────────────┘
         )"
     }
@@ -102,7 +102,48 @@ SELECT quantileReq(12, 0.999)(number) FROM numbers(1000000);
     FunctionDocumentation documentation = {description, syntax, arguments, parameters, returned_value, examples, introduced_in, category};
 
     factory.registerFunction(NameQuantileReq::name, {createAggregateFunctionQuantile<FuncQuantileReq>, documentation});
-    factory.registerFunction(NameQuantilesReq::name, { createAggregateFunctionQuantile<FuncQuantilesReq>, {}, properties });
+
+    FunctionDocumentation::Description description_quantiles = R"(
+Computes multiple approximate [quantiles](https://en.wikipedia.org/wiki/Quantile) of a sample at
+different levels simultaneously using the Relative Error Quantiles (REQ) sketch.
+
+This function works similarly to [`quantileReq`](/sql-reference/aggregate-functions/reference/quantileReq)
+but allows computing multiple quantile levels in a single pass, which is more efficient than calling
+individual quantile functions. Like `quantileReq`, it guarantees a *relative* rank error, so it stays
+accurate at extreme quantiles such as p99.9, and is fully mergeable for distributed aggregation.
+
+Reference: "Relative Error Streaming Quantiles", Cormode, Karnin, Liberty, Thaler, Veselý
+(JACM 2023, https://dl.acm.org/doi/10.1145/3617891).
+    )";
+    FunctionDocumentation::Syntax syntax_quantiles = R"(
+quantilesReq(accuracy, level1, level2, ...)(expr)
+    )";
+    FunctionDocumentation::Arguments arguments_quantiles = {
+        {"expr", "Column with numeric data.", {"(U)Int*", "Float*", "Date", "DateTime"}}
+    };
+    FunctionDocumentation::Parameters parameters_quantiles = {
+        {"accuracy", "Accuracy of the sketch (the `k` parameter). A constant positive even integer; larger values mean less error and more memory. Odd values are rounded up. The recommended value is 12.", {"UInt*"}},
+        {"level", "Levels of quantiles. One or more constant floating-point numbers from 0 to 1.", {"Float*"}}
+    };
+    FunctionDocumentation::ReturnedValue returned_value_quantiles = {"Array of quantiles of the specified levels in the same order as the levels were specified.", {"Array(Float64)", "Array(Date)", "Array(DateTime)"}};
+    FunctionDocumentation::Examples examples_quantiles = {
+    {
+        "Computing multiple tail quantiles with the REQ sketch (results are approximate)",
+        R"(
+SELECT quantilesReq(12, 0.5, 0.99, 0.999)(number) FROM numbers(1000000);
+        )",
+        R"(
+┌─quantilesReq(12, 0.5, 0.99, 0.999)(number)─┐
+│ [501294,989998,998999]                     │
+└────────────────────────────────────────────┘
+        )"
+    }
+    };
+    FunctionDocumentation::IntroducedIn introduced_in_quantiles = {25, 7};
+    FunctionDocumentation::Category category_quantiles = FunctionDocumentation::Category::AggregateFunction;
+    FunctionDocumentation documentation_quantiles = {description_quantiles, syntax_quantiles, arguments_quantiles, parameters_quantiles, returned_value_quantiles, examples_quantiles, introduced_in_quantiles, category_quantiles};
+
+    factory.registerFunction(NameQuantilesReq::name, {createAggregateFunctionQuantile<FuncQuantilesReq>, documentation_quantiles, properties});
 
     /// 'median' is an alias for 'quantile'
     factory.registerAlias("medianReq", NameQuantileReq::name);