프로파일링

프로파일링 (Profiling)

특정 쿼리가 특정 성능 특성을 보이는 이유를 이해하는 데 프로파일링은 필수적이에요. DuckDB에는 쿼리 프로파일링을 활성화하는 여러 내장 기능이 있는데, 이 페이지가 그것을 다룬다. EXPLAIN 사용의 고수준 예시는 [“Inspect Query Plans” 페이지]({% link docs/current/guides/meta/explain.md %})를 참고해요.

출처: 문서

본문

구문 (Statements)

`EXPLAIN` 구문

쿼리를 프로파일링하는 첫 단계는 쿼리 플랜을 검토하는 것일 수 있어요. [EXPLAIN]({% link docs/current/guides/meta/explain.md %}) 구문은 쿼리 플랜을 보여주고 내부에서 무슨 일이 일어나는지 설명해요.

`EXPLAIN ANALYZE` 구문

쿼리 플랜은 개발자가 쿼리의 성능 특성을 이해하는 데 도움을 줘요. 하지만 개별 연산자의 성능 수치와 이를 통과하는 카디널리티를 검토해야 하는 경우도 자주 있어요. [EXPLAIN ANALYZE]({% link docs/current/guides/meta/explain_analyze.md %}) 구문은 쿼리 플랜을 pretty-print하고 쿼리도 실행하므로 이를 얻을 수 있어요. 따라서 실제 실행 시간 성능 수치를 제공해요.

`FORMAT` 옵션

EXPLAIN [ANALYZE] 구문은 여러 형식으로 내보낼 수 있어요:

text – 기본 ASCII-art 스타일 출력
graphviz – Graphviz로 렌더링할 수 있는 DOT 출력을 생성
html – treeflex로 렌더링할 수 있는 HTML 출력을 생성
json – JSON 출력을 생성
mermaid – Mermaid 플로우차트를 생성

형식을 지정하려면 FORMAT 태그를 사용해요:

EXPLAIN (FORMAT html) SELECT 42 AS x;

Pragmas

DuckDB는 프로파일링을 켜고 끄고 프로파일링 출력의 세부 수준을 제어하는 여러 pragma를 지원해요.

