DocValuesConsumer (Lucene 10.5.1 core API)
Description: declaration: package: org.apache.lucene.codecs, class: DocValuesConsumer

Package org.apache.lucene.codecs

# Class DocValuesConsumer

java.lang.Object
org.apache.lucene.codecs.DocValuesConsumer

All Implemented Interfaces:
  `Closeable`, `AutoCloseable`

public abstract class DocValuesConsumer extends Object implements Closeable
Abstract API that consumes numeric, binary and sorted docvalues. Concrete implementations of this actually do "something" with the docvalues (write it into the index in a specific format).

The lifecycle is:

1. DocValuesConsumer is created by `DocValuesFormat.fieldsConsumer(SegmentWriteState)`.
2. `addNumericField(org.apache.lucene.index.FieldInfo, org.apache.lucene.codecs.DocValuesProducer)`, `addBinaryField(org.apache.lucene.index.FieldInfo, org.apache.lucene.codecs.DocValuesProducer)`, `addSortedField(org.apache.lucene.index.FieldInfo, org.apache.lucene.codecs.DocValuesProducer)`, `addSortedSetField(org.apache.lucene.index.FieldInfo, org.apache.lucene.codecs.DocValuesProducer)`, or `addSortedNumericField(org.apache.lucene.index.FieldInfo, org.apache.lucene.codecs.DocValuesProducer)` are called for each Numeric, Binary, Sorted, SortedSet, or SortedNumeric docvalues field. The API is a "pull" rather than "push", and the implementation is free to iterate over the values multiple times (`Iterable.iterator()`).
3. After all fields are added, the consumer is `Closeable.close()`d.

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

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `DocValuesConsumer()`
  Sole constructor.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `abstract void`
  `addBinaryField(FieldInfo field, DocValuesProducer valuesProducer)`
  Writes binary docvalues for a field.
  `abstract void`
  `addNumericField(FieldInfo field, DocValuesProducer valuesProducer)`
  Writes numeric docvalues for a field.
  `abstract void`
  `addSortedField(FieldInfo field, DocValuesProducer valuesProducer)`
  Writes pre-sorted binary docvalues for a field.
  `abstract void`
  `addSortedNumericField(FieldInfo field, DocValuesProducer valuesProducer)`
  Writes pre-sorted numeric docvalues for a field
  `abstract void`
  `addSortedSetField(FieldInfo field, DocValuesProducer valuesProducer)`
  Writes pre-sorted set docvalues for a field
  `protected static OrdinalMap`
  `createOrdinalMapForSortedDV(FieldInfo fieldInfo, MergeState mergeState)`
  Returns a merged sorted doc values instance from all producers in the provided merge state.
  `protected static OrdinalMap`
  `createOrdinalMapForSortedSetDV(List<SortedSetDocValues> toMerge, MergeState mergeState)`
  Creates an ordinal map based on the provided sorted set doc values to merges
  `protected static BinaryDocValues`
  `getMergedBinaryDocValues(FieldInfo mergeFieldInfo, MergeState mergeState)`
  Returns a merged binary doc values instance from all producers in the provided merge state.
  `protected static NumericDocValues`
  `getMergedNumericDocValues(MergeState mergeState, FieldInfo mergeFieldInfo)`
  Returns a merged numeric doc values instance from all producers in the provided merge state.
  `protected static SortedNumericDocValues`
  `getMergedSortedNumericDocValues(FieldInfo mergeFieldInfo, MergeState mergeState)`
  Returns a merged sorted numeric doc values instance from all producers in the provided merge state.
  `protected static SortedDocValues`
  `getMergedSortedSetDocValues(FieldInfo fieldInfo, MergeState mergeState, OrdinalMap map)`
  Returns a merged sorted doc values instance from all producers in the provided merge state.
  `protected static SortedSetDocValues`
  `getMergedSortedSetDocValues(FieldInfo mergeFieldInfo, MergeState mergeState, OrdinalMap map, List<SortedSetDocValues> toMerge)`
  Returns a sorted set doc values instance from all producers in the provided merge state.
  `static boolean`
  `isSingleValued(Iterable<Number> docToValueCount)`
  Helper: returns true if the given docToValue count contains only at most one value
  `void`
  `merge(MergeState mergeState)`
  Merges in the fields from the readers in `mergeState`.
  `void`
  `mergeBinaryField(FieldInfo mergeFieldInfo, MergeState mergeState)`
  Merges the binary docvalues from `MergeState`.
  `void`
  `mergeNumericField(FieldInfo mergeFieldInfo, MergeState mergeState)`
  Merges the numeric docvalues from `MergeState`.
  `void`
  `mergeSortedField(FieldInfo fieldInfo, MergeState mergeState)`
  Merges the sorted docvalues from `toMerge`.
  `void`
  `mergeSortedNumericField(FieldInfo mergeFieldInfo, MergeState mergeState)`
  Merges the sorted docvalues from `toMerge`.
  `void`
  `mergeSortedSetField(FieldInfo mergeFieldInfo, MergeState mergeState)`
  Merges the sortedset docvalues from `toMerge`.
  `protected static SortedDocValues`
  `mergeSortedValues(List<org.apache.lucene.codecs.DocValuesConsumer.SortedDocValuesSub> subs, MergeState mergeState, OrdinalMap map)`
  Returns a merged sorted doc values instance from all producers in the provided merge state.
  `protected static List<SortedSetDocValues>`
  `selectLeavesToMerge(FieldInfo mergeFieldInfo, MergeState mergeState)`
  Selects the sorted set doc values to merge.
  `static Iterable<Number>`
  `singletonView(Iterable<Number> docToValueCount, Iterable<Number> values, Number missingValue)`
  Helper: returns single-valued view, using `missingValue` when count is zero

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

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

  ### Methods inherited from interface java.io.Closeable

  `close`

