跳转到主要内容

SQL 参考手册

vchord_bm25 与 pg_tokenizer 的完整 SQL 数据类型、操作符、类型转换、索引访问方法与函数参考。
重要

当前源码面向 0.4.0（尚未发布），使用原生 tsvector 和新的索引格式。标注 0.3.x 的 bm25vector 示例仅适用于旧版。两者不能原地升级；请先阅读0.4.0 迁移指南。

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 / 扩展模式 0.4.0 / 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) 0.4.0 / 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 0.4.0 / 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 0.4.0 / main tsvector <&> bm25query 操作符的底层实现函数。
bm25_page_inspect(index regclass, blkno int) text v0.3.0 返回 bm25 索引第 blkno 号数据块的可读诊断元数据。

vchord_bm25 访问方法与操作符类

对象类型 名称 目标类型 排序操作符
访问方法 (Access Method) bm25 索引 (Index) 0.4.0 处理器为 bm25_amhandler；0.3.x 为 _bm25_amhandler
操作符族 (Operator Family) bm25_ops USING bm25 <&> 位于扩展模式（0.4.0）或 pg_catalog（0.3.x），按 float_ops 排序
操作符类 (Operator Class) bm25_ops bm25vector（v0.1–v0.3）/ tsvector（main） USING bm25 的显式操作符类

pg_tokenizer 函数（tokenizer_catalog）

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

分词器管理与执行

函数签名 返回类型 说明
create_tokenizer(name TEXT, config TEXT) void 根据 TOML 配置字符串创建一个命名分词器。
drop_tokenizer(name TEXT) void 删除已有的分词器。
tokenize(text TEXT, tokenizer_name TEXT) INT[] 使用 tokenizer_name 对 text 进行分词，返回整数词元 ID 数组（可隐式转换为 bm25vector）。

文本分析器管理

函数签名 返回类型 说明
create_text_analyzer(name TEXT, config TEXT) void 创建可复用的命名文本分析器流水线（包含 character_filters、pre_tokenizer、token_filters）。
drop_text_analyzer(name TEXT) void 删除指定的命名文本分析器。
apply_text_analyzer(text TEXT, text_analyzer_name TEXT) TEXT[] 对 text 运行指定的文本分析器，返回归一化后的字符串词元数组（常用于调试分词效果）。

模型管理

函数签名 返回类型 说明
create_custom_model(name TEXT, config TEXT) void 使用指定的文本分析器，在现有表列上训练自定义词表模型。
drop_custom_model(name TEXT) void 删除自定义模型及其底层词表数据表。
create_custom_model_tokenizer_and_trigger(tokenizer_name TEXT, model_name TEXT, text_analyzer_name TEXT, table_name TEXT, source_column TEXT, target_column TEXT) void 一步创建自定义模型与分词器，回填 table_name 表中的 target_column 列，并绑定自动 BEFORE INSERT OR UPDATE 触发器。
create_huggingface_model(name TEXT, config TEXT) void 从 HuggingFace tokenizer.json 字符串导入模型。
drop_huggingface_model(name TEXT) void 删除已导入的 HuggingFace 模型。
create_lindera_model(name TEXT, config TEXT) void 根据 TOML 配置创建 Lindera 形态学分析模型（如 ipadic）。
drop_lindera_model(name TEXT) void 删除 Lindera 模型。

词典与预加载管理

函数签名 返回类型 说明
create_stopwords(name TEXT, config TEXT) void 创建自定义停用词典（每行一个停用词）。
drop_stopwords(name TEXT) void 删除自定义停用词典。
create_synonym(name TEXT, config TEXT) void 创建自定义同义词典（每行以空格分隔一组同义词，统一映射到该行第一个词）。
drop_synonym(name TEXT) void 删除自定义同义词典。
add_preload_model(name TEXT) void 注册在 PostgreSQL 服务启动（shared_preload_libraries）时预加载的模型。
remove_preload_model(name TEXT) void 从启动预加载列表中移除指定模型。
list_preload_models() TEXT[] 返回当前已注册为启动预加载的所有模型名称列表。

