Rename CollectionStatistics to FieldStats and TermStatistics to TermStats. (#15929)

Author: vsop-479

lucene/CHANGES.txt

@@ -7,6 +7,7 @@ http://s.apache.org/luceneversions
 
 API Changes
 ---------------------
+* GITHUB#15929: Rename CollectionStatistics to FieldStats and TermStatistics to TermStats. (Zhou Hui)
 
 * GITHUB#15763: Deprecate Operations.complement() method. This operation can be slow and is not
   recommended for production use. It will be removed in Lucene 12. (Saurabh Singh)

lucene/MIGRATE.md

@@ -174,6 +174,10 @@ Automaton dfa = Operations.determinize(new RegExp(re).toAutomaton(), 10000);
 Query query = new AutomatonQuery(new Term("myfield", re), dfa);
 ```
 
+### CollectionStatistics and TermStatistics have been renamed to FieldStats and TermStats (GITHUB#15929)
+
+Corresponding methods and parameters have been renamed accordingly.
+
 ## Migration from Lucene 10.4 to Lucene 10.5
 
 ### `[Byte|Float]VectorSimilarityQuery` now performs adaptive HNSW graph traversal

lucene/core/src/java/org/apache/lucene/search/CombinedFieldQuery.java

@@ -52,8 +52,8 @@
  *
  * <ol>
  *   <li>Given a list of fields and weights, it pretends there is a synthetic combined field where
- *       all terms have been indexed. It computes new term and collection statistics for this
- *       combined field.
+ *       all terms have been indexed. It computes new term and field statistics for this combined
+ *       field.
  *   <li>It uses a disjunction iterator and {@link IndexSearcher#getSimilarity} to score documents.
  * </ol>
  *
@@ -279,41 +279,37 @@ class CombinedFieldWeight extends Weight {
         TermStates ts = TermStates.build(searcher, fieldTerms[i], true);
         termStates[i] = ts;
         if (ts.docFreq() > 0) {
-          TermStatistics termStats =
-              searcher.termStatistics(fieldTerms[i], ts.docFreq(), ts.totalTermFreq());
+          TermStats termStats = searcher.termStats(fieldTerms[i], ts.docFreq(), ts.totalTermFreq());
           docFreq = Math.max(termStats.docFreq(), docFreq);
           totalTermFreq += (double) field.weight * termStats.totalTermFreq();
         }
       }
       if (docFreq > 0) {
-        CollectionStatistics pseudoCollectionStats = mergeCollectionStatistics(searcher);
-        TermStatistics pseudoTermStatistics =
-            new TermStatistics(new BytesRef("pseudo_term"), docFreq, Math.max(1, totalTermFreq));
-        this.simWeight =
-            searcher.getSimilarity().scorer(boost, pseudoCollectionStats, pseudoTermStatistics);
+        FieldStats pseudoFieldStats = mergeFieldStats(searcher);
+        TermStats pseudoTermStats =
+            new TermStats(new BytesRef("pseudo_term"), docFreq, Math.max(1, totalTermFreq));
+        this.simWeight = searcher.getSimilarity().scorer(boost, pseudoFieldStats, pseudoTermStats);
       } else {
         this.simWeight = null;
       }
     }
 
-    private CollectionStatistics mergeCollectionStatistics(IndexSearcher searcher)
-        throws IOException {
+    private FieldStats mergeFieldStats(IndexSearcher searcher) throws IOException {
       long maxDoc = 0;
       long docCount = 0;
       long sumTotalTermFreq = 0;
       long sumDocFreq = 0;
       for (FieldAndWeight fieldWeight : fieldAndWeights.values()) {
-        CollectionStatistics collectionStats = searcher.collectionStatistics(fieldWeight.field);
-        if (collectionStats != null) {
-          maxDoc = Math.max(collectionStats.maxDoc(), maxDoc);
-          docCount = Math.max(collectionStats.docCount(), docCount);
-          sumDocFreq = Math.max(collectionStats.sumDocFreq(), sumDocFreq);
-          sumTotalTermFreq += (double) fieldWeight.weight * collectionStats.sumTotalTermFreq();
+        FieldStats fieldStats = searcher.fieldStats(fieldWeight.field);
+        if (fieldStats != null) {
+          maxDoc = Math.max(fieldStats.maxDoc(), maxDoc);
+          docCount = Math.max(fieldStats.docCount(), docCount);
+          sumDocFreq = Math.max(fieldStats.sumDocFreq(), sumDocFreq);
+          sumTotalTermFreq += (double) fieldWeight.weight * fieldStats.sumTotalTermFreq();
         }
       }
 
-      return new CollectionStatistics(
-          "pseudo_field", maxDoc, docCount, sumTotalTermFreq, sumDocFreq);
+      return new FieldStats("pseudo_field", maxDoc, docCount, sumTotalTermFreq, sumDocFreq);
     }
 
     @Override

…/lucene/search/CollectionStatistics.java …org/apache/lucene/search/FieldStats.javalucene/core/src/java/org/apache/lucene/search/CollectionStatistics.java renamed to lucene/core/src/java/org/apache/lucene/search/FieldStats.java lucene/core/src/java/org/apache/lucene/search/CollectionStatistics.java renamed to lucene/core/src/java/org/apache/lucene/search/FieldStats.java

@@ -19,7 +19,7 @@
 import java.util.Objects;
 
 /**
- * Contains statistics for a collection (field).
+ * Contains statistics for a field.
  *
  * <p>This class holds statistics across all documents for scoring purposes:
  *
@@ -54,30 +54,30 @@
  *     Terms#getDocCount()
  * @param sumTotalTermFreq The total number of tokens for this field , in the range [{@link
  *     #sumDocFreq()} .. {@link Long#MAX_VALUE}]. This is the "word count" for this field across all
- *     documents. It is the sum of {@link TermStatistics#totalTermFreq()} across all terms. It is
- *     also the sum of each document's field length across all documents.
+ *     documents. It is the sum of {@link TermStats#totalTermFreq()} across all terms. It is also
+ *     the sum of each document's field length across all documents.
  *     <p>This value is always a positive number, and always at least {@link #sumDocFreq()}. @see
  *     Terms#getSumTotalTermFreq()
  * @param sumDocFreq The total number of posting list entries for this field, in the range [{@link
  *     #docCount()} .. {@link #sumTotalTermFreq()}]. This is the sum of term-document pairs: the sum
- *     of {@link TermStatistics#docFreq()} across all terms. It is also the sum of each document's
- *     unique term count for this field across all documents.
+ *     of {@link TermStats#docFreq()} across all terms. It is also the sum of each document's unique
+ *     term count for this field across all documents.
  *     <p>This value is always a positive number, always at least {@link #docCount()}, and never
  *     exceeds {@link #sumTotalTermFreq()}. @see Terms#getSumDocFreq()
  * @lucene.experimental
  */
-public record CollectionStatistics(
+public record FieldStats(
     String field, long maxDoc, long docCount, long sumTotalTermFreq, long sumDocFreq) {
   /**
-   * Creates statistics instance for a collection (field).
+   * Creates statistics instance for a field.
    *
    * @throws IllegalArgumentException if {@code maxDoc} is negative or zero.
    * @throws IllegalArgumentException if {@code docCount} is negative or zero.
    * @throws IllegalArgumentException if {@code docCount} is more than {@code maxDoc}.
    * @throws IllegalArgumentException if {@code sumDocFreq} is less than {@code docCount}.
    * @throws IllegalArgumentException if {@code sumTotalTermFreq} is less than {@code sumDocFreq}.
    */
-  public CollectionStatistics {
+  public FieldStats {
     Objects.requireNonNull(field);
     if (maxDoc <= 0) {
       throw new IllegalArgumentException("maxDoc must be positive, maxDoc: " + maxDoc);

lucene/core/src/java/org/apache/lucene/search/IndexSearcher.java

@@ -1106,32 +1106,31 @@ public String toString() {
   }
 
   /**
-   * Returns {@link TermStatistics} for a term.
+   * Returns {@link TermStats} for a term.
    *
    * <p>This can be overridden for example, to return a term's statistics across a distributed
    * collection.
    *
    * @param docFreq The document frequency of the term. It must be greater or equal to 1.
    * @param totalTermFreq The total term frequency.
-   * @return A {@link TermStatistics} (never null).
+   * @return A {@link TermStats} (never null).
    * @lucene.experimental
    */
-  public TermStatistics termStatistics(Term term, int docFreq, long totalTermFreq)
-      throws IOException {
+  public TermStats termStats(Term term, int docFreq, long totalTermFreq) throws IOException {
     // This constructor will throw an exception if docFreq <= 0.
-    return new TermStatistics(term.bytes(), docFreq, totalTermFreq);
+    return new TermStats(term.bytes(), docFreq, totalTermFreq);
   }
 
   /**
-   * Returns {@link CollectionStatistics} for a field, or {@code null} if the field does not exist
-   * (has no indexed terms)
+   * Returns {@link FieldStats} for a field, or {@code null} if the field does not exist (has no
+   * indexed terms)
    *
    * <p>This can be overridden for example, to return a field's statistics across a distributed
    * collection.
    *
    * @lucene.experimental
    */
-  public CollectionStatistics collectionStatistics(String field) throws IOException {
+  public FieldStats fieldStats(String field) throws IOException {
     assert field != null;
     long docCount = 0;
     long sumTotalTermFreq = 0;
@@ -1145,7 +1144,7 @@ public CollectionStatistics collectionStatistics(String field) throws IOExceptio
     if (docCount == 0) {
       return null;
     }
-    return new CollectionStatistics(field, reader.maxDoc(), docCount, sumTotalTermFreq, sumDocFreq);
+    return new FieldStats(field, reader.maxDoc(), docCount, sumTotalTermFreq, sumDocFreq);
   }
 
   /**

lucene/core/src/java/org/apache/lucene/search/MultiPhraseQuery.java

@@ -216,7 +216,7 @@ public Weight createWeight(IndexSearcher searcher, ScoreMode scoreMode, float bo
       protected Similarity.SimScorer getStats(IndexSearcher searcher) throws IOException {
 
         // compute idf
-        ArrayList<TermStatistics> allTermStats = new ArrayList<>();
+        ArrayList<TermStats> allTermStats = new ArrayList<>();
         for (final Term[] terms : termArrays) {
           for (Term term : terms) {
             TermStates ts = termStates.get(term);
@@ -225,17 +225,15 @@ protected Similarity.SimScorer getStats(IndexSearcher searcher) throws IOExcepti
               termStates.put(term, ts);
             }
             if (scoreMode.needsScores() && ts.docFreq() > 0) {
-              allTermStats.add(searcher.termStatistics(term, ts.docFreq(), ts.totalTermFreq()));
+              allTermStats.add(searcher.termStats(term, ts.docFreq(), ts.totalTermFreq()));
             }
           }
         }
         if (allTermStats.isEmpty()) {
           return null; // none of the terms were found, we won't use sim at all
         } else {
           return similarity.scorer(
-              boost,
-              searcher.collectionStatistics(field),
-              allTermStats.toArray(TermStatistics[]::new));
+              boost, searcher.fieldStats(field), allTermStats.toArray(TermStats[]::new));
         }
       }
 

lucene/core/src/java/org/apache/lucene/search/PhraseQuery.java

@@ -469,24 +469,21 @@ protected Similarity.SimScorer getStats(IndexSearcher searcher) throws IOExcepti
               "PhraseWeight requires that the first position is 0, call rewrite first");
         }
         states = new TermStates[terms.length];
-        TermStatistics[] termStats = new TermStatistics[terms.length];
+        TermStats[] termStats = new TermStats[terms.length];
         int termUpTo = 0;
         for (int i = 0; i < terms.length; i++) {
           final Term term = terms[i];
           states[i] = TermStates.build(searcher, term, scoreMode.needsScores());
           if (scoreMode.needsScores()) {
             TermStates ts = states[i];
             if (ts.docFreq() > 0) {
-              termStats[termUpTo++] =
-                  searcher.termStatistics(term, ts.docFreq(), ts.totalTermFreq());
+              termStats[termUpTo++] = searcher.termStats(term, ts.docFreq(), ts.totalTermFreq());
             }
           }
         }
         if (termUpTo > 0) {
           return similarity.scorer(
-              boost,
-              searcher.collectionStatistics(field),
-              ArrayUtil.copyOfSubArray(termStats, 0, termUpTo));
+              boost, searcher.fieldStats(field), ArrayUtil.copyOfSubArray(termStats, 0, termUpTo));
         } else {
           return null; // no terms at all, we won't use similarity
         }

lucene/core/src/java/org/apache/lucene/search/SynonymQuery.java

@@ -207,7 +207,7 @@ class SynonymWeight extends Weight {
       super(query);
       assert scoreMode.needsScores();
       this.scoreMode = scoreMode;
-      CollectionStatistics collectionStats = searcher.collectionStatistics(field);
+      FieldStats fieldStats = searcher.fieldStats(field);
       long docFreq = 0;
       long totalTermFreq = 0;
       termStates = new TermStates[terms.length];
@@ -216,17 +216,16 @@ class SynonymWeight extends Weight {
         TermStates ts = TermStates.build(searcher, term, true);
         termStates[i] = ts;
         if (ts.docFreq() > 0) {
-          TermStatistics termStats =
-              searcher.termStatistics(term, ts.docFreq(), ts.totalTermFreq());
+          TermStats termStats = searcher.termStats(term, ts.docFreq(), ts.totalTermFreq());
           docFreq = Math.max(termStats.docFreq(), docFreq);
           totalTermFreq += termStats.totalTermFreq();
         }
       }
       this.similarity = searcher.getSimilarity();
       if (docFreq > 0) {
-        TermStatistics pseudoStats =
-            new TermStatistics(new BytesRef("synonym pseudo-term"), docFreq, totalTermFreq);
-        this.simWeight = similarity.scorer(boost, collectionStats, pseudoStats);
+        TermStats pseudoStats =
+            new TermStats(new BytesRef("synonym pseudo-term"), docFreq, totalTermFreq);
+        this.simWeight = similarity.scorer(boost, fieldStats, pseudoStats);
       } else {
         this.simWeight = null; // no terms exist at all, we won't use similarity
       }

lucene/core/src/java/org/apache/lucene/search/TermQuery.java

@@ -58,18 +58,18 @@ public TermWeight(
       this.termStates = termStates;
       this.similarity = searcher.getSimilarity();
 
-      final CollectionStatistics collectionStats;
-      final TermStatistics termStats;
+      final FieldStats fieldStats;
+      final TermStats termStats;
       if (scoreMode.needsScores()) {
-        collectionStats = searcher.collectionStatistics(term.field());
+        fieldStats = searcher.fieldStats(term.field());
         termStats =
             termStates.docFreq() > 0
-                ? searcher.termStatistics(term, termStates.docFreq(), termStates.totalTermFreq())
+                ? searcher.termStats(term, termStates.docFreq(), termStates.totalTermFreq())
                 : null;
       } else {
         // we do not need the actual stats, use fake stats with docFreq=maxDoc=ttf=1
-        collectionStats = new CollectionStatistics(term.field(), 1, 1, 1, 1);
-        termStats = new TermStatistics(term.bytes(), 1, 1);
+        fieldStats = new FieldStats(term.field(), 1, 1, 1, 1);
+        termStats = new TermStats(term.bytes(), 1, 1);
       }
 
       if (termStats == null) {
@@ -79,7 +79,7 @@ public TermWeight(
         // allocations in case default BM25Scorer is used.
         // See: https://github.com/apache/lucene/issues/12297
         if (scoreMode.needsScores()) {
-          this.simScorer = similarity.scorer(boost, collectionStats, termStats);
+          this.simScorer = similarity.scorer(boost, fieldStats, termStats);
         } else {
           // Assigning a dummy scorer as this is not expected to be called since scores are not
           // needed.

lucene/core/src/java/org/apache/lucene/search/TermScorer.java

@@ -83,7 +83,7 @@ public int docID() {
   }
 
   /** Returns term frequency in the current document. */
-  public final int freq() throws IOException {
+  public int freq() throws IOException {
     return postingsEnum.freq();
   }