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

> 일정한 시간 그리드(regular time grid)의 시계열 값에 선형 회귀 직선을 적합합니다.

# timeSeriesLinearRegressionToGrid

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

도입 버전: v26.9.0

타임스탬프와 값의 쌍으로 이루어진 시계열 데이터를 입력받아, 시작 타임스탬프, 종료 타임스탬프, 간격으로 정의되는 일정한 시간 그리드에서 값에 직선을 적합시키는 집계 함수입니다. 그리드의 각 지점마다 지정된 시간 윈도우 내의 샘플에 직선을 적합시키고, 튜플 `(intercept, slope)`를 반환합니다. `intercept`는 해당 그리드 지점의 타임스탬프에서의 직선 값이고, `slope`는 초당 기울기입니다. 윈도우 내 샘플이 충분하지 않으면 둘 다 NULL이 됩니다.

오프셋 `t`를 적용한 `timeSeriesPredictLinearToGrid`의 결과는 `intercept + slope * t`와 같고, `timeSeriesDerivToGrid`의 결과는 `slope`와 같습니다. PromQL 함수 `predict_linear`는 이 함수를 사용해 구현되어 있으므로, `predict_linear(v, time())`처럼 그리드 지점마다 예측 오프셋을 다르게 지정할 수 있습니다.

샘플은 다음 세 가지 형태 중 하나로 전달할 수 있습니다.

* 두 개의 인수 `timestamp`와 `value`로 전달: 각 행에 샘플 하나가 들어 있습니다.
* 타임스탬프 배열과 값 배열 두 개로 전달: 각 행에 시계열 전체가 들어 있습니다.
* `(timestamp, value)` 튜플로 이루어진 단일 배열로 전달: 각 행에 시계열 전체가 들어 있습니다.

타임스탬프가 같은 샘플이 여러 개 있으면 그중 값이 가장 큰 샘플 하나만 사용됩니다. 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`](/ko/reference/data-types/int-uint) 또는 [`DateTime`](/ko/reference/data-types/datetime) 또는 [`DateTime64`](/ko/reference/data-types/datetime64) 또는 [`Float*`](/ko/reference/data-types/float) 또는 [`Decimal*`](/ko/reference/data-types/decimal) 또는 [`String`](/ko/reference/data-types/string)
* `end_timestamp` — 그리드의 끝 지점을 지정합니다. 소수로 지정하거나, 숫자 또는 날짜-시간 텍스트를 담은 문자열로 지정할 수도 있습니다. [`UInt32`](/ko/reference/data-types/int-uint) 또는 [`DateTime`](/ko/reference/data-types/datetime) 또는 [`DateTime64`](/ko/reference/data-types/datetime64) 또는 [`Float*`](/ko/reference/data-types/float) 또는 [`Decimal*`](/ko/reference/data-types/decimal) 또는 [`String`](/ko/reference/data-types/string)
* `grid_step` — 그리드의 간격을 초 단위로 지정합니다. 소수로 지정하거나, 숫자 또는 '15s', '1m'과 같은 기간을 담은 문자열로 지정할 수도 있습니다. [`UInt32`](/ko/reference/data-types/int-uint) 또는 [`Float*`](/ko/reference/data-types/float) 또는 [`Decimal*`](/ko/reference/data-types/decimal) 또는 [`String`](/ko/reference/data-types/string)
* `staleness` — 계산에 사용할 샘플의 최대 "staleness"를 초 단위로 지정합니다. staleness 윈도우는 왼쪽이 열리고 오른쪽이 닫힌 인터벌입니다. 소수로 지정하거나, 숫자 또는 '15s', '1m'과 같은 기간을 담은 문자열로 지정할 수도 있습니다. [`UInt32`](/ko/reference/data-types/int-uint) 또는 [`Float*`](/ko/reference/data-types/float) 또는 [`Decimal*`](/ko/reference/data-types/decimal) 또는 [`String`](/ko/reference/data-types/string)

**인수**

* `timestamp` — 샘플의 타임스탬프입니다. 개별 값 또는 배열일 수 있습니다. [`UInt32`](/ko/reference/data-types/int-uint) 또는 [`DateTime`](/ko/reference/data-types/datetime) 또는 [`DateTime64`](/ko/reference/data-types/datetime64) 또는 [`Array(UInt32)`](/ko/reference/data-types/array) 또는 [`Array(DateTime)`](/ko/reference/data-types/array) 또는 [`Array(DateTime64)`](/ko/reference/data-types/array)
* `value` — 타임스탬프에 대응하는 시계열 값입니다. 개별 값 또는 배열일 수 있습니다. [`Float*`](/ko/reference/data-types/float) 또는 [`Array(Float*)`](/ko/reference/data-types/array)
* `samples` — `(timestamp, value)` 튜플의 배열로 전달되는 시계열 샘플입니다. 각 튜플 원소의 타입은 위에 나열된 타임스탬프 및 값의 타입과 같습니다. 타임스탬프와 값을 별도의 두 인수로 전달하는 대신 사용할 수 있습니다. [`Array(Tuple(T1, T2))`](/ko/reference/data-types/array)

**반환 값**

각 그리드 지점에 대한 `(intercept, slope)` 튜플입니다. 이는 해당 그리드 지점의 타임스탬프에서 적합된 선의 값과 초당 기울기를 나타냅니다. 특정 그리드 지점의 윈도우 내에 샘플이 충분하지 않으면 두 원소 모두 NULL이 됩니다. [`Array(Tuple(intercept Nullable(Float64), slope Nullable(Float64)))`](/ko/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] │
└─────────────────────────────┴───────────────────┴────────────┘
```