SortedSetDocValues and taxonomy facets size the getTopDims dimension queue from topNDims, so getTopDims(Integer.MAX_VALUE, n) throws where getAllDims(n) returns every dim

Facets#getTopDims(topNDims, topNChildren) is documented to return the same as getAllDims(topNChildren) cut to its first topNDims dims, and the default implementation does exactly that, capped with Math.min(topNDims, allResults.size()) (Facets.java:61-62, :69-72). The faster overrides used by SortedSetDocValues facets (AbstractSortedSetDocValueFacetCounts.java:153-157) and taxonomy facets (TaxonomyFacets.java:610-614) instead create PriorityQueue.usingComparator(topNDims, ...) before they look at any dim. Lucene's PriorityQueue allocates topNDims + 1 slots up front and refuses 2,147,483,631 or more.

So getTopDims(Integer.MAX_VALUE, 10) throws IllegalArgumentException on an index with 2 dims in SortedSetDocValuesFacetCounts, ConcurrentSortedSetDocValuesFacetCounts, FastTaxonomyFacetCounts, TaxonomyFacetIntAssociations and TaxonomyFacetFloatAssociations, while getAllDims(10) and the default getTopDims return both dims. Below the limit results are right but each call reserves the slots: about 64 MiB at 2^24 for 2 dims. Default configuration, any index size, assertions on and off, once a hit was counted (ConcurrentSortedSetDocValuesFacetCounts throws even for a query that matches nothing); every release since getTopDims was added in 9.2.0, through 10.6.0 and main. The fix is one Math.min per site.

1. Contract. Facets#getTopDims (Facets.java:59-68): "Results should be the same as calling getAllDims and then only using the first topNDims. [...] Sub-classes may want to override this implementation with a more efficient one if they are able." The default body is allResults.subList(0, Math.min(topNDims, allResults.size())) (:69-72). validateTopN rejects only topN <= 0 (:80-84). The elided sentence asks that dims be configured as requiring dim counts so that counts are accurate (:62-64); neither override reads that setting before it sizes the queue.
2. SSDV override. AbstractSortedSetDocValueFacetCounts.getTopDims (:143) validates both arguments (:144-145), returns an empty list when hasCounts() is false (:147-149; never for ConcurrentSortedSetDocValuesFacetCounts, whose hasCounts() always returns true, ConcurrentSortedSetDocValuesFacetCounts.java:80-84), then creates PriorityQueue.usingComparator(topNDims, ...) (:153-157; the throw frame is :154). Only then does it iterate state.getDims() (:162), adding a dim while pq.size() < topNDims (:201-202). SortedSetDocValuesFacetCounts and ConcurrentSortedSetDocValuesFacetCounts inherit it.
3. Taxonomy override. TaxonomyFacets.getTopDims (:595) checks topNDims <= 0 || topNChildren <= 0 (:596-598), returns empty while its counters are uninitialized, i.e. no segment with hits was counted (:600-602), then creates PriorityQueue.usingComparator(topNDims, ...) (:610-614; throw frame :611) before it walks the root's children (:620). FastTaxonomyFacetCounts, TaxonomyFacetIntAssociations and TaxonomyFacetFloatAssociations inherit it.
4. The queue. The PriorityQueue constructor throws IllegalArgumentException for maxSize >= ArrayUtil.MAX_ARRAY_LENGTH, commented "Throw exception to prevent confusing OOME" (PriorityQueue.java:121-125), and otherwise allocates new Object[maxSize + 1] (:129, :134). MAX_ARRAY_LENGTH is Integer.MAX_VALUE - NUM_BYTES_ARRAY_HEADER (ArrayUtil.java:33-34), 2,147,483,631 on this JVM. The class javadoc says it pre-allocates (:34); it is @lucene.internal (:39).
5. The cap exists next door. The taxonomy child queue of the same class is new TopOrdAndIntQueue(Math.min(taxoReader.getSize(), topN)) (TaxonomyFacets.java:250-251). Only these two classes override getTopDims; every other Facets implementation inherits the capped default.

Bytes: what one call allocates on the calling thread (thread allocation counter), the minimum of 5 calls after 20 warm-up rounds, on this JVM (compressed references on). With the fix, Integer.MAX_VALUE returns a and b in all five classes and allocates the same as 2^24. getTopDims(2147483631, 10) throws the same way. An independent reproducer got an OutOfMemoryError for getTopDims(1 << 28, 5) with a 512 MB heap; an earlier probe measured 381 MiB at 10^8.

