쿼리 관리 속성

쿼리 관리 속성 (Query management properties)

쿼리의 실행·수명·리소스 사용을 관리하는 속성들이에요.

출처: 문서

본문

`query.client.timeout`

타입: duration
기본값: 5m

클라이언트 애플리케이션(예: CLI)의 접촉 없이 클러스터가 얼마나 오래 작업을 포기·취소하기 전에 실행되는지를 구성해요.

`query.execution-policy`

타입: string
기본값: phased
세션 속성: execution_policy

쿼리의 모든 스테이지 처리를 조직하는 알고리즘을 구성해요. 다음 실행 정책을 쓸 수 있어요:

phased — 스테이지 간 의존성 때문에 막히는 것을 피하기 위해 스테이지를 순서대로 스케줄링해요. 이 정책은 클러스터 리소스 활용을 최대화하고 가장 낮은 쿼리 벽시계 시간(wall time)을 제공해요.
all-at-once — 쿼리의 모든 스테이지를 한 번에 스케줄링해요. 결과적으로 클러스터 리소스 활용이 처음에는 높지만, 스테이지 간 의존성 때문에 보통 완전한 처리가 막히고 대기 시간이 길어져 전체적으로 쿼리 벽시계 시간이 늘어나요.

`query.determine-partition-count-for-write-enabled`

타입: boolean
기본값: false
세션 속성: determine_partition_count_for_write_enabled

쓰기 쿼리에 대해 쿼리가 읽고 처리한 데이터 양에 따라 파티션 수를 결정하는 것을 활성화할지 여부예요.

`query.max-hash-partition-count`

타입: integer
기본값: 100
세션 속성: max_hash_partition_count

조인, 집계, 파티셔닝된 윈도우 함수 등 분산 연산을 처리할 때 사용할 최대 파티션 수예요.

`query.min-hash-partition-count`

타입: integer
기본값: 4
세션 속성: min_hash_partition_count

조인, 집계, 파티셔닝된 윈도우 함수 등 분산 연산을 처리할 때 사용할 최소 파티션 수예요.

`query.min-hash-partition-count-for-write`

타입: integer
기본값: 50
세션 속성: min_hash_partition_count_for_write

쓰기 쿼리에서 조인, 집계, 파티셔닝된 윈도우 함수 등 분산 연산을 처리할 때 사용할 최소 파티션 수예요.

`query.max-writer-task-count`

타입: integer
기본값: 100
세션 속성: max_writer_task_count

INSERT, CREATE TABLE AS SELECT, EXECUTE 쿼리 동안 데이터 쓰기에 참여할 최대 태스크 수예요. 이 한도는 redistribute-writes 또는 scale-writers가 활성화된 경우에만 적용돼요.

`query.low-memory-killer.policy`

타입: string
기본값: total-reservation-on-blocked-nodes

메모리 가용성이 낮을 때 실행 중인 쿼리를 종료하는 동작을 구성해요. 다음 값을 지원해요:

none — 메모리가 낮아도 쿼리를 종료하지 않아요.
total-reservation — 현재 가장 많은 총 메모리를 사용하는 쿼리를 종료해요.
total-reservation-on-blocked-nodes — 메모리가 부족해진 노드에서 특히 가장 많은 메모리를 사용하는 쿼리를 종료해요.

참고 (Note)

태스크 수준 재시도가 비활성화된 쿼리(retry-policy가 NONE 또는 QUERY)에만 적용돼요.

`task.low-memory-killer.policy`

타입: string
기본값: total-reservation-on-blocked-nodes

메모리 가용성이 낮을 때 실행 중인 태스크를 종료하는 동작을 구성해요. 다음 값을 지원해요:

none — 메모리가 낮아도 태스크를 종료하지 않아요.
total-reservation-on-blocked-nodes — 태스크 재시도가 활성화된 쿼리의 일부로, 메모리가 부족해진 노드에서 특히 가장 많은 메모리를 사용하는 태스크를 종료해요.
least-waste — 태스크 재시도가 활성화된 쿼리의 일부로, 메모리가 부족해진 노드에서 상당한 메모리를 사용하는 태스크를 종료해요. 이 정책은 이미 오래 실행 중인 태스크를 종료하지 않아 상당한 작업이 낭비되지 않게 해요.

참고 (Note)

태스크 수준 재시도가 활성화된 쿼리(retry-policy=TASK)에만 적용돼요.

`query.max-execution-time`

타입: duration
기본값: 100d
세션 속성: query_max_execution_time

쿼리가 종료되기 전에 클러스터에서 실제로 활발히 실행될 수 있는 최대 시간이에요. 아래의 실행 시간과 달리, 실행 시간에는 분석·쿼리 계획·큐 대기 시간이 포함되지 않아요.

`query.max-length`

타입: integer
기본값: 1,000,000
최댓값: 1,000,000,000

SQL 쿼리 텍스트에 허용되는 최대 문자 수예요. 더 긴 쿼리는 처리되지 않고 QUERY_TEXT_TOO_LARGE 오류로 종료돼요.

`query.max-planning-time`

타입: duration
기본값: 10m
세션 속성: query_max_planning_time

쿼리가 실행 계획을 적극적으로 세우는 최대 허용 시간이에요. 이 시간이 지나면 코디네이터는 쿼리를 멈추기 위해 최선을 다해요. 계획 단계의 일부 연산은 쉽게 취소되지 않아 즉시 종료되지 않을 수 있다는 점에 유의하세요.

