KNearestFuzzyClassifier reads a documented field boost such as title^10 as part of the field name, so that field is ignored

The KNearestFuzzyClassifier constructor documents that its text field names "can contain boosting indication e.g. title^10" (KNearestFuzzyClassifier.java:83-84). The class never parses that syntax: knnSearch passes every entry unchanged to NearestFuzzyQuery.addTerms(text, fieldName) (:137-140), and NearestFuzzyQuery looks up a field literally named title^10, finds none and adds no terms for it (NearestFuzzyQuery.java:133-136). The fuzzy query is a required clause (:141). With one boosted text field nothing matches, so assignClass returns null and getClasses an empty list on every call; with several fields the boosted one is silently left out and the answer comes from the others: on a six-document index, {"title", "body"} classifies "apple wheel" as fruit (0.667) and {"title^10", "body"} as vehicle (0.971), the body-only answer. The sibling KNearestNeighborClassifier carries the same javadoc sentence and parses it. The gap dates from the class's introduction (LUCENE-7838, first released in 7.0.0), so every release from 7.0.0 to 10.6.0 (10.6.0 by reading) and main is affected. Passing the parsed boost into the one NearestFuzzyQuery the class already builds fixes it; the whole lucene/classification test suite passes with that change.

• KNearestFuzzyClassifier: a k-nearest-neighbour text classifier in the opt-in lucene-classification module (@lucene.experimental). It turns the input text into a NearestFuzzyQuery over the configured text fields, takes the top k documents that have a class, and votes.
• NearestFuzzyQuery: a trimmed copy of the sandbox FuzzyLikeThisQuery. For every field it was given, it analyses the text, collects fuzzy variants of each term (one edit; at most 50 per term and field), keeps the best 300 terms over all fields and rewrites to a BooleanQuery of SHOULD term clauses.
• field^boost: the syntax the constructor javadoc documents for weighting a field, as in title^10. The sibling KNearestNeighborClassifier and both document classifiers parse it.

1. The constructor stores the caller's textFieldNames unchanged (KNearestFuzzyClassifier.java:94); nothing parses or validates it.
2. knnSearch calls nearestFuzzyQuery.addTerms(text, fieldName) with each entry as given (:137-140).
3. NearestFuzzyQuery asks the index for the terms of the field title^10, gets null and returns: that field adds no terms (NearestFuzzyQuery.java:133-136). An index with a field literally named title^5 is read from that field, which shows the entry is used verbatim.
4. The fuzzy query is added as MUST (KNearestFuzzyClassifier.java:141). With one text field it has no clauses and matches nothing: assignClass returns null (:104-117), getClasses an empty list. With several fields the other fields still match, so the top k come from them alone.

NearestFuzzyQuery.addTerms("apple banana", "text") rewrites to (text:apple)^1.5108256 (text:banana)^1.9162908; with "text^2" it rewrites to an empty query. With either fix, {"text^2"} gives fruit 0.8135 and {"title^10", "body"} fruit 0.6667 (vehicle 0.0509).

• Who is hit. Users of KNearestFuzzyClassifier (opt-in lucene-classification module, @lucene.experimental) who write a text field name with a boost, as the constructor javadoc shows. Nothing else is needed: the lookup of the literal name does not depend on the index settings, the codec, the similarity or the index size; the outcomes shown here were run only on the small indexes of this doc.
• Every call, deterministic. The lookup does not depend on data or seeds: the test fails 40 of 40 over 10 iterations.
• One boosted field is loud: null on every call, so a user would probably notice and drop the boost.
• Several fields are silent: the answer is plausible but comes from the other fields only, the opposite of what the user asked for (the field they weighted most counts least). Even ^1 changes the answer.
• Reach. No downstream user is known: a GitHub-wide issue and PR search for the class name found no user report, and the searches found no public report of the bug since 7.0.0 (2017).
• Not a resource problem. The faulty path does less work than the correct one.
• Not counted here: getClasses(text, max) on the empty list throws IndexOutOfBoundsException (KNearestFuzzyClassifier.java:132), the known LUCENE-8110 / #9158.