• Who is hit. Callers of getTopDims(topNDims, n) on SortedSetDocValuesFacetCounts, ConcurrentSortedSetDocValuesFacetCounts, FastTaxonomyFacetCounts, TaxonomyFacetIntAssociations or TaxonomyFacetFloatAssociations with Integer.MAX_VALUE, or any topNDims from 2,147,483,631 up. For a query that matches no document, SortedSetDocValuesFacetCounts and the taxonomy classes return an empty list before they build the queue (AbstractSortedSetDocValueFacetCounts.java:147-149, TaxonomyFacets.java:600-602); ConcurrentSortedSetDocValuesFacetCounts reports counts unconditionally (ConcurrentSortedSetDocValuesFacetCounts.java:80-84), so it throws even then, where its getAllDims(10) returns an empty list (executed). Code written against an implementation that keeps the capped default getTopDims (range, long-value and string-value counts inherit it; the default itself was executed through a wrapper over the SortedSetDocValues and taxonomy counts, not through those classes) meets it on the first call.
• Large but legal topNDims. Values such as 2^24 used as "all" return correct results but reserve topNDims + 1 slots per call however few dims exist: about 64 MiB at 2^24 on the tested JVM (executed on every release point from 9.2.0 to main), 381 MiB at 10^8; an independent reproducer got an OutOfMemoryError at 2^28 with a 512 MB heap.
• Default vs opt-in. Default FacetsConfig, codec and IndexSearcher; no setting is needed. Facets is @lucene.experimental; getTopDims dates from 9.2.0. The trigger is the topNDims value.
• Who is not. getAllDims(n), the obvious call for all dims, works (on SSDV keep n bounded too: getAllDims(Integer.MAX_VALUE) hits the child-queue bug LFV-994). Ordinary topNDims values give correct results.
• Severity. Loud: an exception for that call; no wrong results, nothing written to the index.
• How likely. Rare: getAllDims is the natural call for "all dims", only values from 2,147,483,631 throw, and no public report was found. But Integer.MAX_VALUE is the usual Java "no limit" value, and Yuting Gan, who wrote getTopDims, said on #843, a range-facet getTopChildren change, that users who want all children can specify a large top-n; for dims that is an analogy.

The test indexes one document with SortedSetDocValuesFacetField("a", "x") and SortedSetDocValuesFacetField("b", "y"), counts MatchAllDocsQuery with SortedSetDocValuesFacetCounts, and asserts that getTopDims(Integer.MAX_VALUE, 10) equals getAllDims(10). Single thread, deterministic: the same failure for seeds DEADBEEF and 5EED0983; it fails with assertions on and off, on main and on the 10.6.0 release jars.

• The IllegalArgumentException is caught once and rethrown as an AssertionError that states expected against actual (the exception stays the cause); a plain assertEquals fails too.
• It covers the SortedSetDocValues site. The taxonomy site is the same expression; the probe and the earlier checks executed it in all three taxonomy classes. If you fix both sites in one PR, a taxonomy twin of this method (FastTaxonomyFacetCounts over FacetField("a", "x") and FacetField("b", "y")) covers the second.
• Style: new MatchAllDocsQuery() is deprecated on main and in 10.6.0. The runs used the constructor; it does not affect the failure.
• Set -Ptests.asserts explicitly: with a fixed seed and no value, Lucene's build picks the assertion mode from the seed.

