MB-71971: Add explain to custom score queries

search/query/custom_score.go

@@ -85,7 +85,7 @@ func (q *CustomScoreQuery) Searcher(ctx context.Context, i index.IndexReader, m
 		fieldTypes = resolveFieldTypes(q.Fields, m)
 	}
 
-	return searcher.NewCustomScoreSearcher(ctx, childSearcher, q.scoreFunc, dvReader, i, fieldTypes), nil
+	return searcher.NewCustomScoreSearcher(ctx, childSearcher, q.scoreFunc, dvReader, i, fieldTypes, options.Explain), nil
 }
 
 func (q *CustomScoreQuery) Validate() error {

search/searcher/search_custom_score.go

@@ -42,17 +42,32 @@ type CustomScoreSearcher struct {
 	dvReader    index.DocValueReader
 	indexReader index.IndexReader
 	fieldTypes  map[string]string
+	explain     bool
 }
 
 func NewCustomScoreSearcher(ctx context.Context, s search.Searcher, mutate CustomScoreFunc,
 	dvReader index.DocValueReader, indexReader index.IndexReader,
-	fieldTypes map[string]string) *CustomScoreSearcher {
+	fieldTypes map[string]string, explain bool) *CustomScoreSearcher {
 	return &CustomScoreSearcher{
 		child:       s,
 		mutate:      mutate,
 		dvReader:    dvReader,
 		indexReader: indexReader,
 		fieldTypes:  fieldTypes,
+		explain:     explain,
+	}
+}
+
+// applyScore mutates the score on the hit and, when explain is enabled,
+// replaces the explanation with a single node describing the custom score
+// result.
+func (f *CustomScoreSearcher) applyScore(d *search.DocumentMatch) {
+	d.Score = f.mutate(d)
+	if f.explain {
+		d.Expl = &search.Explanation{
+			Value:   d.Score,
+			Message: "custom_score function result",
+		}
 	}
 }
 
@@ -70,7 +85,7 @@ func (f *CustomScoreSearcher) Next(ctx *search.SearchContext) (*search.DocumentM
 		if err = loadDocValuesOnHitWithTypes(next, f.dvReader, f.indexReader, f.fieldTypes); err != nil {
 			return nil, err
 		}
-		next.Score = f.mutate(next)
+		f.applyScore(next)
 	}
 	return next, nil
 }
@@ -84,7 +99,7 @@ func (f *CustomScoreSearcher) Advance(ctx *search.SearchContext, ID index.IndexI
 		if err = loadDocValuesOnHitWithTypes(adv, f.dvReader, f.indexReader, f.fieldTypes); err != nil {
 			return nil, err
 		}
-		adv.Score = f.mutate(adv)
+		f.applyScore(adv)
 	}
 	return adv, nil
 }

search_test.go

@@ -4944,10 +4944,13 @@ func TestCustomFilterQueryDocumentMatchIDWithoutFields(t *testing.T) {
 		t.Fatalf("expected 3 hits, got %d", res.Total)
 	}
 
-	expectedOrder := []string{"0", "2", "7"}
-	for i, hit := range res.Hits {
-		if hit.ID != expectedOrder[i] {
-			t.Fatalf("expected hit %d to be %s, got %s", i, expectedOrder[i], hit.ID)
+	hitIDs := map[string]struct{}{}
+	for _, hit := range res.Hits {
+		hitIDs[hit.ID] = struct{}{}
+	}
+	for id := range allowedIDs {
+		if _, ok := hitIDs[id]; !ok {
+			t.Fatalf("missing expected hit id %s", id)
 		}
 	}
 }
@@ -4988,6 +4991,50 @@ func TestCustomScoreQueryWithDocValues(t *testing.T) {
 	}
 }
 
+func TestCustomScoreQueryExplain(t *testing.T) {
+	idx := newCustomQueryTestIndex(t)
+	defer func() {
+		if err := idx.Close(); err != nil {
+			t.Fatal(err)
+		}
+	}()
+
+	titleQuery := NewMatchQuery("habit")
+	titleQuery.SetField("title")
+
+	q := query.NewCustomScoreQueryWithScorer(titleQuery, func(d *search.DocumentMatch) float64 {
+		return d.Score * 2
+	}, nil, nil)
+
+	req := NewSearchRequest(q)
+	req.Explain = true
+	req.Size = 10
+
+	res, err := idx.SearchInContext(context.Background(), req)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	if len(res.Hits) == 0 {
+		t.Fatal("expected at least one hit")
+	}
+
+	for _, hit := range res.Hits {
+		if hit.Expl == nil {
+			t.Fatalf("expected explanation on hit %s but got nil", hit.ID)
+		}
+		if hit.Expl.Message != "custom_score function result" {
+			t.Errorf("hit %s: expected wrap message %q, got %q",
+				hit.ID, "custom_score function result", hit.Expl.Message)
+		}
+		if len(hit.Expl.Children) != 0 {
+			t.Errorf("hit %s: expected no children (inner score dropped), got %d",
+				hit.ID, len(hit.Expl.Children))
+		}
+		t.Logf("hit %s (score=%f):\n%s", hit.ID, hit.Score, hit.Expl)
+	}
+}
+
 func newCustomQueryTestIndex(t *testing.T) Index {
 	t.Helper()
 
@@ -5001,7 +5048,10 @@ func newCustomQueryTestIndex(t *testing.T) Index {
 	titleMapping.Analyzer = en.AnalyzerName
 	imap.DefaultMapping.AddFieldMappingsAt("title", titleMapping)
 
-	idx, err := NewMemOnly(imap)
+	tmpIndexPath := createTmpIndexPath(t)
+	t.Cleanup(func() { cleanupTmpIndexPath(t, tmpIndexPath) })
+
+	idx, err := NewUsing(tmpIndexPath, imap, scorch.Name, Config.DefaultKVStore, nil)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -5045,7 +5095,10 @@ func newCustomQueryDocValueTestIndex(t *testing.T) Index {
 	ratingMapping := mapping.NewNumericFieldMapping()
 	imap.DefaultMapping.AddFieldMappingsAt("rating", ratingMapping)
 
-	idx, err := NewMemOnly(imap)
+	tmpIndexPath := createTmpIndexPath(t)
+	t.Cleanup(func() { cleanupTmpIndexPath(t, tmpIndexPath) })
+
+	idx, err := NewUsing(tmpIndexPath, imap, scorch.Name, Config.DefaultKVStore, nil)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -5081,7 +5134,10 @@ func TestCustomFilterQueryDateTimeDocValues(t *testing.T) {
 	dateMapping := mapping.NewDateTimeFieldMapping()
 	imap.DefaultMapping.AddFieldMappingsAt("published", dateMapping)
 
-	idx, err := NewMemOnly(imap)
+	tmpIndexPath := createTmpIndexPath(t)
+	defer cleanupTmpIndexPath(t, tmpIndexPath)
+
+	idx, err := NewUsing(tmpIndexPath, imap, scorch.Name, Config.DefaultKVStore, nil)
 	if err != nil {
 		t.Fatal(err)
 	}