PostgreSQL 19 扩展统计信息导入/导出功能

引言

PostgreSQL 的扩展统计信息功能自版本 10 引入以来，使优化器能够理解简单单列统计信息无法捕获的列间相关性。这包括 n-distinct 系数（存在多少个不同的组合）、函数依赖（当一个列决定另一个列时）以及多列组合的最常见值（MCV）列表。

虽然 PostgreSQL 17 引入了用于导入和导出关系和属性统计信息的函数（pg_restore_relation_stats、pg_restore_attribute_stats），但扩展统计信息被排除在这一初始实现之外。最近在 pgsql-hackers 邮件列表上，由 Corey Huinker 发起的一个讨论线程解决了这一空白，提供了一个全面的补丁系列，添加了 pg_restore_extended_stats()、pg_clear_extended_stats() 及相关基础设施。

这项工作意义重大，原因如下：

实现跨 pg_dump/pg_restore 和 pg_upgrade 的完整统计信息保留
允许使用假设统计信息进行查询计划器实验
支持仅包含 schema 和统计信息的转储，用于在没有实际数据的情况下测试查询计划

技术分析

原始格式的问题

pg_ndistinct 和 pg_dependencies 类型的原始输出格式使用了一种 JSON 结构，其中键本身包含结构化数据：

{"1, 2": 2323, "1, 3": 3232, "2, 3": 1500}

虽然这在技术上是有效的 JSON，但这种格式存在几个问题：

包含逗号分隔属性号的键需要额外解析
难以以编程方式操作
不存在可用的输入函数——这些类型实际上只能输出

新的 JSON 格式

补丁系列引入了一种更清晰、更结构化的 JSON 格式。对于 pg_ndistinct：

[
  {"attributes": [2, 3], "ndistinct": 4},
  {"attributes": [2, -1], "ndistinct": 4},
  {"attributes": [2, 3, -1], "ndistinct": 4}
]

对于 pg_dependencies：

[
  {"attributes": [2], "dependency": 3, "degree": 1.000000},
  {"attributes": [2, 3], "dependency": -1, "degree": 0.850000}
]

主要改进：

规范的 JSON 数组，每个元素都有命名的键
清晰分离属性、值和元数据
机器可读，无需自定义解析逻辑
负数属性号表示统计对象中的表达式（例如，-1 是第一个表达式）

输入函数实现

新的输入函数使用 PostgreSQL 的 JSON 解析器基础设施，配合自定义语义动作处理器。以下是 pg_ndistinct 解析状态机的简化视图：

typedef enum
{
    NDIST_EXPECT_START = 0,
    NDIST_EXPECT_ITEM,
    NDIST_EXPECT_KEY,
    NDIST_EXPECT_ATTNUM_LIST,
    NDIST_EXPECT_ATTNUM,
    NDIST_EXPECT_NDISTINCT,
    NDIST_EXPECT_COMPLETE
} ndistinctSemanticState;

解析器验证：

正确的 JSON 结构（对象数组）
必需的键（ndistinct 统计信息需要 attributes 和 ndistinct）
属性号在有效范围内（正数表示列，负数表示表达式，但不超过 STATS_MAX_DIMENSIONS）
单个项目内没有重复属性

扩展统计信息函数

补丁引入了三个主要 SQL 函数：

pg_restore_extended_stats() — 从先前导出的值导入扩展统计信息：

SELECT pg_restore_extended_stats(
    'public',                    -- 关系 schema
    'my_table',                  -- 关系名称
    'public',                    -- 统计信息 schema
    'my_stats',                  -- 统计信息名称
    false,                       -- inherited（是否继承）
    '{"version": ..., "ndistinct": [...], "dependencies": [...], "mcv": [...], "exprs": [...]}'::text
);

pg_clear_extended_stats() — 从 pg_statistic_ext_data 中删除扩展统计信息数据：

SELECT pg_clear_extended_stats(
    'public',        -- 统计信息 schema
    'my_stats',      -- 统计信息名称
    false            -- inherited（是否继承）
);

这些函数遵循为关系/属性统计信息建立的相同模式：

返回布尔值表示成功与否
遇到问题时发出 WARNING（而非 ERROR），以避免破坏 pg_restore 脚本
需要目标关系的 MAINTAIN 权限

验证与安全

实现包括仔细的验证：

属性边界检查：正数 attnum 必须存在于 stxkeys 中，负数 attnum 不得超过表达式数量
组合完整性：对于 pg_ndistinct，基于最长属性列表，必须存在所有 N 选 K 组合
软错误处理：使用 PostgreSQL 的 ErrorSaveContext 进行安全的错误报告而不会崩溃

属性号验证示例：

if (attnum == 0 || attnum < (0 - STATS_MAX_DIMENSIONS))
{
    errsave(parse->escontext,
            errcode(ERRCODE_INVALID_TEXT_REPRESENTATION),
            errmsg("malformed pg_ndistinct: \"%s\"", parse->str),
            errdetail("Invalid \"%s\" element: %d.",
                      PG_NDISTINCT_KEY_ATTRIBUTES, attnum));
    return JSON_SEM_ACTION_FAILED;
}