TestGetTopDimsAllDims > testGetTopDimsMaxValueReturnsAllDims FAILED
    java.lang.AssertionError: expected getAllDims(10) = [dim=a path=[] value=1 childCount=1
      x (1)
    , dim=b path=[] value=1 childCount=1
      y (1)
    ], but: java.lang.IllegalArgumentException: maxSize must be >= 0 and < 2147483631; got: 2147483647
        at __randomizedtesting.SeedInfo.seed([DEADBEEF:96CD7C7B56D70AB5]:0)
        at org.apache.lucene.facet.sortedset.TestGetTopDimsAllDims.testGetTopDimsMaxValueReturnsAllDims(TestGetTopDimsAllDims.java:56)

        Caused by:
        java.lang.IllegalArgumentException: maxSize must be >= 0 and < 2147483631; got: 2147483647
            at org.apache.lucene.core@11.0.0-SNAPSHOT/org.apache.lucene.util.PriorityQueue.<init>(PriorityQueue.java:123)
            at org.apache.lucene.core@11.0.0-SNAPSHOT/org.apache.lucene.util.PriorityQueue.<init>(PriorityQueue.java:80)
            at org.apache.lucene.core@11.0.0-SNAPSHOT/org.apache.lucene.util.PriorityQueue.usingComparator(PriorityQueue.java:63)
            at org.apache.lucene.facet.sortedset.AbstractSortedSetDocValueFacetCounts.getTopDims(AbstractSortedSetDocValueFacetCounts.java:154)
            at org.apache.lucene.facet.sortedset.SortedSetDocValuesFacetCounts.getTopDims(SortedSetDocValuesFacetCounts.java:57)
            at org.apache.lucene.facet.sortedset.TestGetTopDimsAllDims.testGetTopDimsMaxValueReturnsAllDims(TestGetTopDimsAllDims.java:53)

# main 645d4fe14a20, gradle, -Ptests.seed=DEADBEEF -Ptests.asserts=true; the same with -Ptests.asserts=false.
# On the 10.6.0 release jars (-ea and -da) the frames are AbstractSortedSetDocValueFacetCounts$1.<init>(...:153) and getTopDims(...:152).

