BoostQueryNode's javadoc limits the boost to 0.0-1.0, but the parser's own example jones^2 gives 2.0

In the flexible query parser (StandardQueryParser), a boost such as jones^2 becomes a BoostQueryNode in the query-node tree, and a builder later turns it into a BoostQuery. The node's javadoc says three times that the value "may vary from 0.0 to 1.0": in the class javadoc, the constructor @param and getValue. Nothing in Lucene keeps the value in that range, and nothing should: the grammar and the field-boost processor store the user's number unchanged, BoostQuery sets no upper bound, and the parser's own documentation uses jones^2 and (a OR b NOT c)^2.5 as examples. StandardSyntaxParser.parse("jones^2", "f") returns a node whose getValue() is 2.0.

Parsing, query building and scoring are correct. The only people misled are developers who extend the parser with their own processors, builders or validators and take the stated range at face value. The text has been there since the flexible parser was added in 2009 (LUCENE-1567) and is in every release since 2.9.0. The fix is three javadoc lines.

1. The text. BoostQueryNode.java:29 "The boost value may vary from 0.0 to 1.0."; :39 "@param value the boost value, it may vary from 0.0 to 1.0"; :67 "Returns the boost value. It may vary from 0.0 to 1.0."
2. The node checks nothing. The constructor (:41-51) checks only that the child is not null and stores this.value = value (:47); getValue returns it (:71-73).
3. Producer 1, the grammar. Boost ::= '^' <NUMBER> (StandardSyntaxParser.jj:692) returns new BoostQueryNode(node, parseFloat(boost)) (:701), and parseFloat is Float.parseFloat(token.image) (:115-116): no clamp, no range check.
4. Producer 2, field boosts. For a field node whose parent is not itself a field node, BoostQueryNodeProcessor reads that field's configured boost and, if there is one, returns new BoostQueryNode(node, boost) with the value unchanged (BoostQueryNodeProcessor.java:44-57); the map comes from StandardQueryParser.setFieldsBoost (StandardQueryParser.java:526).
5. Consumer. BoostQueryNodeBuilder returns new BoostQuery(query, boostNode.getValue()) (BoostQueryNodeBuilder.java:48). BoostQuery rejects only non-finite or negative boosts (BoostQuery.java:40-41, "boost must be a positive float"; it compares with Float.compare, so -0.0f counts as negative and +0.0f passes) and documents that values greater than one give more importance (:23-25).
6. So every boost the standard syntax accepts (an unsigned decimal number, StandardSyntaxParser.jj:160) reaches the node unchanged: jones^2 gives 2.0, smith^0.5 gives 0.5, (a OR b)^2.5 gives 2.5, jakarta^4 gives 4.0, and setFieldsBoost({b=5, t=10}) builds (b:one)^5.0 (t:one)^10.0. Negative and non-finite values also reach the node and are rejected only when BoostQuery is built (a field boost of -1; a literal beyond Float.MAX_VALUE, which parses to Infinity). That matters for the fix wording.

• Who. Code that reads BoostQueryNode.getValue(): custom QueryNodeProcessors, QueryBuilders or validators plugged into StandardQueryParser. If it trusted the javadoc it could clamp boosts to 1.0 (silently turning jones^2 into jones^1) or reject the parser's own documented example.
• Who not. Applications that only call StandardQueryParser.parse: the boost reaches BoostQuery unchanged and scoring is correct.
• Default vs opt-in. The javadoc is what everyone sees, and the documented example hits the contradiction; acting on it needs custom code, which is opt-in and rare.
• Scale. None: it is static text.
• Why fix it anyway. A public class states a range that its only producers in Lucene violate, in every release since 2.9.0; the fix is three javadoc lines.

• Deterministic. No randomness is involved; the seed is given only because the test framework wants one. Assertions on and off fail the same way.
• It transcribes the current javadoc. It cannot pass after the javadoc fix and is evidence for it, not a regression test.
• Regression form: the same test with the expectation the fixed javadoc gives, assertEquals(2f, node.getValue(), 0f); in place of the assertTrue(...), passes on the fix with assertions on and off.
• Releases. Equivalent tests (a JUnit, or a main() for old releases) give 2.0 on every release run from 2.9.0 to 10.6.0; 2.4.1 has no flexible parser.

