쿼리 context 레퍼런스

쿼리 context 레퍼런스 (Query context reference)

쿼리 context는 Apache Druid에서 개별 쿼리에 대한 런타임 구성을 제공해요. 쿼리 context의 각 파라미터는 실행 타임아웃·리소스 제한부터 캐싱 정책·처리 전략까지 쿼리 동작의 특정 측면을 제어해요.

출처: 문서

본문

쿼리 context는 Apache Druid에서 개별 쿼리에 대한 런타임 구성을 제공해요. 쿼리 context의 각 파라미터는 실행 타임아웃과 리소스 제한부터 캐싱 정책과 처리 전략까지 쿼리 동작의 특정 측면을 제어해요.

이 레퍼런스에는 범위별로 정리된 context 파라미터가 포함돼요:

일반 파라미터 (General parameters) : 모든 쿼리 타입에 적용돼요.
쿼리 타입별 파라미터 (Parameters by query type) : TopN 같은 특정 쿼리 타입에 적용돼요.
벡터화 파라미터 (Vectorization parameters) : 지원되는 쿼리의 벡터화된 쿼리 실행을 제어해요.

쿼리 context를 설정하는 방법을 배우려면 Set query context 를 참고하세요.

Druid SQL 특유의 쿼리 context 파라미터는 SQL query context 를 참고하세요. SQL 기반 인제스트와 관련된 context 파라미터는 SQL-based ingestion reference 를 참고하세요.

일반 파라미터 (General parameters)

특별히 언급하지 않는 한, 다음 파라미터는 모든 쿼리 타입과 native·SQL 쿼리 양쪽에 적용돼요.

