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, boolean, boolean, boolean, boolean)` 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`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `static TopFieldCollector` | `create(Sort sort, int numHits, boolean fillFields, boolean trackDocScores, boolean trackMaxScore)` Deprecated. Use `create(Sort, int, boolean, boolean, boolean, boolean)`
    `static TopFieldCollector` | `create(Sort sort, int numHits, boolean fillFields, boolean trackDocScores, boolean trackMaxScore, boolean trackTotalHits)` Creates a new `TopFieldCollector` from the given arguments.
    `static TopFieldCollector` | `create(Sort sort, int numHits, FieldDoc after, boolean fillFields, boolean trackDocScores, boolean trackMaxScore)` Deprecated. Use `create(Sort, int, FieldDoc, boolean, boolean, boolean, boolean)`
    `static TopFieldCollector` | `create(Sort sort, int numHits, FieldDoc after, boolean fillFields, boolean trackDocScores, boolean trackMaxScore, boolean trackTotalHits)` Creates a new `TopFieldCollector` from the given arguments.
    `boolean` | `isEarlyTerminated()` Return whether collection terminated early.
    `boolean` | `needsScores()` Indicates if document scores are needed by this collector.
    `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.
    `TopFieldDocs` | `topDocs()` Returns the top docs that were collected by this collector.

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

- - ### Method Detail

    - #### needsScores

          public boolean needsScores()

      Description copied from interface: `Collector`
      Indicates if document scores are needed by this collector.
      Returns:
        `true` if scores are needed.

    - #### create

          @Deprecated
          public static TopFieldCollector create(Sort sort,
                                                             int numHits,
                                                             boolean fillFields,
                                                             boolean trackDocScores,
                                                             boolean trackMaxScore)

      Deprecated. Use `create(Sort, int, boolean, boolean, boolean, boolean)`
      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.
        `fillFields` - specifies whether the actual field values should be returned on the results (FieldDoc).
        `trackDocScores` - specifies whether document scores should be tracked and set on the results. Note that if set to false, then the results' scores will be set to Float.NaN. Setting this to true affects performance, as it incurs the score computation on each competitive result. Therefore if document scores are not required by the application, it is recommended to set it to false.
        `trackMaxScore` - specifies whether the query's maxScore should be tracked and set on the resulting `TopDocs`. Note that if set to false, `TopDocs.getMaxScore()` returns Float.NaN. Setting this to true affects performance as it incurs the score computation on each result. Also, setting this true automatically sets `trackDocScores` to true as well.
      Returns:
        a `TopFieldCollector` instance which will sort the results by the sort criteria.

    - #### create

          public static TopFieldCollector create(Sort sort,
                                                 int numHits,
                                                 boolean fillFields,
                                                 boolean trackDocScores,
                                                 boolean trackMaxScore,
                                                 boolean trackTotalHits)

      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.
        `fillFields` - specifies whether the actual field values should be returned on the results (FieldDoc).
        `trackDocScores` - specifies whether document scores should be tracked and set on the results. Note that if set to false, then the results' scores will be set to Float.NaN. Setting this to true affects performance, as it incurs the score computation on each competitive result. Therefore if document scores are not required by the application, it is recommended to set it to false.
        `trackMaxScore` - specifies whether the query's maxScore should be tracked and set on the resulting `TopDocs`. Note that if set to false, `TopDocs.getMaxScore()` returns Float.NaN. Setting this to true affects performance as it incurs the score computation on each result. Also, setting this true automatically sets `trackDocScores` to true as well.
        `trackTotalHits` - specifies whether the total number of hits should be tracked. If set to false, the value of `TopDocs.totalHits` will be approximated.
      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,
                                                             boolean fillFields,
                                                             boolean trackDocScores,
                                                             boolean trackMaxScore)

      Deprecated. Use `create(Sort, int, FieldDoc, boolean, boolean, boolean, boolean)`
      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
        `fillFields` - specifies whether the actual field values should be returned on the results (FieldDoc).
        `trackDocScores` - specifies whether document scores should be tracked and set on the results. Note that if set to false, then the results' scores will be set to Float.NaN. Setting this to true affects performance, as it incurs the score computation on each competitive result. Therefore if document scores are not required by the application, it is recommended to set it to false.
        `trackMaxScore` - specifies whether the query's maxScore should be tracked and set on the resulting `TopDocs`. Note that if set to false, `TopDocs.getMaxScore()` returns Float.NaN. Setting this to true affects performance as it incurs the score computation on each result. Also, setting this true automatically sets `trackDocScores` to true as well.
      Returns:
        a `TopFieldCollector` instance which will sort the results by the sort criteria.

    - #### create

          public static TopFieldCollector create(Sort sort,
                                                 int numHits,
                                                 FieldDoc after,
                                                 boolean fillFields,
                                                 boolean trackDocScores,
                                                 boolean trackMaxScore,
                                                 boolean trackTotalHits)

      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
        `fillFields` - specifies whether the actual field values should be returned on the results (FieldDoc).
        `trackDocScores` - specifies whether document scores should be tracked and set on the results. Note that if set to false, then the results' scores will be set to Float.NaN. Setting this to true affects performance, as it incurs the score computation on each competitive result. Therefore if document scores are not required by the application, it is recommended to set it to false.
        `trackMaxScore` - specifies whether the query's maxScore should be tracked and set on the resulting `TopDocs`. Note that if set to false, `TopDocs.getMaxScore()` returns Float.NaN. Setting this to true affects performance as it incurs the score computation on each result. Also, setting this true automatically sets `trackDocScores` to true as well.
        `trackTotalHits` - specifies whether the total number of hits should be tracked. If set to false, the value of `TopDocs.totalHits` will be approximated.
      Returns:
        a `TopFieldCollector` instance which will sort the results by the sort criteria.

    - #### 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.

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