cp $REPRO/TestBoostQueryNodeDocumentedRange.java $LUCENE/lucene/queryparser/src/test/org/apache/lucene/queryparser/flexible/core/nodes/
cd $LUCENE
./gradlew :lucene:queryparser:test --tests org.apache.lucene.queryparser.flexible.core.nodes.TestBoostQueryNodeDocumentedRange -Ptests.seed=DEADBEEF -Ptests.asserts=true
# assertions off: -Ptests.asserts=false (same failure)

# gradle, main 645d4fe14a20, seed DEADBEEF, -Ptests.asserts=true
TestBoostQueryNodeDocumentedRange > testStandardQueryParserExampleBoostIsInDocumentedRange FAILED
    java.lang.AssertionError: expected a boost value in [0.0, 1.0], but getValue() = 2.0
        at __randomizedtesting.SeedInfo.seed([DEADBEEF:D82E118751663037]:0)
        at junit@4.13.2/org.junit.Assert.fail(Assert.java:89)
        at junit@4.13.2/org.junit.Assert.assertTrue(Assert.java:42)
        at org.apache.lucene.queryparser.flexible.core.nodes.TestBoostQueryNodeDocumentedRange.testStandardQueryParserExampleBoostIsInDocumentedRange(TestBoostQueryNodeDocumentedRange.java:27)
:lucene:queryparser:test (FAILURE): 1 test, 1  failure
# -Ptests.asserts=false: the same failure
# javadoc fix (option A): checkGoogleJavaFormat, ecjLintMain, renderJavadoc pass; the flexible-parser tests pass (162 tests, 1 skipped);
#   the same test expecting 2.0 passes with assertions on and off

