索引损坏？GIN索引搜索命中0行，Seq Scan却能查到

NickYoung

发布于 2026-07-09 16:40:01

110

分享一个经典案例：zhparser 分词参数不一致导致 PostgreSQL GIN 全文搜索静默失效，GIN索引搜索命中0行，Seq Scan却能查到。

一、问题现象：索引正常扫描，却返回 0 行

这是一次让人困惑的排查经历。一张 15 万行的商品目录表 demo_product_catalog，建有 GIN 全文搜索索引，查询使用 to_tsvector @@ plainto_tsquery 的标准模式，EXPLAIN 显示 索引被正常使用——但返回 0 行。

更诡异的是：关掉索引后走全表扫描，同样的查询立刻命中近 3 万行。

先看表结构和索引定义：

test=> \d+ demo_product_catalog
                          Table "public.demo_product_catalog"
    Column    |         Type          | Nullable |                     Default
--------------+-----------------------+----------+--------------------------------------------------
 id           | bigint                | not null | nextval('demo_product_catalog_id_seq'::regclass)
 product_code | character varying(20) |          |
 product_name | character varying(50) |          |
 category     | character varying(50) |          |
Indexes:
    "demo_product_catalog_pkey" PRIMARY KEY, btree (id)
    "idx_demo_product_catalog_name" gin (to_tsvector('chinese'::regconfig, product_name::text))

GIN 索引 idx_demo_product_catalog_name 建立在表达式 to_tsvector('chinese', product_name) 上，使用 zhparser 提供的 chinese 分词配置。查询也用同样的配置和表达式——看起来天衣无缝。先看第一组 EXPLAIN 输出，查询语句：

EXPLAIN (ANALYZE, BUFFERS)
SELECT * FROM demo_product_catalog
WHERE to_tsvector('chinese', product_name)
    @@ plainto_tsquery('chinese', '华联科技智能终端');

GIN 索引扫描的结果：

 Bitmap Heap Scan on demo_product_catalog  (cost=68.97..73.23 rows=1 width=62)
                                           (actual time=0.169..0.169 rows=0 loops=1)
   Recheck Cond: (to_tsvector('chinese'::regconfig, product_name::text)
       @@ '''华联'' & ''科技'' & ''智能终端'' & ''智能'' & ''终端'''::tsquery)
   Buffers: shared hit=22
   ->  Bitmap Index Scan on idx_demo_product_catalog_name
         (cost=0.00..68.97 rows=1 width=0) (actual time=0.165..0.165 rows=0 loops=1)
         Index Cond: (to_tsvector('chinese'::regconfig, product_name::text)
             @@ '''华联'' & ''科技'' & ''智能终端'' & ''智能'' & ''终端'''::tsquery)
         Index Searches: 1
         Buffers: shared hit=22
 Execution Time: 0.215 ms

索引扫描走了，执行计划看起来完全正常——Bitmap Index Scan 命中了正确的索引 idx_demo_product_catalog_name。但 rows=0，0.215 毫秒，干干净净地返回了空。

接下来，关掉 bitmapscan，强制走顺序扫描：

SET enable_bitmapscan TO off;

EXPLAIN (ANALYZE, BUFFERS)
SELECT * FROM demo_product_catalog
WHERE to_tsvector('chinese', product_name)
    @@ plainto_tsquery('chinese', '华联科技智能终端');

WARNING:  parameter "zhparser.multi_short" cannot be set during a parallel operation

 Gather  (cost=1000.00..26374.29 rows=1 width=62) (actual time=0.375..520.998 rows=29283 loops=1)
   Workers Planned: 1
   Workers Launched: 1
   Buffers: shared hit=1884
   ->  Parallel Seq Scan on demo_product_catalog
         (cost=0.00..25374.19 rows=1 width=62) (actual time=258.841..516.380 rows=14641.50 loops=2)
         Filter: (to_tsvector('chinese'::regconfig, product_name::text)
             @@ '''华联'' & ''科技'' & ''智能终端'' & ''智能'' & ''终端'''::tsquery)
         Rows Removed by Filter: 61824
         Buffers: shared hit=1884
 Execution Time: 522.699 ms