| 파라미터 | 기본값 | 설명 | | timeout | druid.server.http.defaultQueryTimeout | 밀리초 단위 쿼리 타임아웃. 이 시간을 넘기면 완료되지 않은 쿼리는 취소돼요. 0 timeout은 타임아웃이 없음을 의미해요 (서버 측 최대 쿼리 타임아웃 druid.server.http.maxQueryTimeout 까지). 기본 타임아웃과 최대 타임아웃을 설정하려면 Broker configuration 를 참고하세요. | | perSegmentTimeout | null | 밀리초 단위 세그먼트별 처리 타임아웃. 이 시간을 넘기면 완료되지 않은 쿼리는 취소돼요. timeout 보다 작거나 같아야 해요 (≤ timeout). 0 perSegmentTimeout은 세그먼트별 타임아웃이 없음을 의미해요. 일반적으로 표준 기본값은 O(수 초)여야 해요. 이 쿼리 context의 클러스터 전체 기본값은 druid.query.default.context.perSegmentTimeout 로 지정할 수 있어요. | | priority | 기본 우선순위는 다음 중 하나예요: 쿼리 context에서 설정된 priority 값 (설정된 경우) · 런타임 속성 druid.query.default.context.priority 의 값 (설정되고 null이 아닌 경우) · 쿼리 context와 런타임 속성에 priority가 없으면 0 | 쿼리 우선순위. 우선순위가 높은 쿼리가 연산 리소스를 우선적으로 받아요. | | lane | null | 쿼리 레인. 쿼리 클래스(classes of queries)에 대한 사용량 제한을 제어해요. 자세한 내용은 Broker configuration 를 참고하세요. | | queryId | 자동 생성 | 이 쿼리에 부여된 고유 식별자. 쿼리 ID가 설정되거나 알려져 있으면 쿼리를 취소하는 데 사용할 수 있어요. | | brokerService | null | 이 쿼리가 라우팅되어야 하는 Broker 서비스. 이 파라미터는 타입이 manual인 broker selector 전략에서만 적용돼요. 자세한 내용은 Router strategies 를 참고하세요. | | useCache | true | 이 쿼리에 쿼리 캐시를 활용할지 여부를 나타내는 플래그. false로 설정하면 이 쿼리에서 쿼리 캐시 읽기를 비활성화해요. true로 설정하면 Apache Druid가 druid.broker.cache.useCache 또는 druid.historical.cache.useCache 를 사용해 쿼리 캐시에서 읽을지 여부를 결정해요. | | populateCache | true | 쿼리 결과를 쿼리 캐시에 저장할지 여부를 나타내는 플래그. 주로 디버깅에 사용돼요. false로 설정하면 이 쿼리 결과를 쿼리 캐시에 저장하는 것을 비활성화해요. true로 설정하면 Druid가 druid.broker.cache.populateCache 또는 druid.historical.cache.populateCache 를 사용해 이 쿼리 결과를 쿼리 캐시에 저장할지 여부를 결정해요. | | useResultLevelCache | true | 이 쿼리에 결과 레벨 캐시(result level cache)를 활용할지 여부를 나타내는 플래그. false로 설정하면 이 쿼리에서 쿼리 캐시 읽기를 비활성화해요. true로 설정하면 Druid가 druid.broker.cache.useResultLevelCache 를 사용해 결과 레벨 쿼리 캐시를 읽을지 여부를 결정해요. | | populateResultLevelCache | true | 쿼리 결과를 결과 레벨 캐시에 저장할지 여부를 나타내는 플래그. 주로 디버깅에 사용돼요. false로 설정하면 이 쿼리 결과를 쿼리 캐시에 저장하는 것을 비활성화해요. true로 설정하면 Druid가 druid.broker.cache.populateResultLevelCache 를 사용해 이 쿼리 결과를 결과 레벨 쿼리 캐시에 저장할지 여부를 결정해요. | | bySegment | false | native 쿼리 전용. "by segment" 결과를 반환해요. 주로 디버깅에 사용되며, true로 설정하면 결과가 데이터가 온 세그먼트와 연관되어 반환돼요. | | finalize | N/A | 집계 결과를 "finalize"(확정)할지 여부를 나타내는 플래그. 주로 디버깅에 사용돼요. 예를 들어 hyperUnique 집계자는 이 플래그가 false이면 추정 카디널리티 대신 전체 HyperLogLog 스케치를 반환해요. | | maxScatterGatherBytes | druid.server.http.maxScatterGatherBytes | 쿼리를 실행하기 위해 Historical·realtime 프로세스 같은 데이터 프로세스에서 수집하는 최대 바이트 수. 이 파라미터를 사용해 쿼리 시간에 maxScatterGatherBytes 제한을 더 줄일 수 있어요. 자세한 내용은 Broker configuration 를 참고하세요. | | maxQueuedBytes | druid.broker.http.maxQueuedBytes | 데이터 서버로 가는 채널에 백프레셔(backpressure)를 가하기 전에 쿼리당 대기열에 넣는 최대 바이트 수. maxScatterGatherBytes와 비슷하지만, 그 구성과 달리 쿼리 실패가 아니라 백프레셔를 유발해요. 0은 비활성화를 의미해요. | | maxSubqueryRows | druid.server.http.maxSubqueryRows | 서브쿼리가 생성할 수 있는 행 수의 상한. 자세한 내용은 Broker configuration 와 subquery guardrails 를 참고하세요. | | maxSubqueryBytes | druid.server.http.maxSubqueryBytes | 서브쿼리가 생성할 수 있는 바이트 수의 상한. 자세한 내용은 Broker configuration 와 subquery guardrails 를 참고하세요. | | serializeDateTimeAsLong | false | true이면 DateTime이 Broker가 반환하는 결과와 Broker-계산 프로세스 간 데이터 운반에서 long으로 직렬화돼요. | | serializeDateTimeAsLongInner | false | true이면 DateTime이 Broker-계산 프로세스 간 데이터 운반에서 long으로 직렬화돼요. | | enableParallelMerge | true | Broker에서 병렬 결과 병합을 활성화해요. 이 설정을 true로 만들려면 druid.processing.merge.useParallelMergePool 가 활성화되어 있어야 해요. 자세한 내용은 Broker configuration 를 참고하세요. | | parallelMergeParallelism | druid.processing.merge.parallelism | Broker에서 병렬 결과 병합에 사용할 최대 병렬 스레드 수. 자세한 내용은 Broker configuration 를 참고하세요. | | parallelMergeInitialYieldRows | druid.processing.merge.initialYieldNumRows | Broker에서 병렬 결과 병합을 위해 새 태스크를 포크(fork)해 시퀀스 병합을 계속하기 전에 ForkJoinPool 병합 태스크당 양보(yield)할 행 수. 자세한 내용은 Broker configuration 를 참고하세요. | | parallelMergeSmallBatchRows | druid.processing.merge.smallBatchNumRows | Broker에서 병렬 결과 병합을 위해 ForkJoinPool 병합 태스크에서 처리할 결과 배치 크기. 자세한 내용은 Broker configuration 를 참고하세요. | | useFilterCNF | false | true이면 Druid가 쿼리 필터를 CNF(Conjunctive Normal Form)로 변환하려 시도해요. 쿼리 처리 중 적격 필터와 일치하는 모든 값의 비트맵 인덱스를 교차시켜 컬럼을 사전 필터링할 수 있고, 스캔해야 할 원시 행 수를 크게 줄이는 경우가 많아요. 하지만 이 효과는 최상위 필터 또는 최상위 'and' 필터의 개별 절에만 발생해요. 따라서 CNF의 필터는 사전 필터링 중 문자열 컬럼의 많은 비트맵 인덱스를 활용할 확률이 더 높아요. 하지만 이 설정은 성능에 부정적인 영향을 줄 수도 있고, 어떤 경우 필터의 CNF를 계산하는 것 자체가 비용이 들 수 있으므로 매우 신중하게 사용해야 해요. 가능하면 필터를 손으로 튜닝해 최적의 형태를 만들고, 이 파라미터를 사용했을 때 실제로 부작용 없이 쿼리 성능이 개선되는지 실험으로 최소한 검증해 보길 권장해요. | | secondaryPartitionPruning | true | Broker에서 2차 파티션 정리(pruning)를 활성화해요. Broker는 항상 시간 interval 필터를 기반으로 입력 스캔에서 불필요한 세그먼트를 정리하지만, 데이터가 해시·범위 파티셔닝으로 추가 파티셔닝되어 있으면 이 옵션은 2차 파티션 차원 필터를 기반으로 추가 정리를 활성화해요. | | debug | false | 쿼리에 대한 디버깅 출력을 활성화할지 여부를 나타내는 플래그. false로 설정하면 추가 로그가 생성되지 않아요 (생성되는 로그는 전적으로 로깅 레벨에 달려 있어요). true로 설정하면 다음 추가 로그가 생성돼요: - 쿼리가 생성한 예외(있다면)의 스택 트레이스 로그 | | setProcessingThreadNames | true | 쿼리 처리 중에 처리 스레드 이름을 queryType_dataSource_intervals 로 설정할지 여부. 스레드 덤프를 해석하는 데 도움이 되며 기본적으로 켜져 있어요. false로 설정하면 쿼리 오버헤드를 약간 줄일 수 있어요. 대부분 시나리오에서 영향은 미미하지만, 높은 QPS·낮은 세그먼트별 처리 시간 시나리오에서는 의미가 있을 수 있어요. | | sqlPlannerBloat | 1000 | 표현식을 인라인할 때 복잡성이 증가하면 두 Project 연산자를 병합할지 제어하는 Calcite 파라미터. 두 projection의 병합을 거부한 뒤 던져지는 예외 There are not enough rules to produce a node with desired properties: convention=DRUID, sort=[]에 대한 임시 해결책으로 구현됐어요. | | cloneQueryMode | excludeClones | clone Historical이 브로커에 의해 쿼리되어야 하는지 여부를 나타냄. clone 서버는 cloneServers Coordinator 동적 구성으로 생성돼요. 가능한 값은 excludeClones, includeClones, preferClones 예요. excludeClones는 clone Historical이 브로커에 의해 쿼리되지 않음을 의미해요. preferClones는 clone 대상인 원본 Historical과 clone Historical 사이에서 선택해야 할 때 브로커가 clone을 선택함을 나타내요. clone 과정에 관여하지 않는 Historical은 여전히 쿼리돼요. includeClones는 브로커가 clone 상태와 무관하게 모든 Historical을 쿼리함을 의미해요. 이 파라미터는 native 쿼리에만 영향을 줘요. MSQ는 Historical을 직접 쿼리하지 않아요. | | realtimeSegmentsOnly | false | true로 설정하면 realtime 세그먼트만 쿼리해요. Historical 세그먼트는 제외돼요. |

