⌘+k ctrl+k
1.4 (LTS)
搜索快捷键 cmd + k | ctrl + k
配置

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_ONLYREAD_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_FIRSTNULLS_LAST VARCHAR NULLS_LAST
default_order 未指定时使用的排序类型(ASCDESC 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 分析模式(STANDARDDETAILED VARCHAR NULL
progress_bar_time 设置查询需要多长时间(以毫秒为单位)才开始打印进度条 BIGINT 2000
schema 设置默认搜索架构。相当于将 search_path 设置为单个值。 VARCHAR main
search_path 将默认目录搜索路径设置为以逗号分隔的值列表 VARCHAR  
streaming_buffer_size 从流式结果获取数据时缓冲的最大内存(例如 1GB) VARCHAR 976.5 KiB

本节页面

© 2025 DuckDB 基金会,阿姆斯特丹,荷兰
行为准则 商标使用指南