同样的查询，同样的 tsquery，Seq Scan 返回了 29283 行。

更令人困惑的是，索引本身的健康检查也没有任何异常：

test=> SELECT * FROM gin_index_check('idx_demo_product_catalog_name');
 gin_index_check 
-----------------

(1 row)

gin_index_check 返回空——索引结构完整，没有损坏，没有膨胀，没有任何报错。问题不在索引本身，而在索引内容与查询内容之间的分词不一致。

核心矛盾：索引在用，查询计划正常，gin_index_check 也返回空（无异常），但 GIN 索引返回 0 行；禁用索引后全表扫描却能正确命中近 3 万行。没有报错，没有异常日志——这是一次静默失效。

而且，Seq Scan 的输出中还藏着一个 WARNING：

WARNING:  parameter "zhparser.multi_short" cannot be set during a parallel operation

这条 WARNING 在索引扫描时没有出现（因为没走并行），只在 Seq Scan 的并行 worker 启动时才冒出来。它是一个容易被忽略的线索，但恰恰指向了问题的根源。

· · ·

二、线索追踪：从 tsquery 和 WARNING 中找到突破口

2.1 tsquery 里的 5 个词条

仔细看 EXPLAIN 输出中的 Recheck Cond 和 Filter，两者使用了完全相同的 tsquery：

'''华联'' & ''科技'' & ''智能终端'' & ''智能'' & ''终端'''::tsquery

这个 tsquery 由 5 个词条通过 AND 连接：华联 & 科技 & 智能终端 & 智能 & 终端。其中有复合词（智能终端），也有 multi_short=on 额外拆出的短词（智能、终端），而 华联、科技 两种模式下都存在。

关键问题来了：索引中存储的词条，和查询生成的词条，是同一组吗？

2.2 zhparser 的 multi_short 参数

那条 WARNING 提到了 zhparser.multi_short。这是 zhparser 扩展注册的自定义 GUC 参数，控制中文分词的粒度：

multi_short 值	分词模式	"华联科技智能终端" 分词结果
off（默认）	不额外拆分短词	华联 / 科技 / 智能终端（3 个词条）
on	额外拆分短词	华联 / 科技 / 智能终端 / 智能 / 终端（5 个词条）

可以看到，multi_short 从 off 切到 on 后，分词结果多了 智能、终端 这两个短词（智能终端 复合词仍然保留）。

2.3 时间线还原

结合 demo 环境的搭建过程，事件的时间线清晰了：

时间点	操作	session 的 multi_short	分词结果
T1：建索引	SET zhparser.multi_short = off;CREATE INDEX ... USING gin (...)	off	复合词写入 GIN entries：{华联, 科技, 智能终端}
T2：查询	SET zhparser.multi_short = on;SELECT ... WHERE to_tsvector @@ plainto_tsquery(...)	on	短词生成 tsquery：华联 & 科技 & 智能终端 & 智能 & 终端

索引创建时 multi_short=off，查询时 multi_short=on。 分词参数不一致，就是问题的入口。

· · ·

三、根因定位：multi_short 参数与分词一致性

3.1 为什么 GIN 返回 0 行？

GIN 索引的词条匹配是精确字符串匹配——不是子串匹配，不是前缀匹配，不是模糊匹配。索引中存的 智能终端 作为一个完整的 entry，不会匹配查询中的 智能 或 终端——后者是独立的短词 entry，与复合词 智能终端 不是同一个字符串。

对照一下索引 entries 和查询 entries：

