DuckDB 提供了多种配置选项,可用于更改系统的行为。
可以通过 SET 语句 或 PRAGMA 语句 来设置这些配置选项。使用 RESET 语句 可以将它们重置为原始值。
配置选项的值可以通过 current_setting() 标量函数 或 duckdb_settings() 表函数 进行查询。例如:
SELECT current_setting('memory_limit') AS memlimit;
或
SELECT value AS memlimit
FROM duckdb_settings()
WHERE name = 'memory_limit';
示例
将系统内存限制设置为 10 GB。
SET memory_limit = '10GB';
配置系统使用 1 个线程。
SET threads TO 1;
开启日志记录并将日志级别设置为 debug。有关日志级别的更多详细信息,请参阅 日志级别 (Log Level)。
SET enable_logging = true;
SET logging_level = 'debug';
写入一条级别为 debug 且作用域为 connection 的日志消息
SELECT write_log('A new client has connected.', level := 'debug', scope := 'connection');
写入一条级别为 debug、作用域为 connection 并带有自定义 log_type 的日志消息
SELECT write_log(
'A new duck has connected to the lake.',
level := 'debug',
scope := 'connection',
log_type := 'duckdb.docs.example.quack'
);
检查级别为 DEBUG 的日志
SELECT * FROM duckdb_logs WHERE log_level = 'DEBUG';
检查 QueryLog 类型的日志
SELECT * FROM duckdb_logs WHERE type = 'QueryLog';
检查当前日志设置
SELECT * FROM duckdb_settings() WHERE name LIKE '%logging%';
在长时间运行的查询期间启用进度条显示
SET enable_progress_bar = true;
将默认空值顺序设置为 NULLS LAST
SET default_null_order = 'nulls_last';
返回特定设置的当前值
SELECT current_setting('threads') AS threads;
| threads |
|---|
| 10 |
查询特定设置
SELECT *
FROM duckdb_settings()
WHERE name = 'threads';
| name | value | description | 输入类型 | scope |
|---|---|---|---|---|
| threads | 1 | 系统使用的总线程数。 | BIGINT | GLOBAL(全局) |
显示所有可用设置的列表
SELECT *
FROM duckdb_settings();
将系统内存限制重置回默认值
RESET memory_limit;
秘密管理器
DuckDB 拥有一个 Secrets 管理器,它为所有使用密钥的后端(如 AWS S3)提供统一的用户界面。
配置参考
配置选项具有不同的默认 作用域:GLOBAL(全局)和 LOCAL(本地)。以下是按作用域分类的所有可用配置选项列表。
全局配置选项
| 名称 | 描述 | 类型 | 默认值 |
|---|---|---|---|
Calendar |
当前日历 | VARCHAR |
系统(区域设置)日历 |
TimeZone |
当前时区 | VARCHAR |
系统(区域设置)时区 |
access_mode |
数据库访问模式(AUTOMATIC, READ_ONLY 或 READ_WRITE) |
VARCHAR |
automatic |
allocator_background_threads |
是否启用分配器后台线程。 | BOOLEAN |
false |
allocator_bulk_deallocation_flush_threshold |
如果发生的批量释放操作大于此阈值,则刷新未完成的分配。 | VARCHAR |
512.0 MiB |
allocator_flush_threshold |
完成任务后刷新分配器的峰值分配阈值。 | VARCHAR |
128.0 MiB |
allow_community_extensions |
允许加载社区构建的扩展 | BOOLEAN |
true |
allow_extensions_metadata_mismatch |
允许加载元数据不兼容的扩展 | BOOLEAN |
false |
allow_persistent_secrets |
允许创建持久性密钥,这些密钥会在重启时存储和加载 | BOOLEAN |
true |
allow_unredacted_secrets |
允许打印未脱敏的密钥 | BOOLEAN |
false |
allow_unsigned_extensions |
允许加载签名无效或缺失的扩展 | BOOLEAN |
false |
allowed_directories |
始终允许查询的目录/前缀列表 - 即使在 enable_external_access 为 false 时也是如此 | VARCHAR[] |
[] |
allowed_paths |
始终允许查询的文件列表 - 即使在 enable_external_access 为 false 时也是如此 | VARCHAR[] |
[] |
arrow_large_buffer_size |
字符串、BLOB、UUID 和位 (bits) 的 Arrow 缓冲区是否应使用大缓冲区导出 | BOOLEAN |
false |
arrow_lossless_conversion |
每当 DuckDB 类型在 Arrow 中没有明确的原生或规范扩展匹配时,使用 duckdb.type_name 扩展名导出类型。 | BOOLEAN |
false |
arrow_output_list_view |
导出到 Arrow 格式时是否应将 ListView 用作 LIST 列的物理布局 | BOOLEAN |
false |
arrow_output_version |
DuckDB 产生的字符串是否应采用 Utf8View 格式而不是 Utf8 | VARCHAR |
1.0 |
asof_loop_join_threshold |
为了使用嵌套循环连接,ASOF 连接左侧所需的最大行数 | UBIGINT |
64 |
auto_fallback_to_full_download |
允许在可能的情况下自动回退到完整文件下载。 | BOOLEAN |
true |
autoinstall_extension_repository |
覆盖自动加载扩展安装的自定义端点 | VARCHAR |
|
autoinstall_known_extensions |
当查询依赖于已知扩展时,是否允许自动安装它们 | BOOLEAN |
true |
autoload_known_extensions |
当查询依赖于已知扩展时,是否允许自动加载它们 | BOOLEAN |
true |
binary_as_string |
在 Parquet 文件中,将二进制数据解释为字符串。 | BOOLEAN |
false |
ca_cert_file |
用于自签名证书的自定义证书文件路径。 | VARCHAR |
|
catalog_error_max_schemas |
系统在目录中扫描“did you mean...”风格错误时扫描的最大架构数 | UBIGINT |
100 |
checkpoint_threshold, wal_autocheckpoint |
自动触发检查点的 WAL 大小阈值(例如 1GB) | VARCHAR |
16.0 MiB |
custom_extension_repository |
覆盖远程扩展安装的自定义端点 | VARCHAR |
|
custom_user_agent |
来自 DuckDB 调用者的元数据 | VARCHAR |
|
default_block_size |
新 DuckDB 数据库文件的默认块大小(指尚不存在的新文件)。 | UBIGINT |
262144 |
default_collation |
未指定时使用的排序规则设置 | VARCHAR |
|
default_null_order, null_order |
未指定时使用的 NULL 排序(NULLS_FIRST 或 NULLS_LAST) |
VARCHAR |
NULLS_LAST |
default_order |
未指定时使用的排序类型(ASC 或 DESC) |
VARCHAR |
ASCENDING |
default_secret_storage |
允许切换密钥的默认存储 | VARCHAR |
local_file |
disable_database_invalidation |
禁止在遇到致命错误时使数据库实例失效。应非常小心地使用,因为 DuckDB 无法保证致命错误后的正确行为。 | BOOLEAN |
false |
disable_parquet_prefetching |
禁用 Parquet 中的预取机制 | BOOLEAN |
false |
disable_timestamptz_casts |
禁止将时间戳转换为 timestamptz | BOOLEAN |
false |
disabled_compression_methods |
禁用一组特定的压缩方法(逗号分隔) | VARCHAR |
|
disabled_filesystems |
禁用特定的文件系统以阻止访问(例如 LocalFileSystem) | VARCHAR |
|
disabled_log_types |
设置禁用的记录器列表 | VARCHAR |
|
duckdb_api |
DuckDB API 界面 | VARCHAR |
cli |
dynamic_or_filter_threshold |
我们从哈希连接动态生成的 OR 过滤器的最大数量 | UBIGINT |
50 |
enable_curl_server_cert_verification |
为 CURL 后端启用服务器端证书验证。 | BOOLEAN |
true |
enable_external_access |
允许数据库访问外部状态(例如通过加载/安装模块、COPY TO/FROM、CSV 读取器、pandas 替换扫描等) | BOOLEAN |
true |
enable_external_file_cache |
允许数据库在内存中缓存外部文件(例如 Parquet)。 | BOOLEAN |
true |
enable_fsst_vectors |
允许 FSST 压缩段上的扫描发出压缩向量,以利用后期解压缩 | BOOLEAN |
false |
enable_geoparquet_conversion |
如果存在空间扩展,则尝试在 GeoParquet 文件中解码/编码几何数据。 | BOOLEAN |
true |
enable_http_metadata_cache |
是否使用全局 HTTP 元数据缓存 HTTP 元数据 | BOOLEAN |
false |
enable_logging |
启用记录器 | BOOLEAN |
0 |
enable_macro_dependencies |
启用创建的 MACRO 以便在引用的对象(如表)上创建依赖项 | BOOLEAN |
false |
enable_object_cache |
[占位符] 旧设置 - 不起作用 | BOOLEAN |
false |
enable_server_cert_verification |
启用服务器端证书验证。 | BOOLEAN |
false |
enable_view_dependencies |
启用创建的 VIEW 以便在引用的对象(如表)上创建依赖项 | BOOLEAN |
false |
enabled_log_types |
设置启用的记录器列表 | VARCHAR |
|
experimental_metadata_reuse |
实验性:检查点时重用行组和表元数据。 | BOOLEAN |
false |
extension_directory |
设置存储扩展的目录 | VARCHAR |
|
external_threads |
处理 DuckDB 任务的外部线程数。 | UBIGINT |
1 |
force_download |
强制预先下载文件 | BOOLEAN |
false |
http_keep_alive |
保持活动连接。设置为 false 可能有助于解决连接失败问题 | BOOLEAN |
true |
http_proxy_password |
HTTP 代理密码 | VARCHAR |
|
http_proxy_username |
HTTP 代理用户名 | VARCHAR |
|
http_proxy |
HTTP 代理主机 | VARCHAR |
|
http_retries |
I/O 错误时的 HTTP 重试次数 | UBIGINT |
3 |
http_retry_backoff |
用于指数增加重试等待时间的退避因子 | FLOAT |
4 |
http_retry_wait_ms |
重试之间的时间 | UBIGINT |
100 |
http_timeout |
HTTP 超时读/写/连接/重试(以秒为单位) | UBIGINT |
30 |
httpfs_client_implementation |
选择要使用的 HTTPUtil 实现 | VARCHAR |
默认值 (default) |
ieee_floating_point_ops |
使用符合 IEE754 标准的浮点运算(返回 NAN 而不是错误/NULL)。 | BOOLEAN |
true |
immediate_transaction_mode |
事务是应该在需要时延迟启动,还是在调用 BEGIN TRANSACTION 时立即启动 | BOOLEAN |
false |
index_scan_max_count |
最大索引扫描计数设置了索引扫描的阈值。如果匹配的行数少于 MAX(index_scan_max_count, index_scan_percentage * total_row_count),我们将执行索引扫描而不是表扫描。 | UBIGINT |
2048 |
index_scan_percentage |
索引扫描百分比设置了索引扫描的阈值。如果匹配的行数少于 MAX(index_scan_max_count, index_scan_percentage * total_row_count),我们将执行索引扫描而不是表扫描。 | DOUBLE |
0.001 |
integer_division |
/ 运算符默认是整数除法还是浮点除法 | BOOLEAN |
false |
late_materialization_max_rows |
触发延迟物化的 LIMIT/SAMPLE 中的最大行数 | UBIGINT |
50 |
lock_configuration |
配置是否可以更改 | BOOLEAN |
false |
logging_level |
将记录在日志中的日志级别 | VARCHAR |
INFO |
logging_mode |
确定记录哪些类型的日志消息 | VARCHAR |
LEVEL_ONLY |
logging_storage |
设置日志存储(memory/stdout/file/) |
VARCHAR |
memory |
max_memory, memory_limit |
系统最大内存(例如 1GB) | VARCHAR |
80% 的内存 |
max_temp_directory_size |
'temp_directory'(设置时)内存储的最大数据量(例如 1GB) | VARCHAR |
90% 的可用磁盘空间 |
max_vacuum_tasks |
检查点期间要调度的最大清理任务数。 | UBIGINT |
100 |
merge_join_threshold |
选择合并连接的任一表上的最大行数 | UBIGINT |
1000 |
nested_loop_join_threshold |
选择嵌套循环连接的任一表上的最大行数 | UBIGINT |
5 |
old_implicit_casting |
允许与 VARCHAR 进行隐式转换 | BOOLEAN |
false |
order_by_non_integer_literal |
允许按非整数文本排序 - 按此类文本排序无效。 | BOOLEAN |
false |
ordered_aggregate_threshold |
排序前累积的行数,用于调整 | UBIGINT |
262144 |
parquet_metadata_cache |
缓存 Parquet 元数据 - 在多次读取相同文件时很有用 | BOOLEAN |
false |
partitioned_write_flush_threshold |
使用 PARTITION_BY 写入时,刷新线程状态的行数阈值 |
UBIGINT |
524288 |
partitioned_write_max_open_files |
使用 PARTITION_BY 写入时,在刷新到磁盘之前系统可以保持打开的最大文件数 |
UBIGINT |
100 |
password |
要使用的密码。出于旧版兼容性考虑而被忽略。 | VARCHAR |
NULL |
perfect_ht_threshold |
何时使用完美哈希表的字节阈值 | UBIGINT |
12 |
pin_threads |
是否将线程绑定到核心(仅限 Linux,默认 AUTO:在超过 64 个核心时开启) | VARCHAR |
auto |
pivot_filter_threshold |
从使用过滤聚合切换到带有专用透视运算符的 LIST 的阈值 | UBIGINT |
20 |
pivot_limit |
透视语句中的最大透视列数 | UBIGINT |
100000 |
prefer_range_joins |
强制对混合谓词使用范围连接 | BOOLEAN |
false |
prefetch_all_parquet_files |
对所有类型的 parquet 文件使用预取机制 | BOOLEAN |
false |
preserve_identifier_case |
是否保留标识符大小写,而不是总是将所有非引号标识符转换为小写 | BOOLEAN |
true |
preserve_insertion_order |
是否保留插入顺序。如果设置为 false,则系统可以重新排序任何不包含 ORDER BY 子句的结果。 | BOOLEAN |
true |
produce_arrow_string_view |
Arrow 字符串是否应由 DuckDB 以 Utf8View 格式而不是 Utf8 产生 | BOOLEAN |
false |
s3_access_key_id |
S3 访问密钥 ID | VARCHAR |
NULL |
s3_endpoint |
S3 端点 | VARCHAR |
NULL |
s3_kms_key_id |
S3 KMS 密钥 ID | VARCHAR |
NULL |
s3_region |
S3 区域 | VARCHAR |
NULL |
s3_requester_pays |
S3 使用请求者付费模式 | BOOLEAN |
false |
s3_secret_access_key |
S3 访问密钥 | VARCHAR |
NULL |
s3_session_token |
S3 会话令牌 | VARCHAR |
NULL |
s3_uploader_max_filesize |
S3 上传器最大文件大小(50GB 到 5TB 之间) | VARCHAR |
800GB |
s3_uploader_max_parts_per_file |
S3 上传器每个文件的最大分片数(1 到 10000 之间) | UBIGINT |
10000 |
s3_uploader_thread_limit |
S3 上传器全局线程限制 | UBIGINT |
50 |
s3_url_compatibility_mode |
禁用 S3 URL 上的 Globs 和查询参数 | BOOLEAN |
false |
s3_url_style |
S3 URL 样式 | VARCHAR |
vhost |
s3_use_ssl |
S3 使用 SSL | BOOLEAN |
true |
scalar_subquery_error_on_multiple_rows |
当标量子查询返回多行时 - 返回随机行而不是返回错误。 | BOOLEAN |
true |
scheduler_process_partial |
在重新调度之前部分处理任务 - 允许在单独的查询之间实现更好的调度程序公平性 | BOOLEAN |
false |
secret_directory |
设置存储持久性密钥的目录 | VARCHAR |
~/.duckdb/stored_secrets |
storage_compatibility_version |
在检查点序列化时与给定的 duckdb 版本兼容 | VARCHAR |
v0.10.2 |
temp_directory |
设置写入临时文件的目录 | VARCHAR |
⟨database_name⟩.tmp 或 .tmp(在内存模式下) |
temp_file_encryption |
如果数据库已加密,则加密所有临时文件 | BOOLEAN |
false |
threads, worker_threads |
系统使用的总线程数。 | BIGINT |
# CPU 核心数 |
unsafe_disable_etag_checks |
禁用 ETag 一致性检查 | BOOLEAN |
false |
user, username |
要使用的用户名。出于旧版兼容性考虑而被忽略。 | VARCHAR |
NULL |
variant_legacy_encoding |
使 Parquet 读取器能够从结构上识别 Variant。 | BOOLEAN |
false |
zstd_min_string_length |
考虑 ZSTD 压缩的(平均)长度。显式启用 ZSTD 时(1.3.0 及以上版本)被忽略。 | UBIGINT |
4096 |
本地配置选项
| 名称 | 描述 | 类型 | 默认值 |
|---|---|---|---|
custom_profiling_settings |
接受一个启用自定义指标的 JSON |
VARCHAR |
{"TOTAL_BYTES_WRITTEN": "true", "TOTAL_BYTES_READ": "true", "ROWS_RETURNED": "true", "LATENCY": "true", "RESULT_SET_SIZE": "true", "OPERATOR_TIMING": "true", "OPERATOR_ROWS_SCANNED": "true", "CUMULATIVE_ROWS_SCANNED": "true", "OPERATOR_CARDINALITY": "true", "OPERATOR_TYPE": "true", "OPERATOR_NAME": "true", "CPU_TIME": "true", "EXTRA_INFO": "true", "SYSTEM_PEAK_BUFFER_MEMORY": "true", "BLOCKED_THREAD_TIME": "true", "CUMULATIVE_CARDINALITY": "true", "SYSTEM_PEAK_TEMP_DIR_SIZE": "true", "QUERY_NAME": "true"} |
enable_http_logging |
(已弃用)启用 HTTP 日志记录 | BOOLEAN |
true |
enable_profiling |
启用分析并设置输出格式(JSON, QUERY_TREE, QUERY_TREE_OPTIMIZER) |
VARCHAR |
NULL |
enable_progress_bar_print |
当 'enable_progress_bar' 为 true 时,控制进度条的打印 | BOOLEAN |
true |
enable_progress_bar |
启用进度条,在终端中为长查询打印进度 | BOOLEAN |
true |
errors_as_json |
以结构化 JSON 而不是原始字符串输出错误消息 |
BOOLEAN |
false |
explain_output |
EXPLAIN 语句的输出(ALL, OPTIMIZED_ONLY, PHYSICAL_ONLY) |
VARCHAR |
physical_only |
file_search_path |
用于搜索输入文件的以逗号分隔的目录列表 | VARCHAR |
|
home_directory |
设置系统使用的主目录 | VARCHAR |
|
http_logging_output |
(已弃用)保存 HTTP 日志输出的文件,或者留空以打印到终端 | VARCHAR |
|
lambda_syntax |
配置 lambda 函数对已弃用的单箭头运算符 (->) 的使用。 | VARCHAR |
DEFAULT |
log_query_path |
指定应记录查询的路径(默认值:NULL,不记录查询) | VARCHAR |
NULL |
max_expression_depth |
解析器中的最大表达式深度限制。警告:增加此设置并使用非常深的表达式可能会导致堆栈溢出错误。 | UBIGINT |
1000 |
profile_output, profiling_output |
应保存配置文件输出的文件,或者留空以打印到终端 | VARCHAR |
|
profiling_coverage |
分析覆盖率(SELECT 或 ALL) |
VARCHAR |
SELECT |
profiling_mode |
分析模式(STANDARD 或 DETAILED) |
VARCHAR |
NULL |
progress_bar_time |
设置查询需要多长时间(以毫秒为单位)才开始打印进度条 | BIGINT |
2000 |
schema |
设置默认搜索架构。相当于将 search_path 设置为单个值。 | VARCHAR |
main |
search_path |
将默认目录搜索路径设置为以逗号分隔的值列表 | VARCHAR |
|
streaming_buffer_size |
从流式结果获取数据时缓冲的最大内存(例如 1GB) | VARCHAR |
976.5 KiB |