vgram

概览

Collect corpus-specific q-gram statistics before creating the GIN index; upstream supports PostgreSQL 13+.

版本

构建

您可以使用 pig build 命令构建 vgram 扩展的 RPM / DEB 包：

pig build pkg vgram         # 构建 RPM / DEB 包

安装

您可以直接安装 vgram 扩展包的预置二进制包，首先确保 PGDG 和 PIGSTY 仓库已经添加并启用：

pig repo add pgsql -u          # 添加仓库并更新缓存

使用 pig 或者是 apt/yum/dnf 安装扩展：

pig install vgram;          # 当前活跃 PG 版本安装

pig ext install -y vgram -v 18  # PG 18
pig ext install -y vgram -v 17  # PG 17
pig ext install -y vgram -v 16  # PG 16
pig ext install -y vgram -v 15  # PG 15
pig ext install -y vgram -v 14  # PG 14

dnf install -y vgram_18       # PG 18
dnf install -y vgram_17       # PG 17
dnf install -y vgram_16       # PG 16
dnf install -y vgram_15       # PG 15
dnf install -y vgram_14       # PG 14

apt install -y postgresql-18-vgram   # PG 18
apt install -y postgresql-17-vgram   # PG 17
apt install -y postgresql-16-vgram   # PG 16
apt install -y postgresql-15-vgram   # PG 15
apt install -y postgresql-14-vgram   # PG 14

创建扩展：

CREATE EXTENSION vgram;

用法

来源：

• 官方 README
• 官方扩展 SQL
• 官方 GIN 实现

vgram 使用由可变长度 q-gram 构建的 GIN 索引加速 LIKE 和 ILIKE 子串检索。与固定三元组不同，它从目标语料学习常见短 gram，并索引更长或更少见的 gram，因此可能针对特定数据分布获得更好的选择性。

构建语料专用索引

版本 1.0 要求 PostgreSQL 13 或更高版本。在 psql 中收集常见 gram、保存结果，并把它传给 vgram_gin_ops 选项：

CREATE EXTENSION vgram;

SELECT qgram_stat(title, 2, 4, 0.05) AS vgrams
FROM documents
\gset

CREATE INDEX documents_title_vgram_idx
ON documents USING gin (
  title vgram_gin_ops (minq=2, maxq=4, vgrams=:'vgrams')
);

SELECT *
FROM documents
WHERE title ILIKE '%indexing%';

minq 和 maxq 限制提取 gram 的长度。传给 qgram_stat() 的阈值把语料频率达到或超过该值的 gram 标记为过于常见，不纳入索引。可用 get_vgrams() 检查某个候选值和已学习 gram 数组的提取结果。

对象与高级统计

• qgram_stat(text, int, int, float8) 聚合常见 q-gram。
• get_vgrams(text, int, int, text[]) 展示从文本中选出的 gram。
• vgram_gin_ops 为普通 text 的 LIKE 与 ILIKE 建立索引。
• vgram_text 与文本兼容，但会安装自定义频率统计与选择性估算。
• vgram_gin_ops2 是 vgram_text 的 GIN 运算符类。

维护边界

学习得到的选项数组会嵌入索引定义，而且可能非常大。它只反映构建时样本；语言或分布发生重大变化后，需要重新收集统计、比较召回与计划，并通常执行 REINDEX 或创建替代索引。GIN 候选仍会复查，但过于常见或太短的模式仍可能退化成大范围扫描。应评估构建耗时、索引大小、写放大、待处理列表行为、VACUUM、排序规则、多字节文本、大小写折叠和规划器估算。还要保留可复现的训练查询与参数，确保副本和重建环境使用相同的运算符类选项。