# Lucene main 645d4fe14a20, assertions on (-ea), seed DEADBEEF: 1 test(s) run, 1 failed
    => java.lang.AssertionError: expected:<fruit> but was:<null>
       org.junit.Assert.fail(Assert.java:89)
       org.junit.Assert.failNotEquals(Assert.java:835)
       org.junit.Assert.assertEquals(Assert.java:120)
       org.junit.Assert.assertEquals(Assert.java:146)
       org.apache.lucene.classification.TestKNearestFuzzyClassifierBoostedField.testBoostedFieldName(TestKNearestFuzzyClassifierBoostedField.java:52)

• Contract. KNearestFuzzyClassifier.java:83-84: "@param textFieldNames the name of the fields used as the inputs for the classifier, they can contain boosting indication e.g. title^10". It is the only documentation of the parameter; no test, CHANGES entry or MIGRATE note says the syntax is unsupported here, and the searches found no issue or list thread that does.
• Module convention. BM25NBClassifier.java:76-77 and SimpleNaiveBayesClassifier.java:84-85 say "NO boosting supported per field". KNearestNeighborClassifier (:161-168), KNearestNeighborDocumentClassifier (:128-129) and SimpleNaiveBayesDocumentClassifier (:157-158) carry the boost sentence and parse it; the last one writes the stripped name back into the caller's array (:170), so only its first call is boosted (a separate bug, LFV-382).
• Tests. The upstream tests build this class with plain field names only, so nothing caught it; the document classifiers' tests use title^100.
• Precedent. LUCENE-7991 (7.2.0) fixed a field-boost bug in KNearestNeighborDocumentClassifier as a bug.
• History. The sentence and its parsing came to KNearestNeighborClassifier together (LUCENE-6654, 2015). LUCENE-7838 (2017) added this class with the same javadoc block but passed the raw names to the query; it never parsed ^.

The strongest case for "not a bug" (the intended-behaviour checker and the cross-model reviews): the whole constructor javadoc was copied from KNearestNeighborClassifier when the class was created (the neighbouring "@param k ... in the MLT results" names MoreLikeThis, which this class never used), so the boost sentence may be a copy too; the class is @lucene.experimental; and ^ is legal in a field name, so a field literally named text^2 works today.

Why it fails: the copy explains where the sentence came from, not that the behaviour is wanted; the published contract says the syntax works, and the module labels the classes without boost support. @lucene.experimental allows API changes, not a documented input that silently returns no class. The javadoc reserves ^ for boosts, as the siblings do. Whether the code or the sentence is the wrong half is for the maintainers to decide; either way the two disagree. Verdict: a defect, at the least a contract mismatch; the copy-paste origin, the experimental status and the absence of any public report since 2017 make the javadoc-only fix a reasonable maintainer choice.

Two code fixes were built and validated; they give the same classes and scores on every probed configuration and, by the code (not run), can differ only when an input yields more than 300 candidate terms. A javadoc-only fix is the third option.

+29/-4 in KNearestFuzzyClassifier.java and utils/NearestFuzzyQuery.java. knnSearch splits field^boost and calls a new public overload NearestFuzzyQuery.addTerms(String, String, float boost); the old two-argument method delegates with 1f. The new method rejects a negative or non-finite boost; FieldVals keeps the boost (also in equals/hashCode), and each term's score is multiplied by it.

// KNearestFuzzyClassifier.knnSearch
for (String fieldName : textFieldNames) {
  int caret = fieldName.indexOf('^');
  if (caret >= 0) { // "field^boost", e.g. title^10
    float boost = Float.parseFloat(fieldName.substring(caret + 1));
    nearestFuzzyQuery.addTerms(text, fieldName.substring(0, caret), boost);
  } else {
    nearestFuzzyQuery.addTerms(text, fieldName);
  }
}
// NearestFuzzyQuery: new addTerms(String, String, float); FieldVals keeps the boost
st.score = (st.score * st.score) * idf(df, corpusNumDocs) * f.boost;

Trade-offs

