PostgreSQL自带的全文检索对英文等空格分隔语言效果很好，但中文文本没有天然空格，默认解析器会把整段连续中文字符识别成一个词。例如“全文检索中文分词”会被看成一个整体，查询“中文”时无法命中。要让中文搜索真正可用，需要引入支持中文分词能力的解析器，其中比较常用的方案是pg_jieba。
pg_jieba把结巴分词的词库和算法封装成PostgreSQL的text search parser，安装后可以直接用于to_tsvector与to_tsquery，也能配合GIN索引加速查询。
一、原生全文检索在处理中文时的问题
PostgreSQL的全文检索由解析器、词典和配置组成。内置的default解析器主要根据空白字符、标点、数字等规则识别token，对于英文，hello world会变成两个词；而中文“我爱北京天安门”没有空格，整串会被当成一个词条。这样即使查询“北京”，也不会匹配，因为tsvector中只有“我爱北京天安门”这个大词。
可以通过一个简单示例观察。执行SELECT to_tsvector('english', '我爱北京天安门');返回结果中只有一个完整词条。因此必须替换解析器，让它在中文词边界上进行切分。pg_jieba底层使用结巴分词的词典匹配和HMM模型，能够把句子切分为“我/爱/北京/天安门”等中文词，符合用户检索习惯。
SELECT to_tsvector('english', '我爱北京天安门');
-- 结果类似： '我爱北京天安门':1
SELECT * FROM to_tsvector('jiebacfg', '我爱北京天安门');
-- 结果类似： '北京':3 '天安门':4 '我爱':1
二、安装pg_jieba扩展的详细步骤
pg_jieba需要编译安装，依赖PostgreSQL服务端开发包、cmake和C++编译器。Linux下可以先安装postgresql-server-dev或postgresql-devel，不同发行版名称略有不同。以Debian/Ubuntu为例，执行apt-get install postgresql-server-dev-all cmake g++ git。确认pg_config命令可用，因为编译脚本通过它定位PostgreSQL安装目录。
先从源码仓库获取pg_jieba，然后进入目录用cmake生成Makefile。假设PostgreSQL安装在/usr/local/pgsql，可直接执行以下命令。如果pg_config不在PATH中，可以通过CMAKE_PREFIX_PATH或PG_CONFIG环境变量指定路径。
git clone https://github.com/jaiminpan/pg_jieba.git cd pg_jieba cmake -DCMAKE_PREFIX_PATH=/usr/local/pgsql . make sudo make install
编译完成后，扩展文件会被复制到PostgreSQL的extension目录，分词库和词典数据会放到lib、share目录。安装后无需重启数据库服务，只需要在目标库中执行CREATE EXTENSION。要注意，数据库编码应为UTF8，因为jieba词典按UTF8编码处理中文。
三、创建扩展并验证中文分词效果
登录目标数据库，执行CREATE EXTENSION pg_jieba;。如果连接用户权限不足，需要超级用户或具有创建扩展权限的角色。扩展创建成功后会生成jieba解析器，并且通常会自动创建名为jiebacfg的全文检索配置。可以通过\dF命令查看文本搜索配置列表，确认jiebacfg存在。
接着使用to_tsvector函数测试分词。下面例子中，“南京市长江大桥”会被jieba切分为多个词。查询时可以构造tsquery表达式，使用&表示与、|表示或、!表示非。注意tsquery语法中的空格和符号，中文词可以不加引号，但包含特殊符号时建议用单引号包裹。
CREATE EXTENSION pg_jieba;
SELECT to_tsvector('jiebacfg', '南京市长江大桥');
-- 结果包含：南京、市长、长江、大桥等
SELECT to_tsquery('jiebacfg', '南京 & 长江');
SELECT to_tsvector('jiebacfg', '我是中国人') @@ to_tsquery('jiebacfg', '中国');
实际业务中，通常不会每次查询都现场分词，而是把to_tsvector结果存入一个类型为tsvector的列，再创建GIN索引。例如articles表有title列，可以增加title_tsv列并创建索引。
ALTER TABLE articles ADD COLUMN title_tsv tsvector;
UPDATE articles SET title_tsv = to_tsvector('jiebacfg', title);
CREATE INDEX idx_articles_title_tsv ON articles USING GIN (title_tsv);
SELECT title FROM articles
WHERE title_tsv @@ to_tsquery('jiebacfg', 'PostgreSQL & 全文检索');
四、自定义词典与停用词配置
pg_jieba的分词效果依赖词典。默认词典能覆盖常见词汇，但遇到专业术语、人名、产品名时可能切分不准。例如“云原生数据库”可能被切为“云/原生/数据库”，如果希望作为一个整体词出现，可以将其加入用户词典。pg_jieba会在安装目录下加载dict目录中的jieba.dict.utf8文件，也可以修改扩展对应的词典文件或通过参数指定附加词典。
添加词条后需要让数据库重新加载词典。不同版本pg_jieba加载机制略有差异，部分版本重启数据库后生效，部分支持动态加载函数。修改词典前建议备份原文件，并保证文件使用UTF8编码、词条格式为“词语 词频 词性”。如果词频设置过高，可能影响切分优先级，不宜把所有新词都设置成超高频率。
停用词也能提升检索质量。可以创建停用词词典文件，如中文常见虚词“的、了、是、在”，然后在文本搜索配置中把Stop words词典绑定到对应token类型。这样生成的tsvector不会包含这些无意义的词，减少索引体积，提高查询精度。
五、常见故障排查与性能优化
如果CREATE EXTENSION时报错找不到文件，先检查pg_jieba是否安装到当前数据库实例对应的目录。多版本PostgreSQL共存时，make install可能复制到默认实例，而连接的是另一个实例。此时可以通过pg_config确认安装路径，重新指定cmake参数编译安装。如果报错缺少libjieba或词典路径不可读，需要确认postgres进程用户对安装目录和词典文件有读取权限。
查询性能方面，GIN索引对tsvector列的查询非常高效，但要避免在WHERE条件中直接对普通文本列使用to_tsvector，因为这样无法利用索引，只能全表扫描。推荐做法是将分词结果物化到tsvector列，并通过触发器或应用层在插入更新时同步维护。若数据更新频繁，也可以使用表达式索引。
最后，分词准确率和查询召回率需要根据业务语料不断调整。可以定期分析慢查询和未命中记录，把高频专业词补充进词典，同时移除过时词。中文搜索除了PostgreSQL全文检索，还可以结合pg_trgm做模糊匹配，但两者适用场景不同，建议主查询使用jieba分词，模糊补全单独处理。
PostgreSQL全文检索中文分词jieba配置修改时间：2026-08-22 17:59:49