Package org.apache.lucene.search

## Class SortField

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

- Direct Known Subclasses:
    `SortedNumericSortField`, `SortedSetSortField`

      public class SortField
      extends Object

  Stores information about how to sort documents by terms in an individual field. Fields must be indexed in order to sort by them.

  Sorting on a numeric field that is indexed with both doc values and points may use an optimization to skip non-competitive documents. This optimization relies on the assumption that the same data is stored in these points and doc values.

  Sorting on a SORTED(_SET) field that is indexed with both doc values and term index may use an optimization to skip non-competitive documents. This optimization relies on the assumption that the same data is stored in these term index and doc values.

  Created: Feb 11, 2004 1:25:29 PM

  Since:
    lucene 1.4
  See Also:
    `Sort`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static class` | `SortField.Provider` | A SortFieldProvider for field sorts
    `static class` | `SortField.Type` | Specifies the type of the terms to be sorted, or special types such as CUSTOM

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static SortField` | `FIELD_DOC` | Represents sorting by document number (index order).
    `static SortField` | `FIELD_SCORE` | Represents sorting by document score (relevance).
    `protected Object` | `missingValue` |
    `static Object` | `STRING_FIRST` | Pass this to `setMissingValue(java.lang.Object)` to have missing string values sort first.
    `static Object` | `STRING_LAST` | Pass this to `setMissingValue(java.lang.Object)` to have missing string values sort last.

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `SortField​(String field, FieldComparatorSource comparator)` | Creates a sort with a custom comparison function.
    `SortField​(String field, FieldComparatorSource comparator, boolean reverse)` | Creates a sort, possibly in reverse, with a custom comparison function.
    `SortField​(String field, SortField.Type type)` | Creates a sort by terms in the given field with the type of term values explicitly given.
    `SortField​(String field, SortField.Type type, boolean reverse)` | Creates a sort, possibly in reverse, by terms in the given field with the type of term values explicitly given.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `boolean` | `equals​(Object o)` | Returns true if `o` is equal to this.
    `Comparator<BytesRef>` | `getBytesComparator()` |
    `FieldComparator<?>` | `getComparator​(int numHits, Pruning pruning)` | Returns the `FieldComparator` to use for sorting.
    `FieldComparatorSource` | `getComparatorSource()` | Returns the `FieldComparatorSource` used for custom sorting
    `String` | `getField()` | Returns the name of the field.
    `IndexSorter` | `getIndexSorter()` | Returns an `IndexSorter` used for sorting index segments by this SortField.
    `Object` | `getMissingValue()` | Return the value to use for documents that don't have a value.
    `boolean` | `getOptimizeSortWithIndexedData()` | Deprecated.
    `boolean` | `getOptimizeSortWithPoints()` | Deprecated. This is a duplicate method for `SortField#getOptimizeSortWithIndexedData`.
    `boolean` | `getReverse()` | Returns whether the sort should be reversed.
    `SortField.Type` | `getType()` | Returns the type of contents in the field.
    `int` | `hashCode()` | Returns a hash code for this `SortField` instance.
    `boolean` | `needsScores()` | Whether the relevance score is needed to sort documents.
    `protected static SortField.Type` | `readType​(DataInput in)` |
    `SortField` | `rewrite​(IndexSearcher searcher)` | Rewrites this SortField, returning a new SortField if a change is made.
    `void` | `setBytesComparator​(Comparator<BytesRef> b)` |
    `void` | `setMissingValue​(Object missingValue)` | Set the value to use for documents that don't have a value.
    `void` | `setOptimizeSortWithIndexedData​(boolean optimizeSortWithIndexedData)` | Deprecated. should only be used for compatibility with 8.x indices that got created with inconsistent data across fields, or the wrong sort configuration in the index sort
    `void` | `setOptimizeSortWithPoints​(boolean optimizeSortWithPoints)` | Deprecated. should only be used for compatibility with 8.x indices that got created with inconsistent data across fields, or the wrong sort configuration in the index sort.
    `String` | `toString()` |

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

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

