参考手册与基准测试 on Vchord

SQL 参考手册

Mon, 01 Jan 0001 00:00:00 +0000

`vchord_bm25` 数据类型

数据类型	所属模式	适用版本	文本表示形式 / 内部结构	说明
`bm25vector`	`bm25_catalog`	`v0.1.0` – `v0.3.0`	`{token_id:freq, ...}`（例如 `{1:1, 2:2, 15:1}`）	将 32 位无符号词元 ID 映射为 32 位词频的稀疏向量。存储策略为 `STORAGE = EXTERNAL`。
`bm25query`	`bm25_catalog`	`v0.1.0` – `v0.3.0`	`(index_oid regclass, query_vector bm25vector)`	将目标 `bm25` 索引 OID 与查询 `bm25vector` 配对的复合类型。
`bm25query`	`public` / 扩展模式	`main`	`(vector tsvector, index regclass)`	将查询 `tsvector` 与目标 `bm25` 索引 OID 配对的复合类型。

`bm25vector` 字面量语法（`v0.1` – `v0.3`）

-- 空 bm25vector
SELECT '{}'::bm25vector;

-- 显式指定 token_id:frequency 键值对
SELECT '{1:1, 2:3, 10:2}'::bm25vector;

-- 从 int[] 隐式转换（自动将重复的词元 ID 聚合为词频计数）
SELECT ARRAY[1, 2, 2, 2, 10, 10]::bm25vector;
-- 输出：{1:1, 2:3, 10:2}

`vchord_bm25` 操作符

操作符	左操作数	右操作数	返回类型	适用版本	说明
`<&>`	`bm25vector`	`bm25query`	`real` (`f32`)	`v0.1.0` – `v0.3.0`	计算负值 BM25 相关性得分（$-\text{BM25}(D, Q)$）。支持使用 `bm25_ops` 执行索引加速的 `ORDER BY ... ASC` 扫描。
`<&>`	`tsvector`	`bm25query`	`float8` (`f64`)	`main`	在原生 `tsvector` 上计算负值 BM25 相关性得分。支持使用 `bm25_ops` 执行索引加速的 `ORDER BY ... ASC` 扫描。
`=`	`bm25vector`	`bm25vector`	`bool`	`v0.2.0` – `v0.3.0`	比较两个 `bm25vector` 值是否完全相等。
`<>`	`bm25vector`	`bm25vector`	`bool`	`v0.2.0` – `v0.3.0`	比较两个 `bm25vector` 值是否不相等。

`vchord_bm25` 函数

函数签名	返回类型	适用版本	说明
`to_bm25query(index_oid regclass, query_vector bm25vector)`	`bm25query`	`v0.1.1` – `v0.3.0`	根据 `bm25` 索引名称/OID 与查询 `bm25vector`（或经由隐式转换的 `INT[]`）构造 `bm25query`。
`to_bm25query(index_oid regclass, query_vector int[])`	`bm25query`	`v0.3.0+`	直接接受 `INT[]` 词元 ID 数组的显式重载函数。
`to_bm25query(vector tsvector, index regclass)`	`bm25query`	`main`	根据原生 `tsvector` 与目标 `bm25` 索引名称/OID 构造 `bm25query`。
`search_bm25query(target_vector bm25vector, query bm25query)`	`real`	`v0.1.0` – `v0.3.0`	`bm25vector <&> bm25query` 操作符的底层实现函数。
`_bm25_evaluate(left tsvector, right bm25query)`	`float8`	`main`	`tsvector <&> bm25query` 操作符的底层实现函数。
`bm25_page_inspect(index regclass, blkno int)`	`text`	`v0.3.0`	返回 `bm25` 索引第 `blkno` 号数据块的可读诊断元数据。

`vchord_bm25` 访问方法与操作符类

