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;
将默认的空值顺序设置为NULLS LAST
。
SET default_null_order = 'nulls_last';
返回特定设置的当前值。
SELECT current_setting('threads') AS threads;
线程 |
---|
10 |
查询特定设置。
SELECT *
FROM duckdb_settings()
WHERE name = 'threads';
名称 | 值 | 描述 | 输入类型 | 范围 |
---|---|---|---|---|
threads | 1 | 系统使用的总线程数。 | BIGINT | GLOBAL |
显示所有可用设置的列表。
SELECT *
FROM duckdb_settings();
将系统的内存限制重置为默认值。
RESET memory_limit;
Secrets Manager
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 |
arrow_large_buffer_size |
是否应使用大缓冲区导出字符串、二进制数据、UUID和位数据的箭头缓冲区 | BOOLEAN |
false |
arrow_lossless_conversion |
每当DuckDB类型在Arrow中没有明确的本机或规范扩展匹配时,使用duckdb.type_name扩展名导出类型。 | BOOLEAN |
false |
arrow_output_list_view |
是否应将导出到arrow格式使用ListView作为LIST列的物理布局 | BOOLEAN |
false |
autoinstall_extension_repository |
覆盖自动加载时扩展安装的自定义端点 | VARCHAR |
|
autoinstall_known_extensions |
当查询依赖于已知扩展时,是否允许自动安装这些扩展 | BOOLEAN |
true |
autoload_known_extensions |
当查询依赖于已知扩展时,是否允许自动加载这些扩展 | BOOLEAN |
true |
binary_as_string |
在Parquet文件中,将二进制数据解释为字符串。 | BOOLEAN |
|
ca_cert_file |
自定义证书文件的路径,用于自签名证书。 | VARCHAR |
|
catalog_error_max_schemas |
系统将在目录中扫描“您是否指的是…”样式错误的最大模式数 | 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 |
未指定时使用的空值排序方式 (NULLS_FIRST , NULLS_LAST , NULLS_FIRST_ON_ASC_LAST_ON_DESC 或 NULLS_LAST_ON_ASC_FIRST_ON_DESC ) |
VARCHAR |
NULLS_LAST |
default_order |
未指定时使用的排序类型(ASC 或 DESC ) |
VARCHAR |
ASC |
default_secret_storage |
允许切换默认的密钥存储方式 | VARCHAR |
local_file |
disabled_filesystems |
禁用特定的文件系统以防止访问(例如,LocalFileSystem) | VARCHAR |
|
duckdb_api |
DuckDB API 接口 | VARCHAR |
cli |
enable_external_access |
允许数据库访问外部状态(例如,通过加载/安装模块、COPY TO/FROM、CSV读取器、pandas替换扫描等) | BOOLEAN |
true |
enable_fsst_vectors |
允许在FSST压缩段上进行扫描,以发出压缩向量,从而利用延迟解压缩 | BOOLEAN |
false |
enable_http_metadata_cache |
是否使用全局HTTP元数据来缓存HTTP元数据 | BOOLEAN |
false |
enable_macro_dependencies |
启用创建的宏以创建对引用对象(如表)的依赖关系 | BOOLEAN |
false |
enable_object_cache |
是否使用对象缓存来缓存例如Parquet元数据 | BOOLEAN |
false |
enable_server_cert_verification |
启用服务器端证书验证。 | BOOLEAN |
false |
enable_view_dependencies |
启用创建的视图以创建对引用对象(如表)的依赖关系 | BOOLEAN |
false |
extension_directory |
设置存储扩展的目录 | VARCHAR |
|
external_threads |
处理DuckDB任务的外部线程数量。 | BIGINT |
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 |
30000 |
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 |
max_memory , memory_limit |
系统的最大内存(例如,1GB) | VARCHAR |
80% 的 RAM |
max_temp_directory_size |
存储在'temp_directory'中的最大数据量。默认值0 bytes 是一个占位符,表示可以使用该驱动器上的所有可用磁盘空间。要实际将temp_directory 限制为0 bytes ,请将temp_directory 设置为NULL 或空字符串。 |
VARCHAR |
0 bytes |
max_vacuum_tasks |
在检查点期间调度的最大真空任务数 | UBIGINT |
100 |
old_implicit_casting |
允许隐式转换到/从 VARCHAR | BOOLEAN |
false |
password |
使用的密码。为了旧版兼容性而忽略。 | VARCHAR |
NULL |
preserve_insertion_order |
是否保留插入顺序。如果设置为false,系统可以重新排序任何不包含ORDER BY子句的结果。 | BOOLEAN |
true |
produce_arrow_string_view |
DuckDB是否应该以Utf8View格式而不是Utf8格式生成字符串 | BOOLEAN |
false |
s3_access_key_id |
S3 访问密钥 ID | VARCHAR |
|
s3_endpoint |
S3 端点 | VARCHAR |
|
s3_region |
S3 区域 | VARCHAR |
us-east-1 |
s3_secret_access_key |
S3访问密钥 | VARCHAR |
|
s3_session_token |
S3 会话令牌 | VARCHAR |
|
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上的通配符和查询参数 | BOOLEAN |
false |
s3_url_style |
S3 URL 风格 | VARCHAR |
vhost |
s3_use_ssl |
S3 使用 SSL | BOOLEAN |
true |
secret_directory |
设置持久化密钥存储的目录 | VARCHAR |
~/.duckdb/stored_secrets |
storage_compatibility_version |
在检查点上序列化,以兼容给定的duckdb版本 | VARCHAR |
v0.10.2 |
temp_directory |
设置写入临时文件的目录。设置为NULL 或空字符串以禁用。 |
VARCHAR |
⟨database_name⟩.tmp 或 .tmp (在内存模式下) |
threads , worker_threads |
系统使用的总线程数。 | BIGINT |
# CPU 核心数 |
username , user |
要使用的用户名。为了向后兼容性而忽略。 | VARCHAR |
NULL |
本地配置选项
Name | Description | Type | Default value |
---|---|---|---|
custom_profiling_settings |
接受一个JSON ,用于启用自定义指标 |
VARCHAR |
{"RESULT_SET_SIZE": "true", "OPERATOR_TIMING": "true", "OPERATOR_ROWS_SCANNED": "true", "CUMULATIVE_ROWS_SCANNED": "true", "OPERATOR_CARDINALITY": "true", "OPERATOR_TYPE": "true", "CUMULATIVE_CARDINALITY": "true", "EXTRA_INFO": "true", "CPU_TIME": "true", "BLOCKED_THREAD_TIME": "true", "QUERY_NAME": "true"} |
enable_http_logging |
启用HTTP日志记录 | BOOLEAN |
false |
enable_profiling |
启用性能分析,并设置输出格式(JSON , QUERY_TREE , QUERY_TREE_OPTIMIZER ) |
VARCHAR |
NULL |
enable_progress_bar_print |
控制进度条的打印,当'enable_progress_bar'为真时 | 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 |
|
ieee_floating_point_ops |
使用符合IEE754标准的浮点运算(返回NAN而不是错误/NULL) | BOOLEAN |
true |
integer_division |
/ 运算符是否默认为整数除法,或浮点除法 | BOOLEAN |
false |
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 |
使用完美哈希表的字节阈值 | BIGINT |
12 |
pivot_filter_threshold |
从使用过滤聚合切换到使用带有专用透视操作符的LIST的阈值 | BIGINT |
20 |
pivot_limit |
在pivot语句中,pivot列的最大数量 | BIGINT |
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 |