org.apache.lucene.search.Explanation Java Examples

@Override
public Explanation explain(LeafReaderContext context, int doc) throws IOException {
  SortedDocValues values = DocValues.getSorted(context.reader(), joinField);
  if (values == null) {
    return Explanation.noMatch("Not a match");
  }
  if (values.advance(doc) != doc) {
    return Explanation.noMatch("Not a match");
  }

  int segmentOrd = values.ordValue();
  BytesRef joinValue = values.lookupOrd(segmentOrd);

  int ord;
  if (globalOrds != null) {
    ord = (int) globalOrds.getGlobalOrds(context.ord).get(segmentOrd);
  } else {
    ord = segmentOrd;
  }
  if (collector.match(ord) == false) {
    return Explanation.noMatch("Not a match, join value " + Term.toString(joinValue));
  }

  float score = collector.score(ord);
  return Explanation.match(score, "A match, join value " + Term.toString(joinValue));
}
 

@Override
public Explanation explain(LeafReaderContext context, int doc) throws IOException {
  SortedDocValues values = DocValues.getSorted(context.reader(), joinField);
  if (values == null) {
    return Explanation.noMatch("Not a match");
  }

  if (values.advance(doc) != doc) {
    return Explanation.noMatch("Not a match");
  }
  int segmentOrd = values.ordValue();
  BytesRef joinValue = values.lookupOrd(segmentOrd);

  int ord;
  if (globalOrds != null) {
    ord = (int) globalOrds.getGlobalOrds(context.ord).get(segmentOrd);
  } else {
    ord = segmentOrd;
  }
  if (foundOrds.get(ord) == false) {
    return Explanation.noMatch("Not a match, join value " + Term.toString(joinValue));
  }

  return Explanation.match(score(), "A match, join value " + Term.toString(joinValue));
}
 

/** Render an explanation as HTML. */
public static String toHtml(Explanation explanation) {
  StringBuilder buffer = new StringBuilder();
  buffer.append("<ul>\n");

  buffer.append("<li>");
  buffer.append(explanation.getValue()).append(" = ").append(explanation.getDescription());
  buffer.append("<br />\n");

  Explanation[] details = explanation.getDetails();
  for (int i = 0 ; i < details.length; i++) {
    buffer.append(toHtml(details[i]));
  }

  buffer.append("</li>\n");
  buffer.append("</ul>\n");

  return buffer.toString();
}
 

public void testScoreModifyingSource() throws Exception {

    BooleanQuery bq = new BooleanQuery.Builder()
        .add(new TermQuery(new Term(TEXT_FIELD, "first")), BooleanClause.Occur.SHOULD)
        .add(new TermQuery(new Term(TEXT_FIELD, "text")), BooleanClause.Occur.SHOULD)
        .build();
    TopDocs plain = searcher.search(bq, 1);

    FunctionScoreQuery fq = FunctionScoreQuery.boostByValue(bq, DoubleValuesSource.fromIntField("iii"));

    QueryUtils.check(random(), fq, searcher, rarely());

    int[] expectedDocs = new int[]{ 4, 7, 9, 8, 12 };
    TopDocs docs = searcher.search(fq, 5);
    assertEquals(plain.totalHits.value, docs.totalHits.value);
    for (int i = 0; i < expectedDocs.length; i++) {
      assertEquals(expectedDocs[i], docs.scoreDocs[i].doc);
    }

    Explanation expl = searcher.explain(fq, 4);
    assertTrue(expl.toString().contains("first"));
    assertTrue(expl.toString().contains("iii"));

  }
 

@Override
public Explanation explain(LeafReaderContext context, int doc) throws IOException {
    Explanation subQueryExpl = subQueryWeight.explain(context, doc);
    if (!subQueryExpl.isMatch()) {
        return subQueryExpl;
    }
    Explanation expl;
    if (function != null) {
        Explanation functionExplanation = function.getLeafScoreFunction(context).explainScore(doc, subQueryExpl);
        expl = combineFunction.explain(subQueryExpl, functionExplanation, maxBoost);
    } else {
        expl = subQueryExpl;
    }
    if (minScore != null && minScore > expl.getValue()) {
        expl = Explanation.noMatch("Score value is too low, expected at least " + minScore + " but got " + expl.getValue(), expl);
    }
    return expl;
}
 