对象类型	名称	目标类型	排序操作符
访问方法 (Access Method)	`bm25`	索引 (Index)	处理器 `_bm25_amhandler`
操作符族 (Operator Family)	`bm25_ops`	`USING bm25`	`OPERATOR 1 pg_catalog.<&> FOR ORDER BY float_ops`
操作符类 (Operator Class)	`bm25_ops`	`bm25vector`（`v0.1`–`v0.3`）/ `tsvector`（`main`）	`USING bm25` 的默认操作符类

`pg_tokenizer` 函数（`tokenizer_catalog`）

所有 pg_tokenizer 函数均位于 tokenizer_catalog 模式中：

GUC 与索引参数

Mon, 01 Jan 0001 00:00:00 +0000

稳定发布版（`v0.1.0` – `v0.3.0`）：`bm25_catalog.*` GUC 参数

在 v0.1.0 至 v0.3.0 版本中，所有会话级 GUC 参数均使用 bm25_catalog. 前缀，任何普通用户均可在会话或事务级别修改（GucContext::Userset）：

性能与精度基准测试

Mon, 01 Jan 0001 00:00:00 +0000

吞吐量基准测试（QPS 对比 Elasticsearch、Lucene、ParadeDB、PG GIN）

凭借结合 128 文档差分位打包块与单字节 Fieldnorm 量化的 Block-WeakAnd 算法实现，VectorChord-BM25 在 Top-10 排序查询上的 QPS 吞吐量最高可达基于 Tantivy 的 PostgreSQL 扩展（ParadeDB / pg_search）的 3 倍，并比 PostgreSQL 原生 GIN 索引高出一个数量级：

版本历史与 API 演进

Mon, 01 Jan 0001 00:00:00 +0000

本页记录 vchord_bm25（pgsty/vchord_bm25 / supervc-stack/VectorChord-bm25）的版本发布历史与 SQL 模式演进。

版本演进总览矩阵

版本	所属模式	索引列类型	分词方案	核心新增特性
`main`（新一代架构）	扩展所在模式	`tsvector`	原生 `to_tsvector`（或自定义）	基于原生 `tsvector` 完全重写存储与索引引擎；支持外部排序并行构建（`ambuild`）；引入索引级存储参数（`options`、`limit`、`prefilter`）；引入 `bm25.*` GUC 参数；支持 PostgreSQL 18。
`v0.3.0`	`bm25_catalog`	`bm25vector`	`pg_tokenizer`	新增 `bm25_page_inspect(regclass, int)` 函数、`to_bm25query(regclass, int[])` 重载，以及 PostgreSQL 18 兼容性支持。
`v0.2.2`	`bm25_catalog`	`bm25vector`	`pg_tokenizer`	新增 `bm25_catalog.enable_prefilter` GUC 参数，支持带 `WHERE` 子句的精确过滤 Top-K BM25 检索。
`v0.2.1`	`bm25_catalog`	`bm25vector`	`pg_tokenizer`	修复增长段（Growing）向封闭段（Sealed）转换以及 VACUUM 清理过程中的若干缺陷。
`v0.2.0`	`bm25_catalog`	`bm25vector`	`pg_tokenizer`	为 `bm25vector` 新增 `=` 与 `<>` 相等性操作符，以及隐式类型转换 `CREATE CAST (int[] AS bm25vector) AS IMPLICIT`。
`v0.1.1`	`bm25_catalog`	`bm25vector`	`pg_tokenizer`	将分词能力解耦为独立的 `pg_tokenizer` 扩展；调整 `to_bm25query(regclass, bm25vector)` 函数签名。
`v0.1.0`	`bm25_catalog`	`bm25vector`	内置 `unicode`	首个发布版本，提供 `bm25vector`、`bm25query`、`USING bm25` 及 Block-WeakAnd Top-K 扫描。

各版本升级变更详解

`v0.3.0`（`sql/vchord_bm25--0.2.2--0.3.0.sql`）

新增页面诊断函数：

CREATE FUNCTION bm25_page_inspect(index regclass, blkno INT) RETURNS TEXT;