查询词条（multi_short=on）	索引 entries（multi_short=off）	精确匹配
华联	华联 ✓	✓ 命中
科技	科技 ✓	✓ 命中
智能终端	智能终端 ✓	✓ 命中
智能	索引中无此词条	✗ 未命中
终端	索引中无此词条	✗ 未命中

5 个查询词条中，2 个（智能、终端）在索引中不存在。由于 tsquery 使用 AND 连接，任何一个词条不匹配，整个 AND 表达式即为 false。GIN 一致性检查函数判定为不匹配，返回 0 行。

3.2 为什么 Seq Scan 能命中？

Seq Scan 对每一行实时执行 to_tsvector('chinese', product_name)。此时 session 的 multi_short=on，所以实时分词结果也是短词：{华联, 科技, 智能终端, 智能, 终端}。

tsquery 同样是 multi_short=on 下的 5 个短词。两侧分词参数一致，词条完全匹配，所以 Seq Scan 正确命中。

根因一句话：GIN 索引中存储的是 multi_short=off 时的分词结果（3 个词条，无短词），查询时 multi_short=on 生成了不同的分词结果（5 个词条，多了 智能、终端 两个短词），GIN 精确匹配失败。Seq Scan 因为实时分词，两侧参数一致，所以正常工作。

· · ·

四、源码深潜：两次 parsetext 调用读到了不同的值

以上分析基于现象推断。要确认根因，需要深入 PostgreSQL 源码，追踪分词在索引创建和查询两条路径上分别是怎么执行的。

4.1 索引创建路径：to_tsvector → parsetext → zhparser 回调

索引创建时，对每行 product_name 调用 to_tsvector('chinese', product_name)，入口函数是 to_tsvector_byid：

// src/backend/tsearch/to_tsany.c 
Datum to_tsvector_byid(PG_FUNCTION_ARGS)
{
    Oid   cfgId = PG_GETARG_OID(0);
    text *in = PG_GETARG_TEXT_PP(1);
    ParsedText prs;
    TSVector out;

    // 初始化 ParsedText
    prs.lenwords = VARSIZE_ANY_EXHDR(in) / 6;
    if (prs.lenwords < 2) prs.lenwords = 2;
    prs.curwords = 0;
    prs.pos = 0;
    prs.words = (ParsedWord *) palloc(...);

parsetext(cfgId, &prs, VARDATA_ANY(in), VARSIZE_ANY_EXHDR(in));

    out = make_tsvector(&prs);
    PG_RETURN_TSVECTOR(out);
}

核心分词逻辑在 parsetext() 函数中（src/backend/tsearch/ts_parse.c）。它通过 lookup_ts_parser_cache(cfg->prsId) 获取 parser 对象，再循环调用 prsobj->prstoken 回调逐个获取 token：

// src/backend/tsearch/ts_parse.c 
void parsetext(Oid cfgId, ParsedText *prs, char *buf, int buflen)
{
    TSParserCacheEntry *prsobj;
    void *prsdata;

    cfg = lookup_ts_config_cache(cfgId);
    prsobj = lookup_ts_parser_cache(cfg->prsId);

    // 初始化 parser（对 zhparser 而言是 zhprs_start）
    prsdata = DatumGetPointer(FunctionCall2(&prsobj->prsstart, ...));

    do {
        // 逐个获取 token（对 zhparser 而言是 zhprs_get_token）
        type = DatumGetInt32(FunctionCall3(&(prsobj->prstoken), ...));

        // 字典链处理（LexizeExec）
        LexizeAddLemm(&ldata, type, lemm, lenlemm);
        while ((norms = LexizeExec(&ldata, NULL)) != NULL) {
            // 将规范化后的 lexeme 存入 prs->words[]
            ...
        }
    } while (type > 0);

    // 清理 parser（zhprs_end）
    FunctionCall1(&(prsobj->prsend), PointerGetDatum(prsdata));
}

对于 zhparser 配置，prsobj->prstoken 指向 zhparser 的 zhprs_get_token 函数。这个函数内部调用 scws 分词引擎，并实时读取当前 session 的 multi_short GUC 值来决定分词粒度。