@Test
public void testCustom() throws Exception {

  final LTRScoringModel model = createModelFromFiles("neuralnetworkmodel_custom.json",
      "neuralnetworkmodel_features.json");

  final float featureValue1 = 4f;
  final float featureValue2 = 2f;
  final float[] featureValues = { featureValue1, featureValue2 };

  final double expectedScore = (featureValue1+featureValue2) * 42f;
  float actualScore = model.score(featureValues);
  assertEquals(expectedScore, actualScore, 0.001);

  final List<Explanation> explanations = new ArrayList<Explanation>();
  for (int ii=0; ii<featureValues.length; ++ii)
  {
    explanations.add(Explanation.match(featureValues[ii], ""));
  }
  final Explanation explanation = model.explain(null, 0, actualScore, explanations);
  assertEquals(actualScore+" = (name=neuralnetworkmodel_custom"+
      ",featureValues=[constantFour=4.0,constantTwo=2.0]"+
      ",layers=[(matrix=1x2,activation=answer)]"+
      ")\n",
      explanation.toString());
}
 

private Explanation explainScore(Explanation freq, long encodedNorm, float[] normTable) {
  List<Explanation> subs = new ArrayList<Explanation>();
  if (boost != 1F) {
    subs.add(Explanation.match(boost, "boost"));
  }
  subs.add(idf);
  Explanation tf = Explanation.match(tf(freq.getValue().floatValue()), "tf(freq="+freq.getValue()+"), with freq of:", freq);
  subs.add(tf);

  float norm = normTable[(int) (encodedNorm & 0xFF)];
  
  Explanation fieldNorm = Explanation.match(norm, "fieldNorm");
  subs.add(fieldNorm);
  
  return Explanation.match(
      queryWeight * tf.getValue().floatValue() * norm,
      "score(freq="+freq.getValue()+"), product of:",
      subs);
}
 

public Explanation explain(LeafReaderContext context, Weight childWeight) throws IOException {
  int prevParentDoc = parentBits.prevSetBit(parentApproximation.docID() - 1);
  int start = context.docBase + prevParentDoc + 1; // +1 b/c prevParentDoc is previous parent doc
  int end = context.docBase + parentApproximation.docID() - 1; // -1 b/c parentDoc is parent doc

  Explanation bestChild = null;
  int matches = 0;
  for (int childDoc = start; childDoc <= end; childDoc++) {
    Explanation child = childWeight.explain(context, childDoc - context.docBase);
    if (child.isMatch()) {
      matches++;
      if (bestChild == null || child.getValue().floatValue() > bestChild.getValue().floatValue()) {
        bestChild = child;
      }
    }
  }

  return Explanation.match(score(), String.format(Locale.ROOT,
      "Score based on %d child docs in range from %d to %d, best match:", matches, start, end), bestChild
  );
}
 

@Override
public Explanation explain(BasicStats stats, double tfn, double aeTimes1pTfn) {
  double F = stats.getTotalTermFreq();
  double N = stats.getNumberOfDocuments();
  double ne = N * (1 - Math.pow((N - 1) / N, F));
  Explanation explNe = Explanation.match((float) ne,
      "ne, computed as N * (1 - Math.pow((N - 1) / N, F)) from:",
      Explanation.match((float) F,
          "F, total number of occurrences of term across all docs"),
      Explanation.match((float) N,
          "N, total number of documents with field"));

  return Explanation.match(
      (float) (score(stats, tfn, aeTimes1pTfn) * (1 + tfn) / aeTimes1pTfn),
      getClass().getSimpleName() + ", computed as " +
          "tfn * log2((N + 1) / (ne + 0.5)) from:",
      Explanation.match((float) tfn, "tfn, normalized term frequency"),
      explNe);
}
 

@Override
public Explanation explain(LeafReaderContext context, int doc) throws IOException {
  ToChildBlockJoinScorer scorer = (ToChildBlockJoinScorer) scorer(context);
  if (scorer != null && scorer.iterator().advance(doc) == doc) {
    int parentDoc = scorer.getParentDoc();
    return Explanation.match(
      scorer.score(), 
      String.format(Locale.ROOT, "Score based on parent document %d", parentDoc + context.docBase), 
      in.explain(context, parentDoc)
    );
  }
  return Explanation.noMatch("Not a match");
}
 

@Override
public Explanation explain(LeafReaderContext context, int doc) throws IOException {
  FunctionValues functionValues = valueSource.getValues(vsContext, context);
  //note: by using ValueSourceScorer directly, we avoid calling scorer.advance(doc) and checking if true,
  //  which can be slow since if that doc doesn't match, it has to linearly find the next matching
  ValueSourceScorer scorer = scorer(context);
  if (scorer.matches(doc)) {
    scorer.iterator().advance(doc);
    return Explanation.match(scorer.score(), FunctionRangeQuery.this.toString(), functionValues.explain(doc));
  } else {
    return Explanation.noMatch(FunctionRangeQuery.this.toString(), functionValues.explain(doc));
  }
}
 

