> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-vortex-format.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> 在等间隔时间网格上计算 PromQL `quantile_over_time`。

# timeSeriesQuantileToGrid

<h2 id="timeSeriesQuantileToGrid">
  timeSeriesQuantileToGrid
</h2>

引入版本：v26.9.0

聚合函数，接收由时间戳和值组成的时间序列数据对，并在由起始时间戳、结束时间戳和步长定义的等间隔时间网格上计算 [PromQL `quantile_over_time`](https://prometheus.io/docs/prometheus/latest/querying/functions/#quantile_over_time) 函数。对于网格上的每个点，会选取指定时间窗口内的样本来计算分位数。分位数采用 R-7 (包含边界) 方法计算，与 `quantileExactInclusive` 相同。但与 `quantileExactInclusive` 不同，NaN 样本不会被跳过：与 Prometheus 一致，这些样本会被保留，并排在所有实际值之前。因此，窗口 `[1, NaN, 2]` 的中位数为 `1`，而样本全为 NaN 的窗口结果为 NaN。

分位数级别作为最后一个参数，紧跟在样本之后：可以是适用于所有网格点的单个数值，也可以是一个数组，为每个网格点分别提供一个数值。该参数在每一行中都必须相同。与 Prometheus 一致，级别小于 0 时结果为 `-Inf`，大于 1 时结果为 `+Inf`；级别为 NaN 时，所有窗口内有样本的网格点结果均为 NaN。

<Note>
  此函数目前处于私有预览阶段，可通过设置 `enable_time_series_aggregate_functions=true` 启用。
</Note>

**语法**

```sql theme={null}
timeSeriesQuantileToGrid(start_timestamp, end_timestamp, grid_step, staleness)(timestamp, value, phi)
timeSeriesQuantileToGrid(start_timestamp, end_timestamp, grid_step, staleness)(samples, phi)
```

**参数**

* `start_timestamp` — 指定网格的起点。也可以是小数，或包含数字或日期时间文本的字符串。[`UInt32`](/zh/reference/data-types/int-uint) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64) 或 [`Float*`](/zh/reference/data-types/float) 或 [`Decimal*`](/zh/reference/data-types/decimal) 或 [`String`](/zh/reference/data-types/string)
* `end_timestamp` — 指定网格的终点。也可以是小数，或包含数字或日期时间文本的字符串。[`UInt32`](/zh/reference/data-types/int-uint) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64) 或 [`Float*`](/zh/reference/data-types/float) 或 [`Decimal*`](/zh/reference/data-types/decimal) 或 [`String`](/zh/reference/data-types/string)
* `grid_step` — 指定网格的步长 (以秒为单位) 。也可以是小数，或包含数字或时长 (如 '15s' 或 '1m') 的字符串。[`UInt32`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`Decimal*`](/zh/reference/data-types/decimal) 或 [`String`](/zh/reference/data-types/string)
* `staleness` — 指定参与计算的样本的最大“陈旧时间” (以秒为单位) 。陈旧窗口为左开右闭区间。也可以是小数，或包含数字或时长 (如 '15s' 或 '1m') 的字符串。[`UInt32`](/zh/reference/data-types/int-uint) 或 [`Float*`](/zh/reference/data-types/float) 或 [`Decimal*`](/zh/reference/data-types/decimal) 或 [`String`](/zh/reference/data-types/string)

**参数**

* `timestamp` — 样本的时间戳。可以是单个值，也可以是数组。[`UInt32`](/zh/reference/data-types/int-uint) 或 [`DateTime`](/zh/reference/data-types/datetime) 或 [`DateTime64`](/zh/reference/data-types/datetime64) 或 [`Array(UInt32)`](/zh/reference/data-types/array) 或 [`Array(DateTime)`](/zh/reference/data-types/array) 或 [`Array(DateTime64)`](/zh/reference/data-types/array)
* `value` — 与时间戳对应的时间序列值。可以是单个值，也可以是数组。[`Float*`](/zh/reference/data-types/float) 或 [`Array(Float*)`](/zh/reference/data-types/array)
* `samples` — 时间序列样本，以 Tuple `(timestamp, value)` 组成的数组形式传入，其中 Tuple 各元素的类型分别为上文所列的时间戳类型和值类型。可用于替代将时间戳和值作为两个独立参数传入的方式。[`Array(Tuple(T1, T2))`](/zh/reference/data-types/array)
* `phi` — 分位数级别，通常取值范围为 \[0, 1]：可以是适用于整个网格的单个数值，也可以是为每个网格点分别指定一个数值的数组。所有行中的取值必须相同。[`Float*`](/zh/reference/data-types/float) 或 [`UInt8/16/32/64`](/zh/reference/data-types/int-uint) 或 [`Int8/16/32/64`](/zh/reference/data-types/int-uint) 或 [`Array(Float*)`](/zh/reference/data-types/array) 或 [`Array(UInt8/16/32/64)`](/zh/reference/data-types/array) 或 [`Array(Int8/16/32/64)`](/zh/reference/data-types/array)

**返回值**

返回指定网格上各值的 phi 分位数。返回的数组中，每个时间网格点对应一个值。如果某个网格点的窗口内没有任何样本，则该点的值为 NULL。[`Array(Nullable(Float64))`](/zh/reference/data-types/array)

**示例**