perf: trim fuzzy candidate-collection overhead

capemox · claude · capemox · commit c29f000ff78b · 2026-07-16T12:01:04.000+05:30
Three standalone optimizations in the fuzzy candidate-collection path
(search/searcher/search_fuzzy.go), none of which change results:

- findFuzzyCandidateTerms kept a termSet map and did a map insert per
  candidate. But the dictionary iterator already yields each term once
  (merged across segments), so the map is only needed to de-duplicate
  synonym terms against dictionary terms. Skip the map entirely when the
  field has no synonyms (the common case) — the non-automaton fallback
  path already appends without a map, confirming this.

- prefixTerm was built by concatenating runes one at a time (O(n^2),
  realloc per rune). Replace with a behavior-preserving slice of the
  original string at the first rune boundary at/after prefix.

- Hoist the repeated ctx.Value(FuzzyMatchPhraseKey) lookups in
  NewFuzzySearcher into a single lookup.

Benchmark (BenchmarkFuzzyCandidateCollection, added here: scorch index,
1000 terms / 3000 docs, fuzziness-2 query matching 280 candidates), parent
vs this commit, Apple M4 Pro, count=12 via benchstat:

  sec/op      144.0µ -&gt; 135.5µ   -5.9%   (p=0.000)
  B/op        693.3Ki -&gt; 667.1Ki -3.8%   (p=0.000)
  allocs/op   988 -&gt; 975         -1.3%   (p=0.000)

Co-Authored-By: Claude Opus 4.8 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/search/searcher/search_fuzzy.go b/search/searcher/search_fuzzy.go
@@ -66,11 +66,13 @@ func NewFuzzySearcher(ctx context.Context, indexReader index.IndexReader, term s
 	}
 
 	// Note: we don't byte slice the term for a prefix because of runes.
