Geo3DPoint polygon and path queries report the same ramBytesUsed() whatever the shape size, so a query cache can far exceed its RAM budget

Geo3DPoint.newPolygonQuery, newLargePolygonQuery and newPathQuery build a PointInGeo3DShapeQuery, which implements Accountable. Its ramBytesUsed() adds RamUsageEstimator.sizeOfObject(shape) and sizeOfObject(shapeBounds); no GeoShape or XYZBounds is Accountable, so each falls back to the fixed 256 bytes that RamUsageEstimator assigns to unknown objects, and every such query reports the same size whatever its shape, 592 bytes on a field named f with compressed oops (624 without): 4.9x too low for an 8-edge polygon, 47x for 99 edges, about 2,300x for a 2,000-edge large polygon (1,360,960 bytes retained). LRUQueryCache charges a cached Accountable query exactly this value, so its maxRamBytesUsed budget stops bounding these keys and only its entry limit does. Search hits are always correct. The code dates from LUCENE-8855 (8.2.0) and is unchanged on main and in 10.6.0.

1. The factories. Geo3DPoint.java:168-172 (newPolygonQuery, documented for "a limited number of edges (less than 100)", :157-159), :186-190 (newLargePolygonQuery, "optimized for very large numbers of polygon edges", :175-177) and :203-212 (newPathQuery, no documented limit) build a GeoShape and call newShapeQuery (:241-243): new PointInGeo3DShapeQuery(field, shape). newDistanceQuery and newBoxQuery go the same way, but their shapes do not grow with the input.
2. The query. PointInGeo3DShapeQuery.java:44 implements Accountable; it keeps the shape and an XYZBounds (:48-58), and isCacheable always returns true (:113-116).
3. The estimate. :160-166: BASE_RAM_BYTES + sizeOfObject(field) + sizeOfObject(shape) + sizeOfObject(shapeBounds).
4. The fallback. RamUsageEstimator.java:393-395: sizeOfObject(Object) passes UNKNOWN_DEFAULT_RAM_BYTES_USED (256, :82-86) as the default; the type switch (:407-444) knows Accountable, strings, primitive arrays, queries, maps and collections, and any other object gets the default (:435-441). A GeoComplexPolygon, GeoConvexPolygon or GeoStandardPath and an XYZBounds are none of those, so 512 of the 592 bytes are the two fixed guesses.
5. The cache. LRUQueryCache.java:465-471 charges RamUsageEstimator.sizeOf(query, 32) ("Deep RAM cost of the query object itself"), which returns ramBytesUsed() for an Accountable query (RamUsageEstimator.java:378-386); the charge is added when a query is first cached in a partition (LRUQueryCache.java:1121-1124, through onQueryCache, :1037-1039), and eviction runs only while size > maxSize || this.ramBytesUsed > maxRamBytesUsed (:1214-1220). 10.5.2 and 10.6.0 charge LINKED_HASHTABLE_RAM_BYTES_PER_ENTRY + ramBytesUsed() (10.6.0 LRUQueryCache.java:428-433).
6. Why these queries get cached. UsageTrackingQueryCachingPolicy.java:33-54: any class named Point*Query is "costly" and is cached after 2 uses (:122-125).

Retained heap measured with the test framework's RamUsageTester, not counting the shared PlanetModel (compressed oops; on 645d4fe14a20):

One segment of 100 points, new LRUQueryCache(1000, 1 MiB, ctx -> true, Float.POSITIVE_INFINITY, partitions, null) with an always-cache policy, 8 different 2,000-edge newLargePolygonQuery filters each run once as a ConstantScoreQuery: 8 entries, 0 evictions, cache.ramBytesUsed() = 6,080 bytes (8 x 760: 592 for each query key, 168 for the entry and its cached doc id set), while the 8 query keys retain 10,888,352 bytes (with 1 and with 16 partitions); 296 hits in total, the same as with the fix.