索引创建时 session 的 multi_short=off，所以 zhprs_get_token 返回复合词。分词结果通过 gin_extract_tsvector 提取为 GIN entries：

// src/backend/utils/adt/tsginidx.c 
Datum gin_extract_tsvector(PG_FUNCTION_ARGS)
{
    TSVector vector = PG_GETARG_TSVECTOR(0);
    WordEntry *we = ARRPTR(vector);

    for (i = 0; i < vector->size; i++) {
        // 提取每个 lexeme 的原始文本字符串（非哈希值）
        txt = cstring_to_text_with_len(STRPTR(vector) + we->pos, we->len);
        entries[i] = PointerGetDatum(txt);
        we++;
    }
}

4.2 查询路径：plainto_tsquery → pushval_morph → parsetext

查询时调用 plainto_tsquery('chinese', '华联科技智能终端')，入口是 plainto_tsquery_byid：

// src/backend/tsearch/to_tsany.c 
Datum plainto_tsquery_byid(PG_FUNCTION_ARGS)
{
    MorphOpaque data;
    data.cfg_id = PG_GETARG_OID(0);
    data.qoperator = OP_AND;  // 所有词条用 AND 连接

    query = parse_tsquery(text_to_cstring(in),
pushval_morph,       // 分词回调
                          PointerGetDatum(&data),
                          P_TSQ_PLAIN,    // 将整个输入作为单个 morph
                          NULL);
}

parse_tsquery 以 P_TSQ_PLAIN 模式运行，选择 gettoken_query_plain 作为 tokenizer，将整个输入文本交给 pushval_morph 回调处理。

pushval_morph 内部再次调用 parsetext()——是的，和索引创建走的是同一个分词管线：

// src/backend/tsearch/to_tsany.c 
static void pushval_morph(Datum opaque, TSQueryParserState state,
                          char *strval, int lenval, ...)
{
    ParsedText prs;
    MorphOpaque *data = (MorphOpaque *) DatumGetPointer(opaque);

parsetext(data->cfg_id, &prs, strval, lenval);

    // 三层嵌套 while 循环构建 tsquery：
    //   外层：不同 position 的词条，用 data->qoperator (OP_AND) 连接
    //   中层：同一 position 的不同 variant，用 OP_OR 连接
    //   内层：同一 variant 的多个 word，用 OP_AND 连接
    while (count < prs.curwords) {
        ...
        pushValue(state, prs.words[count].word, ...);
        pushOperator(state, OP_AND, 0);
        ...
    }
}

此时 session 的 multi_short=on，parsetext → zhprs_get_token 返回短词。最终生成的 tsquery 为：

华联 & 科技 & 智能终端 & 智能 & 终端

4.3 关键发现：两次 parsetext 调用，同一个函数，不同的 GUC 值

调用时机	函数调用链	session multi_short	分词结果
索引创建	to_tsvector_byid → parsetext → zhprs_get_token	off	华联, 科技, 智能终端
查询生成	plainto_tsquery_byid → pushval_morph → parsetext → zhprs_get_token	on	华联, 科技, 智能终端, 智能, 终端

两次调用走的是完全相同的 parsetext 函数，唯一的区别是 zhprs_get_token 在每次被调用时读到的 multi_short GUC 值不同。

PostgreSQL 内核的盲区：parsetext 通过函数指针 prsobj->prstoken 调用 parser 扩展的回调，内核只知道"调了一个函数拿 token"，完全不感知也无法校验扩展内部依赖了哪些 GUC、这些 GUC 是否在索引创建和查询之间发生了变化。

· · ·

五、GIN 匹配机制：为什么精确匹配会全盘失败

5.1 GIN 查询 entries 提取

