쿼리 context 설정하기

쿼리 context 설정하기 (Set query context)

쿼리 context는 Apache Druid가 개별 쿼리를 실행하는 방식을 세밀하게 제어할 수 있게 해줘요. 대부분의 쿼리에는 Druid 기본값이 잘 맞지만, 특정 요구사항을 처리하거나 성능을 최적화하려면 쿼리 context를 설정하면 돼요.

출처: 문서

본문

쿼리 context는 Apache Druid가 개별 쿼리를 실행하는 방식을 세밀하게 제어할 수 있게 해줘요. Druid의 기본 설정이 대부분의 쿼리에서 잘 동작하지만, 특정 요구사항을 처리하고 성능을 최적화하려면 쿼리 context를 설정할 수 있어요.

쿼리 context의 일반적인 사용 사례는 다음과 같아요:

오래 걸리는 쿼리나 복잡한 집계의 기본 타임아웃을 재정의해요.
테스트 중 캐싱을 비활성화해 쿼리 성능을 디버깅해요.
정확한 시간 기반 분석을 위해 시간대 같은 SQL 특유의 동작을 구성해요.
중요한 쿼리가 연산 리소스를 먼저 받도록 우선순위를 설정해요.
대용량 데이터셋을 처리하는 쿼리의 메모리 제한을 조정해요.

쿼리 context를 설정하는 방식은 Druid에 쿼리를 제출하는 방법에 따라 달라요. 웹 콘솔을 쓰는지 API를 쓰는지에 따라 다르고, 쿼리가 Druid SQL인지 JSON 기반 native 쿼리인지에 따라서도 달라요. 이 가이드는 각 애플리케이션에 대해 쿼리 context를 설정하는 방법을 보여줘요.

시작하기 전에, 쿼리 context 캐리어(carrier)로 어떤 context 파라미터를 구성해야 하는지 식별하세요. 사용 가능한 파라미터와 설명은 Query context reference 를 참고하세요.

웹 콘솔 (Web console)

웹 콘솔 에서 Druid SQL과 native 쿼리 양쪽에 대해 쿼리 context 파라미터를 구성할 수 있어요.

다음 단계들은 웹 콘솔에서 쿼리 context를 설정하는 방법을 보여줘요:

웹 콘솔에서 최상위 탐색의 Query 를 선택하세요.
실행할 쿼리를 입력하세요. quickstart 에서 Wikipedia 데이터셋을 인제스트했다면 다음 쿼리를 사용할 수 있어요: SELECT * FROM wikipedia WHERE user = 'BlueMoon2662'
엔진 선택기의 메뉴에서 Edit query context 를 클릭하세요.
Edit query context 대화상자에서 context 파라미터를 JSON 키-값 쌍으로 추가하세요. 예를 들어 sqlTimeZone 파라미터를 설정해 쿼리 결과가 지정된 시간대를 반영하도록 할 수 있어요. 이는 데이터를 볼 때 로컬 시간대와 다를 수 있어요. { "sqlTimeZone" : "America/Los_Angeles" }
웹 콘솔은 쿼리 context 파라미터가 포함된 JSON 객체를 검증하고 문법 오류를 강조 표시해요.
Save 를 클릭하세요.
Run 을 클릭해 지정된 context 파라미터로 쿼리를 실행하세요. 예시 쿼리를 쿼리 context가 있을 때와 없을 때 비교해 보세요. 쿼리 context가 없으면 쿼리는 __time 값 2015-09-12T00:47:53.259Z를 반환해요. sqlTimeZone 파라미터를 설정하면 쿼리는 2015-09-11T17:47:53.259-07:00를 반환해요.

Druid SQL

Druid SQL을 프로그래밍 방식으로 사용할 때 — 예를 들어 애플리케이션, 자동화 스크립트, 데이터베이스 도구에서 — 쿼리를 제출하는 방식에 따라 다양한 방법으로 쿼리 context를 설정할 수 있어요.

HTTP API

HTTP API를 사용할 때는 JSON 요청의 context 객체에 쿼리 context 파라미터를 포함해요. Druid SQL API 요청을 구성하고 응답을 처리하는 방법에 대한 자세한 내용은 Druid SQL API 를 참고하세요.

다음 예시는 sqlTimeZone 파라미터를 설정해요:

{
  "query": "SELECT * FROM wikipedia WHERE user = 'BlueMoon2662'",
  "context": {
    "sqlTimeZone": "America/Los_Angeles"
  }
}

단일 요청에 여러 context 파라미터를 설정할 수 있어요:

{
  "query": "SELECT * FROM wikipedia WHERE user = 'BlueMoon2662'",
  "context": {
    "sqlTimeZone": "America/Los_Angeles",
    "sqlQueryId": "request01"
  }
}

JDBC 드라이버 API

JDBC로 Druid에 연결하고 Druid SQL JDBC 드라이버 API 를 사용해 Druid SQL 쿼리를 실행할 수 있어요. 이 방식은 Druid를 BI 도구나 Java 애플리케이션과 통합할 때 유용해요. JDBC로 Druid에 연결할 때는 JDBC 연결 속성(connection properties) 객체에 쿼리 context 파라미터를 설정해요. Druid에 연결을 설정할 때 그 객체를 제공해요.

다음 코드 발췌는 연결 속성을 구성하는 방법을 보여줘요:

String url = "jdbc:avatica:remote:url=http://localhost:8888/druid/v2/sql/avatica/";
// Set the time zone to America/Los_Angeles
Properties connectionProperties = new Properties();
connectionProperties.setProperty("sqlTimeZone", "America/Los_Angeles");
try (Connection connection = DriverManager.getConnection(url, connectionProperties)) {
  // create and execute statements, process result sets, etc
}

