⌘+k ctrl+k
1.1.3 (stable)
Search Shortcut cmd + k | ctrl + k
Configuration

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)提供了一个统一的用户界面来管理密钥。

配置参考

配置选项带有不同的默认作用域GLOBALLOCAL。以下是按作用域列出的所有可用配置选项的列表。

全局配置选项

名称 描述 类型 默认值
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
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_DESCNULLS_LAST_ON_ASC_FIRST_ON_DESC) VARCHAR NULLS_LAST
default_order 未指定时使用的排序类型(ASCDESC 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 分析模式(STANDARDDETAILED 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

本节中的页面