查询执行时，GIN 引擎通过 gin_extract_tsquery 从 tsquery 中提取所有 QI_VAL 项作为搜索 entries。该函数采用两遍遍历：第一遍统计词条数量，第二遍通过 GETOPERAND(query) + val->distance 和 val->length 从 tsquery 的 operand 区域提取原始文本（不是 CRC 哈希值）：

// src/backend/utils/adt/tsginidx.c 
// 第二遍：提取每个 QI_VAL 的原始文本
for (i = 0; i < query->size; i++) {
    if (item[i].type == QI_VAL) {
        QueryOperand *val = &item[i].qoperand;
        txt = cstring_to_text_with_len(
            GETOPERAND(query) + val->distance, val->length);
        entries[j] = PointerGetDatum(txt);
        j++;
    }
}

提取出 5 个 entries：[华联, 科技, 智能终端, 智能, 终端]。

5.2 GIN 一致性检查：三元逻辑评估

GIN 引擎在索引中逐个查找这 5 个 entries 是否存在。索引中存储的 entries（multi_short=off 时写入）为 {华联, 科技, 智能终端}。精确匹配结果：

GIN_TRUE（索引中存在）

然后 gin_tsquery_consistent 调用 TS_execute_ternary 评估整个 AND 表达式。TS_execute_recurse 对 OP_AND 操作符的处理逻辑是：先评估左子树，如果结果为 TS_NO，立即短路返回 TS_NO，不再评估右子树。

// src/backend/utils/adt/tsvector_op.c 
case OP_AND:
    lmatch = TS_execute_recurse(curitem + curitem->qoperator.left, ...);
    if (lmatch == TS_NO)
        return TS_NO;    // 短路！左子为 NO，整个 AND 为 NO
    // 否则继续评估右子...

5 个词条中，2 个返回 GIN_FALSE（智能、终端），AND 短路机制立即触发，整个表达式返回 TS_NO。2 个词条不匹配，AND 全盘失败，GIN 索引返回 0 行。

5.3 Seq Scan 的匹配为什么成功

Seq Scan 路径通过 ts_match_vq 执行匹配，使用的是 checkcondition_str 回调（而非 GIN 的 checkcondition_gin）。checkcondition_str 在 tsvector 中通过二分搜索查找 lexeme，原理与 GIN 的 check 数组查找完全不同。

但关键不在于二分搜索 vs check 数组——两者都是精确匹配。关键在于：Seq Scan 时 to_tsvector 实时分词使用的 multi_short=on，与生成 tsquery 时的 multi_short=on 一致，所以 tsvector 中的词条和 tsquery 中的词条完全相同，精确匹配自然成功。

Seq Scan 时的实时分词：
  to_tsvector('chinese', product_name)  → multi_short=on → {华联, 科技, 智能终端, 智能, 终端}
  plainto_tsquery('chinese', '华联科技智能终端') → multi_short=on → 华联 & 科技 & 智能终端 & 智能 & 终端
  两侧词条完全一致 → 精确匹配成功 → 正确命中 ✓

对比总结：GIN 索引中存储的是 multi_short=off 的分词结果（3 个词条），查询时生成的是 multi_short=on 的分词结果（5 个词条），分词结果不一致导致精确匹配失败。Seq Scan 因为实时分词，两侧都用 multi_short=on，自然匹配。问题的本质不是 GIN 的匹配机制有缺陷，而是索引内容和查询内容分属两套分词结果。

· · ·

六、解决方案：三条修复路径

方案 A：统一为 off（无需重建索引，快速恢复）

如果不需要短词搜索粒度，最快的方式是将所有 session 的 multi_short 统一为 off，与索引创建时一致：

-- 数据库级别固化参数（所有新 session 默认 off）
ALTER DATABASE your_db SET zhparser.multi_short = off;

-- 重新连接后验证
SHOW zhparser.multi_short;  -- 预期：off

将 multi_short 切回 off 后，同样的查询立刻恢复正常——GIN 索引命中 61172 行：

