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.

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

  Since:
    lucene 1.4
  See Also:
    `Sort`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and 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 and 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 and 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
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `equals(Object o)` Returns true if `o` is equal to this.
    `Comparator<BytesRef>` | `getBytesComparator()`
    `boolean` | `getCanUsePoints()`
    `FieldComparator<?>` | `getComparator(int numHits, int sortPos)` 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` | `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` | `setCanUsePoints()` For numeric sort fields, setting this field, indicates that the same numeric data has been indexed with two fields: doc values and points and that these fields have the same name.
    `void` | `setMissingValue(Object missingValue)` Set the value to use for documents that don't have a value.
    `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`

    - #### setCanUsePoints

          public void setCanUsePoints()

      For numeric sort fields, setting this field, indicates that the same numeric data has been indexed with two fields: doc values and points and that these fields have the same name. This allows to use sort optimization and skip non-competitive documents.

    - #### getCanUsePoints

          public boolean getCanUsePoints()

    - #### 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). `canUsePoints` field is not part of `equals` and `hasCode` intentionally, as it is only useful during search-time and using it in these functions prevents index sorting optimizations that rely on the equality of the index-time and search-time SortField instances.
      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,
                                                  int sortPos)

      Returns the `FieldComparator` to use for sorting.
      Parameters:
        `numHits` - number of top hits the queue will store
        `sortPos` - position of this SortField within `Sort`. The comparator is primary if sortPos==0, secondary if sortPos==1, etc. Some comparators can optimize themselves when they are the primary sort.
      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.

Copyright © 2000-2024 Apache Software Foundation. All Rights Reserved.