시계열 쿼리

시계열 쿼리 (Time Series Queries)

Pinot에는 적절한 시계열 언어 플러그인이 구현되어 있으면 모든 시계열 쿼리 언어를 지원할 수 있는 "시계열 엔진(Time Series Engine)"이 있어요.

출처: 문서

본문

PromQL, Uber의 M3QL 등과 같은 언어를 이 플러그인으로 구현할 수 있어요. 데모/테스트 용도로만 의도된 장난감 언어 플러그인이 apache/pinot 저장소에 포함되어 있어요.

상태: 시계열 엔진은 Pinot 1.5.0부터 일반적으로 사용 가능(Generally Available) 합니다.

Quickstart로 시계열 쿼리 실행하기

time_series Quickstart 유형을 사용해 시계열 엔진을 활성화한 상태로 Pinot를 실행할 수 있어요. Quickstart는 apache/pinot 저장소에 포함된 장난감 언어 구현을 사용해요.

자세한 내용은 Quick Start Examples 페이지를 참조하세요.

프로덕션에서 시계열 쿼리 실행하기

자신만의 Time Series Language Plugin을 구현했다고 가정하고, 코드 이름을 "mytsql"이라고 해 봐요. Controller, Broker, Server 구성 각각에 다음 구성을 설정할 수 있어요. 클래스와 시리즈 빌더 팩토리 이름은 가상의 것이에요. 플래너와 시리즈 빌더 구성의 키에 언어 코드가 포함된다는 점에 유의하세요.

pinot.timeseries.languages=mytsql
pinot.timeseries.mytsql.logical.planner.class=com.example.mytsql.MyTSLogicalPlanner
pinot.timeseries.mytsql.series.builder.factory=com.example.mytsql.MyTSQLSeriesBuilderFactory

Pinot는 여러 시계열 쿼리 언어를 동시에 실행하는 것도 허용해요. 예를 들어 promql용 쿼리 언어 플러그인이 있고 mytsql과 함께 실행하고 싶다면 구성은 다음과 같아요.

pinot.timeseries.languages=mytsql,promql
pinot.timeseries.mytsql.logical.planner.class=com.example.mytsql.MyTSLogicalPlanner
pinot.timeseries.mytsql.series.builder.factory=com.example.mytsql.MyTSQLSeriesBuilderFactory
pinot.timeseries.promql.logical.planner.class=com.example.promql.PromQLLogicalPlanner
pinot.timeseries.promql.series.builder.factory=com.example.promql.PromQLSeriesBuilderFactory

시계열 기능 (Time Series Features)

Controller UI

Pinot는 Controller UI의 http://localhost:9000/query/timeseries에 Time Series Query 페이지를 포함하고 있어요.

쿼리 편집기와 시간 컨트롤을 보여주는 Time Series Query UI

현재 Controller UI 구현은 M3QL 쿼리로 한정되어 있어요. 편집기, start와 end Unix 타임스탬프 입력, timeout 입력, 원시 JSON 결과 뷰어를 제공해요. UI는 Controller의 /timeseries/api/v1/query_range 프록시를 통해 고정된 step(1m)으로 요청을 보내요. 현재 플러그인별 언어 선택, 차트 시각화, explain 계획, 또는 일반 쿼리 옵션 컨트롤은 노출하지 않아요.

브로커 호환 API (Broker-Compatible API)

시계열 API POST /query/timeseries는 표준 BrokerResponse 형식으로 응답을 반환하므로 기존 Pinot 클라이언트 라이브러리가 수정 없이 동작해요. 응답에는 numDocsScanned, numSegmentsQueried, totalDocs 같은 친숙한 쿼리 통계와 함께 SQL 쿼리와 동일한 예외 처리 구조가 포함돼요.

요청 본문에는 반드시 query가 포함되어야 해요. 브로커가 잘못된 JSON을 받거나 query 필드가 없으면 HTTP 400 Bad Request를 반환해요.

시계열 데이터는 다음 키 컬럼이 있는 ResultTable로 반환돼요.

  • ts - 각 시간 버킷에 대한 타임스탬프 배열
  • values - 각 타임스탬프에 해당하는 메트릭 값 배열
  • __name__ - 시리즈를 식별하는 직렬화된 태그 키-값 쌍
  • 시리즈의 각 태그/레이블에 대한 추가 컬럼

