IndexSorter (Lucene 10.5.0 core API)
Description: declaration: package: org.apache.lucene.index, interface: IndexSorter

Package org.apache.lucene.index

# Interface IndexSorter

All Known Implementing Classes:
  `IndexSorter.BinarySorter`, `IndexSorter.DoubleSorter`, `IndexSorter.FloatSorter`, `IndexSorter.IntSorter`, `IndexSorter.LongSorter`, `IndexSorter.StringSorter`

public interface IndexSorter
Handles how documents should be sorted in an index, both within a segment and between segments.

Implementers must provide the following methods:

- `getDocComparator(LeafReader,int)` - an object that determines how documents within a segment are to be sorted
- `getComparableValues(List)` - an object that reads and compares the sort value of documents across segments, used for merge sorting. The default implementation adapts `getComparableProviders(List)`, so sorts whose value can be expressed as a `long` only need to implement the latter.
- `getProviderName()` - the SPI-registered name of a `SortFieldProvider` to serialize the sort

The companion `SortFieldProvider` should be registered with SPI via `META-INF/services`

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Interface
  Description
  `static interface`
  `IndexSorter.BinaryDocValuesProvider`
  Provide a BinaryDocValues instance for a LeafReader
  `static final class`
  `IndexSorter.BinarySorter`
  Sorts documents by the bytes of a `BinaryDocValues` instance, using the given comparator.
  `static interface`
  `IndexSorter.ComparableProvider`
  Used for sorting documents across segments
  `static interface`
  `IndexSorter.ComparableValues`
  Caches the sort value of the current document of every segment being merged, and compares them.
  `static interface`
  `IndexSorter.DocComparator`
  A comparator of doc IDs, used for sorting documents within a segment
  `static final class`
  `IndexSorter.DoubleSorter`
  Sorts documents based on double values from a NumericDocValues instance
  `static final class`
  `IndexSorter.FloatSorter`
  Sorts documents based on float values from a NumericDocValues instance
  `static final class`
  `IndexSorter.IntSorter`
  Sorts documents based on integer values from a NumericDocValues instance
  `static final class`
  `IndexSorter.LongSorter`
  Sorts documents based on long values from a NumericDocValues instance
  `static interface`
  `IndexSorter.NumericDocValuesProvider`
  Provide a NumericDocValues instance for a LeafReader
  `static interface`
  `IndexSorter.SortedDocValuesProvider`
  Provide a SortedDocValues instance for a LeafReader
  `static final class`
  `IndexSorter.StringSorter`
  Sorts documents based on terms from a SortedDocValues instance

- ## Method Summary

  Modifier and Type
  Method
  Description
  `default IndexSorter.ComparableProvider[]`
  `getComparableProviders(List<? extends LeafReader> readers)`
  Get an array of `IndexSorter.ComparableProvider`, one per segment, for merge sorting documents in different segments.
  `default IndexSorter.ComparableValues`
  `getComparableValues(List<? extends LeafReader> readers)`
  Get a `IndexSorter.ComparableValues`, used for merge sorting documents across the given segments.
  `IndexSorter.DocComparator`
  `getDocComparator(LeafReader reader, int maxDoc)`
  Get a comparator that determines the sort order of docs within a single Reader.
  `String`
  `getProviderName()`
  The SPI-registered name of a `SortFieldProvider` that will deserialize the parent SortField

- ## Method Details

  - ### getComparableProviders

    default IndexSorter.ComparableProvider[] getComparableProviders(List<? extends LeafReader> readers) throws IOException
    Get an array of `IndexSorter.ComparableProvider`, one per segment, for merge sorting documents in different segments.

    Implementations whose sort value is a `long` should implement this method; it is exposed to the merger through the default `getComparableValues(List)`. Implementations that override `getComparableValues(List)` directly need not implement this method.

    Parameters:
      `readers` - the readers to be merged
    Throws:
      `IOException`

  - ### getComparableValues

    default IndexSorter.ComparableValues getComparableValues(List<? extends LeafReader> readers) throws IOException
    Get a `IndexSorter.ComparableValues`, used for merge sorting documents across the given segments.

    The default implementation adapts `getComparableProviders(List)` and is appropriate for any sort whose value can be represented as a `long`.

    Parameters:
      `readers` - the readers to be merged
    Throws:
      `IOException`

  - ### getDocComparator

    IndexSorter.DocComparator getDocComparator(LeafReader reader, int maxDoc) throws IOException
    Get a comparator that determines the sort order of docs within a single Reader.

    NB We cannot simply use the `FieldComparator` API because it requires docIDs to be sent in-order. The default implementations allocate array[maxDoc] to hold native values for comparison, but 1) they are transient (only alive while sorting this one segment) and 2) in the typical index sorting case, they are only used to sort newly flushed segments, which will be smaller than merged segments

    Parameters:
      `reader` - the Reader to sort
      `maxDoc` - the number of documents in the Reader
    Throws:
      `IOException`

  - ### getProviderName

    String getProviderName()
    The SPI-registered name of a `SortFieldProvider` that will deserialize the parent SortField