import java.sql.*;
import java.util.Properties;

public class JdbcDruid {
    public static void main(String args[]) {
        // Connect to /druid/v2/sql/avatica/ on your Broker.
        String url = "jdbc:avatica:remote:url=http://localhost:8888/druid/v2/sql/avatica/;transparent_reconnection=true";
        // The query you want to run.
        String query = "SELECT * FROM wikipedia WHERE user = 'BlueMoon2662'";

        // Set any connection context parameters you need here.
        Properties connectionProperties = new Properties();
        connectionProperties.setProperty("sqlTimeZone", "America/Los_Angeles");

        try (Connection connection = DriverManager.getConnection(url, connectionProperties)) {
            try (
                final Statement statement = connection.createStatement();
                final ResultSet rs = statement.executeQuery(query)
            ) {
                while (rs.next()) {
                    // process result set
                    Timestamp timeStamp = rs.getTimestamp("__time");
                    System.out.println(timeStamp);
                }
            }
        } catch (Exception e) {
            System.out.println(e.toString());
        }
    }
}

SET 문 (SET statements)

SET 명령을 사용해 Druid SQL 쿼리의 동작을 수정하는 SQL 쿼리 context 파라미터를 지정할 수 있어요. Druid는 메인 SQL 쿼리 앞에 하나 이상의 SET 문을 허용해요. SET 명령은 웹 콘솔과 Druid SQL HTTP API 양쪽에서 동작해요.

웹 콘솔에서는 SET 문 뒤에 쿼리를 직접 작성할 수 있어요. 예:

SET sqlTimeZone = 'America/Los_Angeles';
SELECT * FROM wikipedia WHERE user = 'BlueMoon2662';

HTTP API 호출의 쿼리 문자열 일부로 SET 문을 포함할 수도 있어요. 예:

curl -X POST 'http://localhost:8888/druid/v2/sql' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "SET sqlTimeZone='America/Los_Angeles'; SELECT * FROM wikipedia WHERE user='BlueMoon2662'"
}'

SET 문을 context 필드와 결합할 수도 있어요. 둘 다 포함하면 SET의 파라미터 값이 우선해요:

curl -X POST 'http://localhost:8888/druid/v2/sql' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "SET sqlTimeZone='America/Los_Angeles'; SELECT * FROM wikipedia WHERE user='BlueMoon2662'",
    "context": {
      "sqlTimeZone": "UTC"
    }
}'

SQL 쿼리에서 SET 명령을 사용하는 방법에 대한 자세한 내용은 SET 를 참고하세요.

:::admonish 참고

JDBC 연결에서는 SET 문을 사용할 수 없어요.

Native 쿼리

native 쿼리의 경우, 쿼리 안의 context라는 JSON 객체나 웹 콘솔 을 통해 쿼리 context 파라미터를 포함할 수 있어요.

다음 예시는 sqlTimeZone을 America/Los_Angeles로, queryId를 only_query_id_test로 설정하는 native 쿼리를 보여줘요:

{
  "queryType": "timeseries",
  "dataSource": "wikipedia",
  "granularity": "day",
  "descending": true,
  "filter": {
    "type": "and",
    "fields": [
      { "type": "selector", "dimension": "countryName", "value": "Australia" },
      { "type": "selector", "dimension": "isAnonymous", "value": "true" }
    ]
  },
  "aggregations": [
    { "type": "count", "name": "row_count" }
  ],
  "intervals": ["2015-09-12T00:00:00.000/2015-09-13T00:00:00.000"],
  "context": {
    "sqlTimeZone": "America/Los_Angeles",
    "queryId": "only_query_id_test",
  }
}

런타임 속성 (Runtime properties)

구성 파일에 런타임 속성을 추가해 쿼리 context 파라미터를 전역으로 구성할 수 있어요. 속성은 다음 형식을 취해요:

druid.query.default.context.{PARAMETER}={VALUE}

PARAMETER를 쿼리 context 파라미터로, VALUE를 그 값으로 바꾸세요. 예:

druid.query.default.context.debug=true

자세한 내용은 Configuration reference 를 참고하세요.

쿼리 context 우선순위 (Query context precedence)

주어진 쿼리 context에 대해 Druid는 다음 우선순위 순서(낮은 것부터 높은 것)에 따라 사용할 최종 쿼리 context 값을 결정해요:

내장 기본값 (Built-in defaults) : 아무것도 지정하지 않으면 Druid는 문서화된 기본값을 사용해요.
런타임 속성 (Runtime properties) : 구성 파일에 druid.query.default.context.{PARAMETER}로 파라미터를 구성하면 이것이 내장 기본값을 재정의하고 시스템 전체 기본값으로 동작해요.
Broker 동적 구성 (Broker Dynamic Config) : Broker 동적 구성( Broker Dynamic Config 참고)에서 쿼리 context 파라미터를 구성하면 내장 기본값과 런타임 속성을 재정의해요.
HTTP 요청의 context 객체 (Context object in HTTP request) : JSON context 객체 안에 전달된 파라미터는 내장 기본값, 런타임 속성, Broker 동적 구성을 재정의해요.
SET 문 (SET statements) : Druid SQL에서 SET key=value;로 설정된 파라미터는 가장 높은 우선순위를 가지며 다른 모든 설정을 재정의해요.

더 알아보기 (Learn more)

자세한 내용은 다음 주제를 참고하세요:

Query context reference — 사용 가능한 쿼리 context 파라미터.
SQL query context — SQL 특유의 context 파라미터.
Multi-stage query context — SQL 기반 인제스트 특유의 context 파라미터.
Native queries — context가 있는 native 쿼리 구성에 대한 자세한 내용.
SET — SET 문의 완전한 문법과 사용법.