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

Package org.apache.lucene.search

# Class BinarySortField

java.lang.Object
org.apache.lucene.search.SortField
org.apache.lucene.search.BinarySortField

public class BinarySortField extends SortField
SortField for `BinaryDocValues`, usable as an index sort.

Unlike a `SortField.Type.STRING` sort (backed by `SortedDocValues`), values are compared directly rather than through a term dictionary, making this a good fit for high-cardinality fields where a dictionary would be pure overhead. Documents are ordered by the unsigned byte order of their sort key (`BytesRef.compareTo(org.apache.lucene.util.BytesRef)`), optionally reversed, with missing values sorted first or last via `SortField.STRING_FIRST` / `SortField.STRING_LAST` (first by default).

By default the sort key is the stored value. A subclass may override `getSortKeyDocValues(LeafReader)` to derive an order-preserving key from the stored bytes and/or other doc-values fields of the segment (for example to select the minimum of a multi-valued field). Such a subclass must register a `SortFieldProvider` via SPI so the sort can be read back and used on merge.

This field can also sort search results, comparing values with a linear scan of the binary doc values (without the skipping optimizations available to numeric or `SORTED` fields).

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

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static final class`
  `BinarySortField.Provider`
  A SortFieldProvider for this sort

  ## Nested classes/interfaces inherited from class org.apache.lucene.search.SortField

  `SortField.Type`

- ## Field Summary

  ### Fields inherited from class org.apache.lucene.search.SortField

  `FIELD_DOC, FIELD_SCORE, missingValue, reverse, STRING_FIRST, STRING_LAST`

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  ``
  `BinarySortField(String field, boolean reverse)`
  Creates a sort, possibly in reverse, by the unsigned byte order of the field's value.
  ``
  `BinarySortField(String field, boolean reverse, Object missingValue)`
  Creates a sort, possibly in reverse, by the unsigned byte order of the field's value, with the given handling of missing values.
  `protected`
  `BinarySortField(String field, boolean reverse, Object missingValue, String providerName)`
  Creates a sort for a subclass that overrides `getSortKeyDocValues(LeafReader)`.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `equals(Object obj)`
  Returns true if `o` is equal to this.
  `FieldComparator<?>`
  `getComparator(int numHits, Pruning pruning)`
  Returns the `FieldComparator` to use for sorting.
  `IndexSorter`
  `getIndexSorter()`
  Returns an `IndexSorter` used for sorting index segments by this SortField.
  `protected BinaryDocValues`
  `getSortKeyDocValues(LeafReader reader)`
  Returns the per-document sort key, as a `BinaryDocValues` whose `BinaryDocValues.binaryValue()` is the bytes to sort on.
  `int`
  `hashCode()`
  Returns a hash code for this `SortField` instance.
  `String`
  `toString()`

  ### Methods inherited from class org.apache.lucene.search.SortField

  `getComparatorSource, getField, getMissingValue, getOptimizeSortWithIndexedData, getOptimizeSortWithPoints, getReverse, getType, needsScores, readType, rewrite, setMissingValue, setOptimizeSortWithIndexedData, setOptimizeSortWithPoints`

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

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

- ## Constructor Details

  - ### BinarySortField

    public BinarySortField(String field, boolean reverse)
    Creates a sort, possibly in reverse, by the unsigned byte order of the field's value.
    Parameters:
      `field` - Name of field to sort by. Must not be null.
      `reverse` - True if natural order should be reversed.

  - ### BinarySortField

    public BinarySortField(String field, boolean reverse, Object missingValue)
    Creates a sort, possibly in reverse, by the unsigned byte order of the field's value, with the given handling of missing values.
    Parameters:
      `field` - Name of field to sort by. Must not be null.
      `reverse` - True if natural order should be reversed.
      `missingValue` - `SortField.STRING_FIRST`, `SortField.STRING_LAST`, or `null` (missing first).

  - ### BinarySortField

    protected BinarySortField(String field, boolean reverse, Object missingValue, String providerName)
    Creates a sort for a subclass that overrides `getSortKeyDocValues(LeafReader)`.

    The subclass must supply the name of a dedicated `SortFieldProvider` (registered via SPI) whose `SortFieldProvider.readSortField(org.apache.lucene.store.DataInput)` reconstructs the subclass, so that the same sort-key derivation is used when the index sort is read back and on merge.

    Parameters:
      `field` - Name of field to sort by. Must not be null.
      `reverse` - True if natural order should be reversed.
      `missingValue` - `SortField.STRING_FIRST`, `SortField.STRING_LAST`, or `null`.
      `providerName` - the SPI name of the companion `SortFieldProvider`.

- ## Method Details

  - ### getSortKeyDocValues

    protected BinaryDocValues getSortKeyDocValues(LeafReader reader) throws IOException
    Returns the per-document sort key, as a `BinaryDocValues` whose `BinaryDocValues.binaryValue()` is the bytes to sort on. The default returns the field's values unchanged; override to derive a key from the stored bytes and/or other doc-values fields of the segment.

    Values are read in increasing docID order; advance any underlying doc values with `DocIdSetIterator.nextDoc()` only, since at flush time the in-memory doc values do not support `advanceExact`. The returned key has the same lifetime as `BinaryDocValues.binaryValue()` (valid until the next call) and need not be a copy.

    Throws:
      `IOException`

  - ### getIndexSorter

    public IndexSorter getIndexSorter()
    Description copied from class: `SortField`
    Returns an `IndexSorter` used for sorting index segments by this SortField.

    If the SortField cannot be used for index sorting (for example, if it uses scores or other query-dependent values) then this method should return `null`

    SortFields that implement this method should also implement a companion `SortFieldProvider` to serialize and deserialize the sort in index segment headers

    Overrides:
      `getIndexSorter` in class `SortField`

  - ### getComparator

    public FieldComparator<?> getComparator(int numHits, Pruning pruning)
    Description copied from class: `SortField`
    Returns the `FieldComparator` to use for sorting.
    Overrides:
      `getComparator` in class `SortField`
    Parameters:
      `numHits` - number of top hits the queue will store
      `pruning` - controls how can the comparator to skip documents via `LeafFieldComparator.competitiveIterator()`
    Returns:
      `FieldComparator` to use when sorting

  - ### hashCode

    public int hashCode()
    Description copied from class: `SortField`
    Returns a hash code for this `SortField` instance. If a `FieldComparatorSource` was provided, it must properly implement hashCode (unless a singleton is always used).
    Overrides:
      `hashCode` in class `SortField`

  - ### equals

    public boolean equals(Object obj)
    Description copied from class: `SortField`
    Returns true if `o` is equal to this. If a `FieldComparatorSource` was provided, it must properly implement equals (unless a singleton is always used).
    Overrides:
      `equals` in class `SortField`

  - ### toString

    public String toString()
    Overrides:
      `toString` in class `SortField`