• The contract was asked for in review. Greg Miller (gsmiller) asked in the #747 review for the sentence "results should be the same as calling getAllDims and then only using the first topNDims, but may be more efficient" (discussion_r829308926, 2022-03-17); it is Facets.java:61-62.
• The overrides optimize a capped default. The same commit (#747) added the default getTopDims with Math.min(topNDims, allResults.size()) and the uncapped SSDV override; Greg Miller's LUCENE-10488 issue (#11524) describes the other overrides as doing the same work "more optimally". For this input the pre-sizing is what makes the overrides diverge: with the cap they return the default's result in all five classes.
• The input is in contract. validateTopN and the taxonomy check accept every positive value (Facets.java:80-84, TaxonomyFacets.java:596-598); no javadoc names an upper bound.
• Tests. "test getTopDims(10, 10) and expect same results from getAllDims(10)" runs on 2 dims in TestSortedSetDocValuesFacets.java:128-130 and on 2 dims in TestTaxonomyFacetCounts.java:151-153; Integer.MAX_VALUE is the same call at the end of the accepted range.
• Precedents. Michael McCandless capped the taxonomy child queue with Math.min(taxoReader.getSize(), topN) in LUCENE-5339 (#6403, 189feaacb6f), the change that moved the existing Integer.MAX_VALUE child-count test to getTopChildren(Integer.MAX_VALUE, "dim") (the cap is still at TaxonomyFacets.java:250-251). In LUCENE-4938 (#6002) Robert Muir reported an OutOfMemoryError, Uwe Schindler found that IndexSearcher did not apply the Math.min() logic everywhere, and Robert Muir asked for tests with Integer.MAX_VALUE. The hunt's intended-lens cross-model reviewer (OpenAI GPT-5.6) first pointed to that precedent and to the getTopDims(10, 10) tests.

The strongest case for "works as designed": Facets is @lucene.experimental; getAllDims is the API for all dims; PriorityQueue rejects impossible capacities on purpose (SOLR-5661 and 4c646dab3fb, Michael McCandless, crediting rsaavedraf) and documents that it pre-allocates; the javadoc says "should" and itself qualifies the feature (dims "should be configured as requiring dim counts", Facets.java:62-64); topNDims can be read as a caller-chosen resource bound; LUCENE-4938 sits under Optimizations in CHANGES. A later cross-model fact check rated this case moderate.

Why it fails: the PriorityQueue guard is an internal limit of a @lucene.internal class whose message names a maxSize the caller never passed, not the input domain of getTopDims; the "should" is the equivalence the reviewer asked for, and the default implementation honours it for the same input; the dim-count note is about count accuracy (the repro's dims are flat and single-valued, and the queue size does not depend on the setting); read as a resource bound, topNDims still does not explain why the default returns both dims and the overrides throw; and the LUCENE-4938 thread treated a missing Math.min on a top-N queue as a defect. Verdict: not intended, a defect (low severity). A maintainer may still answer "use getAllDims"; the javadoc and the capped default are the reply.

Option A was applied in a scratch worktree of 645d4fe14a20 and run with gradle; the hunt's checks validated the same diff. Options B and C were not built.

One Math.min per site, mirroring the taxonomy child-queue cap (TaxonomyFacets.java:250-251): state.getSize() ("Number of unique labels") in AbstractSortedSetDocValueFacetCounts.getTopDims (:153-157) and taxoReader.getSize() in TaxonomyFacets.getTopDims (:610-614).

// AbstractSortedSetDocValueFacetCounts.getTopDims
PriorityQueue.usingComparator(
    // there cannot be more dims than labels:
    Math.min(topNDims, state.getSize()),
    ...);

// TaxonomyFacets.getTopDims
PriorityQueue.usingComparator(
    // there cannot be more dims than ordinals:
    Math.min(topNDims, taxoReader.getSize()),
    ...);

Trade-offs

• Safe: every SSDV dim with a count has at least one label ordinal and every taxonomy dim is an ordinal, so the dims that can enter the queue never exceed the cap; results are unchanged for every topNDims that works today. The loops still test pq.size() < topNDims (AbstractSortedSetDocValueFacetCounts.java:201, TaxonomyFacets.java:653); that stays safe for the same reason, but a cleaner patch keeps the capped size in a local and uses it in both places.
• Loose: the bound is the field's label count (SSDV) or the taxonomy's ordinal count, not the dim count. With this fix, for 2 dims in a taxonomy of 524,293 ordinals, a call allocated 2,099,320 bytes at Integer.MAX_VALUE against 2,160 at topNDims 2 (SSDV: 2,102,680 against 134,536). It removes the exception but does not make the allocation proportional to the dims; in theory a field or taxonomy with at least ArrayUtil.MAX_ARRAY_LENGTH labels or ordinals would still reach the guard.

What the checks validated

• Gradle on 645d4fe14a20 with the fix: the repro passes with -Ptests.asserts=true and false; the whole facet module passes, 307 tests in 40 classes, 7 skipped, 0 failures (seed DEADBEEF, assertions on), including TestSortedSetDocValuesFacets, TestTaxonomyFacetCounts, TestTaxonomyFacetAssociations, TestTaxonomyFacetValueSource and TestDrillSideways. With the fix reverted the repro fails again.
• The probe: with the fix all five classes return a and b for Integer.MAX_VALUE and allocate 1,408-1,744 bytes at 2^24.
• Earlier: the finder's 6-test JUnit 6 of 6, an independent reproducer's 7 of 7 (-ea, -da), 7 upstream facet test classes (82 tests, together with the LFV-994 fix) and the differential harness (0 saturation and 0 allocation failures with both fixes; its remaining prefix failures belong to LFV-363 and go to 0 with that fix added).

SSDV: count state.getDims() (an Iterable<String>, one pass over the dims). Taxonomy: count the root's children first (one sibling walk) or collect the dims into a growable list. Suggested by the independent root-cause-lens reviewer (OpenAI GPT-5.6).

Trade-offs

Removes the looseness of A, at the cost of one extra pass over the dims per call.

Gather the dim values into a list and pick the top topNDims from it.

Trade-offs

Removes the pre-allocation entirely; a larger change to two optimized methods.

Add an upper bound to the argument check.

Trade-offs

It would turn the working default getTopDims, and the working getTopChildren(Integer.MAX_VALUE, ...) of taxonomy facets that upstream tests use, into errors.

Method: non-formal first signal, then semi-formal checking (an executed probe, then model-based differential testing on the stock jars).

• A planning AI tool for numeric-limit hunts read the facet code and ran a probe on main a9779ef3c193, 10.5.2, 9.12.3 and the 10.6 release candidate: SSDV getTopDims(Integer.MAX_VALUE, 10) threw and getTopDims(10^8, 10) allocated 381 MiB.
• The hunting AI tool wrote a reference model of top-N facet results (saturation: getTopDims(n, k) for n at least the number of dims equals getTopDims(1000, k) and getAllDims(k); allocation bounded by the dims) and a differential harness over 40 seeded random indexes: on stock main 9,924 of 59,600 saturation checks and 3,060 of 14,900 allocation checks failed (these include the sibling child-queue sites, LFV-994), and 0 of each with both fixes. An SMT solver checked the queue-size arithmetic.
• It reduced the case to a public-API JUnit over all five classes with a default-getTopDims control, and later to the one-test repro.