다음 pragma들을 사용할 수 있으며 PRAGMA나 SET으로 설정할 수 있어요. 또한 RESET 다음에 설정 이름을 붙여 재설정할 수도 있어요. 자세한 내용은 pragmas 페이지의 [“Profiling”]({% link docs/current/configuration/pragmas.md %}#profiling) 섹션을 참고해요.

설정	설명	기본값	옵션
[`enable_profiling`]({% link docs/current/configuration/pragmas.md %}#enable_profiling), [`enable_profile`]({% link docs/current/configuration/pragmas.md %}#enable_profiling)	프로파일링 켜기	`query_tree`	`query_tree`, `json`, `query_tree_optimizer`, `no_output`
[`profiling_coverage`]({% link docs/current/configuration/pragmas.md %}#profiling_coverage)	프로파일링할 연산자 설정	`SELECT`	`SELECT`, `ALL`
[`profiling_output`]({% link docs/current/configuration/pragmas.md %}#profiling_output)	프로파일링 출력 파일 설정	Console	파일 경로
[`profiling_mode`]({% link docs/current/configuration/pragmas.md %}#profiling_mode)	추가 옵티마이저·플래너 메트릭 토글	`standard`	`standard`, `detailed`, `all`
[`configure_profiling`]({% link docs/current/configuration/pragmas.md %}#custom_profiling_metrics)	특정 메트릭 활성화/비활성화	detailed profiling이 활성화한 것을 제외한 모든 메트릭	`{"METRIC_NAME": "boolean", ...}` 형식의 JSON 객체. ([사용 가능한 모든 메트릭 목록]({% link docs/current/dev/metrics.md %}#all_metrics))
[`disable_profiling`]({% link docs/current/configuration/pragmas.md %}#disable_profiling), [`disable_profile`]({% link docs/current/configuration/pragmas.md %}#disable_profiling)	프로파일링 끄기

테이블 함수 (Table Functions)

이 테이블 함수들은 DuckDB v1.5.0에서 도입됐어요.

DuckDB는 프로파일링을 활성화·비활성화하는 테이블 함수를 제공하며, 여러 설정을 단일 호출로 통합해요.

`enable_profiling()`

enable_profiling() 함수는 지정된 옵션으로 프로파일링을 구성해요.

CALL enable_profiling(
    format := 'json',
    save_location := '/path/to/output.json',
    coverage := 'select',
    mode := 'standard',
    metrics := ['QUERY_NAME', 'LATENCY', 'OPERATOR_TIMING']
);

파라미터	타입	설명
`metrics`	`LIST`, `STRUCT`, 또는 JSON	활성화할 메트릭을 지정해요
`mode`	`VARCHAR`	프로파일링 수준: `'standard'` 또는 `'detailed'`
`save_location`	`VARCHAR`	프로파일링 출력 파일 경로
`coverage`	`VARCHAR`	쿼리 커버리지: `'select'` 또는 `'all'`
`format`	`VARCHAR`	출력 형식: `'query_tree'`, `'json'`, `'query_tree_optimizer'`, `'no_output'`

모든 파라미터는 선택적이고 명명돼요. 메트릭을 이름 없는 파라미터로 전달할 수도 있어요:

CALL enable_profiling(['LATENCY', 'RESULT_SET_SIZE']);

`disable_profiling()`

disable_profiling() 함수는 프로파일링을 끄는.

CALL disable_profiling();

메트릭 (Metrics)

DuckDB는 독립적으로 활성화·비활성화할 수 있는 광범위한 메트릭을 지원해요. 자세히 알아보고 사용 가능한 전체 메트릭 목록을 보려면 [metrics 문서]({% link docs/current/dev/metrics.md %}#all_metrics)를 참고해요.

상세 프로파일링 (Detailed Profiling)

profiling_mode가 detailed로 설정되면, QUERY_ROOT 노드에서만 사용 가능한 추가 메트릭 집합이 활성화돼요. 이것은 [Phase timing]({% link docs/current/dev/metrics.md %}#phase_timing_metrics) 메트릭 그룹의 모든 메트릭을 포함해요. 이 추가 메트릭 각각을 개별적으로 토글할 수 있어요.

쿼리 그래프 (Query Graphs)

프로파일링 출력을 쿼리 그래프로 렌더링할 수도 있어요. 쿼리 그래프는 쿼리 플랜을 시각적으로 나타내며 연산자와 그 관계를 보여줘요. 쿼리 플랜은 json 형식으로 출력되고 파일에 저장되어야 해요. 프로파일링 출력을 지정된 파일에 쓴 후, Python 스크립트가 그것을 쿼리 그래프로 렌더링할 수 있어요. 스크립트는 duckdb Python 모듈이 설치되어 있어야 해요. HTML 파일을 생성하고 웹 브라우저에서 엽니다.

python -m duckdb.query_graph /path/to/file.json

쿼리 플랜의 표기 (Notation in Query Plans)

쿼리 플랜에서 해시 조인 연산자는 다음 규칙을 따르는. 조인의 _probe side_는 왼쪽 피연산자이고, _build side_는 오른쪽 피연산자예요.

쿼리 플랜의 조인 연산자는 사용된 조인 타입을 보여줘요:

내부 조인은 INNER로 표시돼요.
왼쪽 외부 조인과 오른쪽 외부 조인은 각각 LEFT와 RIGHT로 표시돼요.
전체 외부 조인은 FULL로 표시돼요.

팁: 쿼리 플랜을 시각화하려면 University of Tübingen의 Database Systems Research Group이 개발한 DuckDB 실행 플랜 시각화 도구를 사용해 보세요.

더 알아보기 (Learn more)

프로파일링 pragma 설정에 대한 자세한 내용은 [Pragmas 문서의 Profiling 섹션]({% link docs/current/configuration/pragmas.md %}#profiling)을 참고해요.

프로파일링