Package org.apache.lucene.search

## Class TopFieldCollector

- java.lang.Object
- - org.apache.lucene.search.TopDocsCollector<FieldValueHitQueue.Entry>
  - - org.apache.lucene.search.TopFieldCollector

- All Implemented Interfaces:
    `Collector`

      public abstract class TopFieldCollector
      extends TopDocsCollector<FieldValueHitQueue.Entry>

  A `Collector` that sorts by `SortField` using `FieldComparator`s.

  See the `create(org.apache.lucene.search.Sort, int, int)` method for instantiating a TopFieldCollector.

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

- - ### Field Summary

    - ### Fields inherited from class org.apache.lucene.search.TopDocsCollector

      `EMPTY_TOPDOCS, pq, totalHits, totalHitsRelation`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static TopFieldCollector` | `create​(Sort sort, int numHits, int totalHitsThreshold)` | Deprecated. This method is deprecated in favor of the constructor of `TopFieldCollectorManager` due to its support for concurrency in IndexSearcher
    `static TopFieldCollector` | `create​(Sort sort, int numHits, FieldDoc after, int totalHitsThreshold)` | Deprecated. This method is deprecated in favor of the constructor of `TopFieldCollectorManager` due to its support for concurrency in IndexSearcher
    `static CollectorManager<TopFieldCollector,​TopFieldDocs>` | `createSharedManager​(Sort sort, int numHits, FieldDoc after, int totalHitsThreshold)` | Deprecated. This method is deprecated in favor of the constructor of `TopFieldCollectorManager` due to its support for concurrency in IndexSearcher
    `boolean` | `isEarlyTerminated()` | Return whether collection terminated early.
    `protected TopDocs` | `newTopDocs​(ScoreDoc[] results, int start)` | Returns a `TopDocs` instance containing the given results.
    `protected void` | `populateResults​(ScoreDoc[] results, int howMany)` | Populates the results array with the ScoreDoc instances.
    `static void` | `populateScores​(ScoreDoc[] topDocs, IndexSearcher searcher, Query query)` | Populate `scores` of the given `topDocs`.
    `ScoreMode` | `scoreMode()` | Indicates what features are required from the scorer.
    `TopFieldDocs` | `topDocs()` | Returns the top docs that were collected by this collector.
    `protected void` | `updateGlobalMinCompetitiveScore​(Scorable scorer)` |
    `protected void` | `updateMinCompetitiveScore​(Scorable scorer)` |

    - ### Methods inherited from class org.apache.lucene.search.TopDocsCollector

      `getTotalHits, topDocs, topDocs, topDocsSize`

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

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

    - ### Methods inherited from interface org.apache.lucene.search.Collector

      `getLeafCollector, setWeight`

- - ### Method Detail

    - #### scoreMode

          public ScoreMode scoreMode()

      Description copied from interface: `Collector`
      Indicates what features are required from the scorer.

    - #### updateGlobalMinCompetitiveScore

          protected void updateGlobalMinCompetitiveScore​(Scorable scorer)
                                                  throws IOException

      Throws:
        `IOException`

    - #### updateMinCompetitiveScore

          protected void updateMinCompetitiveScore​(Scorable scorer)
                                            throws IOException

      Throws:
        `IOException`

    - #### create

          @Deprecated
          public static TopFieldCollector create​(Sort sort,
                                                 int numHits,
                                                 int totalHitsThreshold)

      Deprecated.
      This method is deprecated in favor of the constructor of `TopFieldCollectorManager` due to its support for concurrency in IndexSearcher
      Creates a new `TopFieldCollector` from the given arguments.

      NOTE: The instances returned by this method pre-allocate a full array of length `numHits`.

      Parameters:
        `sort` - the sort criteria (SortFields).
        `numHits` - the number of results to collect.
        `totalHitsThreshold` - the number of docs to count accurately. If the query matches more than `totalHitsThreshold` hits then its hit count will be a lower bound. On the other hand if the query matches less than or exactly `totalHitsThreshold` hits then the hit count of the result will be accurate. `Integer.MAX_VALUE` may be used to make the hit count accurate, but this will also make query processing slower.
      Returns:
        a `TopFieldCollector` instance which will sort the results by the sort criteria.

    - #### create

          @Deprecated
          public static TopFieldCollector create​(Sort sort,
                                                 int numHits,
                                                 FieldDoc after,
                                                 int totalHitsThreshold)

      Deprecated.
      This method is deprecated in favor of the constructor of `TopFieldCollectorManager` due to its support for concurrency in IndexSearcher
      Creates a new `TopFieldCollector` from the given arguments.

      NOTE: The instances returned by this method pre-allocate a full array of length `numHits`.

      Parameters:
        `sort` - the sort criteria (SortFields).
        `numHits` - the number of results to collect.
        `after` - only hits after this FieldDoc will be collected
        `totalHitsThreshold` - the number of docs to count accurately. If the query matches more than `totalHitsThreshold` hits then its hit count will be a lower bound. On the other hand if the query matches less than or exactly `totalHitsThreshold` hits then the hit count of the result will be accurate. `Integer.MAX_VALUE` may be used to make the hit count accurate, but this will also make query processing slower. Setting totalHitsThreshold less than `Integer.MAX_VALUE` instructs Lucene to skip non-competitive documents whenever possible. For numeric sort fields the skipping functionality works when the same field is indexed both with doc values and points. In this case, there is an assumption that the same data is stored in these points and doc values.
      Returns:
        a `TopFieldCollector` instance which will sort the results by the sort criteria.

    - #### createSharedManager

          @Deprecated
          public static CollectorManager<TopFieldCollector,​TopFieldDocs> createSharedManager​(Sort sort,
                                                                                                   int numHits,
                                                                                                   FieldDoc after,
                                                                                                   int totalHitsThreshold)

      Deprecated.
      This method is deprecated in favor of the constructor of `TopFieldCollectorManager` due to its support for concurrency in IndexSearcher
      Create a CollectorManager which uses a shared hit counter to maintain number of hits and a shared `MaxScoreAccumulator` to propagate the minimum score accross segments if the primary sort is by relevancy.

    - #### populateScores

          public static void populateScores​(ScoreDoc[] topDocs,
                                            IndexSearcher searcher,
                                            Query query)
                                     throws IOException

      Populate `scores` of the given `topDocs`.
      Parameters:
        `topDocs` - the top docs to populate
        `searcher` - the index searcher that has been used to compute `topDocs`
        `query` - the query that has been used to compute `topDocs`
      Throws:
        `IllegalArgumentException` - if there is evidence that `topDocs` have been computed against a different searcher or a different query.
        `IOException`
      WARNING: This API is experimental and might change in incompatible ways in the next release.

    - #### populateResults

          protected void populateResults​(ScoreDoc[] results,
                                         int howMany)

      Description copied from class: `TopDocsCollector`
      Populates the results array with the ScoreDoc instances. This can be overridden in case a different ScoreDoc type should be returned.
      Overrides:
        `populateResults` in class `TopDocsCollector<FieldValueHitQueue.Entry>`

    - #### newTopDocs

          protected TopDocs newTopDocs​(ScoreDoc[] results,
                                       int start)

      Description copied from class: `TopDocsCollector`
      Returns a `TopDocs` instance containing the given results. If `results` is null it means there are no results to return, either because there were 0 calls to collect() or because the arguments to topDocs were invalid.
      Overrides:
        `newTopDocs` in class `TopDocsCollector<FieldValueHitQueue.Entry>`

    - #### topDocs

          public TopFieldDocs topDocs()

      Description copied from class: `TopDocsCollector`
      Returns the top docs that were collected by this collector.
      Overrides:
        `topDocs` in class `TopDocsCollector<FieldValueHitQueue.Entry>`

    - #### isEarlyTerminated

          public boolean isEarlyTerminated()

      Return whether collection terminated early.