The PRAGMA statement is a SQL extension adopted by DuckDB from SQLite. PRAGMA statements can be issued in a similar manner to regular SQL statements. PRAGMA commands may alter the internal state of the database engine, and can influence the subsequent execution or behavior of the engine.

为选项赋值的 PRAGMA 语句也可以使用 SET 语句发出，并且可以使用 SELECT current_setting(option_name) 检索选项的值。

有关 DuckDB 内置配置选项的信息，请参阅配置参考。DuckDB 扩展可能会注册额外的配置选项。这些选项在其各自的扩展文档页面中有所说明。

本页包含支持的 PRAGMA 设置。

元数据

模式信息

列出所有数据库

PRAGMA database_list;

列出所有表

PRAGMA show_tables;

列出所有表及附加信息，类似于 DESCRIBE

PRAGMA show_tables_expanded;

列出所有函数

PRAGMA functions;

对于针对不存在的模式的查询，DuckDB 会生成“您是不是想找…”样式的错误消息。当有数千个附加数据库时，生成这些错误可能需要很长时间。要限制 DuckDB 查找的模式数量，请使用 catalog_error_max_schemas 选项。

SET catalog_error_max_schemas = 10;

表信息

获取特定表的信息

PRAGMA table_info('table_name');
CALL pragma_table_info('table_name');

table_info 返回有关名为 table_name 的表的列信息。返回表的具体格式如下所示：

cid INTEGER,        -- cid of the column
name VARCHAR,       -- name of the column
type VARCHAR,       -- type of the column
notnull BOOLEAN,    -- if the column is marked as NOT NULL
dflt_value VARCHAR, -- default value of the column, or NULL if not specified
pk BOOLEAN          -- part of the primary key or not

数据库大小

获取每个数据库的文件和内存大小

PRAGMA database_size;
CALL pragma_database_size();

database_size 返回每个数据库的文件和内存大小信息。返回结果的列类型如下所示：

database_name VARCHAR, -- database name
database_size VARCHAR, -- total block count times the block size
block_size BIGINT,     -- database block size
total_blocks BIGINT,   -- total blocks in the database
used_blocks BIGINT,    -- used blocks in the database
free_blocks BIGINT,    -- free blocks in the database
wal_size VARCHAR,      -- write ahead log size
memory_usage VARCHAR,  -- memory used by the database buffer manager
memory_limit VARCHAR   -- maximum memory allowed for the database

存储信息

获取存储信息

PRAGMA storage_info('table_name');
CALL pragma_storage_info('table_name');

此调用为给定表返回以下信息

有关更多信息，请参阅存储。

显示数据库

以下语句等同于 SHOW DATABASES 语句

PRAGMA show_databases;

资源管理

内存限制

设置缓冲区管理器的内存限制

SET memory_limit = '1GB';

警告：指定的内存限制仅适用于缓冲区管理器。对于大多数查询，缓冲区管理器处理大部分已处理的数据。但是，某些内存中的数据结构（例如向量和查询结果）是在缓冲区管理器外部分配的。此外，具有复杂状态的聚合函数（例如 list、mode、quantile、string_agg 和 approx 函数）也使用缓冲区管理器外部的内存。因此，实际内存消耗可能高于指定的内存限制。

线程

设置并行查询执行的线程数量

SET threads = 4;

排序规则

列出所有可用的排序规则

PRAGMA collations;

将默认排序规则设置为其中一个可用选项

SET default_collation = 'nocase';

NULL 值的默认排序方式

将 NULL 值的默认排序设置为 NULLS_FIRST、NULLS_LAST、NULLS_FIRST_ON_ASC_LAST_ON_DESC 或 NULLS_LAST_ON_ASC_FIRST_ON_DESC。

SET default_null_order = 'NULLS_FIRST';
SET default_null_order = 'NULLS_LAST_ON_ASC_FIRST_ON_DESC';

将默认结果集排序方向设置为 ASCENDING 或 DESCENDING

SET default_order = 'ASCENDING';
SET default_order = 'DESCENDING';

按非整数字面量排序

默认情况下，不允许按非整数字面量排序

SELECT 42 ORDER BY 'hello world';

-- Binder Error: ORDER BY non-integer literal has no effect.

要允许此行为，请使用 order_by_non_integer_literal 选项

SET order_by_non_integer_literal = true;

隐式转换为 VARCHAR

在 0.10.0 版本之前，DuckDB 会在函数绑定期间自动允许任何类型隐式转换为 VARCHAR。因此，例如，无需使用显式类型转换即可计算整数的子字符串。对于 v0.10.0 及更高版本，需要显式类型转换。要恢复执行隐式类型转换的旧行为，请将 old_implicit_casting 变量设置为 true。