• Who. Applications that filter or count with Geo3DPoint polygon, large-polygon or path queries (the spatial3d module, @lucene.experimental) on an index searched through a query cache.
• 8.2.0 to 10.6.0: by default. IndexSearcher installs one static LRUQueryCache(1000, min(32 MB, heap / 20)) for every searcher in the JVM (10.6.0 IndexSearcher.java:95-100), caching only on segments of at least 10,000 documents that also hold more than half the average documents per segment (10.6.0 LRUQueryCache.java:175-177, :188-196), with UsageTrackingQueryCachingPolicy, which caches these queries after 2 uses.
• main and branch_11x: "Caching is disabled by default" (IndexSearcher.java:82-84); only applications that install a cache are hit.
• How much. The under-count grows by about 280 bytes per edge for newPolygonQuery, 680 for newLargePolygonQuery and 1,450 per path point (310, 810 and 1,770 without compressed oops). The study's heap probe, on main a9779ef3c19 and 10.5.2 (the files involved are unchanged since): with a 256 MB heap and LRUQueryCache(1000, 13.4 MB) plus the stock caching policy, distinct 3,000-edge newLargePolygonQuery filters, each sent twice, ran the JVM out of heap after 128 polygons while the cache reported 415,744 bytes and had evicted nothing; without a cache all 400 ran. With a 3 GB heap only the entry limits held: on main the cache (16 partitions of at most 62 entries) ended at 964 entries after 136 evictions, all driven by the entry count (it counted 3.1 MB of its 32 MiB budget), holding 1,986,237,856 bytes; the 10.5.2 default cache ended at its maxSize of 1,000 entries, holding 2,057,955,792 bytes.
• What it does not do. Hits were identical with and without a cache in every run; nothing is bypassed, exposed or corrupted. Small polygons are off by little in absolute terms (8 edges: about 2.3 KB).
• How likely: rare. It takes shapes with hundreds to thousands of vertices, repeated often enough to be cached, in enough distinct copies to matter for the heap.

The two queries differ only in the number of edges and come from the same factory, the one documented for very large polygons. The assertion is the weakest one any heap estimate must pass, so it needs no tolerance. The retained sizes quoted on this page come from a separate diagnostic with RamUsageTester, not from the repro.

Release jars: the test fails on 10.6.0 with assertions on and off; the finder's earlier tests failed the same way on 8.2.0 to 10.5.2.

Regression test: this same test; it passes with the recommended fix and fits as one more method of spatial3d's TestGeo3DPoint.

cp $REPRO/TestGeo3DShapeQueryRamBytesUsed.java $LUCENE/lucene/spatial3d/src/test/org/apache/lucene/spatial3d/
cd $LUCENE && ./gradlew :lucene:spatial3d:test --tests TestGeo3DShapeQueryRamBytesUsed -Ptests.seed=DEADBEEF
# the same result with -Ptests.asserts=false

