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;
在长时间运行的查询期间启用进度条的打印。
SET enable_progress_bar = true;
将默认的 NULL 排序设置为 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 manager（密钥管理器），它为所有使用密钥的后端（例如 AWS S3）提供了统一的密钥用户界面。
配置参考
配置选项带有不同的默认 作用域：GLOBAL（全局）和 LOCAL（本地）。以下是按作用域列出的所有可用配置选项。
全局配置选项
| 名称 | 描述 | 类型 | 默认值 |
|---|---|---|---|
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（Arrow大缓冲区大小） |
字符串、Blob、UUID 和位（bits）的 Arrow 缓冲区是否应使用大缓冲区导出 | BOOLEAN |
false（否） |
arrow_lossless_conversion（Arrow无损转换） |
当 DuckDB 类型在 Arrow 中没有明确的本地或规范扩展匹配时，将类型导出为 duckdb.type_name 扩展名称。 |
BOOLEAN |
false（否） |
arrow_output_list_view（Arrow输出列表视图） |
导出到 Arrow 格式时，LIST 列是否应使用 ListView 作为物理布局 | BOOLEAN |
false（否） |
autoinstall_extension_repository（自动安装扩展仓库） |
覆盖自动加载时扩展安装的自定义端点 | VARCHAR |
|
autoinstall_known_extensions（自动安装已知扩展） |
当查询依赖已知扩展时，是否允许自动安装它们 | BOOLEAN |
false（否） |
autoload_known_extensions（自动加载已知扩展） |
当查询依赖已知扩展时，是否允许自动加载它们 | BOOLEAN |
false（否） |
binary_as_string（二进制作为字符串） |
在 Parquet 文件中，将二进制数据解释为字符串。 | BOOLEAN |
|
ca_cert_file（CA证书文件） |
自签名证书的自定义证书文件路径。 | VARCHAR |
|
catalog_error_max_schemas（目录错误最大模式数） |
系统将为目录中的“您是否是指…”样式错误扫描的最大模式数 | UBIGINT |
100 |
checkpoint_threshold（检查点阈值）, wal_autocheckpoint（WAL自动检查点） |
自动触发检查点的 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排序）, null_order（NULL排序） |
未指定时使用的 NULL 排序（NULLS_FIRST（NULL优先）或 NULLS_LAST（NULL最后）） |
VARCHAR |
NULLS_LAST（NULL最后） |
default_order（默认排序） |
未指定时使用的排序类型（ASC（升序）或 DESC（降序）） |
VARCHAR |
ASC（升序） |
default_secret_storage（默认密钥存储） |
允许切换密钥的默认存储 | VARCHAR |
local_file（本地文件） |
disable_parquet_prefetching（禁用Parquet预取） |
禁用 Parquet 中的预取机制 | BOOLEAN |
false（否） |
disabled_compression_methods（禁用的压缩方法） |
禁用一组特定的压缩方法（逗号分隔） | VARCHAR |
|
disabled_filesystems（禁用的文件系统） |
禁用特定文件系统以防止访问（例如 LocalFileSystem） | VARCHAR |
|
disabled_log_types（禁用的日志类型） |
设置禁用的日志记录器列表 | VARCHAR |
|
duckdb_api |
DuckDB API 表面 | VARCHAR |
cli |
enable_external_access（启用外部访问） |
允许数据库访问外部状态（通过例如加载/安装模块、COPY TO/FROM、CSV 读取器、pandas 替换扫描等） | BOOLEAN |
true（是） |
enable_external_file_cache（启用外部文件缓存） |
允许数据库将外部文件（例如 Parquet）缓存在内存中。 | BOOLEAN |
true（是） |
enable_fsst_vectors（启用FSST向量） |
允许对 FSST 压缩段进行扫描，以发出压缩向量以利用后期解压缩 | BOOLEAN |
false（否） |
enable_geoparquet_conversion（启用GeoParquet转换） |
如果存在空间扩展，尝试将几何数据解码/编码为 GeoParquet 文件。 | BOOLEAN |
true（是） |
enable_http_metadata_cache（启用HTTP元数据缓存） |
是否使用全局 HTTP 元数据来缓存 HTTP 元数据 | BOOLEAN |
false（否） |
enable_logging（启用日志记录） |
启用日志记录器 | BOOLEAN |
0 |
enable_macro_dependencies（启用宏依赖） |
使已创建的 MACROs 能够创建对引用对象（例如表）的依赖 | BOOLEAN |
false（否） |
enable_object_cache（启用对象缓存） |
[占位符] 旧版设置 - 无作用 | BOOLEAN |
NULL |
enable_server_cert_verification（启用服务器证书验证） |
启用服务器端证书验证。 | BOOLEAN |
false（否） |
enable_view_dependencies（启用视图依赖） |
使已创建的 VIEWs 能够创建对引用对象（例如表）的依赖 | BOOLEAN |
false（否） |
enabled_log_types（启用的日志类型） |
设置启用的日志记录器列表 | VARCHAR |
|
extension_directory（扩展目录） |
设置存储扩展的目录 | VARCHAR |
|
external_threads（外部线程） |
处理 DuckDB 任务的外部线程数。 | UBIGINT |
1 |
force_download（强制下载） |
强制提前下载文件 | BOOLEAN |
false（否） |
http_keep_alive（HTTP保持连接） |
保持连接。将其设置为 false 有助于解决连接失败问题 | BOOLEAN |
true（是） |
http_proxy_password（HTTP代理密码） |
HTTP 代理密码 | VARCHAR |
|
http_proxy_username（HTTP代理用户名） |
HTTP 代理用户名 | VARCHAR |
|
http_proxy（HTTP代理） |
HTTP 代理主机 | VARCHAR |
|
http_retries（HTTP重试） |
I/O 错误时的 HTTP 重试次数 | UBIGINT |
3 |
http_retry_backoff（HTTP重试退避因子） |
指数增加重试等待时间的退避因子 | FLOAT |
4 |
http_retry_wait_ms（HTTP重试等待毫秒） |
重试之间的等待时间 | UBIGINT |
100 |
http_timeout（HTTP超时） |
HTTP 读/写/连接/重试超时（秒） | UBIGINT |
30 |
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 |
lock_configuration（锁定配置） |
配置是否可以更改 | BOOLEAN |
false（否） |
logging_level（日志级别） |
将记录在日志中的日志级别 | VARCHAR |
INFO（信息） |
logging_mode（日志模式） |
启用日志记录器 | VARCHAR |
LEVEL_ONLY（仅级别） |
logging_storage（日志存储） |
设置日志存储（内存/标准输出/文件） | VARCHAR |
memory（内存） |
max_memory（最大内存）, memory_limit（内存限制） |
系统最大内存（例如，1GB） | VARCHAR |
RAM 的 80% |
max_temp_directory_size（最大临时目录大小） |
存储在“temp_directory”（如果设置）中的最大数据量（例如，1GB） | VARCHAR |
可用磁盘空间的 90% |
max_vacuum_tasks（最大清理任务数） |
在检查点期间计划的最大清理任务数。 | UBIGINT |
100 |
old_implicit_casting（旧式隐式转换） |
允许 VARCHAR 之间的隐式转换 | BOOLEAN |
false（否） |
parquet_metadata_cache（Parquet元数据缓存） |
缓存 Parquet 元数据 - 在多次读取相同文件时很有用 | BOOLEAN |
false（否） |
password（密码） |
要使用的密码。为兼容旧版而忽略。 | VARCHAR |
NULL |
prefetch_all_parquet_files（预取所有Parquet文件） |
对所有类型的 Parquet 文件使用预取机制 | BOOLEAN |
false（否） |
preserve_insertion_order（保留插入顺序） |
是否保留插入顺序。如果设置为 false，系统可以重新排序不包含 ORDER BY 子句的任何结果。 | BOOLEAN |
true（是） |
produce_arrow_string_view（生成Arrow字符串视图） |
DuckDB 是否应以 Utf8View 格式而不是 Utf8 格式生成字符串 | BOOLEAN |
false（否） |
s3_access_key_id（S3访问密钥ID） |
S3 访问密钥 ID | VARCHAR |
|
s3_endpoint（S3端点） |
S3 端点 | VARCHAR |
|
s3_kms_key_id（S3 KMS密钥ID） |
S3 KMS 密钥 ID | VARCHAR |
|
s3_region（S3区域） |
S3 区域 | VARCHAR |
us-east-1 |
s3_secret_access_key（S3秘密访问密钥） |
S3 访问密钥 | VARCHAR |
|
s3_session_token（S3会话令牌） |
S3 会话令牌 | VARCHAR |
|
s3_uploader_max_filesize（S3上传器最大文件大小） |
S3 上传器最大文件大小（50GB 到 5TB 之间） | VARCHAR |
800GB |
s3_uploader_max_parts_per_file（S3上传器每个文件最大分段数） |
S3 上传器每个文件最大分段数（1 到 10000 之间） | UBIGINT |
10000 |
s3_uploader_thread_limit（S3上传器全局线程限制） |
S3 上传器全局线程限制 | UBIGINT |
50 |
s3_url_compatibility_mode（S3 URL兼容模式） |
禁用 S3 URL 上的通配符和查询参数 | BOOLEAN |
false（否） |
s3_url_style（S3 URL样式） |
S3 URL 样式 | VARCHAR |
vhost |
s3_use_ssl（S3使用SSL） |
S3 使用 SSL | 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（在内存模式下） |
threads（线程）, worker_threads（工作线程） |
系统使用的总线程数。 | BIGINT |
CPU 核心数 |
username（用户名）, user（用户） |
要使用的用户名。为兼容旧版而忽略。 | VARCHAR |
NULL |
zstd_min_string_length（ZSTD最小字符串长度） |
启用 ZSTD 压缩的（平均）长度，默认为 4096 | UBIGINT |
4096 |
本地配置选项
| 名称 | 描述 | 类型 | 默认值 |
|---|---|---|---|
asof_loop_join_threshold（ASOF循环连接阈值） |
ASOF 连接左侧使用嵌套循环连接所需的最大行数 | UBIGINT |
64 |
custom_profiling_settings（自定义分析设置） |
接受 JSON，启用自定义指标 |
VARCHAR |
{"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"} |
disable_timestamptz_casts（禁用时间戳时区转换） |
禁用从 timestamp 到 timestamptz 的转换 | BOOLEAN |
false（否） |
dynamic_or_filter_threshold（动态OR筛选阈值） |
从哈希连接动态生成的 OR 筛选器的最大数量 | UBIGINT |
50 |
enable_http_logging（启用HTTP日志记录） |
启用 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） |
将错误消息输出为结构化的 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日志输出） |
HTTP 日志输出应保存到的文件，或空字符串表示打印到终端 | VARCHAR |
|
ieee_floating_point_ops（IEEE浮点运算） |
使用符合 IEE754 的浮点运算（返回 NAN 而不是错误/NULL）。 | BOOLEAN |
true（是） |
integer_division（整数除法） |
/ 运算符是默认为整数除法，还是浮点除法 | BOOLEAN |
false（否） |
lambda_syntax（Lambda语法） |
配置 lambda 函数使用已弃用的单箭头运算符 (->)。 | VARCHAR |
DEFAULT（默认） |
late_materialization_max_rows（后期物化最大行数） |
触发后期物化的 LIMIT/SAMPLE 中的最大行数 | UBIGINT |
50 |
log_query_path（查询日志路径） |
指定查询应记录到的路径（默认：NULL，不记录查询） | VARCHAR |
NULL |
max_expression_depth（最大表达式深度） |
解析器中最大表达式深度限制。警告：增加此设置并使用非常深的表达式可能导致堆栈溢出错误。 | UBIGINT |
1000 |
merge_join_threshold（合并连接阈值） |
选择合并连接所需的任一表中的行数 | UBIGINT |
1000 |
nested_loop_join_threshold（嵌套循环连接阈值） |
选择嵌套循环连接所需的任一表中的行数 | UBIGINT |
5 |
order_by_non_integer_literal（按非整数文字排序） |
允许按非整数文字排序 - 按此类文字排序没有效果。 | BOOLEAN |
false（否） |
ordered_aggregate_threshold（有序聚合阈值） |
在排序之前累积的行数，用于调整 | UBIGINT |
262144 |
partitioned_write_flush_threshold（分区写入刷新阈值） |
使用 PARTITION_BY 写入时，刷新线程状态的行数阈值 |
UBIGINT |
524288 |
partitioned_write_max_open_files（分区写入最大打开文件数） |
使用 PARTITION_BY 写入时，系统在刷新到磁盘之前可以保持打开的最大文件数 |
UBIGINT |
100 |
perfect_ht_threshold（完美哈希表阈值） |
使用完美哈希表的字节阈值 | UBIGINT |
12 |
pivot_filter_threshold（透视筛选阈值） |
从使用筛选聚合切换到使用带有专用透视操作符的 LIST 的阈值 | UBIGINT |
20 |
pivot_limit（透视限制） |
透视语句中透视列的最大数量 | UBIGINT |
100000 |
prefer_range_joins（偏好范围连接） |
强制使用带有混合谓词的范围连接 | BOOLEAN |
false（否） |
preserve_identifier_case（保留标识符大小写） |
是否保留标识符大小写，而不是总是将所有未加引号的标识符小写 | BOOLEAN |
true（是） |
profile_output（配置文件输出）, profiling_output（分析输出） |
配置文件输出应保存到的文件，或空字符串表示打印到终端 | VARCHAR |
|
profiling_mode（分析模式） |
分析模式（STANDARD（标准）或 DETAILED（详细）） |
VARCHAR |
NULL |
progress_bar_time（进度条时间） |
设置查询需要运行多长时间（毫秒）才能开始打印进度条 | BIGINT |
2000 |
scalar_subquery_error_on_multiple_rows（标量子查询多行错误） |
当标量子查询返回多行时 - 返回随机行而不是返回错误。 | BOOLEAN |
true（是） |
schema（模式） |
设置默认搜索模式。等同于将 search_path 设置为单个值。 | VARCHAR |
main（主） |
search_path（搜索路径） |
将默认目录搜索路径设置为逗号分隔的值列表 | VARCHAR |
|
streaming_buffer_size（流式缓冲区大小） |
从流式结果获取之间缓冲的最大内存（例如，1GB） | VARCHAR |
976.5 KiB |