SET old_implicit_casting = true;

Python：扫描所有数据帧

在 1.1.0 版本之前，DuckDB 在 Python 中的替换扫描机制会扫描全局 Python 命名空间。要恢复此旧行为，请使用以下设置：

SET python_scan_all_frames = true;

关于 DuckDB 的信息

版本

显示 DuckDB 版本

PRAGMA version;
CALL pragma_version();

平台

platform 返回当前 DuckDB 可执行文件编译所针对的平台标识符，例如 osx_arm64。此标识符的格式与扩展加载说明中描述的平台名称匹配。

PRAGMA platform;
CALL pragma_platform();

用户代理

以下语句返回用户代理信息，例如 duckdb/v0.10.0(osx_arm64)

PRAGMA user_agent;

元数据信息

以下语句返回元数据存储的信息（block_id、total_blocks、free_blocks 和 free_list）

PRAGMA metadata_info;

进度条

运行查询时显示进度条

PRAGMA enable_progress_bar;

或

PRAGMA enable_print_progress_bar;

运行查询时不显示进度条

PRAGMA disable_progress_bar;

或

PRAGMA disable_print_progress_bar;

EXPLAIN 输出

EXPLAIN 的输出可以配置为仅显示物理计划。

EXPLAIN 的默认配置

SET explain_output = 'physical_only';

仅显示优化后的查询计划

SET explain_output = 'optimized_only';

显示所有查询计划

SET explain_output = 'all';

性能分析

启用性能分析

以下查询以默认格式 query_tree 启用性能分析。无论格式如何，enable_profiling 对于启用性能分析都是强制性的。

PRAGMA enable_profiling;
PRAGMA enable_profile;

性能分析格式

enable_profiling 的格式可以指定为 query_tree、json、query_tree_optimizer 或 no_output。除 no_output 外，每种格式都会将其输出打印到配置的输出中。

默认格式为 query_tree。它会打印物理查询计划和树中每个操作符的指标。

SET enable_profiling = 'query_tree';

另外，json 以 JSON 格式返回物理查询计划。

SET enable_profiling = 'json';

提示：要可视化查询计划，可以考虑使用由蒂宾根大学数据库系统研究组开发的DuckDB 执行计划可视化工具。

返回物理查询计划，包括优化器和规划器指标

SET enable_profiling = 'query_tree_optimizer';

数据库驱动程序和其他应用程序也可以通过 API 调用访问性能分析信息，在这种情况下，用户可以禁用任何其他输出。尽管参数显示为 no_output，但必须注意的是，这仅影响打印到可配置的输出。当通过 API 调用访问性能分析信息时，启用性能分析仍然至关重要。

SET enable_profiling = 'no_output';

性能分析输出

默认情况下，DuckDB 会将性能分析信息打印到标准输出。但是，如果您希望将性能分析信息写入文件，可以使用 PRAGMA profiling_output 来指定文件路径。

警告：对于每个新发出的查询，文件内容都将被覆盖。因此，文件将只包含最后一次运行查询的性能分析信息。

SET profiling_output = '/path/to/file.json';
SET profile_output = '/path/to/file.json';

性能分析模式

默认情况下，提供有限的性能分析信息（standard）。

SET profiling_mode = 'standard';

如需更多详细信息，请将 profiling_mode 设置为 detailed 以使用详细性能分析模式。此模式的输出包括对规划器和优化器阶段的性能分析。

SET profiling_mode = 'detailed';

自定义指标

默认情况下，性能分析会启用所有指标，除了那些由详细性能分析激活的指标。

使用 custom_profiling_settings PRAGMA，每个指标，包括来自详细性能分析的指标，都可以单独启用或禁用。此 PRAGMA 接受一个 JSON 对象，其中包含指标名称作为键，以及用于切换其开/关的布尔值。此 PRAGMA 指定的设置会覆盖默认行为。

注意：这仅在 enable_profiling 设置为 json 或 no_output 时影响指标。query_tree 和 query_tree_optimizer 始终使用默认指标集。

在以下示例中，CPU_TIME 指标被禁用。EXTRA_INFO、OPERATOR_CARDINALITY 和 OPERATOR_TIMING 指标被启用。

SET custom_profiling_settings = '{"CPU_TIME": "false", "EXTRA_INFO": "true", "OPERATOR_CARDINALITY": "true", "OPERATOR_TIMING": "true"}';

性能分析文档中包含可用指标的概述。

禁用性能分析

禁用性能分析