在 main / 0.3.x 后期版本中新增了直接接受 int[] 的便捷重载 to_bm25query(regclass, int[])。

`v0.2.2`（`sql/vchord_bm25--0.2.1--0.2.2.sql`）

在 Block-WeakAnd 中新增预过滤支持（bm25_catalog.enable_prefilter GUC 参数，在 0.3.0 中默认启用）。
改进索引扫描期间的 MVCC 可见性检查，防止死元组（Dead Tuples）或被过滤元组污染 Top-K 剪枝阈值。

`v0.2.0`（`sql/vchord_bm25--0.1.1--0.2.0.sql`）

为 bm25vector 新增 = 与 <> 操作符。
新增从 int[] 到 bm25vector 的隐式类型转换（_vchord_bm25_cast_array_to_bm25vector），允许将 tokenize(text, name) 的输出（INT[]）直接赋值给 bm25vector 列或传入任何接受 bm25vector 的位置。

`v0.1.1`（`sql/vchord_bm25--0.1.0--0.1.1.sql`）

将原本内置的 create_tokenizer / tokenize 函数抽离为独立的 pg_tokenizer 扩展（tokenizer_catalog），从而支持丰富的文本分析器、Snowball 词干提取、停用词、同义词、HuggingFace 模型、jieba 中文分词与 lindera 日文分词。
简化 to_bm25query(index_oid regclass, query_vector bm25vector) 签名，直接接受 bm25vector 参数。

新一代架构重写（`main` 分支）

用 PostgreSQL 原生 tsvector 替代自定义 bm25vector 类型（CREATE OPERATOR CLASS bm25_ops FOR TYPE tsvector USING bm25），允许用户直接使用 USING bm25 为 to_tsvector(...) 列建立索引。
新增基于外部归并排序（External Merge Sort）的并行索引构建（bm25_parallel_build_main），保证恒定的维护内存消耗。
支持通过 WITH (options = $$ k1 = 1.2, b = 0.75 $$) 配置索引级 BM25 超参数（ $k_1 \in [1.2, 2.0]$ ， $b \in [0.0, 1.0]$ ）。

参考手册与基准测试 on Vchord

SQL 参考手册

vchord_bm25 数据类型

bm25vector 字面量语法（v0.1 – v0.3）

vchord_bm25 操作符

vchord_bm25 函数

vchord_bm25 访问方法与操作符类

pg_tokenizer 函数（tokenizer_catalog）

GUC 与索引参数

稳定发布版（v0.1.0 – v0.3.0）：bm25_catalog.* GUC 参数

性能与精度基准测试

吞吐量基准测试（QPS 对比 Elasticsearch、Lucene、ParadeDB、PG GIN）

版本历史与 API 演进

版本演进总览矩阵

各版本升级变更详解

v0.3.0（sql/vchord_bm25--0.2.2--0.3.0.sql）

v0.2.2（sql/vchord_bm25--0.2.1--0.2.2.sql）

v0.2.0（sql/vchord_bm25--0.1.1--0.2.0.sql）

v0.1.1（sql/vchord_bm25--0.1.0--0.1.1.sql）

新一代架构重写（main 分支）

`vchord_bm25` 数据类型

`bm25vector` 字面量语法（`v0.1` – `v0.3`）

`vchord_bm25` 操作符

`vchord_bm25` 函数

`vchord_bm25` 访问方法与操作符类

`pg_tokenizer` 函数（`tokenizer_catalog`）

稳定发布版（`v0.1.0` – `v0.3.0`）：`bm25_catalog.*` GUC 参数

`v0.3.0`（`sql/vchord_bm25--0.2.2--0.3.0.sql`）

`v0.2.2`（`sql/vchord_bm25--0.2.1--0.2.2.sql`）

`v0.2.0`（`sql/vchord_bm25--0.1.1--0.2.0.sql`）

`v0.1.1`（`sql/vchord_bm25--0.1.0--0.1.1.sql`）

新一代架构重写（`main` 分支）