org.apache.lucene.search.CollectionStatistics Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of org.apache.servicemix.bundles.lucene
This OSGi bundle wraps ${pkgArtifactId} ${pkgVersion} jar file.
There is a newer version: 6.4.2_1
/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.lucene.search;

import java.util.Objects;

/**
 * Contains statistics for a collection (field).
 *
 * This class holds statistics across all documents for scoring purposes:
 *
 * 

 *   {@link #maxDoc()}: number of documents.
 *   
{@link #docCount()}: number of documents that contain this field.
 *   
{@link #sumDocFreq()}: number of postings-list entries.
 *   
{@link #sumTotalTermFreq()}: number of tokens.
 * 
 *
 * The following conditions are always true:
 *
 * 

 *   All statistics are positive integers: never zero or negative.
 *   
{@code docCount} <= {@code maxDoc}
 *   
{@code docCount} <= {@code sumDocFreq} <= {@code 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 {@code double} for your use.
 *
 * @param field Field's name.
 *     
This value is never {@code null}.
 * @param maxDoc The total number of documents in the range [1 .. {@link Long#MAX_VALUE}],
 *     regardless of whether they all contain values for this field.
 *     
This value is always a positive number. @see IndexReader#maxDoc()
 * @param docCount The total number of documents that have at least one term for this field , in the
 *     range [1 .. {@link #maxDoc()}].
 *     
This value is always a positive number, and never exceeds {@link #maxDoc()}. @see
 *     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.
 *     
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.
 *     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(
    String field, long maxDoc, long docCount, long sumTotalTermFreq, long sumDocFreq) {
  /**
   * Creates statistics instance for a collection (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 {
    Objects.requireNonNull(field);
    if (maxDoc <= 0) {
      throw new IllegalArgumentException("maxDoc must be positive, maxDoc: " + maxDoc);
    }
    if (docCount <= 0) {
      throw new IllegalArgumentException("docCount must be positive, docCount: " + docCount);
    }
    if (docCount > maxDoc) {
      throw new IllegalArgumentException(
          "docCount must not exceed maxDoc, docCount: " + docCount + ", maxDoc: " + maxDoc);
    }
    if (sumDocFreq <= 0) {
      throw new IllegalArgumentException("sumDocFreq must be positive, sumDocFreq: " + sumDocFreq);
    }
    if (sumDocFreq < docCount) {
      throw new IllegalArgumentException(
          "sumDocFreq must be at least docCount, sumDocFreq: "
              + sumDocFreq
              + ", docCount: "
              + docCount);
    }
    if (sumTotalTermFreq <= 0) {
      throw new IllegalArgumentException(
          "sumTotalTermFreq must be positive, sumTotalTermFreq: " + sumTotalTermFreq);
    }
    if (sumTotalTermFreq < sumDocFreq) {
      throw new IllegalArgumentException(
          "sumTotalTermFreq must be at least sumDocFreq, sumTotalTermFreq: "
              + sumTotalTermFreq
              + ", sumDocFreq: "
              + sumDocFreq);
    }
  }
}