FacetSets.adoc says each facet-set matcher counts documents, but MatchingFacetSetsCounts counts matching facet sets

The facet-set user guide, lucene/facet/docs/FacetSets.adoc, which the package javadoc points to, says MatchingFacetSetCounts is "A Facets implementation which counts how many documents are matched by each of a list of FacetSetMatcher, in addition to counting the total number of documents that were matched", and its motivating table counts actors, one document each. The code adds 1 to a matcher's count for every facet set of a hit document that the matcher accepts, and adds 1 to the total (FacetResult.value) once per document. So one document holding (Thriller, 2020) and (Thriller, 2021) gives a "Thriller 2020-2022" range matcher 2 while FacetResult.value is 1. The bundled demo shows the same, 4 for 2 city documents, under a javadoc that says "Counting documents", and its upstream test asserts the 4. The per-set count is pinned by upstream tests and very likely intended, so this is a documentation defect: the guide and the demo javadoc should say that each matcher counts matching facet sets. It has been so since facet sets first shipped in 9.3.0.

• FacetSets.adoc:119-120: "A Facets implementation which counts how many documents are matched by each of a list of FacetSetMatcher, in addition to counting the total number of documents that were matched." The heading above it (:117) spells the class MatchingFacetSetCounts.
• The guide's motivation counts actors: "show how many actors appeared in each year or genre" (:16) and the table "Number of Actors performing in movies by Genre and Year" (:27), one document per actor (:13-23); the guide indexes each actor's (genre, year) combinations as facet sets (:36-38, and "indexed genre and year facet sets" in that example, :123-124). package-info.java:19-20 sends users to this guide.
• CustomFacetSetExample.java:206: "Counting documents which match a certain degrees value for any date."

for (int doc = it.nextDoc(); doc != DocIdSetIterator.NO_MORE_DOCS; doc = it.nextDoc()) {
  boolean shouldCountDoc = false;
  ...
  for (int start = Integer.BYTES; start < bytesRef.length; ) {   // every facet set of the document
    start += facetSetDecoder.decode(bytesRef, start, dimValues);
    for (int j = 0; j < facetSetMatchers.length; j++) {           // every matcher
      if (facetSetMatchers[j].matches(dimValues)) {
        counts[j]++;                                              // :128, once per matching SET
        shouldCountDoc = true;
      }
    }
  }
  if (shouldCountDoc) {
    totCount++;                                                   // :134, once per DOCUMENT
  }
}

Label values are counts[i] and FacetResult.value is totCount (:150-154, :194). A matcher sees one set at a time: matches(long[] dimValues), "the encoded dimension values of a single facet set in this field" (FacetSetMatcher.java:49-54).