protected Explanation idfExplain(BasicStats stats, double freq, double docLen){
  return Explanation.match((float) idf(stats, freq, docLen),
      "idf, inverted document frequency computed as " +
          "Math.pow((N + 1) / n, k) from:",
      Explanation.match((float) stats.getNumberOfDocuments(),
          "N, total number of documents with field"),
      Explanation.match((float) stats.getDocFreq(),
          "n, number of documents containing term"));
}
 

public Explanation explain(Query<Entity> q, EntityType entityType, Object entityId) {
  Explanation explanation = elasticsearchService.explain(entityType, entityId, q);
  if (explanation != null) {
    if (LOG.isDebugEnabled()) {
      LOG.debug(explanation.toString());
    }

    return explanation;
  }
  return null;
}
 

@Override
public Explanation explain(final LeafReaderContext context, final int doc) throws IOException {

    Scorer scorer = scorer(context);
    if (scorer != null) {
        int newDoc = scorer.iterator().advance(doc);
        if (newDoc == doc) {

            Explanation scoreExplanation = Explanation.match(score, "product of:",
                    Explanation.match(queryBoost, "queryBoost"),
                    Explanation.match(fieldBoost, "fieldBoost")
            );

            Explanation result = Explanation.match(scorer.score(),
                    "weight(" + getQuery() + " in " + doc + ") ["
                            + FieldBoostTermQuery.this.fieldBoost.getClass().getSimpleName() + "], result of:",
                    scoreExplanation

            );



            return result;
        }
    }
    return Explanation.noMatch("no matching term");
}
 

@Override
public final Explanation explain(BasicStats stats, double tfn) {
  return Explanation.match(
      (float) (scoreTimes1pTfn(stats) / (1 + tfn)),
      getClass().getSimpleName() + ", computed as 1 / (tfn + 1) from:",
      Explanation.match((float) tfn, "tfn, normalized term frequency"));
}
 

@Test
public void testExplain() throws IOException {
  Query rangeQuery = new FunctionRangeQuery(INT_VALUESOURCE, 2, 2, true, true);
  ScoreDoc[] scoreDocs = indexSearcher.search(rangeQuery, N_DOCS).scoreDocs;
  Explanation explain = indexSearcher.explain(rangeQuery, scoreDocs[0].doc);
  // Just validate it looks reasonable
  assertEquals(
          "2.0 = frange(int(" + INT_FIELD + ")):[2 TO 2]\n" +
          "  2.0 = int(" + INT_FIELD + ")=2\n",
      explain.toString());
}
 

@Test
void testConvertAttribute() {
  when(dataService.getEntityType(ATTRIBUTE_META_DATA)).thenReturn(attributeMetadata);
  Explanation explanation = Explanation.match(0.3f, "match");
  when(elasticSearchExplainService.explain(query, attributeMetadata, "attrID"))
      .thenReturn(explanation);
  when(elasticSearchExplainService.findQueriesFromExplanation(
          collectExpandedQueryMap, explanation))
      .thenReturn(explainedQueryStrings);

  assertEquals(
      explainedQueryStrings,
      semanticSearchService.convertAttributeToExplainedAttribute(
          attribute, collectExpandedQueryMap, query));
}
 

protected Explanation idfExplain(BasicStats stats, double freq, double docLen){
  return Explanation.match((float) idf(stats, freq, docLen),
      "idf, inverted document frequency computed as log((N + 1) / n) from:",
      Explanation.match((float) stats.getNumberOfDocuments(),
          "N, total number of documents with field"),
      Explanation.match((float) stats.getDocFreq(),
          "n, number of documents containing term"));
}
 

@Override
public Explanation explain(LeafReaderContext context, int doc) throws IOException {
  BlockJoinScorer scorer = (BlockJoinScorer) scorer(context);
  if (scorer != null && scorer.iterator().advance(doc) == doc) {
    return scorer.explain(context, in);
  }
  return Explanation.noMatch("Not a match");
}
 

@Override
public final SimScorer scorer(float boost, CollectionStatistics collectionStats, TermStatistics... termStats) {
  Explanation idf = termStats.length == 1 ? idfExplain(collectionStats, termStats[0]) : idfExplain(collectionStats, termStats);
  float avgdl = avgFieldLength(collectionStats);

  float[] cache = new float[256];
  for (int i = 0; i < cache.length; i++) {
    cache[i] = 1f / (k1 * ((1 - b) + b * LENGTH_TABLE[i] / avgdl));
  }
  return new BM25Scorer(boost, k1, b, idf, avgdl, cache);
}
 

@Override
protected void explain(
    List<Explanation> subs, BasicStats stats, double freq, double docLen) {
  if (stats.getBoost() != 1.0d) {
    subs.add(Explanation.match((float)stats.getBoost(), "boost, query boost"));
  }
  Explanation normExpl = normalization.explain(stats, freq, docLen);
  Explanation lambdaExpl = lambda.explain(stats);
  subs.add(normExpl);
  subs.add(lambdaExpl);
  subs.add(distribution.explain(stats, normExpl.getValue().floatValue(), lambdaExpl.getValue().floatValue()));
}
 

