> ## 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.

> 在等间隔时间网格上对时间序列值进行直线拟合。

# timeSeriesLinearRegressionToGrid

<h2 id="timeSeriesLinearRegressionToGrid">
  timeSeriesLinearRegressionToGrid
</h2>

引入版本：v26.9.0

聚合函数，接收由时间戳和值对组成的时间序列数据，并在由起始时间戳、结束时间戳和步长定义的等间隔时间网格上对这些值进行直线拟合。对于网格上的每个点，函数会用一条直线拟合指定时间窗口内的样本，并返回 Tuple `(intercept, slope)`：`intercept` 是该直线在网格点时间戳处的值，`slope` 是其每秒斜率。如果窗口内的样本不足，两者均为 NULL。

当偏移量为 `t` 时，`timeSeriesPredictLinearToGrid` 的结果等于 `intercept + slope * t`，而 `timeSeriesDerivToGrid` 的结果等于 `slope`。PromQL 函数 `predict_linear` 正是基于此函数实现的，因此不同网格点可以使用不同的预测偏移量，例如 `predict_linear(v, time())`。

样本可以通过以下三种形式之一传入：

* 两个参数 `timestamp` 和 `value`，每行包含一个样本；
* 时间戳数组和值数组，每行包含一整条时间序列；
* 由 `(timestamp, value)` Tuple 组成的单个数组，每行包含一整条时间序列。

如果多个样本的时间戳相同，则只使用其中值最大的那个样本。NaN 值小于任何其他值，因此只有当该时间戳上的所有样本均为 NaN 时，才会使用 NaN 值。

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

**语法**

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

**参数**

* `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` — 指定参与计算的样本的最大“陈旧时长” (staleness) ，单位为秒。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)

**返回值**

每个网格点对应一个 Tuple `(intercept, slope)`：即拟合直线在该网格点时间戳处的值，以及其每秒斜率。如果某个网格点的窗口内样本不足，则两个元素均为 NULL。[`Array(Tuple(intercept Nullable(Float64), slope Nullable(Float64)))`](/zh/reference/data-types/array)

**示例**

**在网格 \[100, 110, 120] 上拟合直线，并与 timeSeriesPredictLinearToGrid 和 timeSeriesDerivToGrid 进行对比**

```sql title=Query theme={null}
SET enable_time_series_aggregate_functions = 1;
WITH
    [100, 110, 120]::Array(DateTime) AS timestamps,
    [10, 20, 30]::Array(Float64) AS values,
    timeSeriesLinearRegressionToGrid(100, 120, 10, 30)(timestamps, values) AS regression
SELECT
    regression,
    arrayMap(r -> r.intercept + r.slope * 60, regression) AS predict_linear_60,
    arrayMap(r -> r.slope, regression) AS deriv;
```

```response title=Response theme={null}
┌─regression──────────────────┬─predict_linear_60─┬─deriv──────┐
│ [(NULL,NULL),(20,1),(30,1)] │ [NULL,80,90]      │ [NULL,1,1] │
└─────────────────────────────┴───────────────────┴────────────┘
```