쿼리 타입별 파라미터 (Parameters by query type)

일부 쿼리 타입은 그 쿼리 타입 특유의 context 파라미터를 제공해요.

TopN

| 파라미터 | 기본값 | 설명 | | minTopNThreshold | 1000 | 각 세그먼트의 상위 minTopNThreshold 지역 결과가 전역 topN을 결정하기 위해 병합에 반환돼요. |

Timeseries

Join filter

GroupBy

groupBy 쿼리 페이지 에서 사용 가능한 GroupBy 쿼리 context 파라미터 목록을 참고하세요.

벡터화 파라미터 (Vectorization parameters)

GroupBy와 Timeseries 쿼리 타입은 한 번에 행 배치를 처리해 쿼리 실행을 빠르게 하는 벡터화 모드로 실행할 수 있어요. 모든 쿼리가 벡터화될 수 있는 건 아니에요. 특히 벡터화는 현재 다음 요구사항이 있어요:

모든 쿼리 레벨 필터는 비트맵 인덱스에서 실행될 수 있거나 벡터화된 행 매처(row-matcher)를 제공해야 해요. 여기에는 selector, bound, in, like, regex, search, and, or, not 가 포함돼요.
filtered 집계자의 모든 필터는 벡터화된 행 매처를 제공해야 해요.
모든 집계자는 벡터화된 구현을 제공해야 해요. 여기에는 count, doubleSum, floatSum, longSum, longMin, longMax, doubleMin, doubleMax, floatMin, floatMax, longAny, doubleAny, floatAny, stringAny, hyperUnique, filtered, approxHistogram, approxHistogramFold, fixedBucketsHistogram(숫자 입력 포함)이 포함돼요.
모든 가상 컬럼은 벡터화된 구현을 제공해야 해요. 현재 표현식 가상 컬럼의 경우 벡터화 지원 여부는 입력 타입과 표현식이 사용하는 함수에 따라 표현식별로 결정돼요. expression 문서 의 현재 지원 목록을 참고하세요.
GroupBy의 경우: 모든 차원 스펙이 "default"여야 해요 (추출 함수나 filtered 차원 스펙이 없음).
GroupBy의 경우: 멀티-밸류 차원이 없어야 해요.
Timeseries의 경우: "descending" 순서가 없어야 해요.
불변 세그먼트만 (realtime 세그먼트는 안 됨).
table datasource만 (조인, 서브쿼리, lookup, inline datasource는 안 됨).