• The repro: one document with (1, 2020) and (1, 2021), matcher "Thriller 2020-2022": label value 2, FacetResult.value 1.
• The demo: 2 city documents with 3 temperature readings each, 2 of them in 80-100 degrees (CustomFacetSetExample.java:85-105): "Eighty to Hundred Degrees" 4, value 2, asserted by TestCustomFacetSetExample.java:54, :57.
• An exact matcher is enough when a document repeats a set: FacetSetsField.create packs the sets as given (FacetSetsField.java:52-75), and one document holding (1, 2020) twice gives ExactFacetSetMatcher "Thriller 2020" 2 (a study verifier's run).

• Who: users of MatchingFacetSetsCounts with ExactFacetSetMatcher, RangeFacetSetMatcher or a custom matcher. Several sets per document is the documented shape (FacetSets.adoc:98-99: a field "which lets you index a list of FacetSet"; FacetSetsField.java:23-26). A matcher that accepts at most one set of each hit document gives the document count (the controls of the independent reproducer and of the executed cross-model review pass).
• Default vs opt-in: opt-in, experimental module API; no codec, flag or scale condition. The smallest case is one document with two sets.
• Effect: silent. A facet UI that labels the matcher's value as actors or documents shows a number larger than the number of documents the matcher matched whenever a hit document has two or more sets it accepts; with one matcher it is then also larger than FacetResult.value. The hit list, the total and which documents are counted are correct.
• No stock alternative: the constructors take only the field, the hits, the decoder, an optional fastMatchQuery and the matchers (MatchingFacetSetsCounts.java:52-85), so an application that needs per-document counts must write its own Facets.
• Likelihood: plausible but limited. Facet sets are niche; a GitHub code search for the class name found no use of MatchingFacetSetsCounts in the Elasticsearch, OpenSearch or Solr repositories (2026-10-26, repeated 2026-11-01; a control query returned hits), and the prior-report searches found no report since 9.3.0 (2022).

• Smallest input: one document and two sets is the least that can show a value above the document count.
• Releases: the same test fails on the 10.6.0 and 10.5.2 release jars; 9.3.0, 9.12.3 and 10.0.0 fail with a copy that uses new MatchAllDocsQuery() (they have no MatchAllDocsQuery.INSTANCE); 9.2.0 has no facet-set API.
• Not a regression test for the doc fix: it asserts the documented promise. With the recommended text fix the code does not change, so drop the test, or keep it with its one assertion changed to the fixed text (2 sets), which this doc ran. With the per-document code change (option B) it passes unchanged.

cp $REPRO/TestMatchingFacetSetsCountsPerDocument.java $LUCENE/lucene/facet/src/test/org/apache/lucene/facet/facetset/
cd $LUCENE
./gradlew :lucene:facet:test --tests org.apache.lucene.facet.facetset.TestMatchingFacetSetsCountsPerDocument -Ptests.seed=DEADBEEF -Ptests.asserts=true
# assertions off: -Ptests.asserts=false (same failure)

# gradle, main 645d4fe14a20, seed DEADBEEF, -Ptests.asserts=true
TestMatchingFacetSetsCountsPerDocument > testOneDocumentTwoMatchingSets FAILED
    java.lang.AssertionError: documents matched by 'Thriller 2020-2022' expected:<1> but was:<2>
        at org.apache.lucene.facet.facetset.TestMatchingFacetSetsCountsPerDocument.testOneDocumentTwoMatchingSets(TestMatchingFacetSetsCountsPerDocument.java:54)
1 test completed, 1 failed
BUILD FAILED
# -Ptests.asserts=false: the same AssertionError

# upstream demo test on main (passes: the per-set count is asserted upstream)
TestCustomFacetSetExample: 4 run, 0 failed   (testRangeMatching: value 2, "Eighty to Hundred Degrees" 4)

• The guide: the ordinary reading of FacetSets.adoc:119-120 is a count of distinct documents per matcher, which a value larger than the number of matched documents contradicts. Its motivating table counts actors (:27), one document per actor (:13-23), whose (genre, year) combinations the guide indexes as facet sets (:36-38, :123-124). The automotive-parts motivation counts parts too: aggregating on sub-fields "will lead to a wrong count of 2 (in the above example) instead of 1" (:66-69).
• The demo: CustomFacetSetExample.java:206 says "Counting documents which match a certain degrees value for any date"; TestCustomFacetSetExample.java:54, :57 assert value 2 and label 4.
• Other facet counters: FacetResult.value: "If a document contains multiple values for the same path, it will only be counted once in this value" (FacetResult.java:30-35); the range counters roll multi-valued counts up per document "so that counts don't get double-counted" (range/OverlappingLongRangeCounter.java:211-216); LongValueFacetCounts skips a value repeated within one document, "do not increment the count for duplicate values" (LongValueFacetCounts.java:263-276, :271; #191). Association facets aggregate weights, not counts, and are not compared here.
• The authors described it both ways: in the #841 design discussion shaie wrote that the class "counts how many documents each matcher matched as well as how many documents matched overall" (2022-05-31); in #11664 (2022-07-12) mdmarshmallow, the PR's author, described counting matching "points". Nobody discussed several matching sets in one document.

Strongest case (the study's intended-behaviour verifier and cross-model reviews, OpenAI GPT-5.6): the per-set count is the intended, tested semantics. The class javadoc says "Returns the counts for each given FacetSet" (MatchingFacetSetsCounts.java:36); a matcher evaluates one set at a time; TestRangeFacetSetMatcher adds 1 per matching set to its expected child counts and 1 per document to its expected value (TestRangeFacetSetMatcher.java:66-94, :123); the demo test pins 4 for 2 documents; the API is @lucene.experimental; the adoc line is a loose summary.

Why it fails: it succeeds against calling this a counting bug, which is why it is classed as a documentation defect. It does not make the documentation right: the guide names a different quantity (documents) from the one computed (sets), a matcher that accepts several of one actor's facet sets (a year range, or a repeated set) would report more than the number of actors the guide's table counts, and the demo javadoc says "documents" right above the asserted 4 for 2. The per-set semantics are strongly supported but not proven to be what the authors meant (shaie's #841 comment says documents), so the maintainers may pick either meaning.

The per-set behaviour is intended and tested, so the recommended fix changes text only. Both options were applied in a scratch worktree of 645d4fe14a20 and run with gradle (OpenJDK 25.0.3, seed DEADBEEF).

Reword FacetSets.adoc:119-120 as below, the demo javadoc CustomFacetSetExample.java:206 ("Counting temperature readings (facet sets) which match a certain degrees value for any date. A city with several matching readings is counted once per reading, so the count can be larger than the number of matching documents.") and optionally the class javadoc MatchingFacetSetsCounts.java:36.

A `Facets` implementation which counts, for each of a list of `FacetSetMatcher`, how many facet sets of the matching
documents it matches, in addition to counting the total number of documents that were matched. A document counts once
in the total but once per matching facet set for each matcher: a document with the facet sets (Thriller, 2020) and
(Thriller, 2021) adds 2 to a "Thriller 2020-2022" range matcher, so a matcher's count can be larger than the total. It
uses the `FacetSetDecoder` to decode the

Trade-offs

• Text only: no behaviour or API change, every existing test kept.
• Applications that want per-document counts still have no stock option (the adoc could say so).
• The fix can also correct the heading typo MatchingFacetSetCounts (FacetSets.adoc:117). The exact-matcher demo javadocs (CustomFacetSetExample.java:122, :152) are true for the demo's data, where no document repeats a set.

What the checks validated

• :lucene:facet:checkGoogleJavaFormat, :lucene:demo:checkGoogleJavaFormat, :lucene:facet:renderJavadoc and :lucene:demo:renderJavadoc pass.
• The code is unchanged, so the minimal test as written still fails; with its one assertion changed to the fixed text (2 sets) it passes, assertions on and off.
• :lucene:facet:test --tests 'org.apache.lucene.facet.facetset.*': 4 classes, 15 tests, 0 failures (assertions on; with assertions off 1 test that assumes assertions is skipped); :lucene:demo:test --tests TestCustomFacetSetExample: 4 tests, 0 failures, assertions on and off.

Keep a boolean[] per document in MatchingFacetSetsCounts.count and skip a matcher that already matched an earlier set of the same document (+5/-1 lines).

if (matchedInDoc[j] == false && facetSetMatchers[j].matches(dimValues)) {
  // count each document at most once per matcher
  matchedInDoc[j] = true;
  counts[j]++;
  shouldCountDoc = true;
}

Trade-offs

• Makes the guide's sentence true and matches the range facets' once-per-document rule.
• Changes the results of an API shipped since 9.3.0 and reverses semantics the tests pin: 7 upstream tests need new expected values, plus a CHANGES/MIGRATE note.
• Per-set counts may be what some users want ("how many readings were in range"); an opt-in per-document mode (a flag or a separate class) is a third way, not written or run here.
• As written it stops calling a matcher's matches() for the later sets of a document once that matcher has matched. The stock matchers are stateless, so results do not change, but FacetSetMatcher does not promise that a custom matcher has no side effects (FacetSetMatcher.java:49-54); calling matches() for every set and gating only counts[j]++ avoids that (not run here).

What the checks validated

• :lucene:facet:checkGoogleJavaFormat passes; the unchanged minimal test passes, assertions on and off; TestExactFacetSetMatcher (6) and TestMatchingFacetSetsCounts (3) pass.
• TestRangeFacetSetMatcher fails 5 of 5 (for example expected:<Ford [2010-2014] (60)> but was:<Ford [2010-2014] (48)>) and TestCustomFacetSetExample fails 2 of 4 (expected:<Eighty to Hundred Degrees (4)> but was:<Eighty to Hundred Degrees (2)>), because they assert per-set counts.

• First signal: code reading in a hunt unit (facet taxonomy, SSDV and DrillSideways), 2026-10-26, while writing FacetCountsBX, a brute-force reference whose facet-set part counts per set as the demo test does. No model produced or witnessed the defect, so the finding is non-formal.
• Repro: the finder's public-API JUnit failed on main with assertions on and off and on 10.5.2.
• Minimal repro (2026-10-29): one method, one assertion, try-with-resources; fails on main 645d4fe14a20 with assertions on and off.