PRAGMA

PRAGMA 语句是 Goose 从 SQLite 借鉴的一个 SQL 扩展。PRAGMA 语句的发出方式与普通 SQL 语句类似。PRAGMA 命令可能会改变数据库引擎的内部状态，并影响后续的执行结果或引擎行为。

对于“给某个选项赋值”的 PRAGMA 语句，你也可以使用 SET 语句 来完成；而选项的值可以通过 SELECT current_setting(option_name) 获取。

关于 Goose 内置的配置选项，请参阅配置参考。 Goose 的扩展也可能会注册额外的配置选项，这些内容会记录在各扩展的文档页面中。

本页包含当前支持的 PRAGMA 设置项。

元数据

模式信息

列出所有数据库：

PRAGMA database_list;

列出所有表：

PRAGMA show_tables;

列出所有表并包含额外信息（类似于 DESCRIBE）：

PRAGMA show_tables_expanded;

列出所有函数：

PRAGMA functions;

当查询目标指向不存在的 schema 时，Goose 会生成类似 “did you mean...” 的提示性错误信息。 当附加（attach）的数据库数量达到上千时，这些错误信息可能需要很长时间才能生成。 若要限制 Goose 在生成提示时要扫描的 schema 数量，请使用 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');

该调用会返回给定表的如下信息：

Name	Type	Description
row_group_id	BIGINT
column_name	VARCHAR
column_id	BIGINT
column_path	VARCHAR
segment_id	BIGINT
segment_type	VARCHAR
start	BIGINT	此 chunk 的起始行 id
count	BIGINT	此存储 chunk 中的条目数量
compression	VARCHAR	该列使用的压缩类型——参见 “Goose 中的轻量级压缩”博客文章
stats	VARCHAR
has_updates	BOOLEAN
persistent	BOOLEAN	若为临时表则为 false
block_id	BIGINT	除非为持久化表，否则为空
block_offset	BIGINT	除非为持久化表，否则为空

更多信息请参阅存储。

显示数据库

以下语句等价于 SHOW DATABASES 语句：

PRAGMA show_databases;

资源管理

内存上限

为缓冲区管理器（buffer manager）设置内存上限：

SET memory_limit = '1GB';

警告：指定的内存上限只会应用到缓冲区管理器。 对于大多数查询，缓冲区管理器会处理绝大部分被处理的数据。 但某些内存数据结构（例如 向量）以及查询结果，会在缓冲区管理器之外分配内存。 此外，带复杂状态的聚合函数（例如 list、mode、quantile、string_agg 与 approx）也会使用缓冲区管理器之外的内存。 因此，实际内存消耗可能会高于所设置的内存上限。

线程数

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

SET threads = 4;

排序规则（Collation）

列出所有可用的排序规则：

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 版本之前，Goose 在函数绑定（function binding）阶段会自动允许任意类型隐式转换为 VARCHAR。因此，你可以在不显式 cast 的情况下对整数做 substring 等操作。从 v0.10.0 起，需要改为显式 cast。若要恢复旧的隐式转换行为，请将 old_implicit_casting 变量设为 true：

SET old_implicit_casting = true;

Python：扫描所有 DataFrame

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

SET python_scan_all_frames = true;

Goose 信息

版本

显示 Goose 版本：

PRAGMA version;
CALL pragma_version();

平台

platform 会返回当前 Goose 可执行文件编译目标平台的标识符，例如 osx_arm64。 该标识符的格式与扩展加载说明中描述的平台名称一致：

PRAGMA platform;
CALL pragma_platform();

User Agent

以下语句会返回 user agent 信息，例如 goose/v0.10.0(osx_arm64)：

PRAGMA user_agent;

元数据存储信息

以下语句会返回元数据存储（metadata store）的信息（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 的输出可以配置为仅显示物理计划（physical plan）。

EXPLAIN 的默认配置：

SET explain_output = 'physical_only';

仅显示优化后的查询计划：

SET explain_output = 'optimized_only';

显示所有查询计划：

SET explain_output = 'all';

Profiling（性能分析）

启用 Profiling

下面的查询会以默认格式 query_tree 启用 profiling。 无论选择哪种格式，enable_profiling 都是启用 profiling 的必需项。

PRAGMA enable_profiling;
PRAGMA enable_profile;

Profiling 覆盖范围

默认情况下，profiling 覆盖范围设为 SELECT。 SELECT 会对 SELECT 语句物理计划中的每个算子（operator）运行 profiler。

SET profiling_coverage = 'SELECT';

