ComplexPhraseQueryParser reads a quoted phrase that is only one bracketed group as a sequence of positions

Inside a ComplexPhraseQueryParser phrase, a bracketed group is one word position with alternatives: the class javadoc's example is "(john jon jonathan~) peters*", and the upstream tests check "(jo* -john) smith" and "(john OR johathon) smith" (two spaces before smith in the test). That works when another element follows the group. When the group is the whole text between the quotes, the brackets are lost: the second pass parses the text with the classic grammar, which returns the inner query of a lone ( ... ), so "(john OR jonathan)" gets exactly the contents of "john OR jonathan", and ComplexPhraseQuery.rewrite turns each member into its own consecutive position. On five documents, "(john OR jonathan)" returns 1 document (the one with the sequence "john jonathan") instead of 4, and "(jo* -john)" returns all 5, including "john smith", instead of the 4 with a jo* term other than john. There is no error. It has behaved this way since the parser was added in 2.9.0: executed on 28 releases and main (both lone shapes on 16, the OR shape only on 12 more); the releases in between share the unchanged code.

• Complex phrase: ComplexPhraseQueryParser (in lucene/queryparser, opt-in) lets the text between quotes use query syntax: wildcards, fuzzy terms, ranges and bracketed groups. It parses the query twice. Pass 1 keeps the raw text of each phrase; pass 2 parses that text with the same classic grammar and turns the result into span queries.
• Position: each top-level element of the phrase is one word position, and the positions must follow each other (SpanNearQuery, with the phrase's slop). Top-level OR and AND are ignored inside a phrase: the implicit operator is "next to".
• Bracketed group: the documented exception. A group stands for one position whose word is any of its alternatives (spanOr), or any of its positive alternatives minus its negative ones (spanNot).

1. Pass 2 parses the raw phrase text: contents[0] = qp.parse(phrasedQueryStringContents) (ComplexPhraseQueryParser.java:246, in parsePhraseElements, :234-250).
2. The classic grammar drops brackets around the whole input. Clause() returns the inner query of <LPAREN> q=Query(field) <RPAREN> (QueryParser.jj:311), and Query() returns a lone, unmodified clause as it is: if (clauses.size() == 1 && firstQuery != null) return firstQuery; (:289-293). So (john OR jonathan) parses to the same BooleanQuery(john, jonathan) as john OR jonathan. For Boolean logic that is harmless.
3. ComplexPhraseQuery.rewrite (ComplexPhraseQueryParser.java:258-361) reads every top-level clause of that BooleanQuery as one position (:278-330) and returns new SpanNearQuery(allSpanClauses, slopFactor, inOrder) (:333): "(john OR jonathan)" becomes spanNear([john, jonathan], 0, true).
4. With a MUST_NOT clause it builds SpanNotQuery(include = the positive clauses, exclude = SpanNearQuery over all clauses) (:338-360): "(jo* -john)" becomes "a jo* term not followed by john", which "john smith" satisfies.
5. Inside a longer phrase the group survives as a nested BooleanQuery clause, and addComplexPhraseClause makes it one spanOr or spanNot position (:294-300, :371-420). That is why the same group followed by "smith" works.

The lone group gives the same rewritten query and hits as the bracket-free "john OR jonathan" and "jo* -john"; so do "((john OR jonathan))", "(john jonathan)", a field prefix and slop ("(john OR jonathan)"~2 still returns only "john jonathan"). A boosted lone group, "(john OR jonathan)^2", throws IllegalArgumentException ("Unknown query type ... BoostQuery") at search time instead: that is the separate sibling single-clause bug in the same rewrite.

• Who is hit. Users of ComplexPhraseQueryParser, with default settings. The brackets are lost in the parser's grammar, before analysis, so the analyzer should not matter; it was reproduced with MockAnalyzer (whitespace and simple tokenizers, lower-casing) and StandardAnalyzer. Solr's complexphrase query parser subclasses it without overriding the second pass, so it should inherit the behaviour (read in its source, not run).
• Trigger. The whole text between the quotes is one bracketed group, such as name:"(jo* -john)" or name:"(color OR colour)": typed by a user, or produced by an application that wraps the alternatives of each word position in quotes and gets a one-word input. Slop, a field prefix and either default operator do not matter.
• Effect. Wrong hits in both directions with no error. An OR group misses every document that holds only one alternative. A NOT group returns documents its own exclusion should drop, and dropping the quotes does not rescue it: the unquoted (jo* -john) drops every document that also contains john (3 hits instead of 4).
• Scale. None needed: five one-line documents show it. Nothing is stored or corrupted.
• How likely. Rare. People seldom quote a lone OR group, since the unquoted group already gives the OR. The only upstream use found is the 2017 query "(emissi* OR investerin*)"~30 in #8746 (LUCENE-7695), which the reporter called "works fine" after a crash fix; which documents it matched was not discussed.
• Bounds. In a probe of 126 two-member lone-group shapes (OR, implicit and NOT forms over 4 terms and 3 prefixes, whitespace MockAnalyzer, 84 documents), the wrong hits always lay inside what the unquoted positive terms match, and a FILTER clause around the parsed query was honoured exactly (0 violations). Other syntax and analyzers were not probed for this.

# Lucene main 645d4fe14a20, assertions on (-ea), seed DEADBEEF: 1 test(s) run, 1 failed
    => java.lang.AssertionError: expected:<1> but was:<0>
       org.junit.Assert.fail(Assert.java:89)
       org.junit.Assert.failNotEquals(Assert.java:835)
       org.junit.Assert.assertEquals(Assert.java:647)
       org.junit.Assert.assertEquals(Assert.java:633)
       org.apache.lucene.queryparser.complexPhrase.TestComplexPhraseLoneGroup.testLoneOrGroup(TestComplexPhraseLoneGroup.java:45)

• Class javadoc (ComplexPhraseQueryParser.java:47, also package-info.java:18): "QueryParser which permits complex phrase query syntax eg "(john jon jonathan~) peters*"".
• Upstream tests (TestComplexPhraseQuery.java): :70 "(jo* -john) smith" gives doc 2 ("boolean logic works"); :74 "(john OR johathon) smith" gives docs 1 and 2 (comment "boolean logic with" / "brackets works" over :74-75); also :76 and :78.
• One-element phrases are supported: :73 "john" ("Simple single-term still works") and testSingleTermPhrase (:92-99, from LUCENE-7614).
• The original author's rule (LUCENE-1486, #2560, 2009): "OR,||,+, AND, && ..... ignored. The implicit operator is AND_NEXT_TO apart from in bracketed sections where all elements at this level are ORed", and "In brackets it's an OR - the brackets are used to suggest that the current phrase element at position X is composed of some choices".
• Behaviour. The same characters (john OR jonathan) mean one position inside a longer phrase and a two-position sequence alone, with no error. The lone NOT group falls back to the top-level reading "jo* not followed by john" of the bracket-free "jo* -john"; the test file keeps top-level NOT inside a phrase commented out as unsupported (:81-82, "not logic doesn't work currently").
• History. It came with the class in 2009; no later test or commit covers a phrase that is only a group, and no issue about it was found.

The strongest case for "intended": outer brackets are transparent in the classic grammar, and the parser reuses that grammar on purpose ("working within the constraints of the existing parser as a base class", :56-59); the author said top-level operators inside a phrase are ignored; no doc or test shows a phrase that is only a group; the behaviour is 17 years old; and for a pure OR group the unquoted query already gives the OR.

Why it fails: that explains how the result arises, not a contract. The same author made bracketed sections the exception to the "next to" rule, the documented example and the tests rely on it, and nothing says it stops applying when the group stands alone. Dropping the quotes changes the NOT form's meaning, so it is no answer. The cross-model reviews and the adjudication rated the intended-behaviour argument weak; the devil's-advocate verifier was "moderately high" confident it is not intended; the final cross-model fact check called it a moderate case on whether this is a defect at all. Maintainers may still label the fix an improvement, as they labelled LUCENE-7614 (one-term phrases).

What still stands: compatibility. The sequence reading is 17 years old, so existing queries such as the #8746 one ("(emissi* OR investerin*)"~30) change meaning with a fix. The cross-model fact check also called the case that the practical impact is small a strong one (opt-in parser, rare shape, no report found, #16820 proposes deprecating the parser). That argues for a clear CHANGES entry, or a fix on 10.x only, rather than for the behaviour being intended.

One fix was built and validated in a scratch worktree; the other options are untested. The fix contains the guard of the sibling single-clause bug in the same rewrite (a boosted, +-prefixed or stop-word phrase that reduces to one clause throws).

ComplexPhraseQueryParser.java only, +40/-1. In parsePhraseElements, after parsing, isSingleGroup(phrasedQueryStringContents) checks that the stripped text starts with ( and that its matching ) (backslash escapes skipped) ends it, optionally followed directly (no space) by a boost ^<number>; then the parsed group is wrapped in a one-clause BooleanQuery, so rewrite sees one top-level clause, the group, and makes it one spanOr or spanNot position. In rewrite, a top-level BoostQuery is unwrapped and a lone span clause is returned as it is (a one-clause SpanNearQuery throws "Less than 2 subSpans" at search time).

// parsePhraseElements, after contents[0] = qp.parse(phrasedQueryStringContents);
if (isSingleGroup(phrasedQueryStringContents)) {
  contents[0] =
      new BooleanQuery.Builder().add(contents[0], BooleanClause.Occur.SHOULD).build();
}
// rewrite(): unwrap a top-level boost; return a lone span clause as it is
while (contents instanceof BoostQuery boostQuery) {
  contents = boostQuery.getQuery();
}
if (allSpanClauses.length == 1) {
  return allSpanClauses[0];
}

Trade-offs

• Compatibility. "(john OR jonathan)"~2 changes from "john, then jonathan within 2 positions" to "john or jonathan" (slop does not apply to one position), which changes existing queries such as the #8746 one. The bracket-free "jo* -john" and "john OR jonathan" keep their sequence readings (users rely on "foo -bar" meaning "foo not followed by bar"), and so do the groups inside a longer phrase that were run ("(john OR jonathan) smith", "(jo* -john) smith", "(john OR jonathan) (smith OR walker)"), with the regexp exception below.
• "(john OR jonathan)^2" and "+(jo* -john)" stop throwing and return the 4 documents (the sibling's shapes); the boost is dropped ("(john OR jonathan)^2" scores exactly like the unboosted group).
• Query structure and scores change for some one-position shapes (BM25 probe): "(jo*)" gives the same hits but becomes a spanOr instead of a scoring BooleanQuery, with different scores and order (stock 0.643, 0.630, 0.398, 0.245, 0.245; fixed 1.750, then 1.273 for the other four). "(john)" keeps its hits and, in the probe, its scores, but is returned as a SpanTermQuery instead of the TermQuery fast path. "(-john)" keeps its hits (none), but rewrites to the parser's dummy SpanTermQuery that matches nothing. Scores were compared only for these probe shapes.
• isSingleGroup is a character-level check of the raw text, wrong in three ways. A boost after a space is missed: "(john OR jonathan) ^2" is valid (the grammar skips whitespace before ^) but keeps the sequence reading with the fix, 1 hit. A bracket inside a regexp character class can hide a lone group: "(/a[(a]/ OR cc)" keeps today's reading. It can also join two groups: "(/a[(a]/) (/[)b]b/)" works on main (spanNear([aa, bb], 0, true), 1 of 5 test documents) and becomes one position with the fix (spanOr([aa, bb]), all 5), so a contrived phrase that works today breaks. The token-level check below avoids all three; a maintainer may also prefer a marker for the bracketed clause in the parsed result, through the grammar hook, over any check of the text.
• The sibling's guard alone does not fix this bug: both lone-group tests still fail with only that guard.
• Add a CHANGES entry.

What the checks validated

• Clean scratch worktrees at a9779ef3c193, gradle, seed B71EF714. Stock: the repro fails 2 of 3 and the first new TestComplexPhraseQuery line fails (14 tests, 3 failed), with -Ptests.asserts=true and with the seed's default, which is assertions off. With the fix: the repro passes 3 of 3 and TestComplexPhraseQuery 11 of 11 with the two new lines, with -Ptests.asserts=true and with -Ptests.asserts=false. The whole lucene/queryparser module with the fix and the repro, with the seed's default (assertions off): 31 classes, 536 tests, 1 skipped, 0 failures. checkGoogleJavaFormat, ecjLintMain, ecjLintTest, forbiddenApisMain and forbiddenApisTest pass with the fix, the repro and the two test lines in place.
• With the fixed class shadowed into the stock jars: the repro passes 3 of 3; earlier, the hunt's repro, the independent reproducer's test and the second reviewer's test pass.
• Executed edge cases of the character check (stock vs fix): the spaced boost (fix/probe-edge) and the two regexp-bracket phrases (the fact check's edge-stock and edge-fix runs), as listed under the trade-offs.

Detect the lone group with QueryParserTokenManager (LPAREN, the matching RPAREN, an optional CARAT NUMBER, then EOF) instead of characters, so regexp and escaped terms are single tokens and whitespace before ^ does not matter.

Trade-offs

Same behaviour otherwise; not written or run.

Give Clause() in QueryParser.jj a protected hook for a bracketed sub-query (the default returns it unchanged) that ComplexPhraseQueryParser overrides in pass 2 to keep the group as one clause.

Trade-offs

Exact, but it changes the shared classic grammar and needs the generated parser regenerated. Untested.

Throw a ParseException that suggests dropping the quotes.

Trade-offs

No silent wrong hits, but it breaks queries that are only odd today, and the NOT form would have no query-string spelling left on stock main. Untested.

Document that a phrase that is only a group is read as a sequence of positions.

Trade-offs

Keeps the silent wrong hits and contradicts the bracket rule. Not recommended.

Method: bounded-exhaustive translation validation of the stock jar (semi-formal tier; no model checker, solver or prover).

• The harness parses and runs every 1- and 2-clause phrase over 15 atoms (term, prefix, wildcard, fuzzy, range, regexp, empty prefix) and 90 groups ((x OR y), (x y), (x -y)), plus 3-clause phrases over 13 clauses, with slop 0-2, inOrder true and false and splitOnWhitespace false and true: 159,924 checks on an index of all 1,364 documents of 1-5 tokens over 4 terms.
• The reference, built from the javadoc and the upstream tests, treats each clause as a set of index terms at one position.
• The lone-group shape was first suspected while reading the grammar's Query() and Clause() for the model, and probed by hand. The harness then showed it as one signature: 1,056 of the 1,080 lone-group checks mismatch (516 with inOrder=false, 540 with inOrder=true; the rest coincide by accident) on main and on 10.5.2, while the same 90 groups as one clause of a two-clause phrase give 0 mismatches.
• The harness's other signature (3-clause plain runs) is a different, separately registered classic-parser bug.