Prometheus 호환 /query_range 엔드포인트

Pinot는 Prometheus HTTP API와 같은 규칙을 따르는 Prometheus 호환 /query_range 엔드포인트를 제공해요. 이 엔드포인트는 Broker와 Controller 모두에서 사용할 수 있으며 GET과 POST 메서드를 모두 지원해요.

엔드포인트 (Endpoint)
GET /timeseries/api/v1/query_range
POST /timeseries/api/v1/query_range
요청 파라미터 (Request Parameters)
Parameter Required Description
language Yes 사용할 시계열 쿼리 언어(예: promql). 구성된 언어 플러그인 중 하나와 일치해야 해요.
query Yes 시계열 쿼리 표현식(예: PromQL 표현식).
start Yes 쿼리 범위의 시작 타임스탬프. 초 단위 Unix 타임스탬프(예: 1700000000) 또는 RFC3339 형식을 허용해요.
end Yes 쿼리 범위의 종료 타임스탬프. start와 동일한 형식.
step Yes 쿼리 해상도 단계 너비를 기간 문자열로 표시(예: 15s, 1m, 1h).

GET 요청의 경우 파라미터는 쿼리 파라미터로 전달돼요. POST 요청의 경우 파라미터는 URL 인코딩된 폼 데이터 또는 쿼리 파라미터로 보낼 수 있어요.

GET 요청 예시
curl -G 'http://localhost:8099/timeseries/api/v1/query_range' \
  --data-urlencode 'language=promql' \
  --data-urlencode 'query=sum(rate(myMetric[5m]))' \
  --data-urlencode 'start=1700000000' \
  --data-urlencode 'end=1700003600' \
  --data-urlencode 'step=60s'
응답 예시

응답은 시계열 데이터를 ResultTable에 담은 표준 Pinot BrokerResponse 형식을 따릅니다.

{
  "resultTable": {
    "dataSchema": {
      "columnNames": ["ts", "values", "__name__"],
      "columnDataTypes": ["LONG_ARRAY", "DOUBLE_ARRAY", "STRING"]
    },
    "rows": [
      [
        [1700000000, 1700000060, 1700000120],
        [1.5, 2.3, 3.1],
        "sum(rate(myMetric[5m])){}"
      ]
    ]
  },
  "numDocsScanned": 10000,
  "numSegmentsQueried": 4,
  "totalDocs": 50000
}
Controller 프록시

Controller를 통해 쿼리할 때(예: http://localhost:9000/timeseries/api/v1/query_range) 요청은 사용 가능한 Broker 인스턴스로 자동 전달돼요. 이는 클라이언트가 Broker 엔드포인트에 직접 접근할 수 없을 때 유용해요.

/query/timeseries와의 차이점
Feature POST /query/timeseries GET/POST /query_range
Request format JSON body with language, query, and time parameters Query parameters (Prometheus-compatible)
HTTP methods POST only GET and POST
Time range Specified inside the JSON body Specified via start, end, and step parameters
Compatibility Pinot-native API Prometheus-compatible, works with tools like Grafana

/query_range 엔드포인트는 같은 API 규칙을 따르므로 Grafana 같은 기존 Prometheus 호환 도구와 Pinot를 통합할 때 특히 유용해요.

기타 기능 (Other Features)

  • 인증 지원(Auth Support) - 시계열 쿼리는 SQL 쿼리와 동일한 인증·권한 부여 메커니즘(사용자 역할 및 테이블 수준 권한)을 지원해요.
  • 쿼리 옵션(Query Options) - 쿼리 실행 동작을 수정하기 위해 사용자 지정 쿼리 옵션을 요청의 일부로 전달할 수 있어요(사용자 지정 플러그인과 기본 Pinot 엔진 모두에 대해).
  • 쿼리 이벤트 리스너(Query Event Listeners) - 시계열 쿼리는 SQL 쿼리와 동일한 쿼리 이벤트 리스너를 트리거하여 로깅, 감사, 사용자 정의 메트릭을 가능하게 해요.
  • Explain 계획(Explain Plans) - Explain 계획은 사용자 지정 언어 플러그인이 생성한 논리 쿼리 계획을 시각화하는 데 도움이 돼요.

더 알아보기 (Learn more)