PRAGMA 语句是 DuckDB 从 SQLite 采纳的一种 SQL 扩展。PRAGMA 语句的发布方式与常规 SQL 语句类似。PRAGMA 命令可以更改数据库引擎的内部状态，并可能影响引擎后续的执行或行为。

为选项赋值的 PRAGMA 语句也可以使用 SET 语句来发布，并且可以使用 SELECT current_setting(option_name) 来获取选项的值。

有关 DuckDB 内置配置选项的信息，请参阅配置参考。DuckDB 扩展可能会注册额外的配置选项。这些选项记录在相应扩展的文档页面中。

本页面包含支持的 PRAGMA 设置。

元数据

模式信息 (Schema Information)

列出所有数据库

PRAGMA database_list;

列出所有表

PRAGMA show_tables;

列出所有表并提供额外信息，类似于 DESCRIBE

PRAGMA show_tables_expanded;

列出所有函数

PRAGMA functions;

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

SET catalog_error_max_schemas = 10;

表信息 (Table Information)

获取特定表的信息

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

数据库大小 (Database Size)

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

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

存储信息 (Storage Information)

获取存储信息

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

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

更多信息请参阅存储 (Storage)。

显示数据库 (Show Databases)

以下语句等同于 SHOW DATABASES 语句

PRAGMA show_databases;

资源管理

内存限制

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

SET memory_limit = '1GB';

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

线程

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

SET threads = 4;

排序规则

列出所有可用的排序规则 (Collations)

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：扫描所有 Dataframe

在 1.1.0 版本之前，DuckDB 在 Python 中的 替换扫描机制 (replacement scan mechanism) 会扫描全局 Python 命名空间。要恢复到这种旧行为，请使用以下设置

SET python_scan_all_frames = true;

关于 DuckDB 的信息

版本

显示 DuckDB 版本

PRAGMA version;
CALL pragma_version();

平台

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

PRAGMA platform;
CALL pragma_platform();

用户代理 (User Agent)

以下语句返回用户代理信息，例如 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';

性能分析

启用性能分析 (Profiling)

以下查询使用默认格式 query_tree 启用性能分析。无论格式如何，enable_profiling 都是启用性能分析的必要条件。

PRAGMA enable_profiling;
PRAGMA enable_profile;

性能分析覆盖范围

默认情况下，性能分析覆盖范围设置为 SELECT。SELECT 会针对 SELECT 语句物理计划中的每个运算符运行性能分析器。

SET profiling_coverage = 'SELECT';

默认情况下，性能分析器不会为其他语句类型（INSERT INTO、ATTACH 等）输出性能分析信息。要为所有语句类型运行性能分析器，请将此设置更改为 ALL。

SET profiling_coverage = 'ALL';

性能分析格式

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;

检查点 (Checkpointing)

压缩

在检查点期间，现有的列数据加上任何新的更改都会被压缩。存在几个可以影响使用哪些压缩函数的 pragmas。

强制压缩

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

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;

块大小 (Block Sizes)

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

对于可能的块大小值有一些约束。

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

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

SET default_block_size = '16384';

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