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

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

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

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

元数据

模式信息

列出所有数据库：

PRAGMA database_list;

列出所有表格：

PRAGMA show_tables;

列出所有表，并附带额外信息，类似于 DESCRIBE：

PRAGMA show_tables_expanded;

列出所有函数：

PRAGMA functions;

表格信息

获取特定表的信息：

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

数据库大小

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

SET 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;

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: 扫描所有数据框

在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();

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';

性能分析

启用性能分析

以下查询启用了默认格式的剖析，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';

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

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;

查询优化

Optimizer

要禁用查询优化器：

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 选项应仅用于调试性能问题，在生产环境中应避免使用。

Logging

设置查询日志的路径：

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;

Object Cache

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

PRAGMA enable_object_cache;

禁用对象的缓存：

PRAGMA disable_object_cache;

检查点

强制检查点

当没有进行任何更改时调用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会写入一个专用文件，该文件包含保存数据的块列表。对于只包含非常少量数据的文件，例如一个小表，默认的256KB块大小可能并不理想。因此，DuckDB的存储格式支持不同的块大小。

可能的块大小值有一些限制。

• 必须是2的幂。
• 必须大于或等于16384（16 KB）。
• 必须小于或等于262144（256 KB）。

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

SET default_block_size = '16384';

也可以基于每个文件设置块大小，详情请参见ATTACH。