다른 쿼리 타입(TopN, Scan, Select, Search)은 vectorize 파라미터를 무시하고 벡터화 없이 실행해요. 이 쿼리 타입들은 vectorize가 "force"로 설정되어 있어도 그 파라미터를 무시해요.

| 파라미터 | 기본값 | 설명 | | vectorize | true | 벡터화된 쿼리 실행을 활성화하거나 비활성화해요. 가능한 값은 false(비활성화), true(가능하면 활성화, 그렇지 않으면 세그먼트별로 비활성화), force(활성화, 벡터화할 수 없는 groupBy·timeseries 쿼리는 실패)예요. "force" 설정은 테스트를 돕기 위한 것이며 프로덕션에서 일반적으로 유용하지 않아요 (realtime 세그먼트는 벡터화 실행으로 처리할 수 없으므로, realtime 데이터에 대한 쿼리는 실패하기 때문이에요). 설정되어 있으면 druid.query.default.context.vectorize 를 재정의해요. | | vectorSize | 512 | 특정 쿼리의 행 배치 크기를 설정해요. 설정되어 있으면 druid.query.default.context.vectorSize 를 재정의해요. | | vectorizeVirtualColumns | true | 가상 컬럼이 있는 쿼리의 벡터화된 쿼리 처리를 활성화하거나 비활성화해요. vectorize 위에 레이어로 적용돼요 (쿼리가 벡터화를 활용하려면 vectorize도 true로 설정되어야 해요). 가능한 값은 false(비활성화), true(가능하면 활성화, 그렇지 않으면 세그먼트별로 비활성화), force(활성화, 벡터화할 수 없는 가상 컬럼이 있는 groupBy·timeseries 쿼리는 실패)예요. "force" 설정은 테스트를 돕기 위한 것이며 프로덕션에서 일반적으로 유용하지 않아요. 설정되어 있으면 druid.query.default.context.vectorizeVirtualColumns 를 재정의해요. |

더 알아보기 (Learn more)

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

Set query context — 쿼리 context 파라미터를 구성하는 방법.
SQL query context — Druid SQL 특유의 쿼리 context 파라미터.
SQL-based ingestion reference — SQL 기반 인제스트(MSQ)에서 사용되는 context 파라미터.