SQL 쿼리 컨텍스트

SQL 쿼리 컨텍스트

Druid SQL 쿼리가 어떻게 실행되는지 제어하는 query context 파라미터를 소개해요. 근사 계산 사용, 특정 필터 선택, lookup 실행 방식 조정 등을 파라미터로 다룰 수 있어요.

출처: 문서

본문

Apache Druid는 Druid SQL과 native 쿼리 두 가지 쿼리 언어를 지원해요. 이 문서는 SQL 언어를 설명해요.

Apache Druid에서 query context 파라미터를 사용해 Druid SQL 쿼리가 어떻게 실행되는지 제어할 수 있어요. 이 파라미터들은 근사 계산 사용, 특정 필터 선택, lookup 실행 방식 제어 같은 쿼리 처리의 여러 측면을 조정하게 해줘요.

모든 쿼리 유형에서 지원되는 추가 컨텍스트 파라미터는 Query context reference 문서를 참고해요. query context 설정 방법은 Set query context 문서를 보세요.

아래 표는 Druid SQL과 함께 사용할 수 있는 query context 파라미터를 정리한 것이에요.

| Parameter | Description | Default value | | sqlQueryId | SQL 쿼리 ID예요. HTTP 클라이언트의 경우 Druid가 X-Druid-SQL-Query-Id 헤더에 이 값을 반환해요. SQL 쿼리 ID를 지정하려면 queryId 대신 sqlQueryId 를 사용해요. SQL 요청에 queryId 를 설정해도 효과가 없어요. SQL을 구성하는 모든 native 쿼리는 자동 생성된 queryId 를 사용해요. | auto-generated | | sqlTimeZone | 연결(connection)의 시간대예요. 예를 들어 "America/Los_Angeles" 또는 "-08:00" 같은 오프셋이에요. 이 파라미터는 시간 함수와 timestamp 리터럴의 동작에 영향을 줘요. | UTC | | sqlStringifyArrays | true 이면 Druid가 배열 값을 가진 결과 컬럼을 응답에서 배열이 아닌 JSON 문자열로 직렬화해요. | true , 단 JDBC 연결에서는 항상 false 예요 | | useApproximateCountDistinct | COUNT(DISTINCT foo) 에 근사 카디널리티 알고리즘을 사용할지 여부예요. | true | | useGroupingSetForExactDistinct | 여러 정확한(비근사) distinct 집계가 있는 쿼리를 실행할 때 grouping set을 사용할지 여부예요. | false | | useApproximateTopN | true 이면 Druid가 가능한 한 SQL 쿼리를 근사 TopN 쿼리로 변환해요. false 이면 정확한 GroupBy 쿼리를 대신 사용해요. | true | | useLexicographicTopN | true 이면 Druid가 사전순 차원 정렬과 함께 TopN 쿼리를 사용할 수 있어요. false 이면 사전순 정렬에 GroupBy 쿼리를 대신 사용해요. useLexicographicTopN 과 useApproximateTopN 이 모두 false 일 때는 TopN 쿼리를 절대 사용하지 않아요. | false | | enableTimeBoundaryPlanning | true 이면 Druid가 가능한 한 SQL 쿼리를 time boundary 쿼리로 변환해요. Time boundary 쿼리는 데이터소스의 __time 컬럼에서 min-max 계산에 매우 효율적이에요. | false | | useNativeQueryExplain | true 이면 EXPLAIN PLAN FOR 가 동등한 native 쿼리의 JSON 표현으로 explain plan을 반환하고, false 면 Calcite가 생성한 원래 버전의 explain plan을 반환해요. 이 속성은 하위 호환성을 위해 제공돼요. 애플리케이션이 이전 동작에 의존하지 않는 한 이 파라미터를 설정하는 것을 권장하지 않아요. | true | | sqlFinalizeOuterSketches | false 일 때(Druid 25.0.0 이후의 기본 동작) DS_HLL , DS_THETA , DS_QUANTILES_SKETCH 가 쿼리 결과에 sketch를 반환해요. true 일 때(Druid 24.0.1 이하의 기본 동작) Druid가 이 함수들이 쿼리 결과에 나타날 때 sketch를 finalize해요. 이 속성은 Druid 24.0.1 이하 동작과의 하위 호환성을 위해 제공돼요. 애플리케이션이 Druid 24.0.1 이하를 사용하지 않는다면 이 파라미터를 설정하지 않는 것을 권장해요. 대신 APPRAX_COUNT_DISTINCT_DS_HLL , APPROX_COUNT_DISTINCT_DS_THETA , APPROX_QUANTILE_DS , DS_THETA_ESTIMATE , DS_GET_QUANTILE 처럼 sketch를 반환하지 않는 함수를 사용해요. | false | | sqlUseBoundAndSelectors | false 일 때(Druid 27.0.0 이후의 기본 동작) SQL 플래너가 selector/bound 대신 equality , null , range 필터를 사용해요. ARRAY 타입 값 필터링에는 sqlUseBoundAndSelectors 가 반드시 false 여야 해요. | false . | | sqlUseExtractionFns | false 면 SQL 플래너가 extractionFn 사용을 피하고 virtual column 같은 다른 구조를 선호해요. 이 파라미터는 이전 동작과의 호환성을 위해 제공되며, 향후 릴리스에서 제거될 수 있어요. | false | | sqlReverseLookup | SQL 계획 중 LOOKUP 함수의 reverse-lookup 재작성(rewrite)을 고려할지 여부예요. Druid는 일치하는 키의 수가 inSubQueryThreshold 와 sqlReverseLookupThreshold 보다 모두 적을 때만 LOOKUP 호출을 반대로 바꿔요. | true | | sqlReverseLookupThreshold | reverse-lookup 재작성을 적용할 때 만들 IN 필터의 최대 크기예요. LOOKUP 호출이 지정된 임계값보다 많은 키와 일치하면 변경되지 않은 채로 유지돼요. inSubQueryThreshold 가 sqlReverseLookupThreshold 보다 낮으면 Druid가 대신 inSubQueryThreshold 임계값을 사용해요. | 10000 | | sqlPullUpLookup | SQL 계획 중 LOOKUP 함수의 pull-up 재작성을 고려할지 여부예요. | true | | enableJoinLeftTableScanDirect | 이 파라미터는 join이 있는 쿼리에 적용돼요. 기본적으로 왼쪽 자식이 필터가 있는 단순 scan일 때, Druid는 scan을 쿼리로 실행한 다음 Broker에서 오른쪽 자식과 join해요. 이 파라미터를 true 로 설정하면 그 동작을 재정의하고 join을 데이터 서버로 밀어넣어요. 쿼리에 명시적으로 join이 없더라도, SQL 플래너가 내부적으로 쿼리를 join으로 변환할 수 있으므로 이 파라미터가 여전히 적용될 수 있어요. | false | | maxNumericInFilters | 쿼리의 전체 SQL WHERE 절이 bound filter 의 OR로만 변환될 때, string 타입 차원에 대해 Druid가 비교할 수 있는 숫자 값의 최대 개수예요. 기본적으로 Druid는 string 컬럼의 숫자 bound filter 개수를 제한하지 않아서, 이 상황이 다른 쿼리 실행을 막을 수 있어요. 이 파라미터를 더 작은 값으로 설정하면 지나치게 긴 segment 처리 시간이 걸리는 쿼리를 Druid가 실행하지 못하게 할 수 있어요. 최적 한도는 시행착오가 필요해요. 100으로 시작하는 것을 권장해요. maxNumericInFilters 한도를 초과하는 쿼리를 제출하는 사용자는 WHERE 절에서 숫자 대신 문자열을 사용하도록 쿼리를 다시 작성해야 해요. 예를 들어 WHERE someString IN ('123', '456') 처럼요. 이 값은 시스템 설정 druid.sql.planner.maxNumericInFilters 를 초과할 수 없어요. druid.sql.planner.maxNumericInFilters 가 명시적으로 설정되지 않았으면 Druid는 이 값을 무시해요. | -1 | | inFunctionThreshold | 값 수가 이 임계값 이상이면 Druid가 SQL IN 을 SCALAR_IN_ARRAY 로 변환해요. 임계값 0은 모든 경우에 이 변환을 강제해요. Integer.MAX_VALUE 임계값은 이 변환을 비활성화해요. 변환된 함수는 계획 시 최적화 대상 수가 줄어 계획이 빨라지지만, 일부 계획 시 최적화를 막을 수 있어요. | 100 | | inFunctionExprThreshold | 값 수가 이 임계값 이상이면, 값 수가 inFunctionThreshold 미만이더라도 SQL IN 은 == 의 || 대신 native 함수 scalar_in_array 로 실행될 자격이 생겨요. 이 속성은 SQL IN 의 native expression 변환에만 영향을 줘요. SQL IN 의 native filter 변환에는 영향을 주지 않아요. 이 속성은 하위 호환성을 위해 제공되며, 향후 릴리스에서 제거될 수 있어요. | 2 | | inSubQueryThreshold | 값 수가 이 임계값 이상이면 Druid가 SQL IN 을 인라인 테이블에 대한 JOIN 으로 변환해요. inFunctionThreshold 가 이 설정보다 우선해요. 임계값 0은 SQL IN 의 크기가 inFunctionThreshold 보다 큰 모든 경우에 인라인 테이블 사용을 강제해요. 임계값 2147483647 은 SQL IN 의 JOIN 재작성을 비활성화해요. | 2147483647 |

더 알아보기 (Learn more)