内部触发器与辅助函数（tokenizer_catalog）

函数签名 返回类型 说明
apply_text_analyzer_for_custom_model(text TEXT, text_analyzer_name TEXT) TEXT[] 调用 text_analyzer_name 分词，并在写入自定义模型词表前自动过滤掉长度超过 2600 字节（PostgreSQL B-tree UNIQUE 索引键最大长度限制）的超长词元。
custom_model_insert_trigger() trigger AFTER INSERT OR UPDATE 触发器函数，从源文本列提取词元并将新出现的词元自动追加写入 tokenizer_catalog."model_<name>" 词表。
custom_model_tokenizer_set_target_column_trigger() trigger 由 create_custom_model_tokenizer_and_trigger 安装的 BEFORE INSERT OR UPDATE 触发器函数，自动执行 NEW.<target_column> = tokenize(NEW.<source_column>, tokenizer_name)。

pg_tokenizer 元数据表（tokenizer_catalog）

表名 列定义 说明
tokenizer_catalog.tokenizer name TEXT NOT NULL UNIQUE, config TEXT NOT NULL 存储已注册的分词器名称及其序列化后的 JSON/TOML 配置。
tokenizer_catalog.text_analyzer name TEXT NOT NULL UNIQUE, config TEXT NOT NULL 存储独立命名且可复用的文本分析器定义。
tokenizer_catalog.model name TEXT NOT NULL UNIQUE, config TEXT NOT NULL 存储已注册的自定义模型、HuggingFace 模型与 Lindera 模型定义。
tokenizer_catalog.stopwords name TEXT NOT NULL PRIMARY KEY, config TEXT NOT NULL 存储内置（lucene_english、nltk_english、iso_english）及自定义停用词典。
tokenizer_catalog.synonym name TEXT NOT NULL PRIMARY KEY, config TEXT NOT NULL 存储自定义同义词典。
tokenizer_catalog."model_<name>" id SERIAL PRIMARY KEY, token TEXT NOT NULL UNIQUE 为每个自定义模型 <name> 自动创建的底层词表数据表，将唯一归一化词元映射为从 1 开始的自增整数 ID。

pg_tokenizer TOML 配置参数参考

分词器配置项（create_tokenizer）

参数名 类型 说明
text_analyzer string（可选） 预先创建的命名 text_analyzer 名称。若省略，可在支持文本分析器的模型中直接内联定义 character_filters、pre_tokenizer 和 token_filters。
model string（必填） 内置模型（llmlingua2、bert_base_uncased、wiki_tocken、gemma2b）或用户创建的模型（custom、huggingface、lindera）名称。

文本分析器配置项（create_text_analyzer）

参数名 类型 说明
character_filters array / table 在分词前对整段字符串依次应用的字符过滤器列表：to_lowercase、unicode_normalization（nfc、nfd、nfkc、nfkd）。
pre_tokenizer string / table 将字符串切分为初始词元的单个预分词器：unicode_segmentation、regex（Rust 正则表达式）或 jieba（mode = "full" | "precise" | "search"，enable_hmm = true | false）。
token_filters array 按顺序执行的词元过滤器列表：skip_non_alphanumeric、stemmer（支持 30 种 Snowball 词干提取器）、stopwords（内置 lucene_english、nltk_english、iso_english 或自定义停用词典）、synonym、pg_dict（除 Thesaurus 外的任意 pg_ts_dict 词典）、ngram（min_gram、max_gram 范围 1..=255，preserve_original）。

自定义模型配置项（create_custom_model）

参数名 类型 说明
table string（必填） 包含源文本语料的目标表名称。
column string（必填） table 表中用于构建词表的源 TEXT 列名称。
text_analyzer string（必填） 用于将 column 列切分为词表词元的 text_analyzer 名称。
最后修改 2026-11-03 · feat(home): compact 2x2 horizontal metric cards and vivid SQL/Bash syntax highlighting (972ccec)
本页改编自 tensorchord/VectorChord-bm25，© 2024–2026 TensorChord Inc.，依 GNU Affero General Public License v3.0 授权，详见归属声明与修改历史。