• The same module documents boosts above 1. StandardQueryParser.java:161-173 ("Term boosting"): jones^2 OR smith^0.5 and field:(a OR b NOT c)^2.5 OR field:d. The classic syntax page: "The higher the boost factor, the more relevant the term will be" (classic/package-info.java:250-251), jakarta^4 apache (:261), and "By default, the boost factor is 1. Although the boost factor must be positive, it can be less than 1 (e.g. 0.2)" (:268-269).
• The query it builds says so too. BoostQuery.java:23-25: "values that are greater than one will give more importance to the scores returned by this query"; the constructor sets no upper bound and rejects only negative values (-0.0f too), NaN and infinities (:40-41).
• Upstream tests. TestQPHelper.java:974-976 ("hello"^2.0 builds BoostQuery with boost 2.0) and TestMultiFieldQPHelper.java:154-166 (testBoostsSimple: field boosts 5 and 10, asserted as (b:one)^5.0 (t:one)^10.0); both check the built query, not the node itself. No test asserts a value in [0, 1] for BoostQueryNode; no queryparser test names the class.
• History. The commit that wrote the three sentences, 343992fcbb4 (LUCENE-1567, 2009), also added tests asserting term^2 gives term^2.0 (with ^3 and ^4 cases and field boosts 5 and 10), and the query syntax page of that time already said jakarta^4. The saved history and prior-art searches found no commit, issue or list thread that discusses or defends a [0, 1] range; a 2025 clean-up of this file (#14737) left the line untouched without comment.

The strongest case for "not a bug": "may vary" is permissive, a loose hint rather than a contract; or the range is a caller precondition of a generic core node that some other syntax could honour. The intended-behaviour checker also tried "normalized-boost design", "accepted / won't fix" and "unreachable".

Why it fails: the text names a closed range, and the only producers in Lucene (the only new BoostQueryNode sites in the source tree), the standard grammar and BoostQueryNodeProcessor, put values above 1 into the node as designed, starting with the module's own documented example. A hint that is wrong for every value above 1 the documented syntax produces is still wrong, and no saved search found a discussion defending it. Verdict: a documentation defect; the code is right and should not change.

Three options, all javadoc-only; option A was applied in a scratch worktree of main 645d4fe14a20 and checked with gradle. Same file as LFV-975 (toQueryString prints small boosts in E-notation).

Say that values above 1.0 raise the score and values below 1.0 lower it, with the documented example, and that the node does not check the value while BoostQuery rejects negative and non-finite boosts.

--- a/lucene/queryparser/src/java/org/apache/lucene/queryparser/flexible/core/nodes/BoostQueryNode.java
+++ b/lucene/queryparser/src/java/org/apache/lucene/queryparser/flexible/core/nodes/BoostQueryNode.java
@@ -26,7 +26,9 @@ import org.apache.lucene.queryparser.flexible.messages.MessageImpl;
  * A {@link BoostQueryNode} boosts the QueryNode tree which is under this node. So, it must only and
  * always have one child.
  *
- * <p>The boost value may vary from 0.0 to 1.0.
+ * <p>Boost values above 1.0 raise the score of the boosted query and values below 1.0 lower it; for
+ * example {@code jones^2} gives a value of 2.0. This node does not check the value: {@link
+ * org.apache.lucene.search.BoostQuery} rejects negative and non-finite boosts.
  */
 public class BoostQueryNode extends QueryNodeImpl {
 
@@ -36,7 +38,7 @@ public class BoostQueryNode extends QueryNodeImpl {
    * Constructs a boost node
    *
    * @param query the query to be boosted
-   * @param value the boost value, it may vary from 0.0 to 1.0
+   * @param value the boost value
    */
   public BoostQueryNode(QueryNode query, float value) {
     if (query == null) {
@@ -64,7 +66,7 @@ public class BoostQueryNode extends QueryNodeImpl {
   }
 
   /**
-   * Returns the boost value. It may vary from 0.0 to 1.0.
+   * Returns the boost value.
    *
    * @return the boost value
    */

Trade-offs

• It does not imply that the node validates anything: the node stores whatever it gets, and BoostQuery is where negative and non-finite boosts are rejected.
• It adds a cross-module {@link} from a core node to org.apache.lucene.search.BoostQuery (the standard package's javadoc already links org.apache.lucene.search.Query). A custom builder that builds something else is not covered by that sentence; "This node does not check the value." alone also works.
• Option C (delete the range, add nothing) makes no new claim and is the most conservative alternative. "Negative" in the last sentence means what BoostQuery checks (Float.compare, so -0.0f is rejected too); "This node does not check the value." alone avoids the point.
• Backport: not tested on a maintenance branch. BoostQueryNode.java is byte-identical (the same git blob) on main, at the 10.6.0 tag and on branch_10_6, so the diff applies as is; the checks were not run there.

What the checks validated

• Gradle, scratch worktree of 645d4fe14a20, JDK 25.0.3, seed DEADBEEF: :lucene:queryparser:checkGoogleJavaFormat, :lucene:queryparser:ecjLintMain (its settings make invalid javadoc an error: EcjLintPlugin.java:52 loads ecj.javadocs.prefs, which sets invalidJavadoc=error) and :lucene:queryparser:renderJavadoc pass, and the rendered BoostQueryNode.html shows the new class text, value - the boost value and "Returns the boost value."
• The flexible-parser tests (org.apache.lucene.queryparser.flexible.*: the 14 upstream classes incl. TestQPHelper and TestMultiFieldQPHelper, plus the minimal test in its regression form expecting 2.0, 15 classes in all) pass: 162 tests, 1 skipped (the @Ignore at TestQPHelper.java:928), 0 failures, assertions on; the regression form passes with assertions off too.
• The first run did not record the scratch worktree's HEAD. An independent fact check applied option A to a fresh worktree of 645d4fe14a20 and re-ran checkGoogleJavaFormat, ecjLintMain and the regression form: all pass.
• The minimal test as written (the old range) was not re-run with the fix: the fix changes only comments, so it keeps failing as on stock main, by design.

The hunt's first sketch: the class sentence becomes "The boost value is a non-negative float: values above 1.0 raise the score of the boosted query, values below 1.0 lower it", and @param and getValue say "a non-negative float".

Trade-offs

• Reads as if the node guaranteed non-negativity, which it does not: a field boost of -1 reaches the node and fails only when BoostQuery is built.

What the checks validated

Not run (only patch --dry-run, which applies to main).

Drop "The boost value may vary from 0.0 to 1.0.", and leave @param value the boost value and "Returns the boost value."

Trade-offs

• Smallest change and correct, but loses the hint about what values mean.

What the checks validated

Not run (option A makes the same @param and getValue change).

• Lead. The unit swept the flexible parser's number printing (toQueryString siblings of LFV-892). While modelling the boost printer, the finder saw the javadoc range; the cross-model review of the sibling printing bug had also leaned on it.
• Test. A public-API JUnit parsed the documented example jones^2 and checked the node value against the stated range: 1 of 1 fails on main with assertions on and off, on branch_10_6 4ae946e5a9b, 10.5.2 and 9.12.3.
• Verification. An independent reproducer, a cross-model refute review (OpenAI GPT-5.6), an intended-behaviour devil's advocate, an adjudication and a credibility audit followed; all agree on the facts.