test=> SET zhparser.multi_short TO off;
SET

test=> EXPLAIN (ANALYZE, BUFFERS)
SELECT * FROM demo_product_catalog
WHERE to_tsvector('chinese', product_name)
    @@ plainto_tsquery('chinese', '华联科技智能终端');

 Bitmap Heap Scan on demo_product_catalog  (cost=371.07..15026.91 rows=49127 width=62)
                                           (actual time=10.655..19.097 rows=61172 loops=1)
   Recheck Cond: (to_tsvector('chinese'::regconfig, product_name::text)
       @@ '''华联'' & ''科技'' & ''智能终端'''::tsquery)
   Heap Blocks: exact=1760
   Buffers: shared hit=1837
   ->  Bitmap Index Scan on idx_demo_product_catalog_name
         (cost=0.00..358.79 rows=49127 width=0) (actual time=10.454..10.454 rows=61172 loops=1)
         Index Cond: (to_tsvector('chinese'::regconfig, product_name::text)
             @@ '''华联'' & ''科技'' & ''智能终端'''::tsquery)
         Index Searches: 1
         Buffers: shared hit=77
 Execution Time: 21.061 ms

注意 Recheck Cond 中的 tsquery 变成了 '''华联'' & ''科技'' & ''智能终端'''——只有 3 个词条，与索引创建时 multi_short=off 的分词结果完全一致。分词参数统一后，GIN 精确匹配立即恢复。

优点：零停机，无需重建索引，立即生效。代价：无法单独用短词（如 智能、终端）搜索，因为索引中没有这些短词 entries。

方案 B：统一为 on 并 REINDEX（支持短词搜索）

如果业务需要细粒度搜索能力（如单独搜 终端），则统一为 on 并重建索引：

-- 数据库级别固化参数
ALTER DATABASE your_db SET zhparser.multi_short = on;

-- 重新连接后在 multi_short=on 状态下重建索引
REINDEX INDEX CONCURRENTLY idx_demo_product_catalog_name;

REINDEX 过程中同样会触发并行 WARNING（因为 CONCURRENTLY 内部使用了并行 worker），但 REINDEX 仍能正常完成：

test=> SET zhparser.multi_short TO on;
SET

test=> REINDEX INDEX CONCURRENTLY idx_demo_product_catalog_name;
WARNING:  parameter "zhparser.multi_short" cannot be set during a parallel operation
REINDEX

REINDEX 完成后，同样的查询恢复正常——GIN 索引命中 28841 行：

test=> EXPLAIN (ANALYZE, BUFFERS)
SELECT * FROM demo_product_catalog
WHERE to_tsvector('chinese', product_name)
    @@ plainto_tsquery('chinese', '华联科技智能终端');

 Bitmap Heap Scan on demo_product_catalog  (cost=68.97..73.23 rows=1 width=62)
                                           (actual time=8.142..12.114 rows=28841 loops=1)
   Recheck Cond: (to_tsvector('chinese'::regconfig, product_name::text)
       @@ '''华联'' & ''科技'' & ''智能终端'' & ''智能'' & ''终端'''::tsquery)
   Heap Blocks: exact=830
   Buffers: shared hit=941
   ->  Bitmap Index Scan on idx_demo_product_catalog_name
         (cost=0.00..68.97 rows=1 width=0) (actual time=8.046..8.047 rows=28841 loops=1)
         Index Cond: (to_tsvector('chinese'::regconfig, product_name::text)
             @@ '''华联'' & ''科技'' & ''智能终端'' & ''智能'' & ''终端'''::tsquery)
         Index Searches: 1
         Buffers: shared hit=111
 Execution Time: 13.062 ms

注意 tsquery 仍然是 5 个词条（multi_short=on），但 REINDEX 后索引中也存储了这 5 个短词 entries，分词参数统一后，GIN 精确匹配恢复。现在短词搜索也可正常工作。

