Pragmas
Pragmas
PRAGMA 구문은 DuckDB가 SQLite에서 채택한 SQL 확장이에요. PRAGMA 구문은 일반 SQL 구문과 유사한 방식으로 발행할 수 있어요. PRAGMA 명령은 데이터베이스 엔진의 내부 상태를 변경할 수 있고, 엔진의 후속 실행이나 동작에 영향을 줄 수 있어요.
옵션에 값을 할당하는 PRAGMA 구문은 [SET 구문]({% link docs/current/sql/statements/set.md %})으로도 발행할 수 있고, 옵션 값은 SELECT current_setting(option_name)으로 검색할 수 있어요.
출처: 문서
본문
DuckDB의 내장 구성 옵션은 [Configuration Reference]({% link docs/current/configuration/overview.md %}#configuration-reference)를 참고해요. DuckDB [확장]({% link docs/current/extensions/overview.md %})은 추가 구성 옵션을 등록할 수 있어요. 이들은 각 확장의 문서 페이지에 문서화돼요.
이 페이지는 지원되는 PRAGMA 설정을 포함해요.
메타데이터 (Metadata)
스키마 정보
모든 데이터베이스를 나열:
PRAGMA database_list;
모든 테이블을 나열:
PRAGMA show_tables;
[DESCRIBE]({% link docs/current/guides/meta/describe.md %})와 유사하게, 추가 정보와 함께 모든 테이블을 나열:
PRAGMA show_tables_expanded;
모든 함수를 나열하려면:
PRAGMA functions;
존재하지 않는 스키마를 대상으로 하는 쿼리에 대해 DuckDB는 "의도한 것이 이것인가요?" 스타일 오류 메시지를 생성해요.
연결된 데이터베이스가 수천 개 있으면 이런 오류를 생성하는 데 오래 걸릴 수 있어요.
DuckDB가 살펴볼 스키마 수를 제한하려면 catalog_error_max_schemas 옵션을 사용해요:
SET catalog_error_max_schemas = 10;
테이블 정보
특정 테이블의 정보를 얻기:
PRAGMA table_info('table_name');
CALL pragma_table_info('table_name');
table_info는 이름이 table_name인 테이블의 컬럼 정보를 반환해요. 반환된 테이블의 정확한 형식은 다음과 같아요:
cid INTEGER, -- 컬럼의 cid
name VARCHAR, -- 컬럼의 이름
type VARCHAR, -- 컬럼의 타입
notnull BOOLEAN, -- 컬럼이 NOT NULL로 표시되었는지
dflt_value VARCHAR, -- 컬럼의 기본값, 또는 지정되지 않았으면 NULL
pk BOOLEAN -- 기본 키의 일부인지 여부
데이터베이스 크기
각 데이터베이스의 파일 및 메모리 크기 얻기:
PRAGMA database_size;
CALL pragma_database_size();
database_size는 각 데이터베이스의 파일 및 메모리 크기에 대한 정보를 반환해요. 반환 결과의 컬럼 타입은 다음과 같아요:
database_name VARCHAR, -- 데이터베이스 이름
database_size VARCHAR, -- 총 블록 수 곱하기 블록 크기
block_size BIGINT, -- 데이터베이스 블록 크기
total_blocks BIGINT, -- 데이터베이스의 총 블록
used_blocks BIGINT, -- 데이터베이스의 사용된 블록
free_blocks BIGINT, -- 데이터베이스의 여유 블록
wal_size VARCHAR, -- write ahead log 크기
memory_usage VARCHAR, -- 데이터베이스 버퍼 매니저가 사용하는 메모리
memory_limit VARCHAR -- 데이터베이스에 허용된 최대 메모리
저장 정보
저장 정보를 얻으려면:
PRAGMA storage_info('table_name');
CALL pragma_storage_info('table_name');
이 호출은 주어진 테이블에 대해 다음 정보를 반환해요:
| 이름 | 타입 | 설명 |
|---|---|---|
row_group_id |
BIGINT |
|
column_name |
VARCHAR |
|
column_id |
BIGINT |
|
column_path |
VARCHAR |
|
segment_id |
BIGINT |
|
segment_type |
VARCHAR |
|
start |
BIGINT |
이 chunk의 시작 행 id |
count |
BIGINT |
이 저장 chunk의 항목 수 |
compression |
VARCHAR |
이 컬럼에 사용된 압축 타입 – [“Lightweight Compression in DuckDB” 블로그 포스트]({% post_url 2022-10-28-lightweight-compression %}) 참고 |
stats |
VARCHAR |
|
has_updates |
BOOLEAN |
|
persistent |
BOOLEAN |
임시 테이블이면 false |
block_id |
BIGINT |
영구가 아니면 비어 있음 |
block_offset |
BIGINT |
영구가 아니면 비어 있음 |
자세한 내용은 [Storage]({% link docs/current/internals/storage.md %})를 참고해요.
데이터베이스 보기
다음 구문은 [SHOW DATABASES 구문]({% link docs/current/sql/statements/attach.md %})과 동등해요:
PRAGMA show_databases;
리소스 관리 (Resource Management)
메모리 제한
버퍼 매니저의 메모리 제한을 설정:
SET memory_limit = '1GB';
경고: 지정된 메모리 제한은 버퍼 매니저에만 적용돼요. 대부분의 쿼리에서 버퍼 매니저가 처리되는 데이터의 대부분을 담당해요. 하지만 [vectors]({% link docs/current/internals/vector.md %})와 쿼리 결과 같은 특정 인메모리 데이터 구조는 버퍼 매니저 밖에 할당돼요. 또한 복잡한 상태를 가진 [집계 함수들]({% link docs/current/sql/functions/aggregates.md %})(예:
list,mode,quantile,string_agg,approx함수)은 버퍼 매니저 밖의 메모리를 사용해요. 따라서 실제 메모리 소비는 지정된 메모리 제한보다 높을 수 있어요.
스레드
병렬 쿼리 실행을 위한 스레드 수 설정:
SET threads = 4;
콜레이션 (Collations)
사용 가능한 모든 콜레이션을 나열:
PRAGMA collations;
기본 콜레이션을 사용 가능한 것 중 하나로 설정:
SET default_collation = 'nocase';
NULL 기본 정렬 (Default Ordering for NULLs)
NULL의 기본 정렬을 NULLS_FIRST, NULLS_LAST, NULLS_FIRST_ON_ASC_LAST_ON_DESC 또는 NULLS_LAST_ON_ASC_FIRST_ON_DESC 중 하나로 설정:
SET default_null_order = 'NULLS_FIRST';
SET default_null_order = 'NULLS_LAST_ON_ASC_FIRST_ON_DESC';
기본 결과 집합 정렬 방향을 ASCENDING 또는 DESCENDING으로 설정:
SET default_order = 'ASCENDING';
SET default_order = 'DESCENDING';
비정수 리터럴로 정렬 (Ordering by Non-Integer Literals)
기본적으로 비정수 리터럴로 정렬하는 것은 허용되지 않아요:
SELECT 42 ORDER BY 'hello world';
-- Binder Error: ORDER BY non-integer literal has no effect.
이 동작을 허용하려면 order_by_non_integer_literal 옵션을 사용해요:
SET order_by_non_integer_literal = true;
VARCHAR로의 암시적 캐스팅 (Implicit Casting to VARCHAR)
버전 0.10.0 이전에는 DuckDB가 함수 바인딩 중에 어떤 타입이든 VARCHAR로 자동으로 암시적 캐스팅을 허용했어요. 그 결과 명시적 캐스팅 없이도 정수의 부분문자열(substring)을 계산하는 것이 가능했어요. v0.10.0 이후 버전에서는 대신 명시적 캐스팅이 필요해요. 암시적 캐스팅을 수행하는 옛 동작으로 되돌리려면 old_implicit_casting 변수를 true로 설정해요:
SET old_implicit_casting = true;
Python: 모든 데이터프레임 스캔
버전 1.1.0 이전에는 DuckDB의 Python [replacement scan 메커니즘]({% link docs/current/clients/c/replacement_scans.md %})이 전역 Python 네임스페이스를 스캔했어요. 이 옛 동작으로 되돌리려면 다음 설정을 사용해요:
SET python_scan_all_frames = true;
DuckDB 정보 (Information on DuckDB)
버전
DuckDB 버전 표시:
PRAGMA version;
CALL pragma_version();
플랫폼
platform은 현재 DuckDB 실행 파일이 컴파일된 플랫폼의 식별자를 반환해요. 예: osx_arm64.
이 식별자의 형식은 [확장 로딩 설명 문서]({% link docs/current/extensions/extension_distribution.md %}#platforms)에 설명된 플랫폼 이름과 일치해요:
PRAGMA platform;
CALL pragma_platform();
사용자 에이전트
다음 구문은 사용자 에이전트 정보를 반환해요. 예: duckdb/v0.10.0(osx_arm64):
PRAGMA user_agent;
메타데이터 정보
다음 구문은 메타데이터 저장소 정보(block_id, total_blocks, free_blocks, free_list)를 반환해요:
PRAGMA metadata_info;
진행 표시줄 (Progress Bar)
쿼리 실행 시 진행 표시줄 표시:
PRAGMA enable_progress_bar;
또는:
PRAGMA enable_print_progress_bar;
실행 중인 쿼리에 진행 표시줄을 표시하지 않음:
PRAGMA disable_progress_bar;
또는:
PRAGMA disable_print_progress_bar;
EXPLAIN 출력
[EXPLAIN]({% link docs/current/sql/statements/profiling.md %})의 출력은 물리적 플랜만 표시하도록 구성할 수 있어요.
EXPLAIN의 기본 구성:
SET explain_output = 'physical_only';
최적화된 쿼리 플랜만 표시하려면:
SET explain_output = 'optimized_only';
모든 쿼리 플랜을 표시하려면:
SET explain_output = 'all';
프로파일링 (Profiling)
프로파일링 활성화
다음 쿼리는 기본 형식 query_tree로 프로파일링을 활성화해요.
형식과 무관하게, 프로파일링을 활성화하려면 enable_profiling이 필수예요.
PRAGMA enable_profiling;
PRAGMA enable_profile;
프로파일링 커버리지
기본적으로 프로파일링 커버리지는 SELECT로 설정돼요.
SELECT는 SELECT 구문의 물리적 플랜에서 각 연산자에 대해 프로파일러를 실행해요.
SET profiling_coverage = 'SELECT';
기본적으로 프로파일러는 다른 구문 타입(INSERT INTO, ATTACH 등)에 대해 프로파일링 정보를 발행하지 않아요.
모든 구문 타입에 대해 프로파일러를 실행하려면 이 설정을 ALL로 변경해요.
SET profiling_coverage = 'ALL';
프로파일링 형식
enable_profiling의 형식은 query_tree, json, query_tree_optimizer, 또는 no_output으로 지정할 수 있어요.
각 형식은 no_output을 제외하고 구성된 출력에 출력을 인쇄해요.
기본 형식은 query_tree예요.
물리적 쿼리 플랜과 트리의 각 연산자 메트릭을 인쇄해요.
SET enable_profiling = 'query_tree';
대안으로 json은 물리적 쿼리 플랜을 JSON으로 반환해요:
SET enable_profiling = 'json';
팁: 쿼리 플랜을 시각화하려면 University of Tübingen의 Database Systems Research Group이 개발한 DuckDB 실행 플랜 시각화 도구를 사용해 보세요.
옵티마이저와 플래너 메트릭을 포함한 물리적 쿼리 플랜을 반환하려면:
SET enable_profiling = 'query_tree_optimizer';
데이터베이스 드라이버와 다른 애플리케이션도 API 호출을 통해 프로파일링 정보에 접근할 수 있으며, 이 경우 사용자는 다른 출력을 비활성화할 수 있어요.
파라미터가 no_output으로 읽혀도 이것이 구성 가능한 출력으로의 인쇄에만 영향을 준다는 점을 주의하는 것이 중요해요.
API 호출로 프로파일링 정보에 접근할 때도 프로파일링 활성화는 여전히 중요해요:
SET enable_profiling = 'no_output';
프로파일링 출력
기본적으로 DuckDB는 프로파일링 정보를 표준 출력으로 인쇄해요.
하지만 프로파일링 정보를 파일에 쓰고 싶다면 PRAGMA profiling_output으로 파일 경로를 지정할 수 있어요.
경고: 파일 내용은 새로 발행되는 쿼리마다 덮어써져요. 따라서 파일에는 마지막으로 실행된 쿼리의 프로파일링 정보만 포함돼요:
SET profiling_output = '/path/to/file.json';
SET profile_output = '/path/to/file.json';
프로파일링 모드
기본적으로 제한된 양의 프로파일링 정보가 제공돼요 (standard).
SET profiling_mode = 'standard';
더 자세한 내용을 원하면 profiling_mode를 detailed로 설정해 상세 프로파일링 모드를 사용해요.
이 모드의 출력은 플래너와 옵티마이저 단계의 프로파일링을 포함해요.
SET profiling_mode = 'detailed';
모든 사용 가능한 메트릭에 접근하려면 profiling_mode를 all로 설정해요.
SET profiling_mode = 'all';
커스텀 메트릭
기본적으로 프로파일링은 detailed 프로파일링이 활성화한 것을 제외한 모든 메트릭을 활성화해요.
custom_profiling_settings PRAGMA를 사용하면 detailed 프로파일링의 것들을 포함한 각 메트릭을 개별적으로 활성화·비활성화할 수 있어요.
이 PRAGMA는 메트릭 이름을 키로, 켜고 끄는 Boolean 값을 값으로 가진 JSON 객체를 받아요.
이 PRAGMA가 지정한 설정은 기본 동작을 덮어써요.
참고: 이것은
enable_profiling이json또는no_output으로 설정된 경우의 메트릭에만 영향을 줘요.query_tree와query_tree_optimizer는 항상 기본 메트릭 집합을 사용해요.
다음 예시에서 CPU_TIME 메트릭이 비활성화돼요.
EXTRA_INFO, OPERATOR_CARDINALITY, OPERATOR_TIMING 메트릭이 활성화돼요.
SET custom_profiling_settings = '{"CPU_TIME": "false", "EXTRA_INFO": "true", "OPERATOR_CARDINALITY": "true", "OPERATOR_TIMING": "true"}';
프로파일링 문서에는 사용 가능한 [메트릭]({% link docs/current/dev/profiling.md %}#metrics) 개요가 있어요.
프로파일링 비활성화
프로파일링을 비활성화하려면:
PRAGMA disable_profiling;
PRAGMA disable_profile;
쿼리 최적화 (Query Optimization)
옵티마이저
쿼리 옵티마이저를 비활성화하려면:
PRAGMA disable_optimizer;
쿼리 옵티마이저를 활성화하려면:
PRAGMA enable_optimizer;
옵티마이저 선택적 비활성화
disabled_optimizers 옵션은 최적화 단계를 선택적으로 비활성화할 수 있게 해줘요.
예를 들어 filter_pushdown과 statistics_propagation을 비활성화하려면:
SET disabled_optimizers = 'filter_pushdown,statistics_propagation';
사용 가능한 최적화는 [duckdb_optimizers() 테이블 함수]({% link docs/current/sql/meta/duckdb_table_functions.md %}#duckdb_optimizers)로 조회할 수 있어요.
옵티마이저를 다시 활성화하려면:
SET disabled_optimizers = '';
경고:
disabled_optimizers옵션은 성능 문제 디버깅에만 사용해야 하고 프로덕션에서는 피해야 해요.
로깅 (Logging)
쿼리 로깅 경로 설정:
SET log_query_path = '/tmp/duckdb_log/';
쿼리 로깅 비활성화:
SET log_query_path = '';
전문 검색 인덱스 (Full-Text Search Indexes)
create_fts_index와 drop_fts_index 옵션은 [fts 확장]({% link docs/current/core_extensions/full_text_search.md %})이 로드된 경우에만 사용할 수 있어요. 사용법은 [Full-Text Search 확장 페이지]({% link docs/current/core_extensions/full_text_search.md %})에 문서화돼요.
검증 (Verification)
외부 연산자 검증
외부 연산자의 검증 활성화:
PRAGMA verify_external;
외부 연산자의 검증 비활성화:
PRAGMA disable_verify_external;
왕복 기능 검증
지원되는 논리 플랜의 왕복 기능 검증 활성화:
PRAGMA verify_serializer;
왕복 기능 검증 비활성화:
PRAGMA disable_verify_serializer;
객체 캐시 (Object Cache)
예: Parquet 메타데이터와 같은 객체의 캐싱 활성화:
PRAGMA enable_object_cache;
객체 캐싱 비활성화:
PRAGMA disable_object_cache;
체크포인팅 (Checkpointing)
압축
체크포인팅 중에 기존 컬럼 데이터 + 새 변경 사항이 압축돼요. 어떤 압축 함수를 고려할지에 영향을 주는 pragma가 몇 가지 있어요.
압축 강제
가능하면 다른 어떤 방법보다 이 압축 방법을 선호:
PRAGMA force_compression = 'bitpacking';
비활성화된 압축 방법
쉼표로 구분된 목록의 압축 방법을 피해라:
PRAGMA disabled_compression_methods = 'fsst,rle';
체크포인트 강제
변경 사항이 없을 때 [CHECKPOINT]({% link docs/current/sql/statements/checkpoint.md %})가 호출되면, 어쨌든 체크포인트를 강제로 실행:
PRAGMA force_checkpoint;
종료 시 체크포인트
성공적인 종료 시 CHECKPOINT를 실행하고 WAL을 삭제해 단일 데이터베이스 파일만 남기기:
PRAGMA enable_checkpoint_on_shutdown;
종료 시 CHECKPOINT를 실행하지 않기:
PRAGMA disable_checkpoint_on_shutdown;
디스크 스필 임시 디렉토리
기본적으로 DuckDB는 ⟨database_file_name⟩.tmp라는 이름의 임시 디렉토리를 사용해 디스크로 스필하며, 데이터베이스 파일과 같은 디렉토리에 있어요. 이를 변경하려면:
SET temp_directory = '/path/to/temp_dir.tmp/';
오류를 JSON으로 반환
errors_as_json 옵션을 설정하면 원시 JSON 형식의 오류 정보를 얻을 수 있어요. 특정 오류에 대해 머신 처리를 더 쉽게 하기 위한 추가 정보나 분해된 정보가 제공돼요. 예를 들어:
SET errors_as_json = true;
그러면 오류를 초래하는 쿼리를 실행하면 JSON 출력이 생성돼요:
SELECT * FROM nonexistent_tbl;
{
"exception_type":"Catalog",
"exception_message":"Table with name nonexistent_tbl does not exist!\nDid you mean \"temp.information_schema.tables\"?",
"name":"nonexistent_tbl",
"candidates":"temp.information_schema.tables",
"position":"14",
"type":"Table",
"error_subtype":"MISSING_ENTRY"
}
IEEE 부동소수점 연산 시멘틱
DuckDB는 IEEE 부동소수점 연산 시멘틱을 따르는. 이것을 끄려면:
SET ieee_floating_point_ops = false;
이 경우 부동소수점 0으로 나누기(예: 1.0 / 0.0, 0.0 / 0.0, -1.0 / 0.0)는 모두 NULL을 반환해요.
쿼리 검증 (개발용)
다음 PRAGMA들은 주로 개발과 내부 테스트에 사용돼요.
쿼리 검증 활성화:
PRAGMA enable_verification;
쿼리 검증 비활성화:
PRAGMA disable_verification;
병렬 쿼리 처리를 강제:
PRAGMA verify_parallelism;
병렬 쿼리 처리를 강제하지 않기:
PRAGMA disable_verify_parallelism;
블록 크기 (Block Sizes)
데이터베이스를 디스크에 유지할 때 DuckDB는 데이터를 보유한 블록 목록을 포함하는 전용 파일에 씁니다. 매우 적은 데이터만 보유한 파일의 경우, 예를 들어 작은 테이블이라면, 기본 블록 크기 256 kB가 이상적이지 않을 수 있어요. 따라서 DuckDB의 저장 형식은 서로 다른 블록 크기를 지원해요.
가능한 블록 크기 값에는 몇 가지 제약이 있어요.
- 2의 거듭제곱이어야 해요.
- 16384 (16 kB) 이상이어야 해요.
- 262144 (256 kB) 이하여야 해요.
인스턴스가 만든 모든 새 DuckDB 파일에 대한 기본 블록 크기를 이렇게 설정할 수 있어요:
SET default_block_size = '16384';
파일별로 블록 크기를 설정하는 것도 가능해요. 자세한 내용은 [ATTACH]({% link docs/current/sql/statements/attach.md %})를 참고해요.
더 알아보기 (Learn more)
내장 구성 옵션 전체 목록은 [Configuration Reference]({% link docs/current/configuration/overview.md %}#configuration-reference)를 참고해요.