默认情况下，profiler 不会为其他语句类型（INSERT INTO、ATTACH 等）输出 profiling 信息。 若要对所有语句类型运行 profiler，请将此设置改为 ALL。

SET profiling_coverage = 'ALL';

Profiling 格式

enable_profiling 的格式可以设置为 query_tree、json、query_tree_optimizer 或 no_output。 除 no_output 外，其余格式都会把输出打印到配置的输出位置。

默认格式为 query_tree。 它会打印物理查询计划以及计划树中每个算子的指标（metrics）。

SET enable_profiling = 'query_tree';

另外，json 会以 JSON 形式返回物理查询计划：

SET enable_profiling = 'json';

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

若要返回包含 optimizer 与 planner 指标的物理查询计划：

SET enable_profiling = 'query_tree_optimizer';

数据库驱动与其他应用也可以通过 API 调用来访问 profiling 信息，此时用户可以关闭其他输出。 尽管该参数名为 no_output，但需要注意它只影响打印到可配置输出的位置。 当通过 API 调用访问 profiling 信息时，仍然必须启用 profiling：

SET enable_profiling = 'no_output';

Profiling 输出

默认情况下，Goose 会将 profiling 信息输出到标准输出。 如果你希望将 profiling 信息写入文件，可以使用 PRAGMA profiling_output 指定文件路径。

警告：该文件内容会在每次发出新查询时被覆盖。 因此，该文件只会包含最近一次运行查询的 profiling 信息：

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

Profiling 模式

默认只提供有限的 profiling 信息（standard）。

SET profiling_mode = 'standard';

若要获得更多细节，可将 profiling_mode 设为 detailed 来启用详细模式。 该模式的输出包含 planner 与 optimizer 阶段的 profiling 信息。

SET profiling_mode = 'detailed';

自定义指标

默认情况下，profiling 会启用除“详细 profiling 专用指标”之外的所有指标。

通过 custom_profiling_settings 这个 PRAGMA，你可以对每个指标（包括详细 profiling 的指标）逐项启用或禁用。 该 PRAGMA 接受一个 JSON 对象：以指标名为 key，以布尔值为 value 来开关该指标。 通过该 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"}';

Profiling 文档包含可用指标的概览。

禁用 Profiling

要禁用 profiling：

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

可用的优化项可以通过 goose_optimizers() 表函数 查询。

要重新启用优化器，执行：

SET disabled_optimizers = '';

警告：disabled_optimizers 只应在调试性能问题时使用，生产环境应尽量避免。

日志

设置查询日志的输出路径：

SET log_query_path = '/tmp/goose_log/';

禁用查询日志：

SET log_query_path = '';

全文搜索索引

create_fts_index 与 drop_fts_index 选项仅在加载了 fts 扩展 时可用。它们的用法记录在全文搜索扩展页面中。

校验

外部算子校验

启用外部算子校验：

PRAGMA verify_external;

禁用外部算子校验：

PRAGMA disable_verify_external;

Round-trip 能力校验

对支持的逻辑计划启用 round-trip 能力校验：

PRAGMA verify_serializer;

禁用 round-trip 能力校验：

PRAGMA disable_verify_serializer;

对象缓存

启用对象缓存（例如用于缓存 Parquet 元数据）：

PRAGMA enable_object_cache;

禁用对象缓存：

PRAGMA disable_object_cache;

Checkpoint（检查点）

压缩

在 checkpoint 过程中，已有的列数据以及所有新增变更都会被压缩。 有若干 PRAGMA 可用于影响将被考虑的压缩函数。

强制压缩

如果可能，优先使用该压缩方法而不是其他方法：

PRAGMA force_compression = 'bitpacking';

禁用压缩方法

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

PRAGMA disabled_compression_methods = 'fsst,rle';

强制 Checkpoint

当在没有任何变更的情况下调用 CHECKPOINT 时，仍然强制执行一次 checkpoint：

PRAGMA force_checkpoint;

退出时执行 Checkpoint

在成功退出时运行一次 CHECKPOINT 并删除 WAL，以便最终只留下一个数据库文件：

PRAGMA enable_checkpoint_on_shutdown;

退出时不运行 CHECKPOINT：

PRAGMA disable_checkpoint_on_shutdown;

溢写到磁盘的临时目录

默认情况下，Goose 会使用名为 ⟨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 浮点运算语义

Goose 遵循 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;

块大小

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

块大小的可选值需要满足一些约束：

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

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

SET default_block_size = '16384';

也可以按文件粒度设置块大小，详见 ATTACH。