timeSeriesResetsToGrid

시계열 데이터를 지정한 시간 그리드(grid) 위에서 PromQL 스타일의 리셋(resets)을 계산하는 집계 함수예요. 시작 타임스탬프·끝 타임스탬프·스텝으로 정의되는 규칙적인 시간 그리드를 사용해요.

출처: 문서

본문

timeSeriesResetsToGrid는 타임스탬프와 값의 쌍으로 된 시계열 데이터를 받아, 시작 타임스탬프·끝 타임스탬프·스텝으로 설명되는 규칙적인 시간 그리드 위에서 이 데이터의 PromQL 스타일 리셋을 계산하는 집계 함수예요. 그리드의 각 지점에 대해 resets 계산에 쓰이는 샘플은 지정된 시간 창(윈도우) 내에서 고려돼요. 샘플은 다음 세 가지 형태 중 하나로 전달될 수 있어요:

timestamp와 value 두 인자로 전달 — 각 행이 단일 샘플을 보유
타임스탬프와 값 두 배열로 전달 — 각 행이 전체 시계열을 보유
(timestamp, value) 튜플의 단일 배열로 전달 — 각 행이 전체 시계열을 보유

여러 샘플이 같은 타임스탬프를 가지면 그중 하나만 사용돼요: 값이 가장 큰 샘플이 사용돼요. NaN 값은 다른 어떤 값에도 지며, 따라서 이 타임스탬프의 모든 샘플이 NaN일 때만 NaN 값이 사용돼요.

이 함수는 비공개 프리뷰(preview) 상태이며, enable_time_series_aggregate_functions=true로 설정하면 활성화돼요.

구문 (Syntax)

timeSeriesResetsToGrid(start_timestamp, end_timestamp, grid_step, staleness)(timestamp, value)
timeSeriesResetsToGrid(start_timestamp, end_timestamp, grid_step, staleness)(samples)

매개변수 (Parameters)

start_timestamp — 그리드의 시작을 지정해요. DateTime64 타임스탬프 인자에서는 분수 숫자, 혹은 숫자나 날짜-시간 텍스트를 담은 문자열일 수도 있어요. UInt32, DateTime, DateTime64, Float*, Decimal* 또는 String
end_timestamp — 그리드의 끝을 지정해요. DateTime64 타임스탬프 인자에서는 분수 숫자, 혹은 숫자나 날짜-시간 텍스트를 담은 문자열일 수도 있어요. UInt32, DateTime, DateTime64, Float*, Decimal* 또는 String
grid_step — 그리드의 스텝을 초 단위로 지정해요. DateTime64 타임스탬프 인자에서는 분수 숫자, 혹은 숫자나 '15s', '1m' 같은 기간을 담은 문자열일 수도 있어요. UInt32, Float*, Decimal* 또는 String
staleness — 고려되는 샘플의 최대 "staleness"(오래됨)를 초 단위로 지정해요. DateTime64 타임스탬프 인자에서는 분수 숫자, 혹은 숫자나 '15s', '1m' 같은 기간을 담은 문자열일 수도 있어요. UInt32, Float*, Decimal* 또는 String

인자 (Arguments)

timestamp — 샘플의 타임스탬프. 개별 값이거나 배열일 수 있어요. UInt32, DateTime, DateTime64, Array(UInt32), Array(DateTime) 또는 Array(DateTime64)
value — 타임스탬프에 해당하는 시계열의 값. 개별 값이거나 배열일 수 있어요. Float* 또는 Array(Float*)
samples — 위에 나열된 타임스탬프·값 타입의 튜플 (timestamp, value) 배열로 전달된 시계열 샘플. 타임스탬프와 값을 두 개의 별도 인자로 전달하는 대안이에요. Array(Tuple(T1, T2))

반환 값 (Returned value)

지정한 그리드 위의 resets 값으로, Array(Nullable(Float64)) 타입이에요. 반환 배열은 각 시간 그리드 지점마다 하나의 값을 포함해요. 특정 그리드 지점의 resets 값을 계산할 창 내에 샘플이 없으면 값은 NULL이에요.

예제 (Examples)

그리드 [90, 105, 120, 135, 150, 165, 180, 195, 210, 225] 위에서 resets 값 계산하기

쿼리:

SET enable_time_series_aggregate_functions = 1;
WITH
    -- NOTE: the gap between 130 and 190 is to show how values are filled for ts = 180 according to window parameter
    [110, 120, 130, 190, 200, 210, 220, 230]::Array(DateTime) AS timestamps,
    [1, 3, 2, 6, 6, 4, 2, 0]::Array(Float32) AS values, -- array of values corresponding to timestamps above
    90 AS start_ts,       -- start of timestamp grid
    90 + 135 AS end_ts,   -- end of timestamp grid
    15 AS step_seconds,   -- step of timestamp grid
    45 AS window_seconds  -- "staleness" window
SELECT timeSeriesResetsToGrid(start_ts, end_ts, step_seconds, window_seconds)(timestamp, value)
FROM
(
    -- This subquery converts arrays of timestamps and values into rows of `timestamp`, `value`
    SELECT
        arrayJoin(arrayZip(timestamps, values)) AS ts_and_val,
        ts_and_val.1 AS timestamp,
        ts_and_val.2 AS value
);

응답:

┌─timeSeriesResetsToGrid(start_ts, end_ts, step_seconds, window_seconds)(timestamp, value)─┐
│ [NULL,NULL,0,1,1,0,NULL,0,1,2]                                                           │
└──────────────────────────────────────────────────────────────────────────────────────────┘

배열 인자를 사용한 동일 쿼리

쿼리:

SET enable_time_series_aggregate_functions = 1;
WITH
    [110, 120, 130, 190, 200, 210, 220, 230]::Array(DateTime) AS timestamps,
    [1, 3, 2, 6, 6, 4, 2, 0]::Array(Float32) AS values,
    90 AS start_ts,
    90 + 135 AS end_ts,
    15 AS step_seconds,
    45 AS window_seconds
SELECT timeSeriesResetsToGrid(start_ts, end_ts, step_seconds, window_seconds)(timestamps, values);

응답:

┌─timeSeriesResetsToGrid(start_ts, end_ts, step_seconds, window_seconds)(timestamps, values)─┐
│ [NULL,NULL,0,1,1,0,NULL,0,1,2]                                                             │
└────────────────────────────────────────────────────────────────────────────────────────────┘

timeSeriesResetsToGrid

timeSeriesResetsToGrid

본문

더 알아보기 (Learn more)