如何获取Lucene中单个文档的PhraseQuery匹配总数？

我明白你现在的需求——已经能拿到PhraseQuery返回的文档得分，但想知道每个文档里这个短语到底匹配了多少次。确实，Lucene默认的得分机制（基于TF-IDF、词项位置等）不会直接暴露这个计数，不过我们有两种可靠的方法来实现它：

方法一：使用SpanPhraseQuery + SpanCollector（推荐） #

Lucene的SpanQuery体系专门用于处理位置相关的查询，其中SpanPhraseQuery和普通PhraseQuery的匹配逻辑完全一致，但它支持通过SpanCollector来遍历每个文档中的所有匹配实例，从而轻松统计次数。

代码示例 #

首先把你的PhraseQuery转换成SpanPhraseQuery，然后用自定义SpanCollector收集匹配次数：

// 先获取你原来的PhraseQuery的核心参数
PhraseQuery originalQuery = builder.build();
Term[] terms = originalQuery.getTerms();
int slop = originalQuery.getSlop();

// 转换为SpanTermQuery数组，用来构建SpanPhraseQuery
SpanTermQuery[] spanTermQueries = new SpanTermQuery[terms.length];
for (int i = 0; i < terms.length; i++) {
    spanTermQueries[i] = new SpanTermQuery(terms[i]);
}
SpanPhraseQuery spanPhraseQuery = new SpanPhraseQuery(slop, spanTermQueries);

// 用Map存储每个文档ID对应的匹配次数
Map<Integer, Integer> docMatchCountMap = new HashMap<>();

// 执行查询并收集匹配次数
searcher.search(spanPhraseQuery, new SpanCollector() {
    @Override
    public void collectLeaf(LeafReaderContext context, int doc, SpanCollectorDelegate delegate) throws IOException {
        int matchCount = 0;
        // 遍历当前文档的所有匹配Span
        while (delegate.nextSpan()) {
            matchCount++;
        }
        // 转换为全局文档ID
        int globalDocId = context.docBase + doc;
        docMatchCountMap.put(globalDocId, matchCount);
    }
});

// 输出结果
for (Map.Entry<Integer, Integer> entry : docMatchCountMap.entrySet()) {
    System.out.printf("文档ID: %d, 短语匹配次数: %d%n", entry.getKey(), entry.getValue());
}

这种方法的优势是完全复用Lucene内部的短语匹配逻辑，不会因为自己实现位置判断而出现错误，代码也更简洁。

方法二：手动遍历词项位置（适合理解底层逻辑） #

如果你想深入了解匹配过程，可以手动获取每个文档中词项的位置列表，然后自己统计符合slop条件的短语组合。

代码示例 #

private static int countPhraseMatches(IndexReader reader, int docId, PhraseQuery query) throws IOException {
    Term[] terms = query.getTerms();
    int slop = query.getSlop();
    String field = terms[0].field();

    // 收集每个词项在文档中的位置列表
    List<List<Integer>> termPositions = new ArrayList<>();
    for (Term term : terms) {
        PostingsEnum postings = reader.postings(term, PostingsEnum.POSITIONS);
        if (postings == null || postings.advance(docId) != docId) {
            // 文档中缺少任意一个词项，直接返回0
            return 0;
        }
        List<Integer> positions = new ArrayList<>();
        int freq = postings.freq();
        for (int i = 0; i < freq; i++) {
            positions.add(postings.nextPosition());
        }
        termPositions.add(positions);
    }

    // 统计符合条件的短语组合（这里以3个词项的情况为例，可扩展到任意长度）
    int matchCount = 0;
    List<Integer> posList1 = termPositions.get(0);
    List<Integer> posList2 = termPositions.get(1);
    List<Integer> posList3 = termPositions.get(2);

    for (int pos1 : posList1) {
        for (int pos2 : posList2) {
            for (int pos3 : posList3) {
                // 计算实际位置与目标相对位置的总偏差（符合Lucene的slop规则）
                int targetDiff1 = 1; // 你的短语中word2相对word1的位置差是1
                int targetDiff2 = 1; // word3相对word2的位置差是1
                int actualDiff1 = Math.abs((pos2 - pos1) - targetDiff1);
                int actualDiff2 = Math.abs((pos3 - pos2) - targetDiff2);
                // 处理词项顺序颠倒的情况（slop允许相邻交换，交换一次需消耗2个slop）
                int totalSlopNeeded = actualDiff1 + actualDiff2;
                if (pos3 < pos2) totalSlopNeeded += 2;
                if (pos2 < pos1) totalSlopNeeded += 2;
                
                if (totalSlopNeeded <= slop) {
                    matchCount++;
                }
            }
        }
    }
    return matchCount;
}

// 使用方式
PhraseQuery query = builder.build();
TopDocs topDocs = searcher.search(query, 10);
for (ScoreDoc scoreDoc : topDocs.scoreDocs) {
    int count = countPhraseMatches(indexReader, scoreDoc.doc, query);
    System.out.printf("文档ID: %d, 匹配次数: %d%n", scoreDoc.doc, count);
}

这种方法适合学习Lucene的短语匹配原理，但需要自己处理slop的复杂规则，容易出错，所以更推荐第一种方法。

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