PostgreSQL 中的 pg_trgm GIN 索引详解

文章目录

[PostgreSQL 中的 pg_trgm GIN 索引详解](#PostgreSQL 中的 pg_trgm GIN 索引详解)
- [1. pg_trgm 基础概念](#1. pg_trgm 基础概念)
- - [1.1 什么是 trigram（三元组）？](#1.1 什么是 trigram（三元组）？)
  - [1.2 相似度度量](#1.2 相似度度量)
- [2. GIN 索引简介](#2. GIN 索引简介)
- [3. 启用 pg_trgm 并创建 GIN 索引](#3. 启用 pg_trgm 并创建 GIN 索引)
- - [3.1 安装扩展](#3.1 安装扩展)
  - [3.2 创建 GIN 索引](#3.2 创建 GIN 索引)
- [4. 支持的查询操作](#4. 支持的查询操作)
- - [4.1 模糊匹配 `LIKE` / `ILIKE`](#4.1 模糊匹配 LIKE / ILIKE)
  - [4.2 正则表达式匹配 `~` / `~*`](#4.2 正则表达式匹配 ~ / ~*)
  - [4.3 相似度搜索](#4.3 相似度搜索)
- [5. 索引工作原理与执行计划](#5. 索引工作原理与执行计划)
- - [5.1 内部结构](#5.1 内部结构)
  - [5.2 执行计划示例](#5.2 执行计划示例)
- [6. 性能特性与调优](#6. 性能特性与调优)
- - [6.1 优点](#6.1 优点)
  - [6.2 缺点与注意事项](#6.2 缺点与注意事项)
  - [6.3 调优建议](#6.3 调优建议)
- [7. 与其他索引/方法的对比](#7. 与其他索引/方法的对比)
- [8. 完整示例](#8. 完整示例)
- [9. 局限性总结](#9. 局限性总结)
- [10. 实际应用场景](#10. 实际应用场景)
- 参考文档

pg_trgm 是 PostgreSQL 的一个官方扩展模块，它基于 trigram（三元组） 模型提供字符串相似度计算和模式匹配加速功能。当与 GIN（Generalized Inverted Index） 索引结合使用时，可以极大提升 LIKE、 ILIKE、正则表达式以及相似性搜索的查询性能。

1. pg_trgm 基础概念

1.1 什么是 trigram（三元组）？

一个 trigram 是从一个字符串中抽取的连续三个字符组成的序列。

字符串会被自动处理为小写（若使用大小写敏感操作符则不会） ，并且前后各添加两个空格，以便匹配前缀和后缀。
例如：字符串 "cat" 产生的 trigram 为：" c"、" ca"、"cat"、"at "、"t "。

1.2 相似度度量

similarity(text, text) 返回两个字符串的 trigram 交集大小除以并集大小（0~1 之间）。
操作符 % 判断相似度是否超过当前阈值（由 pg_trgm.similarity_threshold 控制）。
操作符 <-> 返回"距离" = 1 - similarity，常用于 ORDER BY 排序。

2. GIN 索引简介

GIN（Generalized Inverted Index）是 PostgreSQL 中的一种索引类型，特别适合包含多个键值的数据结构（如数组、全文检索、JSONB 等）。

对于 pg_trgm 而言，GIN 索引会将字符串分解为所有 trigram，并为每个 trigram 存储指向原始行的指针。当查询需要匹配某个 trigram 组合时，GIN 可以快速找到包含这些 trigram 的行，避免全表扫描。

3. 启用 pg_trgm 并创建 GIN 索引

3.1 安装扩展

sql 复制代码

CREATE EXTENSION IF NOT EXISTS pg_trgm;

3.2 创建 GIN 索引

基本语法：

sql 复制代码

CREATE INDEX idx_name ON table_name USING GIN (column_name gin_trgm_ops);

gin_trgm_ops 是专门针对 trigram 的 GIN 操作符类，支持 LIKE、ILIKE、正则、相似度等操作。

也可以创建多列索引或表达式索引，例如：

sql 复制代码

-- 对两列合并的 trigram 索引
CREATE INDEX idx_multi ON my_table USING GIN ((col1 || ' ' || col2) gin_trgm_ops);

-- 仅对字符串前缀建索引（不常用，通常直接用 gin_trgm_ops）

4. 支持的查询操作

一旦创建了 GIN 索引，以下查询类型会自动利用该索引（前提是查询条件满足 trigram 可优化性）。

4.1 模糊匹配 `LIKE` / `ILIKE`

LIKE 'abc%'（前缀匹配）可被 B-tree 索引优化，但 %abc%（中缀/后缀）通常只能走 trigram GIN 索引。
ILIKE 忽略大小写，同样受益。

示例：

sql 复制代码

SELECT * FROM users WHERE name LIKE '%john%';

注意：模式中至少需要 3 个非通配符字符 才能有效使用 trigram 索引。例如 '%jo%' 只有 2 个字符，不会使用索引。

4.2 正则表达式匹配 `~` / `~*`

只有正则表达式中包含至少一个长度 ≥ 3 的常量字符串时，索引才可能被使用。

sql 复制代码

SELECT * FROM docs WHERE content ~ 'PostgreSQL';

执行计划中会显示 Bitmap Index Scan 或 Index Scan 使用 gin_trgm_ops 索引。

4.3 相似度搜索

操作符 %：找到相似度超过阈值的记录

sql 复制代码

SET pg_trgm.similarity_threshold = 0.4;   -- 默认 0.3
SELECT * FROM words WHERE word % 'Postgres';

距离操作符 <->：按相似度排序

sql 复制代码

SELECT * FROM words ORDER BY word <-> 'Postgres' LIMIT 10;

5. 索引工作原理与执行计划

5.1 内部结构

GIN 索引存储的是 (trigram → 行指针列表) 的倒排映射。

对于查询 LIKE '%pattern%'：

从模式中提取所有 trigram（如 pattern → " pa", "pat", "att", "tte", "ter", "ern", "rn "）。
在索引中查找包含这些 trigram 的行，并取交集。
对候选行进行精确过滤（因为 trigram 匹配只是必要条件，不是充分条件）。

5.2 执行计划示例

sql 复制代码

EXPLAIN SELECT * FROM t WHERE c LIKE '%foo%';

输出可能包含：

复制代码

Bitmap Heap Scan on t
  Recheck Cond: (c ~~ '%foo%'::text)
  ->  Bitmap Index Scan on t_c_gin_idx
        Index Cond: (c ~~ '%foo%'::text)

Recheck Cond 说明索引返回了候选行，需要再次验证实际字符串是否真的匹配（因为 trigram 索引可能产生假阳性）。

6. 性能特性与调优

6.1 优点

对中缀模糊搜索（%abc%）加速明显，能从全表扫描 O(N) 降到对数级或更低。
支持多种字符串操作，一索引多用。
对相似度排序（ORDER BY col <-> 'query'）支持良好。

6.2 缺点与注意事项

索引大小 ：对于长文本，trigram 数量约为 长度 × 3，索引可能比堆表大几倍。例如 1GB 的表，索引可能达到 2~3GB。
写入开销 ：每次 INSERT 或 UPDATE 都需要更新所有 trigram 条目，对写性能有影响。
短模式限制 ：模式中少于 3 个非通配符字符时无法使用索引（例如 LIKE '%a%' 会退化为全表扫描）。
大小写敏感 ：LIKE 默认大小写敏感，若数据混合大小写但模式为小写，索引仍有效（因为 trigram 存储原始字符，但查询时会匹配准确字符）。需要不区分大小写可用 ILIKE 或创建 lower(col) 表达式索引。
非字母字符：空格、标点也会参与 trigram 生成，可能影响索引效率，但对匹配通常有帮助。

6.3 调优建议

调整相似度阈值：pg_trgm.similarity_threshold 影响 % 操作符，默认 0.3。调高可减少结果集，但索引扫描时仍会检索所有候选，最终过滤。
限制候选集：如果数据量大，可先用其他条件（如外键、时间范围）缩小扫描范围，再应用 trigram 过滤。
考虑使用 GIN 快速更新 ：gin_pending_list_limit 参数控制 GIN 索引的延迟更新缓冲区，适度调大可提高批量写入性能。
对超长文本（如整篇文章），可考虑先截取部分（如前 2000 字符）建索引，或结合全文检索。

7. 与其他索引/方法的对比

场景	建议方案	说明
前缀模糊 `LIKE 'abc%'`	B-tree 索引（`col text_pattern_ops`）	比 GIN 更小更快，但只支持前缀。
中缀/后缀 `LIKE '%abc%'`	pg_trgm GIN	几乎唯一高效的方案。
全文搜索（含词干、排名、停用词）	GIN 全文检索（tsvector）	专为自然语言优化，支持字典、权重。
编辑距离（Levenshtein）	`levenshtein()` 函数 + 普通索引	无法用索引，只能全表计算。trigram 是其近似替代。
正则表达式（常量片段≥3字符）	pg_trgm GIN	比顺序扫描快得多。
相似度排序 `ORDER BY col <-> 'q'`	pg_trgm GIN	支持，但若 `LIMIT` 很小且表很大，效率可能不如全表计算后排序（需测试）。

8. 完整示例

sql 复制代码

-- 1. 建表并导入数据
CREATE TABLE products (id SERIAL, name TEXT);
INSERT INTO products (name) VALUES ('PostgreSQL'), ('Postgres'), ('MySQL'), ('MongoDB');

-- 2. 创建 GIN 索引
CREATE INDEX idx_products_name ON products USING GIN (name gin_trgm_ops);

-- 3. 模糊查询
EXPLAIN (ANALYZE, BUFFERS) 
SELECT * FROM products WHERE name LIKE '%post%';
-- 将使用索引，尽管数据小可能不体现

-- 4. 相似度查询
SET pg_trgm.similarity_threshold = 0.5;
SELECT name, similarity(name, 'postgresql') AS sim 
FROM products 
WHERE name % 'postgresql';

-- 5. 按距离排序
SELECT name, name <-> 'postgresql' AS distance 
FROM products 
ORDER BY name <-> 'postgresql';

9. 局限性总结

无法处理 少于 3 个字符 的搜索词。
对于包含大量重复 trigram 的列（例如全是数字或相同字符），索引效率会下降。
索引维护成本较高，不适合频繁写入且对实时性要求极高的场景。
不能直接用于 LIKE 中的转义字符（如 % 作为普通字符时需要额外处理）。

10. 实际应用场景

搜索引擎的模糊补全：用户输入部分关键词，快速检索包含该关键词的标题。
日志分析：在日志消息列中查找包含特定错误码或 ID 的行。
地址/名称去重：使用相似度操作符找出重复或近似重复的记录。
代码库搜索：在存储源码的列中按函数名或字符串片段查找。

参考文档

PostgreSQL 官方文档：pg_trgm
GIN 索引

通过合理使用 pg_trgm 的 GIN 索引，可以高效解决传统 B-tree 索引无法处理的"包含式"模糊匹配和相似性搜索问题，是 PostgreSQL 中非常实用的高级索引技术。

PostgreSQL 中的 pg_trgm GIN 索引详解