ParadeDB全文检索查询结果缺失评分字段问题分析

在ParadeDB 0.15.5版本中，用户在使用BM25索引进行全文检索时遇到了一个典型问题：查询结果中缺少评分(score)字段。本文将深入分析该问题的成因、技术背景以及解决方案。

问题现象

用户在使用如下SQL查询时：

SELECT ms1.id, ms1.name, paradedb.score(ms1.id) 
FROM mcp_server ms1
WHERE ms1.synced_at IS NOT NULL
  AND ms1.removed_at IS NULL
  AND ms1.id @@@ '{
      "boolean": {
        "should": [
          {"boost": {"factor": 2, "query": {"fuzzy_term": {"field": "name", "value": "example"}}}},
          {"boost": {"factor": 1, "query": {"fuzzy_term": {"field": "description", "value": "example"}}}}
        ]
      }
    }'::jsonb
ORDER BY paradedb.score(ms1.id) DESC;

查询结果中的score列显示为空值，而预期应该返回每个匹配文档的相关性评分。

技术背景

ParadeDB是基于PostgreSQL的全文搜索引擎扩展，它通过BM25算法提供高效的文本搜索能力。在实现上，它使用了Tantivy作为底层搜索引擎，并通过PostgreSQL的扩展机制提供SQL接口。

评分功能是全文检索的核心特性之一，它表示查询与文档的匹配程度。在ParadeDB中，评分通过paradedb.score()函数获取，该函数需要与@@@操作符配合使用。

问题根源

经过开发团队分析，该问题源于ParadeDB的自定义扫描(Custom Scan)和谓词下推(Predicate Pushdown)功能在处理特定查询条件时的不足。具体表现为：

1. 当查询中包含IS NOT NULL和IS NULL条件时，早期版本(0.15.5及之前)的谓词下推逻辑无法正确处理这些条件
2. 这导致查询计划没有使用ParadeDB的Custom Scan执行路径，而是回退到普通的索引扫描
3. 普通索引扫描无法获取评分信息，因此paradedb.score()函数返回空值

解决方案

该问题已在ParadeDB 0.15.7版本中通过PR #2262得到部分解决，该PR改进了谓词下推对IS [NOT] NULL条件的支持。但用户反馈0.15.7版本仍未完全解决问题。

进一步的修复工作发现，这实际上是自定义扫描处理JOIN操作时的普遍性问题，与另一个issue(#2308)有相同的根本原因。开发团队正在优化Custom Scan的实现，确保在各种查询条件下都能正确返回评分信息。

验证方法

用户可以通过EXPLAIN VERBOSE命令验证查询是否使用了Custom Scan执行路径。正确的执行计划应包含类似以下内容：

Custom Scan (ParadeDB Scan) on public.mcp_server ms1
  Output: id, name, paradedb.score(id)
  Scores: true

最佳实践建议

1. 确保使用最新版本的ParadeDB(建议0.15.7或更高)
2. 对于复杂查询条件，先验证执行计划是否使用了Custom Scan
3. 如果必须使用IS NULL/IS NOT NULL条件，考虑将其放在查询的最后部分
4. 对于关键业务场景，建议在应用层添加对评分空值的检查和处理

总结

全文检索评分缺失问题展示了数据库扩展开发中查询优化器集成的复杂性。ParadeDB团队正在持续改进其自定义扫描实现，以提供更稳定和全面的功能支持。用户遇到类似问题时，建议检查执行计划并考虑升级到最新版本。