pg_textsearch

概览

bm25 am conflicts with pg_search and vchord_bm25

版本

构建

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

pig build pkg pg_textsearch         # 构建 RPM / DEB 包

安装

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

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

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

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

pig ext install -y pg_textsearch -v 18  # PG 18
pig ext install -y pg_textsearch -v 17  # PG 17

dnf install -y pg_textsearch_18       # PG 18
dnf install -y pg_textsearch_17       # PG 17

apt install -y postgresql-18-textsearch   # PG 18
apt install -y postgresql-17-textsearch   # PG 17

预加载配置：

shared_preload_libraries = 'pg_textsearch';

创建扩展：

CREATE EXTENSION pg_textsearch;

用法

来源：

• Version 1.5.1 README
• Control file
• Versioned SQL
• Version 1.5.1 release

pg_textsearch 通过 bm25 访问方法和 <@> 运算符提供 BM25 全文检索。1.5.1 支持 PostgreSQL 17 和 18，要求预加载并重启。修改预加载列表时应保留已有条目。

构建与查询

shared_preload_libraries = 'pg_textsearch'

CREATE EXTENSION pg_textsearch;
CREATE TABLE documents (id bigserial PRIMARY KEY, content text);
INSERT INTO documents(content) VALUES
    ('PostgreSQL is a database system'),
    ('BM25 ranks full text search results');
CREATE INDEX docs_idx ON documents USING bm25(content)
WITH (text_config = 'english');

SELECT id, content <@> 'database system' AS score
FROM documents
ORDER BY content <@> 'database system'
LIMIT 5;

分数是 BM25 值的相反数，因此数值越低越靠前。使用 ORDER BY 与 LIMIT 进行 top-k 检索。独立评分、部分索引或 PL/pgSQL 中应明确指定索引：

SELECT id FROM documents
ORDER BY content <@> to_bm25query('database system', 'docs_idx')
LIMIT 5;

索引与查询选项

text_config 是必填项，指定 PostgreSQL 文本搜索配置。k1 默认是 1.2，b 默认是 0.75。bm25query 类型和 to_bm25query(text, text) 显式携带查询及索引上下文。独立评分需要目标表或索引列的 SELECT 权限。

扩展支持 text[]、varchar[] 和 bpchar[]、不可变文本表达式索引、部分索引及分区表。查询中须使用与索引匹配的表达式。部分索引需要匹配的过滤条件及明确的索引名。1.5.0 改进了带过滤条件的 top-k 执行，但严格的后置过滤仍可能导致结果数少于请求数。

中文分词可配置 zhparser 等解析器，再使用相应的文本搜索配置；这是该工作流的可选依赖。对于缺少空白分词边界的超长文本，上游建议由应用确定分块边界，并使用文本数组保存。

维护与配置

从 1.3.0 开始，持久化内存表存放于索引页中，使用 PostgreSQL 标准 WAL 回放。查询仍可使用共享内存读缓存，由下列缓存和内存上限配置控制。自动压实在刷写过程中同步执行，重写入负载可能受到压实延迟影响。

SELECT bm25_spill_index('docs_idx');
SELECT bm25_force_merge('docs_idx');

强制合并适合在批量加载后执行，持续写入时应谨慎使用。VACUUM 也会刷写待处理的内存表页。相关配置包括：

并行构建要求 maintenance_work_mem 至少为 64 MB，且有可用的并行维护进程。升级时先准备匹配的二进制文件，重启 PostgreSQL，再按发布说明执行扩展更新。

ALTER EXTENSION pg_textsearch UPDATE;

使用边界

bm25 访问方法名与 pg_search、vchord_bm25 冲突，不应在同一数据库安装相互冲突的提供者。短语匹配在需要时通过保守的堆表复查实现。分数采用各分区自身的统计信息，跨分区可能不可直接比较。超长词项受 PostgreSQL 文本搜索限制影响。固定的 LWLock tranche ID 也可能与其他扩展冲突，导致等待事件名称不准确。

1.5.0 查询与维护

布尔过滤现在接受 PostgreSQL tsquery，包含 AND/OR/NOT、纯否定、前缀、权重与短语条件；短语／权重可能需要堆表复查。PostgreSQL 19 支持仍为 beta。可选的受管理后台合并要求同一配置数据库中的 pg_durable 0.2.8+，并按上游要求预加载和配置；内联／手动模式无需该依赖。pg_textsearch.allow_rls 默认开启，BM25 统计包含被 RLS 隐藏的索引行。关闭该设置可阻止在受保护表上新建／重建 BM25 索引及相应 RLS 启用，但不会禁用现有索引。

升级到 1.5.1

1.5.1 修复并发刷写／强制合并造成的截断损坏、表达式索引及数组／域类型处理，以及未安装扩展的数据库中的维护操作。安装匹配的库文件并重启 PostgreSQL，然后在各数据库中更新扩展。1.5.0 到 1.5.1 的迁移检查库是否已预加载，没有新增 SQL 对象或显式索引格式迁移。

ALTER EXTENSION pg_textsearch UPDATE TO '1.5.1';

缓存预算是近似值，并发操作可能超过它。执行 BM25 查询的热备库需要设置 hot_standby_feedback = on，以便在活动快照期间延迟物理页复用。修改索引的维护函数要求索引所有权，不能在恢复期间执行；已发布的物理合并替换不会被事务回滚撤销。