-- 短词搜索现在也可用
SELECT * FROM demo_product_catalog
WHERE to_tsvector('chinese', product_name)
    @@ plainto_tsquery('chinese', '终端');

优点：支持短词搜索，搜索粒度更细。代价：索引体积更大（更多 entries），REINDEX 期间有额外开销（CONCURRENTLY 可避免阻塞写入）。

最佳实践：参数全局固化

最稳妥的做法是在 postgresql.conf 中全局固定参数，或者database级配置，彻底杜绝 session 级修改的可能性：

# postgresql.conf
zhparser.multi_short = off   # 或 on，但必须全局固定且不可被 session 覆盖

核心原则：全文搜索索引的分词参数必须在索引创建时和所有查询时保持完全一致。任何影响分词结果的参数（zhparser 的 multi_short、multi_duality、multi_zmain、multi_padd 等）都必须全局固定。从源码角度看，这确保了 parsetext 在不同调用时机读到相同的 GUC 值，从而产生一致的分词结果。

· · ·

七、核心启示：PostgreSQL 信任模型的边界

7.1 这不是 Bug，是架构边界的代价

PostgreSQL 的全文搜索架构有一个隐含契约：同一份文本搜索配置对相同输入必须产生确定性的分词结果。这个契约是索引有效性的前提——索引创建时的分词结果必须与查询时的分词结果一致，否则精确匹配必然失败。

zhparser 的 multi_short 参数以 PGC_USERSET（session 级可设）的方式注册，允许用户在任意时刻切换分词粒度。这直接打破了上述契约。而 PostgreSQL 内核通过函数指针调用 parser 回调，无法感知也无法校验扩展内部依赖了哪些 GUC、这些 GUC 是否在索引创建和查询之间发生了变化。

这不是 PostgreSQL 的 Bug——parser 扩展接口的设计就是让内核与扩展解耦。也不是 zhparser 的 Bug——它正确实现了 multi_short 参数的功能。问题出在使用层面：在创建索引和查询时使用了不同的 multi_short 值，导致分词结果不一致。

7.2 "静默失效"才是最危险的

这个问题最让人后怕的地方在于：没有任何报错。索引在用，执行计划看起来正常，查询不抛异常，只是返回 0 行。如果不是用户偶然关掉 bitmapscan 做对比，可能永远发现不了——只会觉得"这些商品搜不到"。

更隐蔽的是，如果查询恰好命中了索引中存在的词条（比如只用 智能终端 这个复合词搜索），索引会正常工作，给人"一切正常"的错觉。只有当查询包含索引中不存在的短词时，AND 短路机制才会让整个查询返回 0 行。

7.3 那条 WARNING 的诊断价值

回到文章开头那条 WARNING：

WARNING:  parameter "zhparser.multi_short" cannot be set during a parallel operation

这条 WARNING 本身不影响查询正确性——并行 worker 仍然使用 leader 传递的 GUC 值。但它是一个有用的信号：它告诉你当前 session 修改了一个影响分词行为的 GUC 参数。如果你在日志中看到这条 WARNING，应该立即检查：索引创建时的 multi_short 值与当前 session 是否一致？

7.4 通用教训

这个案例的教训不只适用于 zhparser。任何 PostgreSQL parser 扩展，只要注册了影响分词结果的自定义 GUC 参数，都存在同样的风险：

索引创建和查询使用不同的参数值 → 分词结果不一致 → GIN 精确匹配失败 → 静默返回 0 行。

排查方法也很直接：

-- 对比索引创建时和查询时的分词结果
SET zhparser.multi_short = off;
SELECT * FROM to_tsvector('chinese', '华联科技智能终端');

SET zhparser.multi_short = on;
SELECT * FROM to_tsvector('chinese', '华联科技智能终端');

-- 如果两次结果不同，且你的 GIN 索引在 off 下创建、on 下查询，
-- 那就是问题所在。