Lucene多查询组合下匹配文档出现次数统计异常问题

我来帮你捋清楚这个问题——你遇到的scorer.freq()返回2而不是实际1次的情况，本质是Lucene的BooleanQuery对应的Scorer，其freq()方法返回的是当前文档匹配的子查询数量，而非单个PhraseQuery的短语出现次数。

为什么会返回2？ #

当你把PhraseQuery、文件后缀查询、PrefixQuery组合成BooleanQuery后，Lucene会使用BooleanScorer来处理这个组合查询。此时scorer.freq()的含义变成了：当前文档命中了几个子查询。比如你的示例Doc1，同时匹配了PhraseQuery（"Roman General"）和文件后缀查询，所以freq()返回2，这和短语实际出现次数无关。而当你单独用PhraseQuery时，Scorer是PhraseScorer，它的freq()才会返回短语在文档中的实际出现次数。

如何正确统计短语的出现次数？ #

要获取特定PhraseQuery的实际匹配次数，你需要绕过BooleanScorer的统计，直接针对目标短语查询进行计数。这里有两种可靠的方案：

方案1：使用TermPositionVector统计短语位置

通过读取文档的TermPositionVector，手动检查两个连续term的位置关系，来统计短语出现次数：

@Override
public void collect(int doc) throws IOException {
    int absoluteDocId = DOCID + doc;
    Document document = searcher.doc(absoluteDocId);
    String filePath = document.get(Constants.INDEX_FIELD_FILE_PATH);
    
    // 获取内容字段的Term字典
    Terms contentTerms = context.reader().terms(Constants.INDEX_FIELD_CONTENT);
    if (contentTerms == null) {
        result.put(filePath, 0);
        return;
    }

    TermsEnum termsEnum = contentTerms.iterator();
    int phraseCount = 0;

    // 先定位第一个term（注意匹配分析器的大小写处理，比如如果你的分析器转小写，这里用"roman"）
    if (termsEnum.seekExact(new BytesRef("roman"))) {
        PostingsEnum romanPostings = termsEnum.postings(null, PostingsEnum.POSITIONS);
        if (romanPostings.advance(doc) == doc) {
            int[] romanPositions = romanPostings.getPositions();
            
            // 定位第二个term
            termsEnum.seekExact(new BytesRef("general"));
            PostingsEnum generalPostings = termsEnum.postings(null, PostingsEnum.POSITIONS);
            if (generalPostings.advance(doc) == doc) {
                int[] generalPositions = generalPostings.getPositions();
                
                // 统计两个term连续出现的次数（即短语"Roman General"）
                int i = 0, j = 0;
                while (i < romanPositions.length && j < generalPositions.length) {
                    if (romanPositions[i] + 1 == generalPositions[j]) {
                        phraseCount++;
                        i++;
                        j++;
                    } else if (romanPositions[i] < generalPositions[j]) {
                        i++;
                    } else {
                        j++;
                    }
                }
            }
        }
    }

    result.put(filePath, phraseCount);
}

方案2：用IndexSearcher.explain()解析短语匹配细节

通过explain()方法获取PhraseQuery的匹配解释，从中提取短语出现次数：

// 注意：需要在外部保留PhraseQuery的引用，比如作为Collector的成员变量
private final PhraseQuery phraseQuery;

public SearchTermFrequencyCollector(IndexSearcher searcher, PhraseQuery phraseQuery) {
    this.searcher = searcher;
    this.phraseQuery = phraseQuery;
}

@Override
public void collect(int doc) throws IOException {
    int absoluteDocId = DOCID + doc;
    Document document = searcher.doc(absoluteDocId);
    String filePath = document.get(Constants.INDEX_FIELD_FILE_PATH);
    
    // 获取PhraseQuery的匹配解释
    Explanation explanation = searcher.explain(phraseQuery, absoluteDocId);
    int phraseCount = extractPhraseFrequency(explanation);
    
    result.put(filePath, phraseCount);
}

// 递归解析Explanation，提取短语出现次数
private int extractPhraseFrequency(Explanation exp) {
    // 匹配PhraseQuery的解释描述，比如"phrase freq=1"
    String desc = exp.getDescription();
    if (desc.contains("phrase freq=")) {
        int startIdx = desc.indexOf("freq=") + 5;
        int endIdx = desc.indexOf(" ", startIdx);
        if (endIdx == -1) endIdx = desc.length();
        return Integer.parseInt(desc.substring(startIdx, endIdx));
    }
    
    // 递归检查子解释
    for (Explanation childExp : exp.getDetails()) {
        int count = extractPhraseFrequency(childExp);
        if (count > 0) {
            return count;
        }
    }
    return 0;
}

关键提醒 #

Lucene中不同Query类型的Scorer，freq()方法的语义是不同的：

• PhraseQuery/TermQuery：返回term/短语在文档中的实际出现次数
• BooleanQuery：返回文档匹配的子查询数量
• PrefixQuery：返回匹配的前缀term数量

所以组合查询时，不能直接用顶层BooleanQuery的Scorer来统计单个子查询的匹配次数，必须单独针对目标查询进行处理。

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