# gradle, stock 645d4fe14a20, -Ptests.seed=DEADBEEF (assertions on; the same with -Ptests.asserts=false)
TestGeo3DShapeQueryRamBytesUsed > testRamBytesUsedGrowsWithPolygonSize FAILED
    java.lang.AssertionError: 8 edges: 592 bytes, 2000 edges: 592 bytes
        at __randomizedtesting.SeedInfo.seed([DEADBEEF:F9C51CF1D77A9822]: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.spatial3d.TestGeo3DShapeQueryRamBytesUsed.testRamBytesUsedGrowsWithPolygonSize(TestGeo3DShapeQueryRamBytesUsed.java:44)

# the numbers behind it (a diagnostic test on the same build, RamUsageTester, PlanetModel excluded; not the repro)
newLargePolygonQuery    8 edges: reported 592, retained     6,400
newLargePolygonQuery 2000 edges: reported 592, retained 1,360,960
# with the fix: reported 9,560 and 2,049,368; the test passes

• The contract. Accountable.java:34-40: "Returns an estimate of the JVM heap memory used by this object in bytes." LRUQueryCache.java:137-140: the cache holds "at most maxSize cache entries ... with at most maxRamBytesUsed bytes of memory"; the class javadoc says it evicts "in order to remain under a given maximum size and number of bytes used" (:60-62).
• The fallback's own definition. RamUsageEstimator.java:82-86: "Approximate memory usage that we assign to all unknown objects - this maps roughly to a few primitive fields and a couple short String-s."
• The introducing change's goal. LUCENE-8855 (#9898), the 2019-06-19 patch note that introduced the design that was committed: it "adds Accountable to Queries that may be much larger than the default estimate (10x or more)". On the same issue Adrien Grand wrote: "For the caching use-case I suspect it's better to overestimate memory usage a bit?"
• Upstream tests. TestPointQueries.java:2653-2669 and TestTermInSetQuery.java:377-389 hold ramBytesUsed() within 5% of RamUsageTester.ramUsed(query); TestLRUQueryCache.testCachingAccountableQuery (:702-726) checks that the cache reflects big Accountable queries. No spatial3d test calls ramBytesUsed.
• Precedent. #16405 ("PointInSetQuery#ramBytesUsed under-reports memory", type:bug, fixed by #16406); #15097 ("Incorrect size estimation of BooleanQuery in LRUQueryCache causing heap exhaustion", fixed by #15124, a fix that does not reach Accountable queries).

The strongest case: ramBytesUsed() is only an estimate and sizeOfObject documents its 256-byte fallback; on LUCENE-8855 its author wrote "It's not a strict calculation anyway"; Accountable is @lucene.internal and Geo3DPoint, the query and LRUQueryCache are @lucene.experimental; GeoShape is an open interface, so no estimate fits every shape; caching is off by default on main; and on the same issue Adrien Grand first argued against making queries Accountable at all, naming Weight#isCacheable (keep large queries out of the cache) or a rough visitor-based estimate as alternatives. Open issue #16113 also proposes counting constructor inputs "only to the extent they are owned".

Why it fails: neither Accountable nor the cache promises an accuracy, but the value is not rough, it is constant; it does not move when the edge count grows 250-fold (the retained heap about 213-fold). The constant is documented for a few primitive fields, and the change that wrote this method aimed at queries 10x or more above the default. Adrien Grand then proposed the design that was merged themselves (ramBytesUsed() for Accountable queries, a constant for the rest), and this class was made Accountable under it. The isCacheable route was not taken either: isCacheable is always true, so large shapes neither opt out nor get sized. An open GeoShape explains the fallback for user shapes, not for the shapes Geo3DPoint builds itself; under #16113 those still count, since the factory builds each shape for that query alone and the cache keeps it alive. The verifier panel rated the case moderate and convincing to none.

Option A was built and run through gradle. B (make the GeoShape classes Accountable) is potentially the most accurate but a much larger change, not built; C (return false from isCacheable for large shapes, one of the two alternatives Adrien Grand named on LUCENE-8855 before proposing the merged design) stops the cache overrun but leaves the value wrong and can complement A; D (document it) leaves the budget broken. Workarounds that need no fix: cap the vertices per shape for request-built queries, install a QueryCachingPolicy that declines these queries, or run without a query cache (the default on main).

The polygon, large-polygon and path factories know how many vertices they were given (holes included). They pass vertices x bytes per vertex to a new package-private PointInGeo3DShapeQuery constructor, which uses it instead of sizeOfObject(shape), never less than the old 256. newShapeQuery(field, shape) and the existing two-argument constructor keep sizeOfObject(shape), which already uses a caller's shape's ramBytesUsed() when that shape is Accountable. 2 files, +35/-4.

// Geo3DPoint: per-vertex heap estimates for the shapes built below (comment shortened)
private static final long POLYGON_BYTES_PER_VERTEX = 512;
private static final long LARGE_POLYGON_BYTES_PER_VERTEX = 1024;
private static final long PATH_BYTES_PER_POINT = 2048;
...
return new PointInGeo3DShapeQuery(
    field, shape, numVertices(polygons) * LARGE_POLYGON_BYTES_PER_VERTEX);

// PointInGeo3DShapeQuery.ramBytesUsed()
return BASE_RAM_BYTES
    + RamUsageEstimator.sizeOfObject(field)
    + shapeRamBytesUsed
    + RamUsageEstimator.sizeOfObject(shapeBounds);

Trade-offs

• How close. Each constant is the next power of two above the measured heap per edge or point for shapes of 8 or more edges or 20 or more path points (about 280-430, 680-960 and 1,400-1,770 bytes, with and without compressed oops). Smaller shapes cost more per edge (3 edges: up to 643 and 1,232 bytes) but are still over-reported. With the fix every measured polygon and path of 3 or more vertices reports 1.16x to 1.86x its retained heap on both layouts (8 edges: 9,560 vs 6,408 bytes; 2,000 edges: 2,049,368 vs 1,360,968); the larger gaps are short paths, 1 point (2,392 vs 624) and 2 points (4,440 vs 1,888). No measured polygon or path is under-reported, in line with Adrien Grand's remark on LUCENE-8855, made about the constant for unknown queries, that for caching it is "better to overestimate".
• Constants. They follow today's spatial3d.geom internals and would need re-measuring if those change; a RamUsageTester test with a tolerance, like TestPointQueries.testRamBytesUsedMatchesActualWithinTolerance, could guard them.
• Tiling fallback. newPolygonQuery falls back to GeoComplexPolygon when it cannot tile the polygon (GeoPolygonFactory.java:352-362), about 680 bytes per vertex, so 512 under-counts that case by about 1.3x.
• Unchanged. Shapes that callers pass to newShapeQuery, and circles and boxes, are priced as before.
• Effect on the cache. Large shapes now count against the budget: in the cache diagnostic each 2,000-edge key is charged about 2 MB, more than the whole 1 MiB budget, so the cache evicts all 8 (0 entries, 8 evictions, the same 296 hits). By arithmetic (not run), the 10.x default cache (one budget of at most 32 MiB) has room for about 16 such keys before other overhead, instead of up to 1,000; on main the budget is split across partitions, so a key larger than one partition's share is not kept. Re-running an evicted filter costs one BKD intersection per segment.
• Cost. One pass over the input vertex arrays when the query is built.

What the checks validated

Applied to a scratch worktree of 645d4fe14a20 and run through gradle with OpenJDK 25.0.3, seed DEADBEEF (2026-10-31; the worktree was removed afterwards):

• stock: the minimal test fails with assertions on and off;
• with the fix: the minimal test passes with assertions on and off;
• the finder's original two tests: the size test (reported within 2x of retained for 8- and 99-edge polygons, a 2,000-edge large polygon and a 200-point path) passes; the cache test now fails at its first assertion, which expects all 8 keys to stay cached (cache entries=0 evictions=8): the cache evicts them, the intended effect, so that test is not a regression test for the fix;
• the closest suite TestGeo3DPoint: 17 tests, 0 failures, 2 skipped;
• the whole :lucene:spatial3d:test: 19 classes, 181 tests, 0 failures, 3 skipped;
• checkGoogleJavaFormat, ecjLintMain, forbiddenApisMain and renderJavadoc for spatial3d pass.

Implement ramBytesUsed() in GeoComplexPolygon, GeoConvexPolygon, GeoConcavePolygon, the composite shapes and GeoStandardPath (and other shapes as needed) from their arrays, edges, planes and trees; sizeOfObject(shape) then picks it up with no change to the query.

Trade-offs

Potentially the most accurate option (not built or measured), with no constants, and it also covers newShapeQuery with built-in shapes. A much larger change across spatial3d.geom (the large polygon alone holds edges, planes and three search trees), with a RamUsageTester test per shape type, and an ownership rule so that shared objects (the PlanetModel, parts that composite shapes share) are not counted twice. Not run.

Return false from isCacheable (PointInGeo3DShapeQuery.java:113-116) for large shapes, for example above a vertex count the factories pass. Adrien Grand named this route on LUCENE-8855 ("rely on the existing Weight#isCacheable logic, which disables caching on large queries") as one of two alternatives to making queries Accountable, before proposing the compromise that was merged.

Trade-offs

Stops the cache overrun without constants, but ramBytesUsed() stays wrong, the minimal test still fails, and repeated large filters are re-evaluated every time. Can be combined with the recommended option. Not run.

Say in the javadoc that the estimate leaves out the shape.

Trade-offs

The cache budget stays broken. Not run.

Method: semi-formal (the hunt's tier for a systematic differential against an independent measurement). The unit hunted identity and accounting defects outside query semantics.

• Differential. A harness built 26 constructions of 12 Accountable query classes through public APIs (the join module's GlobalOrdinalsQuery and GlobalOrdinalsWithScoreQuery were not covered) and compared Accountable#ramBytesUsed() with the heap each query object retains (the test framework's RamUsageTester, not following readers, directories or the PlanetModel singleton), before and after a search through an always-caching LRUQueryCache. The AutomatonQuery NFA case of LFV-192 served as a positive control.
• Signal. 11 of the 26 were flagged (more than 2x under-reported): all 9 Geo3DPoint polygon and path constructions (4.9x to 5,745x), the AutomatonQuery NFA positive control (3.2x) and the numeric score join (2.4x, the separate LFV-402). The others were at most 1.9x under (the Geo3DPoint box), most within 1.1x.
• Confirmation. Reading PointInGeo3DShapeQuery.ramBytesUsed() showed the sizeOfObject(shape) fallback, and a JUnit on the stock jars failed on main, 10.5.2 and 9.12.3. A cross-model review's objection (a 2,000-edge newPolygonQuery exceeds its documented "less than 100" edges) led to using newLargePolygonQuery for large polygons. A 2026-10-29 minimization cut the repro to the one test above.