Doc-values CONTAINS with several points matches documents that hold only one of them

LatLonDocValuesField.newSlowGeometryQuery(field, CONTAINS, p1, p2, ...) should match the documents whose points include every query point, as LatLonPoint.newGeometryQuery(field, CONTAINS, p1, p2, ...) does with one MUST clause per point. Its javadoc says to wrap it in an IndexOrDocValuesQuery alongside exactly that query, and IndexOrDocValuesQuery requires that "Both provided queries must match the same documents". Instead LatLonDocValuesQuery.contains() keeps a single flag per document and sets it as soon as any document point equals any query point, so it computes an OR: on four documents A = {P1}, B = {P2}, C = {P1, P2}, D = {P3}, CONTAINS(P1, P2) returns [C] on the points path and [A, B, C] on the doc-values path, the INTERSECTS hit set. The wrapper's answer then depends on which side runs: with 2,000 more one-point documents it returns [C] alone, A under id:A AND, and its explain() reports a match for A. No error; default configuration; extra hits only. LUCENE-9641 (14009f4424d, 8.8.0) added the AND and the OR in the same commit; every release since is affected, and a one-method fix that requires every query point passes the repro and the closest existing suites.

• Point fields: LatLonPoint indexes a location in a points (BKD) index; LatLonDocValuesField stores it as doc values, read one document at a time. A document may hold several points on one field.
• CONTAINS on points: newGeometryQuery(field, CONTAINS, p1, ..., pk) and newSlowGeometryQuery(field, CONTAINS, p1, ..., pk) accept only Point geometries for CONTAINS (others give MatchNoDocsQuery, LatLonDocValuesField.java:255-262). A query point is contained when a document point equals it on the encoding grid: the query point is rounded up to the grid (Point2D.java:168-181) and compared with exact == (Point2D.java:56-57).
• IndexOrDocValuesQuery: wraps a points query and an equivalent doc-values query and picks a side per segment: the doc-values one only when the points cost shifted right by 3 (divided by 8, rounded down) is greater than the lead clause's cost, cost() >>> 3 > leadCost (IndexOrDocValuesQuery.java:183-193), otherwise the points one; explain() and matches() always use the doc-values one (:153-163). "Both provided queries must match the same documents" (:61-62).

1. LatLonDocValuesQuery.contains() (LatLonDocValuesQuery.java:244-273) builds one component per query point (:245-248), because a multi-component tree cannot answer withinPoint (ComponentTree.java:284-289).
2. Per document it starts with answer = DISJOINT (:252) and, for every (document point, query point) pair, sets answer to any relation other than DISJOINT (:261-262); it returns answer == CANDIDATE (:266).
3. A point component answers only CANDIDATE or DISJOINT (Point2D.java:126-127), so the NOTWITHIN exit never fires and the document matches as soon as one of its points equals one query point: an OR.
4. LatLonPoint.newGeometryQuery sends CONTAINS to makeContainsGeometryQuery, one MUST LatLonPointQuery(CONTAINS, point) per point (LatLonPoint.java:337-354): an AND. LatLonShape and XYShape also AND one clause per geometry.

P1 = 22.5° N 45° E, P2 = 45° N 135° E, P3 = 22.5° S 90° W (exact on the grid); A = {P1}, B = {P2}, C = {P1, P2}, D = {P3}. CONTAINS(P1): [A, C] on both paths. CONTAINS(P1, P2): points [C], doc values [A, B, C], the same as INTERSECTS(P1, P2). With 2,000 more one-point documents (alternately at P1 and P2): points and the wrapper alone [C], doc values 2,003 hits instead of 1, FILTER(id:A) + FILTER(wrapper) [A], wrapper explain(A).isMatch() true. The same on main and 10.5.2 (assertions on and off), 10.0.0 and 9.12.3.