- - ### Field Detail

    - #### FIELD_SCORE

          public static final SortField FIELD_SCORE

      Represents sorting by document score (relevance).

    - #### FIELD_DOC

          public static final SortField FIELD_DOC

      Represents sorting by document number (index order).

    - #### missingValue

          protected Object missingValue

    - #### STRING_FIRST

          public static final Object STRING_FIRST

      Pass this to `setMissingValue(java.lang.Object)` to have missing string values sort first.

    - #### STRING_LAST

          public static final Object STRING_LAST

      Pass this to `setMissingValue(java.lang.Object)` to have missing string values sort last.

  - ### Constructor Detail

    - #### SortField

          public SortField​(String field,
                           SortField.Type type)

      Creates a sort by terms in the given field with the type of term values explicitly given.
      Parameters:
        `field` - Name of field to sort by. Can be `null` if `type` is SCORE or DOC.
        `type` - Type of values in the terms.

    - #### SortField

          public SortField​(String field,
                           SortField.Type type,
                           boolean reverse)

      Creates a sort, possibly in reverse, by terms in the given field with the type of term values explicitly given.
      Parameters:
        `field` - Name of field to sort by. Can be `null` if `type` is SCORE or DOC.
        `type` - Type of values in the terms.
        `reverse` - True if natural order should be reversed.

    - #### SortField

          public SortField​(String field,
                           FieldComparatorSource comparator)

      Creates a sort with a custom comparison function.
      Parameters:
        `field` - Name of field to sort by; cannot be `null`.
        `comparator` - Returns a comparator for sorting hits.

    - #### SortField

          public SortField​(String field,
                           FieldComparatorSource comparator,
                           boolean reverse)

      Creates a sort, possibly in reverse, with a custom comparison function.
      Parameters:
        `field` - Name of field to sort by; cannot be `null`.
        `comparator` - Returns a comparator for sorting hits.
        `reverse` - True if natural order should be reversed.

  - ### Method Detail

    - #### readType

          protected static SortField.Type readType​(DataInput in)
                                            throws IOException

      Throws:
        `IOException`

    - #### getMissingValue

          public Object getMissingValue()

      Return the value to use for documents that don't have a value. A value of `null` indicates that default should be used.

    - #### setMissingValue

          public void setMissingValue​(Object missingValue)

      Set the value to use for documents that don't have a value.

    - #### getField

          public String getField()

      Returns the name of the field. Could return `null` if the sort is by SCORE or DOC.
      Returns:
        Name of field, possibly `null`.

    - #### getType

          public SortField.Type getType()

      Returns the type of contents in the field.
      Returns:
        One of the constants SCORE, DOC, STRING, INT or FLOAT.

    - #### getReverse

          public boolean getReverse()

      Returns whether the sort should be reversed.
      Returns:
        True if natural order should be reversed.

    - #### getComparatorSource

          public FieldComparatorSource getComparatorSource()

      Returns the `FieldComparatorSource` used for custom sorting

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

    - #### equals

          public boolean equals​(Object o)

      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 `Object`

    - #### hashCode

          public int hashCode()

      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 `Object`

    - #### setBytesComparator

          public void setBytesComparator​(Comparator<BytesRef> b)

    - #### getBytesComparator

          public Comparator<BytesRef> getBytesComparator()

    - #### getComparator

          public FieldComparator<?> getComparator​(int numHits,
                                                  Pruning pruning)

      Returns the `FieldComparator` to use for sorting.
      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
      WARNING: This API is experimental and might change in incompatible ways in the next release.

    - #### rewrite

          public SortField rewrite​(IndexSearcher searcher)
                            throws IOException

      Rewrites this SortField, returning a new SortField if a change is made. Subclasses should override this define their rewriting behavior when this SortField is of type `SortField.Type.REWRITEABLE`
      Parameters:
        `searcher` - IndexSearcher to use during rewriting
      Returns:
        New rewritten SortField, or `this` if nothing has changed.
      Throws:
        `IOException` - Can be thrown by the rewriting
      WARNING: This API is experimental and might change in incompatible ways in the next release.

    - #### needsScores

          public boolean needsScores()

      Whether the relevance score is needed to sort documents.

    - #### getIndexSorter

          public IndexSorter getIndexSorter()

      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

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

    - #### setOptimizeSortWithIndexedData

          @Deprecated
          public void setOptimizeSortWithIndexedData​(boolean optimizeSortWithIndexedData)

      Deprecated.
      should only be used for compatibility with 8.x indices that got created with inconsistent data across fields, or the wrong sort configuration in the index sort
      Enables/disables numeric sort optimization to use the indexed data.

      Enabled by default. By default, sorting on a numeric field activates point sort optimization that can efficiently skip over non-competitive hits. Sort optimization has a number of requirements, one of which is that SortField.Type matches the Point type with which the field was indexed (e.g. sort on IntPoint field should use SortField.Type.INT). Another requirement is that the same data is indexed with points and doc values for the field.

      By default, sorting on a SORTED(_SET) field activates sort optimization that can efficiently skip over non-competitive hits. Sort optimization requires that the same data is indexed with term index and doc values for the field.

      Parameters:
        `optimizeSortWithIndexedData` - providing `false` disables the optimization, in cases where these requirements can't be met.

    - #### getOptimizeSortWithIndexedData

          @Deprecated
          public boolean getOptimizeSortWithIndexedData()

      Deprecated.
      Returns whether sort optimization should be optimized with indexed data
      Returns:
        whether sort optimization should be optimized with indexed data

    - #### setOptimizeSortWithPoints

          @Deprecated
          public void setOptimizeSortWithPoints​(boolean optimizeSortWithPoints)

      Deprecated.
      should only be used for compatibility with 8.x indices that got created with inconsistent data across fields, or the wrong sort configuration in the index sort. This is a duplicate method for `SortField#setOptimizeSortWithIndexedData`.
      Enables/disables numeric sort optimization to use the Points index.

      Enabled by default. By default, sorting on a numeric field activates point sort optimization that can efficiently skip over non-competitive hits. Sort optimization has a number of requirements, one of which is that SortField.Type matches the Point type with which the field was indexed (e.g. sort on IntPoint field should use SortField.Type.INT). Another requirement is that the same data is indexed with points and doc values for the field.

      Parameters:
        `optimizeSortWithPoints` - providing `false` disables the optimization, in cases where these requirements can't be met.

    - #### getOptimizeSortWithPoints

          @Deprecated
          public boolean getOptimizeSortWithPoints()

      Deprecated.
      This is a duplicate method for `SortField#getOptimizeSortWithIndexedData`.
      Returns whether sort optimization should be optimized with points index
      Returns:
        whether sort optimization should be optimized with points index