-	prefixTerm := ""
-	for i, r := range term {
-		if i < prefix {
-			prefixTerm += string(r)
-		} else {
+	// prefixTerm is the leading runes of term whose start byte offset is
+	// below prefix; slicing term at the first rune boundary at/after prefix
+	// yields the same string without per-rune string concatenation.
+	prefixTerm := term
+	for i := range term {
+		if i >= prefix {
+			prefixTerm = term[:i]
 			break
 		}
 	}
@@ -89,21 +91,21 @@ func NewFuzzySearcher(ctx context.Context, indexReader index.IndexReader, term s
 		dictBytesRead = fuzzyCandidates.bytesRead
 	}
 
+	var fuzzyTermMatches map[string][]string
 	if ctx != nil {
 		reportIOStats(ctx, dictBytesRead)
 		search.RecordSearchCost(ctx, search.AddM, dictBytesRead)
-		fuzzyTermMatches := ctx.Value(search.FuzzyMatchPhraseKey)
-		if fuzzyTermMatches != nil {
-			fuzzyTermMatches.(map[string][]string)[term] = candidates
+		if ftm := ctx.Value(search.FuzzyMatchPhraseKey); ftm != nil {
+			fuzzyTermMatches = ftm.(map[string][]string)
 		}
 	}
+	if fuzzyTermMatches != nil {
+		fuzzyTermMatches[term] = candidates
+	}
 	// check if the candidates are empty or have one term which is the term itself
 	if len(candidates) == 0 || (len(candidates) == 1 && candidates[0] == term) {
-		if ctx != nil {
-			fuzzyTermMatches := ctx.Value(search.FuzzyMatchPhraseKey)
-			if fuzzyTermMatches != nil {
-				fuzzyTermMatches.(map[string][]string)[term] = []string{term}
-			}
+		if fuzzyTermMatches != nil {
+			fuzzyTermMatches[term] = []string{term}
 		}
 		return NewTermSearcher(ctx, indexReader, term, field, boost, options)
 	}
@@ -156,15 +158,33 @@ func findFuzzyCandidateTerms(ctx context.Context, indexReader index.IndexReader,
 	// the levenshtein automaton based iterator to collect the
 	// candidate terms
 	if ir, ok := indexReader.(index.IndexReaderFuzzy); ok {
-		termSet := make(map[string]struct{})
+		// Synonym terms (if any) for this field need to be matched against the
+		// automaton and de-duplicated against the dictionary candidates.
+		var synonymTerms map[string][]string
+		if ctx != nil {
+			if fts, ok := ctx.Value(search.FieldTermSynonymMapKey).(search.FieldTermSynonymMap); ok {
+				synonymTerms = fts[field]
+			}
+		}
+		// The dictionary iterator already yields each term exactly once (merged
+		// across segments), so the only purpose of termSet is to de-duplicate
+		// synonym terms against the dictionary candidates. When there are no
+		// synonyms, skip the map entirely to avoid a per-candidate map insert.
+		var termSet map[string]struct{}
+		if len(synonymTerms) > 0 {
+			termSet = make(map[string]struct{}, len(synonymTerms))
+		}
 		addCandidateTerm := func(term string, editDistance uint8) error {
-			if _, exists := termSet[term]; !exists {
-				termSet[term] = struct{}{}
-				rv.candidates = append(rv.candidates, term)
-				rv.editDistances = append(rv.editDistances, editDistance)
-				if tooManyClauses(len(rv.candidates)) {
-					return tooManyClausesErr(field, len(rv.candidates))
+			if termSet != nil {
+				if _, exists := termSet[term]; exists {
+					return nil
 				}
+				termSet[term] = struct{}{}
+			}
+			rv.candidates = append(rv.candidates, term)
+			rv.editDistances = append(rv.editDistances, editDistance)
+			if tooManyClauses(len(rv.candidates)) {
+				return tooManyClausesErr(field, len(rv.candidates))
 			}
 			return nil
 		}
@@ -188,24 +208,18 @@ func findFuzzyCandidateTerms(ctx context.Context, indexReader index.IndexReader,
 		if err != nil {
 			return nil, err
 		}
-		if ctx != nil {
-			if fts, ok := ctx.Value(search.FieldTermSynonymMapKey).(search.FieldTermSynonymMap); ok {
-				if ts, exists := fts[field]; exists {
-					for term := range ts {
-						if _, exists := termSet[term]; exists {
-							continue
-						}
-						if !strings.HasPrefix(term, prefixTerm) {
-							continue
-						}
-						match, editDistance := a.MatchAndDistance(term)
-						if match {
-							err = addCandidateTerm(term, editDistance)
-							if err != nil {
-								return nil, err
-							}
-						}
-					}
+		for term := range synonymTerms {
+			if _, exists := termSet[term]; exists {
+				continue
+			}
+			if !strings.HasPrefix(term, prefixTerm) {
+				continue
+			}
+			match, editDistance := a.MatchAndDistance(term)
+			if match {
+				err = addCandidateTerm(term, editDistance)
+				if err != nil {
+					return nil, err
 				}
 			}
 		}
diff --git a/search/searcher/search_fuzzy_bench_test.go b/search/searcher/search_fuzzy_bench_test.go
@@ -0,0 +1,127 @@
+//  Copyright (c) 2024 Couchbase, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// 		http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package searcher
+
+import (
+	"context"
+	"fmt"
+	"testing"
+
+	"github.com/blevesearch/bleve/v2/document"
+	"github.com/blevesearch/bleve/v2/index/scorch"
+	"github.com/blevesearch/bleve/v2/search"
+	index "github.com/blevesearch/bleve_index_api"
+)
+
+// buildFuzzyBenchIndex builds a scorch index whose "desc" field has numTerms
+// distinct terms spread across numDocs documents (perDoc terms per document),
+// so candidate terms have real multi-doc postings lists.
+func buildFuzzyBenchIndex(b *testing.B, numTerms, numDocs, perDoc int) index.Index {
+	analysisQueue := index.NewAnalysisQueue(1)
+	idx, err := scorch.NewScorch(scorch.Name,
+		map[string]interface{}{"path": b.TempDir()}, analysisQueue)
+	if err != nil {
+		b.Fatal(err)
+	}
+	if err = idx.Open(); err != nil {
+		b.Fatal(err)
+	}
+
+	terms := make([]string, numTerms)
+	for i := range terms {
+		terms[i] = fmt.Sprintf("term%04d", i)
+	}
+
+	batch := index.NewBatch()
+	for d := 0; d < numDocs; d++ {
+		doc := document.NewDocument(fmt.Sprintf("%d", d))
+		buf := make([]byte, 0, perDoc*9)
+		for j := 0; j < perDoc; j++ {
+			if j > 0 {
+				buf = append(buf, ' ')
+			}
+			buf = append(buf, terms[(d*perDoc+j)%numTerms]...)
+		}
+		doc.AddField(document.NewTextFieldCustom("desc", nil, buf,
+			twoDocIndexDescIndexingOptions, testAnalyzer))
+		batch.Update(doc)
+	}
+	if err = idx.Batch(batch); err != nil {
+		b.Fatal(err)
+	}
+	return idx
+}
+
+// BenchmarkFuzzyCandidateCollection isolates candidate-term collection
+// (findFuzzyCandidateTerms) over a real scorch index for a fuzziness-2 query.
+// This is the step the fuzzy optimizations touch; the full NewFuzzySearcher is
+// dominated by building one term searcher per candidate downstream, which these
+// changes do not affect and which would dilute the measurement.
+func BenchmarkFuzzyCandidateCollection(b *testing.B) {
+	idx := buildFuzzyBenchIndex(b, 1000, 3000, 40)
+	defer func() { _ = idx.Close() }()
+
+	r, err := idx.Reader()
+	if err != nil {
+		b.Fatal(err)
+	}
+	defer func() { _ = r.Close() }()
+
+	ctx := context.Background()
+
+	// sanity: report how many candidates the query matches, once.
+	fc, err := findFuzzyCandidateTerms(ctx, r, "term0500", 2, "desc", "")
+	if err != nil {
+		b.Fatal(err)
+	}
+	b.Logf("candidates=%d", len(fc.candidates))
+
+	b.ResetTimer()
+	b.ReportAllocs()
+	for n := 0; n < b.N; n++ {
+		_, err := findFuzzyCandidateTerms(ctx, r, "term0500", 2, "desc", "")
+		if err != nil {
+			b.Fatal(err)
+		}
+	}
+}
+
+// BenchmarkFuzzySearcherEndToEnd measures the full NewFuzzySearcher path for
+// reference (candidate collection + building the boosted disjunction).
+func BenchmarkFuzzySearcherEndToEnd(b *testing.B) {
+	idx := buildFuzzyBenchIndex(b, 1000, 3000, 40)
+	defer func() { _ = idx.Close() }()
+
+	r, err := idx.Reader()
+	if err != nil {
+		b.Fatal(err)
+	}
+	defer func() { _ = r.Close() }()
+
+	opts := search.SearcherOptions{Score: "none"}
+	ctx := context.Background()
+
+	b.ResetTimer()
+	b.ReportAllocs()
+	for n := 0; n < b.N; n++ {
+		s, err := NewFuzzySearcher(ctx, r, "term0500", 0, 2, "desc", 1.0, opts)
+		if err != nil {
+			b.Fatal(err)
+		}
+		if err = s.Close(); err != nil {
+			b.Fatal(err)
+		}
+	}
+}