PRAGMA disable_profiling;
PRAGMA disable_profile;

查询优化

优化器

禁用查询优化器

PRAGMA disable_optimizer;

启用查询优化器

PRAGMA enable_optimizer;

选择性禁用优化器

disabled_optimizers 选项允许选择性地禁用优化步骤。例如，要禁用 filter_pushdown 和 statistics_propagation，请运行：

SET disabled_optimizers = 'filter_pushdown,statistics_propagation';

可以使用 duckdb_optimizers() 表函数查询可用的优化项。

要重新启用优化器，请运行：

SET disabled_optimizers = '';

警告：disabled_optimizers 选项仅应用于调试性能问题，在生产环境中应避免使用。

日志记录

设置查询日志的路径

SET log_query_path = '/tmp/duckdb_log/';

禁用查询日志记录

SET log_query_path = '';

全文搜索索引

create_fts_index 和 drop_fts_index 选项仅在加载 fts 扩展时可用。它们的用法在全文搜索扩展页面中有说明。

验证

外部操作符验证

启用外部操作符验证

PRAGMA verify_external;

禁用外部操作符验证

PRAGMA disable_verify_external;

往返能力验证

启用支持的逻辑计划的往返能力验证

PRAGMA verify_serializer;

禁用往返能力验证

PRAGMA disable_verify_serializer;

对象缓存

启用对象缓存，例如 Parquet 元数据

PRAGMA enable_object_cache;

禁用对象缓存

PRAGMA disable_object_cache;

检查点

压缩

在检查点过程中，现有列数据和任何新更改都会被压缩。有几个 PRAGMA 可以影响哪些压缩函数被考虑。

强制压缩

如果可能，优先使用此压缩方法而不是其他任何方法

PRAGMA force_compression = 'bitpacking';

禁用的压缩方法

避免使用逗号分隔列表中列出的任何压缩方法

PRAGMA disabled_compression_methods = 'fsst,rle';

强制检查点

当在没有进行任何更改时调用 CHECKPOINT 时，无论如何都强制执行检查点。

PRAGMA force_checkpoint;

关闭时检查点

在成功关闭时运行 CHECKPOINT 并删除 WAL，以仅留下一个数据库文件。

PRAGMA enable_checkpoint_on_shutdown;

关闭时不运行 CHECKPOINT

PRAGMA disable_checkpoint_on_shutdown;

用于将数据溢出到磁盘的临时目录

默认情况下，DuckDB 使用一个名为 database_file_name.tmp 的临时目录将数据溢出到磁盘，该目录位于与数据库文件相同的目录中。要更改此设置，请使用：

SET temp_directory = '/path/to/temp_dir.tmp/';

以 JSON 格式返回错误

可以设置 errors_as_json 选项以原始 JSON 格式获取错误信息。对于某些错误，会提供额外信息或分解信息，以便于机器处理。例如：

SET errors_as_json = true;

然后，运行导致错误的查询会产生 JSON 输出。

SELECT * FROM nonexistent_tbl;

{
   "exception_type":"Catalog",
   "exception_message":"Table with name nonexistent_tbl does not exist!\nDid you mean \"temp.information_schema.tables\"?",
   "name":"nonexistent_tbl",
   "candidates":"temp.information_schema.tables",
   "position":"14",
   "type":"Table",
   "error_subtype":"MISSING_ENTRY"
}

IEEE 浮点运算语义

DuckDB 遵循 IEEE 浮点运算语义。如果您想关闭此功能，请运行：

SET ieee_floating_point_ops = false;

在这种情况下，浮点数除以零（例如 1.0 / 0.0、0.0 / 0.0 和 -1.0 / 0.0）都将返回 NULL。

查询验证（用于开发）

以下 PRAGMA 主要用于开发和内部测试。

启用查询验证

PRAGMA enable_verification;

禁用查询验证

PRAGMA disable_verification;

启用强制并行查询处理

PRAGMA verify_parallelism;

禁用强制并行查询处理

PRAGMA disable_verify_parallelism;

块大小

将数据库持久化到磁盘时，DuckDB 会写入一个专用文件，其中包含存储数据的块列表。如果文件只包含很少的数据（例如，一个小表），则 256 kB 的默认块大小可能不理想。因此，DuckDB 的存储格式支持不同的块大小。

块大小值存在一些限制。

• 必须是 2 的幂。
• 必须大于或等于 16384 (16 kB)。
• 必须小于或等于 262144 (256 kB)。

您可以像这样设置实例创建的所有新 DuckDB 文件的默认块大小：

SET default_block_size = '16384';

还可以按文件设置块大小，详情请参阅 ATTACH。