`query.max-run-time`

타입: duration
기본값: 100d
세션 속성: query_max_run_time

쿼리가 종료되기 전에 클러스터에서 처리될 수 있는 최대 허용 시간이에요. 이 시간에는 분석·계획 시간뿐 아니라 큐에서 대기하는 시간도 포함되므로, 본질적으로 쿼리가 생성된 이후 존재할 수 있는 시간이에요.

`query.max-scan-physical-bytes`

타입: data size
세션 속성: query_max_scan_physical_bytes

쿼리가 실행 중 스캔할 수 있는 최대 바이트 수예요. 이 한도에 도달하면 과도한 리소스 사용을 막기 위해 쿼리 처리가 종료돼요.

`query.max-write-physical-size`

타입: data size
세션 속성: query_max_write_physical_size

쿼리가 실행 중 쓸 수 있는 데이터의 최대 물리적 크기예요. 이 한도에 도달하면 과도한 리소스 사용을 막기 위해 쿼리 처리가 종료돼요.

`query.max-stage-count`

타입: integer
기본값: 150
최솟값: 1

쿼리당 생성이 허용되는 최대 스테이지 수예요. 쿼리가 이보다 많은 스테이지를 생성하면 QUERY_HAS_TOO_MANY_STAGES 오류로 종료돼요.

경고 (Warning)

이 값을 높게 설정하면 스테이지가 많은 쿼리가 클러스터에 불안정을 초래해, 관련 없는 쿼리가 REMOTE_TASK_ERROR와 Max requests queued per destination exceeded for HttpDestination ... 메시지로 종료될 수 있어요.

`query.max-history`

타입: integer
기본값: 100

통계와 기타 정보를 제공하고 Web UI에서 데이터를 사용할 수 있게 하도록 쿼리 히스토리에 보관할 최대 쿼리 수예요. 이 수에 도달하면 쿼리는 나이(age)에 따라 제거돼요.

더 많은 쿼리에 대한 정보를 외부 시스템에 저장하려면 이벤트 리스너를 사용해야 해요.

`query.min-expire-age`

타입: duration
기본값: 15m

히스토리에서 만료되기 전의 쿼리 최소 나이예요. 만료된 쿼리는 쿼리 히스토리 버퍼에서 제거되고 Web UI에서 더 이상 사용할 수 없어요.

더 많은 쿼리에 대한 정보를 외부 시스템에 저장하려면 이벤트 리스너를 사용해야 해요.

`query.remote-task.enable-adaptive-request-size`

타입: boolean
기본값: true
세션 속성: remote_task_adaptive_update_request_size_enabled

태스크가 보내는 서버 요청을 동적으로 분할하는 것을 활성화할지 여부예요. 대형 스키마에서 메모리 부족 오류를 막을 수 있어요. 기본 설정은 일반적인 사용에 맞게 최적화되어 있으며, 극도로 큰 테이블을 다루는 고급 사용자만 수정해야 해요.

`query.remote-task.guaranteed-splits-per-task`

타입: integer
기본값: 3
세션 속성: remote_task_guaranteed_splits_per_request

각 원격 태스크에 할당되어야 하는 최소 스플릿 수예요. 각 태스크가 최소한의 작업을 수행하도록 보장해요. query.remote-task.enable-adaptive-request-size가 활성화되어 있어야 해요.

`query.remote-task.max-error-duration`

타입: duration
기본값: 1m

코디네이터와 통신하지 못하는 원격 태스크의 타임아웃 값이에요. 이 값이 도달하기 전에 코디네이터가 원격 태스크로부터 업데이트를 받지 못하면, 코디네이터는 그 태스크를 실패로 처리해요.

`query.remote-task.max-request-size`

타입: data size
기본값: 8MB
세션 속성: remote_task_max_request_size

원격 태스크가 만드는 단일 요청의 최대 크기예요. query.remote-task.enable-adaptive-request-size가 활성화되어 있어야 해요.

`query.remote-task.request-size-headroom`

타입: data size
기본값: 2MB
세션 속성: remote_task_request_size_headroom

요청 데이터의 크기 너머로 할당되어야 하는 여유분(headroom)의 양을 결정해요. query.remote-task.enable-adaptive-request-size가 활성화되어 있어야 해요.

`query.info-url-template`

타입: string
기본값: (코디네이터의 쿼리 정보 페이지 URL)

쿼리 정보를 위한 대체 위치로 클라이언트를 리다이렉트하도록 구성해요. URL에는 쿼리 id 플레이스홀더 ${QUERY_ID}가 포함되어야 해요.

예를 들어 https://example.com/query/${QUERY_ID}.

${QUERY_ID}는 실제 쿼리의 id로 대체돼요.

`retry-policy`

타입: string
기본값: NONE

장애 허용 실행에 사용할 재시도 정책이에요. 다음 값을 지원해요:

NONE — 장애 허용 실행을 비활성화해요.
TASK — 실패 시 쿼리 내 개별 태스크를 재시도해요. 교환 매니저 구성이 필요해요.
QUERY — 실패 시 전체 쿼리를 재시도해요.

더 알아보기 (Learn more)

장애 허용 실행과 재시도 정책이 궁금하다면 장애 허용 실행 문서를 이어서 읽어 보세요.