• One query and one shared 300-term budget, as today; the boost scales the field's term weights, like mlt.setBoostFactor in the sibling. Without ^ the only scoring change is a multiplication by 1f, which is exact, so the rewritten query is unchanged (FieldVals also carries the boost, in equals and hashCode, so its hash values change); title^1 equals title.
• The scaled score is also used for the 300-term cut, so a boosted field wins more of the budget when an input has more candidate terms than that. The earlier cap of 50 variants per term and field is applied before the boost, as today. Neither cap was reached in any run (the probe indexes have at most 8 distinct terms per field), neither was tested with a fix, and the new overload has no direct unit test.
• Adds one public overload to NearestFuzzyQuery (an exported package of the module).
• It parses on every call, like KNearestNeighborClassifier (SimpleNaiveBayesDocumentClassifier parses on its first call only), and a field literally named title^5 can no longer be addressed (the mechanism probe now gets fruit instead of tool). A malformed boost (title^x, title^) throws NumberFormatException on every call; parsing once in the constructor would fail fast instead (not run).
• The accepted grammar is that of Float.parseFloat: title^1e1 is accepted, title^2^3 throws (the sibling reads it as boost 2), and a literal ^ cannot be escaped. The new overload rejects negative (also -0.0) and non-finite boosts but accepts 0, while its message says "positive": reword the message, or reject 0, in the PR. None of these inputs was run.

What the checks validated

• stock: the new test fails 4 of 4 through gradle with assertions on (seed 5EED0811) and off (5EED0812), and again with the final test file (5EED0816);
• fix B: the whole :lucene:classification:test passes, 13 suites, 47 tests (the new class's 4 included), 1 skipped (@Monster 20 Newsgroups), 0 failures, with assertions on (5EED0813) and off (5EED0814);
• fix B: :lucene:classification:check passes (google-java-format, ecj lint, forbidden APIs and the tests, 5EED0817);
• standalone runner with fix B shadowed: the new test (assertions on and off), the independent reproduction's test (4 of 4), the finder's test, and the probe (the tables above) pass.

+26/-3 in KNearestFuzzyClassifier.java only. Without ^ today's code runs unchanged; otherwise each field gets its own NearestFuzzyQuery, wrapped in a BoostQuery, as a SHOULD clause of a required BooleanQuery. No API change; it mirrors the sibling, which builds one MoreLikeThis query per field.

Trade-offs

Two code paths. With any boost, each field gets its own 300-term budget, so the query can grow to 300 terms per field; and title^1 takes the boosted path, so for long inputs it can differ from title. Raised by the reviewers; not measured.

What the checks validated

• the whole :lucene:classification:test passes, 13 suites, 47 tests, 1 skipped, 0 failures (assertions on, 5EED0815), and so does :lucene:classification:check (5EED0818);
• standalone runner with fix A shadowed: the new test passes with assertions on and off; earlier runs of the hunt: the finder's test, the 3 upstream TestKNearestFuzzyClassifier tests, the independent reproduction's test (4 of 4) and the portable history probe pass.

Replace "they can contain boosting indication e.g. title^10" with the module's wording for classes without boost support, "NO boosting supported per field".

Trade-offs

Not run. Removes the broken promise but keeps the silent result for anyone who already writes a boosted name; rejecting entries with ^ would make it loud but would break a field literally named with ^.

Method: a documented-syntax check (the hunt's "non-formal" tier), 2026-10-26, stock main jars.

• While a hunt unit built a property-based baseline for the classification module, it checked the constructor javadoc's documented field^boost syntax against knnSearch. Its fuzz harness never passes a boosted field name, so the harness itself could not find it. The lead was left unfiled.
• On 2026-10-27 a later unit turned the lead into a public-API JUnit test with a differential oracle (the unboosted call and the sibling classifier) and re-ran it on main a9779ef3c193: it failed with assertions on and off and on 10.5.2.
• Then independent AI tools reproduced, reviewed and judged it (see the checks), and the history step ran one portable probe on eight releases from 7.0.0 to 10.5.2 plus main.