PostgreSQL中ts_headline高亮非查询匹配部分是特性还是Bug？

结论 #

这是PostgreSQL ts_headline函数的既定设计特性，不属于Bug，也不是调用方式错误，问题核心是官方文档描述存在歧义，导致对函数行为的预期和实际实现有偏差。

底层逻辑说明 #

ts_headline的底层实现没有预先校验整个tsquery的组合逻辑（AND、FOLLOWED_BY等运算符的全局匹配结果）的步骤，它只会拆解tsquery中所有独立词素，只要文本中存在对应词素就会高亮，完全不考虑多个词素之间的逻辑关系是否满足匹配要求。
这对应官方文档里更准确的描述：「返回文档中查询相关术语被高亮的摘录」，这里的「相关术语」就是指query拆解后的单个词素，而非满足整个query匹配条件的片段。

对应两个测试场景的具体原因 #

• 第一个场景中，plainto_tsquery('english', 'red dog')拆解后得到red和dog两个词素，即使整个query和文本的匹配结果为false，只要文本中出现了dog就会被高亮。
• 第二个使用短语查询的场景中，phraseto_tsquery生成的'red' <-> 'dog'拆解后依然是red和dog两个独立词素，所以不管二者是否相邻、是否满足紧随关系，只要单独出现就会被高亮，这就是单独的red、不相邻的dog也被标亮的原因。

正确使用方案 #

ts_headline的设计定位就是和全文匹配运算符@@配合使用的，需要先通过@@过滤出真正满足整个tsquery匹配条件的文档，再对这些文档调用ts_headline做高亮，就不会出现不符合预期的高亮结果。
如果需要在单次查询中同时完成匹配校验和高亮，可以参考以下写法：

-- 示例：只对满足短语匹配条件的内容做高亮
SELECT 
  CASE
    WHEN to_tsvector('english', content) @@ phraseto_tsquery('english', 'red dog')
    THEN ts_headline('english', content, phraseto_tsquery('english', 'red dog'), 'StartSel=<b>, StopSel=</b>')
    ELSE content
  END AS highlighted_content
FROM (
  VALUES ('I want a red dog, but not a black dog.  No red cats, either.')
) AS t(content);

补充说明 #

目前PostgreSQL 13及之后的所有稳定版本都保持该行为，社区多次收到类似的反馈，官方目前的结论是属于文档描述不够清晰的问题，尚未计划修改ts_headline的默认行为，后续可能会新增可选参数支持按全局query匹配逻辑来高亮片段。

内容的提问来源于stack exchange，提问作者ryanhkerr