@Override
protected Explanation tfExplain(BasicStats stats, double freq, double docLen){
  return Explanation.match((float) tf(stats, freq, docLen),
      "tf, term frequency computed as 1 + log(1 + log(freq)) from:",
      Explanation.match((float) freq,
          "freq, number of occurrences of term in the document"));
}
 

private void debugExplainResults(String indexName, Hits hits, IndexSearcher searcher,
        Query q, Set<Term> queryTerms)
    throws IOException {
    log.debug("Parsed Query is " + q.toString());
    log.debug("Looking at index:  " + indexName);
    for (int i = 0; i < hits.length(); i++) {
        if ((i < 10)) {
            Document doc = hits.doc(i);
            Float score = hits.score(i);
            Explanation ex = searcher.explain(q, hits.id(i));
            log.debug("Looking at hit<" + i + ", " + hits.id(i) + ", " + score +
                    ">: " + doc);
            log.debug("Explanation: " + ex);
            MatchingField match = new MatchingField(q.toString(), doc, queryTerms);
            String fieldName = match.getFieldName();
            String fieldValue = match.getFieldValue();
            log.debug("Guessing that matched fieldName is " + fieldName + " = " +
                    fieldValue);
        }
    }
}
 

public Explanation explain(Similarity similarity, Query query, int doc) {
  if (!isMatched(doc)) {
    return null;
  }
  ComplexExplanation result = new ComplexExplanation();
  result.setDescription(
      "weight(" + query + " in " + doc + ") [" + similarity.getClass().getSimpleName() + "], result of:");
  Explanation scoreExplanation = docScorer.explain(doc, new Explanation(matchedFreq, "termFreq=" + matchedFreq));
  result.addDetail(scoreExplanation);
  result.setValue(scoreExplanation.getValue());
  result.setMatch(true);
  return result;
}
 

@Override
public Explanation explain(AtomicReaderContext context, int doc) throws IOException {
  FlexibleScorer scorer = (FlexibleScorer) scorer(context, context.reader().getLiveDocs());
  if (scorer != null) {
    int newDoc = scorer.advance(doc);
    if (newDoc == doc) {
      FlexibleScoreModelStrategy strategy = scorer.getStrategy();
      strategy.prepare(0, 0, true);
      return strategy.explain(similarity, query, doc);
    }
  }
  return new ComplexExplanation(false, 0.0f, "no matching term");
}
 

@Override
public Explanation explain(LeafReaderContext ctx, int docId, Explanation scoreExplanation) throws IOException {
  Map<Object, Object> context = new HashMap<>();
  ScoreAndDoc scorer = new ScoreAndDoc();
  scorer.score = scoreExplanation.getValue().floatValue();
  context.put("scorer", scorer);
  context.put("searcher", searcher);
  FunctionValues fv = in.getValues(context, ctx);
  return fv.explain(docId);
}
 

public Explanation getNormalizerExplanation(Explanation e, int idx) {
  Normalizer n = norms.get(idx);
  if (n != IdentityNormalizer.INSTANCE) {
    return n.explain(e);
  }
  return e;
}
 

private LindenHit parseExplain(int doc, LindenHit lindenHit) throws IOException {
  if (request.isExplain()) {
    Explanation expl = indexSearcher.explain(query, doc);
    LindenExplanation lindenExpl = parseLindenExplanation(expl);
    lindenHit.setExplanation(lindenExpl);
  }
  return lindenHit;
}
 

private LindenExplanation parseLindenExplanation(Explanation expl) {
  LindenExplanation lindenExpl = new LindenExplanation();
  lindenExpl.setDescription(expl.getDescription());
  lindenExpl.setValue(expl.getValue());
  if (expl.getDetails() != null) {
    for (Explanation subExpl : expl.getDetails()) {
      LindenExplanation subLindenExpl = parseLindenExplanation(subExpl);
      lindenExpl.addToDetails(subLindenExpl);
    }
  }
  return lindenExpl;
}
 

protected Explanation tflnExplain(BasicStats stats, double freq, double docLen){
  return Explanation.match((float) tfln(stats, freq, docLen),
      "tfln, mixed term frequency and document length, " +
          "computed as freq / (freq + s + s * dl / avgdl) from:",
      Explanation.match((float) freq,
          "freq, number of occurrences of term in the document"),
      Explanation.match((float) docLen,
          "dl, length of field"),
      Explanation.match((float) stats.getAvgFieldLength(),
          "avgdl, average length of field across all documents"));
}