- ## Constructor Details

  - ### DocValuesConsumer

    protected DocValuesConsumer()
    Sole constructor. (For invocation by subclass constructors, typically implicit.)

- ## Method Details

  - ### addNumericField

    public abstract void addNumericField(FieldInfo field, DocValuesProducer valuesProducer) throws IOException
    Writes numeric docvalues for a field.
    Parameters:
      `field` - field information
      `valuesProducer` - Numeric values to write.
    Throws:
      `IOException` - if an I/O error occurred.

  - ### addBinaryField

    public abstract void addBinaryField(FieldInfo field, DocValuesProducer valuesProducer) throws IOException
    Writes binary docvalues for a field.
    Parameters:
      `field` - field information
      `valuesProducer` - Binary values to write.
    Throws:
      `IOException` - if an I/O error occurred.

  - ### addSortedField

    public abstract void addSortedField(FieldInfo field, DocValuesProducer valuesProducer) throws IOException
    Writes pre-sorted binary docvalues for a field.
    Parameters:
      `field` - field information
      `valuesProducer` - produces the values and ordinals to write
    Throws:
      `IOException` - if an I/O error occurred.

  - ### addSortedNumericField

    public abstract void addSortedNumericField(FieldInfo field, DocValuesProducer valuesProducer) throws IOException
    Writes pre-sorted numeric docvalues for a field
    Parameters:
      `field` - field information
      `valuesProducer` - produces the values to write
    Throws:
      `IOException` - if an I/O error occurred.

  - ### addSortedSetField

    public abstract void addSortedSetField(FieldInfo field, DocValuesProducer valuesProducer) throws IOException
    Writes pre-sorted set docvalues for a field
    Parameters:
      `field` - field information
      `valuesProducer` - produces the values to write
    Throws:
      `IOException` - if an I/O error occurred.

  - ### merge

    public void merge(MergeState mergeState) throws IOException
    Merges in the fields from the readers in `mergeState`. The default implementation calls `mergeNumericField(org.apache.lucene.index.FieldInfo, org.apache.lucene.index.MergeState)`, `mergeBinaryField(org.apache.lucene.index.FieldInfo, org.apache.lucene.index.MergeState)`, `mergeSortedField(org.apache.lucene.index.FieldInfo, org.apache.lucene.index.MergeState)`, `mergeSortedSetField(org.apache.lucene.index.FieldInfo, org.apache.lucene.index.MergeState)`, or `mergeSortedNumericField(org.apache.lucene.index.FieldInfo, org.apache.lucene.index.MergeState)` for each field, depending on its type. Implementations can override this method for more sophisticated merging (bulk-byte copying, etc).
    Throws:
      `IOException`

  - ### mergeNumericField

    public void mergeNumericField(FieldInfo mergeFieldInfo, MergeState mergeState) throws IOException
    Merges the numeric docvalues from `MergeState`.

    The default implementation calls `addNumericField(org.apache.lucene.index.FieldInfo, org.apache.lucene.codecs.DocValuesProducer)`, passing a DocValuesProducer that merges and filters deleted documents on the fly.

    Throws:
      `IOException`

  - ### getMergedNumericDocValues

    protected static NumericDocValues getMergedNumericDocValues(MergeState mergeState, FieldInfo mergeFieldInfo) throws IOException
    Returns a merged numeric doc values instance from all producers in the provided merge state.
    Throws:
      `IOException`
    WARNING: This API is experimental and might change in incompatible ways in the next release.

  - ### mergeBinaryField

    public void mergeBinaryField(FieldInfo mergeFieldInfo, MergeState mergeState) throws IOException
    Merges the binary docvalues from `MergeState`.

    The default implementation calls `addBinaryField(org.apache.lucene.index.FieldInfo, org.apache.lucene.codecs.DocValuesProducer)`, passing a DocValuesProducer that merges and filters deleted documents on the fly.

    Throws:
      `IOException`

  - ### getMergedBinaryDocValues

    protected static BinaryDocValues getMergedBinaryDocValues(FieldInfo mergeFieldInfo, MergeState mergeState) throws IOException
    Returns a merged binary doc values instance from all producers in the provided merge state.
    Throws:
      `IOException`
    WARNING: This API is experimental and might change in incompatible ways in the next release.

  - ### mergeSortedNumericField

    public void mergeSortedNumericField(FieldInfo mergeFieldInfo, MergeState mergeState) throws IOException
    Merges the sorted docvalues from `toMerge`.

    The default implementation calls `addSortedNumericField(org.apache.lucene.index.FieldInfo, org.apache.lucene.codecs.DocValuesProducer)`, passing iterables that filter deleted documents.

    Throws:
      `IOException`

  - ### getMergedSortedNumericDocValues

    protected static SortedNumericDocValues getMergedSortedNumericDocValues(FieldInfo mergeFieldInfo, MergeState mergeState) throws IOException
    Returns a merged sorted numeric doc values instance from all producers in the provided merge state.
    Throws:
      `IOException`
    WARNING: This API is experimental and might change in incompatible ways in the next release.

  - ### mergeSortedField

    public void mergeSortedField(FieldInfo fieldInfo, MergeState mergeState) throws IOException
    Merges the sorted docvalues from `toMerge`.

    The default implementation calls `addSortedField(org.apache.lucene.index.FieldInfo, org.apache.lucene.codecs.DocValuesProducer)`, passing an Iterable that merges ordinals and values and filters deleted documents .

    Throws:
      `IOException`

  - ### createOrdinalMapForSortedDV

    protected static OrdinalMap createOrdinalMapForSortedDV(FieldInfo fieldInfo, MergeState mergeState) throws IOException
    Returns a merged sorted doc values instance from all producers in the provided merge state.
    Throws:
      `IOException`
    WARNING: This API is experimental and might change in incompatible ways in the next release.

  - ### getMergedSortedSetDocValues

    protected static SortedDocValues getMergedSortedSetDocValues(FieldInfo fieldInfo, MergeState mergeState, OrdinalMap map) throws IOException
    Returns a merged sorted doc values instance from all producers in the provided merge state.
    Throws:
      `IOException`
    WARNING: This API is experimental and might change in incompatible ways in the next release.

  - ### mergeSortedValues

    protected static SortedDocValues mergeSortedValues(List<org.apache.lucene.codecs.DocValuesConsumer.SortedDocValuesSub> subs, MergeState mergeState, OrdinalMap map) throws IOException
    Returns a merged sorted doc values instance from all producers in the provided merge state.
    Throws:
      `IOException`
    WARNING: This API is experimental and might change in incompatible ways in the next release.

  - ### mergeSortedSetField

    public void mergeSortedSetField(FieldInfo mergeFieldInfo, MergeState mergeState) throws IOException
    Merges the sortedset docvalues from `toMerge`.

    The default implementation calls `addSortedSetField(org.apache.lucene.index.FieldInfo, org.apache.lucene.codecs.DocValuesProducer)`, passing an Iterable that merges ordinals and values and filters deleted documents .

    Throws:
      `IOException`

  - ### createOrdinalMapForSortedSetDV

    protected static OrdinalMap createOrdinalMapForSortedSetDV(List<SortedSetDocValues> toMerge, MergeState mergeState) throws IOException
    Creates an ordinal map based on the provided sorted set doc values to merges
    Throws:
      `IOException`
    WARNING: This API is experimental and might change in incompatible ways in the next release.

  - ### selectLeavesToMerge

    protected static List<SortedSetDocValues> selectLeavesToMerge(FieldInfo mergeFieldInfo, MergeState mergeState) throws IOException
    Selects the sorted set doc values to merge.
    Throws:
      `IOException`
    WARNING: This API is experimental and might change in incompatible ways in the next release.

  - ### getMergedSortedSetDocValues

    protected static SortedSetDocValues getMergedSortedSetDocValues(FieldInfo mergeFieldInfo, MergeState mergeState, OrdinalMap map, List<SortedSetDocValues> toMerge) throws IOException
    Returns a sorted set doc values instance from all producers in the provided merge state.
    Throws:
      `IOException`
    WARNING: This API is experimental and might change in incompatible ways in the next release.

  - ### isSingleValued

    public static boolean isSingleValued(Iterable<Number> docToValueCount)
    Helper: returns true if the given docToValue count contains only at most one value

  - ### singletonView

    public static Iterable<Number> singletonView(Iterable<Number> docToValueCount, Iterable<Number> values, Number missingValue)
    Helper: returns single-valued view, using `missingValue` when count is zero