org.apache.lucene.search

## Class FieldComparator<T>

- java.lang.Object
- - org.apache.lucene.search.FieldComparator<T>

- Direct Known Subclasses:
    FieldComparator.DocComparator, FieldComparator.RelevanceComparator, FieldComparator.TermOrdValComparator, FieldComparator.TermValComparator, SimpleFieldComparator

      public abstract class FieldComparator<T>
      extends Object

  Expert: a FieldComparator compares hits so as to determine their sort order when collecting the top results with `TopFieldCollector`. The concrete public FieldComparator classes here correspond to the SortField types.

  This API is designed to achieve high performance sorting, by exposing a tight interaction with `FieldValueHitQueue` as it visits hits. Whenever a hit is competitive, it's enrolled into a virtual slot, which is an int ranging from 0 to numHits-1. Segment transitions are handled by creating a dedicated per-segment `LeafFieldComparator` which also needs to interact with the `FieldValueHitQueue` but can optimize based on the segment to collect.

  The following functions need to be implemented

  - `compare(int, int)` Compare a hit at 'slot a' with hit 'slot b'.
  - `setTopValue(T)` This method is called by `TopFieldCollector` to notify the FieldComparator of the top most value, which is used by future calls to `LeafFieldComparator.compareTop(int)`.
  - `getLeafComparator(org.apache.lucene.index.LeafReaderContext)` Invoked when the search is switching to the next segment. You may need to update internal state of the comparator, for example retrieving new values from DocValues.
  - `value(int)` Return the sort value stored in the specified slot. This is only called at the end of the search, in order to populate `FieldDoc.fields` when returning the top results.
  See Also:
    `LeafFieldComparator`
  WARNING: This API is experimental and might change in incompatible ways in the next release.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `FieldComparator.DocComparator` Sorts by ascending docID
    `static class` | `FieldComparator.DoubleComparator` Parses field's values as double (using `LeafReader.getNumericDocValues(java.lang.String)` and sorts by ascending value
    `static class` | `FieldComparator.FloatComparator` Parses field's values as float (using `LeafReader.getNumericDocValues(String)` and sorts by ascending value
    `static class` | `FieldComparator.IntComparator` Parses field's values as int (using `LeafReader.getNumericDocValues(String)` and sorts by ascending value
    `static class` | `FieldComparator.LongComparator` Parses field's values as long (using `LeafReader.getNumericDocValues(String)` and sorts by ascending value
    `static class` | `FieldComparator.NumericComparator<T extends Number>` Base FieldComparator class for numeric types
    `static class` | `FieldComparator.RelevanceComparator` Sorts by descending relevance.
    `static class` | `FieldComparator.TermOrdValComparator` Sorts by field's natural Term sort order, using ordinals.
    `static class` | `FieldComparator.TermValComparator` Sorts by field's natural Term sort order.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `FieldComparator()`

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `abstract int` | `compare(int slot1, int slot2)` Compare hit at slot1 with hit at slot2.
    `int` | `compareValues(T first, T second)` Returns a negative integer if first is less than second, 0 if they are equal and a positive integer otherwise.
    `abstract LeafFieldComparator` | `getLeafComparator(LeafReaderContext context)` Get a per-segment `LeafFieldComparator` to collect the given `LeafReaderContext`.
    `abstract void` | `setTopValue(T value)` Record the top value, for future calls to `LeafFieldComparator.compareTop(int)`.
    `abstract T` | `value(int slot)` Return the actual value in the slot.

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

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

- - ### Constructor Detail

    - #### FieldComparator

          public FieldComparator()

  - ### Method Detail

    - #### compare

          public abstract int compare(int slot1,
                                      int slot2)

      Compare hit at slot1 with hit at slot2.
      Parameters:
        `slot1` - first slot to compare
        `slot2` - second slot to compare
      Returns:
        any `N < 0` if slot2's value is sorted after slot1, any `N > 0` if the slot2's value is sorted before slot1 and `0` if they are equal

    - #### setTopValue

          public abstract void setTopValue(T value)

      Record the top value, for future calls to `LeafFieldComparator.compareTop(int)`. This is only called for searches that use searchAfter (deep paging), and is called before any calls to `getLeafComparator(LeafReaderContext)`.

    - #### value

          public abstract T value(int slot)

      Return the actual value in the slot.
      Parameters:
        `slot` - the value
      Returns:
        value in this slot

    - #### getLeafComparator

          public abstract LeafFieldComparator getLeafComparator(LeafReaderContext context)
                                                         throws IOException

      Get a per-segment `LeafFieldComparator` to collect the given `LeafReaderContext`. All docIDs supplied to this `LeafFieldComparator` are relative to the current reader (you must add docBase if you need to map it to a top-level docID).
      Parameters:
        `context` - current reader context
      Returns:
        the comparator to use for this segment
      Throws:
        `IOException` - if there is a low-level IO error

    - #### compareValues

          public int compareValues(T first,
                                   T second)

      Returns a negative integer if first is less than second, 0 if they are equal and a positive integer otherwise. Default impl to assume the type implements Comparable and invoke .compareTo; be sure to override this method if your FieldComparator's type isn't a Comparable or if your values may sometimes be null

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