CollectionStatistics (Lucene 10.5.0 core API)
Description: declaration: package: org.apache.lucene.search, record: CollectionStatistics

Package org.apache.lucene.search

# Record Class CollectionStatistics

java.lang.Object
java.lang.Record
org.apache.lucene.search.CollectionStatistics

Record Components:
  `field` - Field's name.

  This value is never `null`.

  `maxDoc` - The total number of documents in the range [1 .. `Long.MAX_VALUE`], regardless of whether they all contain values for this field.

  This value is always a positive number. @see IndexReader#maxDoc()

  `docCount` - The total number of documents that have at least one term for this field , in the range [1 .. `maxDoc()`].

  This value is always a positive number, and never exceeds `maxDoc()`. @see Terms#getDocCount()

  `sumTotalTermFreq` - The total number of tokens for this field , in the range [`sumDocFreq()` .. `Long.MAX_VALUE`]. This is the "word count" for this field across all documents. It is the sum of `TermStatistics.totalTermFreq()` across all terms. It is also the sum of each document's field length across all documents.

  This value is always a positive number, and always at least `sumDocFreq()`. @see Terms#getSumTotalTermFreq()

  `sumDocFreq` - The total number of posting list entries for this field, in the range [`docCount()` .. `sumTotalTermFreq()`]. This is the sum of term-document pairs: the sum of `TermStatistics.docFreq()` across all terms. It is also the sum of each document's unique term count for this field across all documents.

  This value is always a positive number, always at least `docCount()`, and never exceeds `sumTotalTermFreq()`. @see Terms#getSumDocFreq()

public record CollectionStatistics(String field, long maxDoc, long docCount, long sumTotalTermFreq, long sumDocFreq) extends Record
Contains statistics for a collection (field).

This class holds statistics across all documents for scoring purposes:

- `maxDoc()`: number of documents.
- `docCount()`: number of documents that contain this field.
- `sumDocFreq()`: number of postings-list entries.
- `sumTotalTermFreq()`: number of tokens.

The following conditions are always true:

- All statistics are positive integers: never zero or negative.
- `docCount` <= `maxDoc`
- `docCount` <= `sumDocFreq` <= `sumTotalTermFreq`

Values may include statistics on deleted documents that have not yet been merged away.

Be careful when performing calculations on these values because they are represented as 64-bit integer values, you may need to cast to `double` for your use.

WARNING: This API is experimental and might change in incompatible ways in the next release.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `CollectionStatistics(String field, long maxDoc, long docCount, long sumTotalTermFreq, long sumDocFreq)`
  Creates statistics instance for a collection (field).

- ## Method Summary

  Modifier and Type
  Method
  Description
  `long`
  `docCount()`
  Returns the value of the `docCount` record component.
  `final boolean`
  `equals(Object o)`
  Indicates whether some other object is "equal to" this one.
  `String`
  `field()`
  Returns the value of the `field` record component.
  `final int`
  `hashCode()`
  Returns a hash code value for this object.
  `long`
  `maxDoc()`
  Returns the value of the `maxDoc` record component.
  `long`
  `sumDocFreq()`
  Returns the value of the `sumDocFreq` record component.
  `long`
  `sumTotalTermFreq()`
  Returns the value of the `sumTotalTermFreq` record component.
  `final String`
  `toString()`
  Returns a string representation of this record class.

  ### Methods inherited from class java.lang.Object

  `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- ## Constructor Details

  - ### CollectionStatistics

    public CollectionStatistics(String field, long maxDoc, long docCount, long sumTotalTermFreq, long sumDocFreq)
    Creates statistics instance for a collection (field).
    Throws:
      `IllegalArgumentException` - if `maxDoc` is negative or zero.
      `IllegalArgumentException` - if `docCount` is negative or zero.
      `IllegalArgumentException` - if `docCount` is more than `maxDoc`.
      `IllegalArgumentException` - if `sumDocFreq` is less than `docCount`.
      `IllegalArgumentException` - if `sumTotalTermFreq` is less than `sumDocFreq`.

- ## Method Details

  - ### toString

    public final String toString()
    Returns a string representation of this record class. The representation contains the name of the class, followed by the name and value of each of the record components.
    Specified by:
      `toString` in class `Record`
    Returns:
      a string representation of this object

  - ### hashCode

    public final int hashCode()
    Returns a hash code value for this object. The value is derived from the hash code of each of the record components.
    Specified by:
      `hashCode` in class `Record`
    Returns:
      a hash code value for this object

  - ### equals

    public final boolean equals(Object o)
    Indicates whether some other object is "equal to" this one. The objects are equal if the other object is of the same class and if all the record components are equal. Reference components are compared with `Objects::equals(Object,Object)`; primitive components are compared with '=='.
    Specified by:
      `equals` in class `Record`
    Parameters:
      `o` - the object with which to compare
    Returns:
      `true` if this object is the same as the `o` argument; `false` otherwise.

  - ### field

    public String field()
    Returns the value of the `field` record component.
    Returns:
      the value of the `field` record component

  - ### maxDoc

    public long maxDoc()
    Returns the value of the `maxDoc` record component.
    Returns:
      the value of the `maxDoc` record component

  - ### docCount

    public long docCount()
    Returns the value of the `docCount` record component.
    Returns:
      the value of the `docCount` record component

  - ### sumTotalTermFreq

    public long sumTotalTermFreq()
    Returns the value of the `sumTotalTermFreq` record component.
    Returns:
      the value of the `sumTotalTermFreq` record component

  - ### sumDocFreq

    public long sumDocFreq()
    Returns the value of the `sumDocFreq` record component.
    Returns:
      the value of the `sumDocFreq` record component