• Who is exposed. Applications that call newSlowGeometryQuery(field, CONTAINS, p1, p2, ...) directly (for example on a field with doc values but no points index), or the documented pair IndexOrDocValuesQuery(LatLonPoint.newGeometryQuery(...), newSlowGeometryQuery(...)) when a selective lead clause makes it run the doc-values side, or explain()/matches() of that pair, which always use the doc-values side, so explain() can report a match that search() does not return.
• Default, not opt-in. Default IndexWriterConfig, codec and searcher; both factories are public and not deprecated (IndexOrDocValuesQuery is @lucene.experimental). Four documents suffice for the doc-values query alone; the wrapper runs the doc-values side only under a lead clause more than 8 times cheaper than the points query (exactly: cost() >>> 3 > leadCost).
• What you see. Extra hits, silently: documents that hold some but not all of the query points. The doc-values CONTAINS(P1, ..., Pk) returns the INTERSECTS hits. Documents that hold all points still match.
• Query cache. A cached entry is built from the points side (LRUQueryCache.java:609 with IndexOrDocValuesQuery.java:196-201), so where a query cache is in use the same query can change its answer once it is cached (read from the code, not executed). That needs a cache configured explicitly (main's IndexSearcher has none by default), a segment the cache accepts (the default LRUQueryCache skips segments under 10,000 documents) and a query used often enough for the caching policy; neither repro index qualifies.
• Not affected. Single-point CONTAINS, the other relations, the points-only query; XYDocValuesField has no relation-taking factory.
• How likely. Rare: "documents that hold all of these locations" is a niche query, and the searches of 2026-10-27 found no user report since 8.8.0. A downstream remark (code reading only, not executed): one downstream search engine builds exactly this pair for its geo-point field and uses the doc-values query alone for doc-values-only fields.

# Lucene main 645d4fe14a20, assertions on (-ea), seed DEADBEEF: 1 test(s) run, 1 failed
    => java.lang.AssertionError: expected:<0> but was:<1>
       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.document.TestLatLonDocValuesContainsTwoPoints.testDocWithOnlyOneOfTwoPointsDoesNotMatch(TestLatLonDocValuesContainsTwoPoints.java:44)

• The pairing is documented. LatLonDocValuesField.java:232-238: "It is best used wrapped in an {@link IndexOrDocValuesQuery} alongside a {@link LatLonPoint#newGeometryQuery(String, ShapeField.QueryRelation, LatLonGeometry...)}". IndexOrDocValuesQuery.java:61-62: "Both provided queries must match the same documents and give the same scores." The code relies on it: "Both index and dv query should return the same values" (:212-213).
• CONTAINS over several geometries is an AND elsewhere. LatLonPoint.java:343-354, LatLonShape.java:354-370 and XYShape.java:263-267 add one MUST clause per geometry.
• One commit added both. 14009f4424d (LUCENE-9641, 2021-01-08): "Equivalent to LatLonShape, LatLonPoint can be queried now using spatial relationships." It added the AND and the OR together, with no comment on a difference; issue #10680 states the goal that LatLonShape and LatLonPoint return the same results. contains() is unchanged since.
• The author's intent elsewhere. The LUCENE-9641 author's downstream test expects 0 hits for CONTAINS(MULTIPOINT(a, b)) on a document holding only a (it runs the points side). Their open PR #12162 documents CONTAINS for newSlowGeometryQuery as "one or more points of the field matches all the provided LatLonGeometry".
• The test gap. BaseSpatialTestCase.java:562-565 sends only queryPoints[0] for CONTAINS, so the two paths were never compared with several points. No test asserts the OR.

The strongest case for "intended": LatLonPoint.newGeometryQuery's javadoc says "@return query matching points within at least one geometry" (LatLonPoint.java:322), which reads like OR; the pairing is only "best used"; a committer has said relations make little sense for points; and no javadoc spells out multi-point CONTAINS. Independent reviews by another model family (OpenAI GPT-5.6, refute lens and intended lens) rated this moderate; the devil's advocate rejected it point by point; the adjudication called it weak. A maintainer may also cite the IndexOrDocValuesQuery class note ("only works well with point range/exact queries and their equivalent doc values queries", IndexOrDocValuesQuery.java:51-52).

Why it fails: that @return line dates from LUCENE-9552, before relations existed, and the same method builds an AND for CONTAINS, so it does not follow it either. The javadoc names the exact counterpart with the same arguments, and the wrapper forbids operands that disagree. The committer's remark is about API design; both factories are public and shipped since 8.8.0. Under OR, CONTAINS would duplicate INTERSECTS. The IndexOrDocValuesQuery class note is about performance ("works well") and does not relax "must match the same documents"; newSlowGeometryQuery's own javadoc recommends this wrapping. #12162's wording is not literally the per-point AND (read literally, one document point equal to every query point, it would reject C too), but neither reading admits A or B, which hold only one of the two points. Verdict: a defect.

One fix was built and validated through gradle; the hunt validated a variant of it; two alternatives were not built.

In LatLonDocValuesQuery.contains(): keep one flag per query component in a boolean[] allocated once per iterator, reset it per document, count the components found, and match only when all are found; NOTWITHIN still rejects at once. 1 file, +11/-6.

final boolean[] contained = new boolean[component2Ds.size()];
// in matches():
Arrays.fill(contained, false);
int numContained = 0;
// for each document point (lat, lon) and each query component c:
Component2D.WithinRelation relation = component2Ds.get(c).withinPoint(lon, lat);
if (relation == Component2D.WithinRelation.NOTWITHIN) {
  return false;
} else if (relation == Component2D.WithinRelation.CANDIDATE && contained[c] == false) {
  contained[c] = true;
  numContained++;
}
// after the loop:
return numContained == contained.length;

Trade-offs

Same loop and cost as today plus an Arrays.fill of k booleans per document (k = number of query points); no allocation per document. The array is created once per scorer supplier (per segment or intra-segment partition, and also when IndexOrDocValuesQuery then runs the points side, since it creates both suppliers first); the stock code already allocates a list and one Component2D per query point there. One-point CONTAINS behaves as before. The diff keeps the full loop; it could return true as soon as every point is found, since only Point geometries reach contains() and they never return NOTWITHIN. No benchmark was run.

What the checks validated

• Scratch worktree of a9779ef3c193, gradle, JDK 25: stock + the new test fails 2 of 2 with assertions on and off; + fix it passes 2 of 2 with assertions on and off.
• With the fix, the existing TestLatLon*, TestXY* and TestIndexOrDocValuesQuery: 31 suites, 224 tests, 0 failures, 25 skipped (24 @Nightly), assertions on and off (gradle's totals of 32 suites and 226 tests include a first version of the new test); the two doc-values point suites with -Ptests.nightly=true: 10 tests, 0 failures; :lucene:core:check -x test passes.
• Standalone runner with the fix: the finder's test, the independent reproducer's 4 tests, the devil's advocate's probe and the cross-model reviewers' own tests pass.
• Not run: the full Lucene test suite, and any benchmark.

Functionally the same as the recommended option, but allocates the array for every candidate document.

Trade-offs

One small allocation per candidate document; the recommended option avoids it.

What the checks validated

Through the standalone runner: the finder's, the independent reproducer's, the devil's advocate's and the cross-model reviewers' tests pass, and 49 of 49 tests of four existing doc-values and point suites.

In newSlowGeometryQuery, for CONTAINS with several points, return a ConstantScoreQuery over one MUST LatLonDocValuesQuery(CONTAINS, point) per point, mirroring makeContainsGeometryQuery.

Trade-offs

Symmetric and obviously equivalent, but each clause reads the document's doc values again (k reads per document), the query's structure changes (toString, equals), and contains() stays an OR for any other caller.

Declare that CONTAINS with several points on the doc-values path matches any of them.

Trade-offs

Makes it identical to INTERSECTS and still breaks the IndexOrDocValuesQuery contract unless the points CONTAINS changes too, which would break parity with LatLonShape, the goal of LUCENE-9641.

Method: bounded-exhaustive differential testing against an exact reference (the hunt's semi-formal tier).

• The hunt unit compared Lucene's shape and point relation queries with JTS 1.20 DE-9IM relations on the decoded coordinates, with a strict and a permissive boundary band per relation, so a boundary convention cannot show up as a bug.
• Inputs: lattices of 6 x 6 grid-exact coordinates in nine families (around the origin, the poles and the antimeridian, and XY), every point, segment and small polygon of the lattice plus random ones, multi-part and multi-point documents, and 2-3-point CONTAINS queries, each document indexed as LatLonShape, LatLonPoint and LatLonDocValuesField.
• At scale 1 the doc-values point path disagreed with the reference and with both index paths in 606 (document, query) pairs in six of the seven LatLon families (490 with a multi-point document, 116 with a one-point document) and 585 in the dateline family, all multi-point CONTAINS; the index paths agreed with the reference. The root cause was read from LatLonDocValuesQuery.contains() and reduced to a public-API JUnit.
• The same harness also explained every other mismatch by known bugs or documented conventions.