> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-detect-table-modification.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
> Fits a line to time-series values on a regular time grid.
# timeSeriesLinearRegressionToGrid
timeSeriesLinearRegressionToGrid
Introduced in: v26.9.0
Aggregate function that takes time series data as pairs of timestamps and values and fits a line to the values on a regular time grid described by start timestamp, end timestamp and step. For each point on the grid the samples within the specified time window are fitted by a line, and the function returns the tuple `(intercept, slope)`: `intercept` is the value of that line at the grid point's timestamp and `slope` is its slope per second. Both are NULL if there are not enough samples in the window.
The result of `timeSeriesPredictLinearToGrid` with the offset `t` equals `intercept + slope * t`, and the result of `timeSeriesDerivToGrid` equals `slope`. The PromQL function `predict_linear` is implemented with this function, which allows the prediction offset to differ between grid points, like in `predict_linear(v, time())`.
The samples can be passed in one of three forms:
* as two arguments `timestamp` and `value`, where each row holds a single sample;
* as two arrays of timestamps and values, where each row holds a whole time series;
* as a single array of `(timestamp, value)` tuples, where each row holds a whole time series.
If several samples have the same timestamp, only one of them is used: the sample with the greatest value. A NaN value loses to any other value, so a NaN value is used only if all samples at this timestamp are NaN.
This function is in private preview, enable it by setting `enable_time_series_aggregate_functions=true`.
**Syntax**
```sql theme={null}
timeSeriesLinearRegressionToGrid(start_timestamp, end_timestamp, grid_step, staleness)(timestamp, value)
timeSeriesLinearRegressionToGrid(start_timestamp, end_timestamp, grid_step, staleness)(samples)
```
**Parameters**
* `start_timestamp` — Specifies start of the grid. It can also be a fractional number, or a string containing a number or a date-time text. [`UInt32`](/reference/data-types/int-uint) or [`DateTime`](/reference/data-types/datetime) or [`DateTime64`](/reference/data-types/datetime64) or [`Float*`](/reference/data-types/float) or [`Decimal*`](/reference/data-types/decimal) or [`String`](/reference/data-types/string)
* `end_timestamp` — Specifies end of the grid. It can also be a fractional number, or a string containing a number or a date-time text. [`UInt32`](/reference/data-types/int-uint) or [`DateTime`](/reference/data-types/datetime) or [`DateTime64`](/reference/data-types/datetime64) or [`Float*`](/reference/data-types/float) or [`Decimal*`](/reference/data-types/decimal) or [`String`](/reference/data-types/string)
* `grid_step` — Specifies step of the grid in seconds. It can also be a fractional number, or a string containing a number or a duration like '15s' or '1m'. [`UInt32`](/reference/data-types/int-uint) or [`Float*`](/reference/data-types/float) or [`Decimal*`](/reference/data-types/decimal) or [`String`](/reference/data-types/string)
* `staleness` — Specifies the maximum "staleness" in seconds of the considered samples. The staleness window is a left-open and right-closed interval. It can also be a fractional number, or a string containing a number or a duration like '15s' or '1m'. [`UInt32`](/reference/data-types/int-uint) or [`Float*`](/reference/data-types/float) or [`Decimal*`](/reference/data-types/decimal) or [`String`](/reference/data-types/string)
**Arguments**
* `timestamp` — Timestamp of the sample. Can be individual values or arrays. [`UInt32`](/reference/data-types/int-uint) or [`DateTime`](/reference/data-types/datetime) or [`DateTime64`](/reference/data-types/datetime64) or [`Array(UInt32)`](/reference/data-types/array) or [`Array(DateTime)`](/reference/data-types/array) or [`Array(DateTime64)`](/reference/data-types/array)
* `value` — Value of the time series corresponding to the timestamp. Can be individual values or arrays. [`Float*`](/reference/data-types/float) or [`Array(Float*)`](/reference/data-types/array)
* `samples` — Samples of the time series passed as an array of tuples `(timestamp, value)`, where the tuple elements have the timestamp and value types listed above. An alternative to passing the timestamps and the values as two separate arguments. [`Array(Tuple(T1, T2))`](/reference/data-types/array)
**Returned value**
The tuple `(intercept, slope)` for each grid point: the value of the fitted line at the grid point's timestamp and its slope per second. Both elements are NULL if there are not enough samples within the window for a particular grid point. [`Array(Tuple(intercept Nullable(Float64), slope Nullable(Float64)))`](/reference/data-types/array)
**Examples**
**Fit a line on the grid \[100, 110, 120] and compare with timeSeriesPredictLinearToGrid and 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] │
└─────────────────────────────┴───────────────────┴────────────┘
```