org.apache.lucene.search

## Class IndexSearcher

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

-     public class IndexSearcher
      extends Object

  Implements search over a single IndexReader.

  Applications usually need only call the inherited `search(Query,int)` method. For performance reasons, if your index is unchanging, you should share a single IndexSearcher instance across multiple searches instead of creating a new one per-search. If your index has changed and you wish to see the changes reflected in searching, you should use `DirectoryReader.openIfChanged(DirectoryReader)` to obtain a new reader and then create a new IndexSearcher from that. Also, for low-latency turnaround it's best to use a near-real-time reader (`DirectoryReader.open(IndexWriter)`). Once you have a new `IndexReader`, it's relatively cheap to create a new IndexSearcher from it.

  NOTE: The `search(org.apache.lucene.search.Query, int)` and `searchAfter(org.apache.lucene.search.ScoreDoc, org.apache.lucene.search.Query, int)` methods are configured to only count top hits accurately up to `1,000` and may return a `lower bound` of the hit count if the hit count is greater than or equal to `1,000`. On queries that match lots of documents, counting the number of hits may take much longer than computing the top hits so this trade-off allows to get some minimal information about the hit count without slowing down search too much. The `TopDocs.scoreDocs` array is always accurate however. If this behavior doesn't suit your needs, you should create collectors manually with either `TopScoreDocCollector.create(int, int)` or `TopFieldCollector.create(org.apache.lucene.search.Sort, int, int)` and call `search(Query, Collector)`.

  NOTE: ``IndexSearcher`` instances are completely thread safe, meaning multiple threads can call any of its methods, concurrently. If your application requires external synchronization, you should not synchronize on the `IndexSearcher` instance; use your own (non-Lucene) objects instead.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `IndexSearcher.LeafSlice` A class holding a subset of the `IndexSearcher`s leaf contexts to be executed within a single thread.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected List<LeafReaderContext>` | `leafContexts`
    `protected IndexReaderContext` | `readerContext`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `IndexSearcher(IndexReader r)` Creates a searcher searching the provided index.
    `IndexSearcher(IndexReaderContext context)` Creates a searcher searching the provided top-level `IndexReaderContext`.
    `IndexSearcher(IndexReaderContext context, ExecutorService executor)` Creates a searcher searching the provided top-level `IndexReaderContext`.
    `IndexSearcher(IndexReader r, ExecutorService executor)` Runs searches for each segment separately, using the provided ExecutorService.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `CollectionStatistics` | `collectionStatistics(String field)` Returns `CollectionStatistics` for a field, or `null` if the field does not exist (has no indexed terms) This can be overridden for example, to return a field's statistics across a distributed collection.
    `int` | `count(Query query)` Count how many documents match the given query.
    `Weight` | `createWeight(Query query, ScoreMode scoreMode, float boost)` Creates a `Weight` for the given query, potentially adding caching if possible and configured.
    `Document` | `doc(int docID)` Sugar for `.getIndexReader().document(docID)`
    `Document` | `doc(int docID, Set<String> fieldsToLoad)` Sugar for `.getIndexReader().document(docID, fieldsToLoad)`
    `void` | `doc(int docID, StoredFieldVisitor fieldVisitor)` Sugar for `.getIndexReader().document(docID, fieldVisitor)`
    `Explanation` | `explain(Query query, int doc)` Returns an Explanation that describes how `doc` scored against `query`.
    `protected Explanation` | `explain(Weight weight, int doc)` Expert: low-level implementation method Returns an Explanation that describes how `doc` scored against `weight`.
    `static QueryCache` | `getDefaultQueryCache()` Expert: Get the default `QueryCache` or `null` if the cache is disabled.
    `static QueryCachingPolicy` | `getDefaultQueryCachingPolicy()` Expert: Get the default `QueryCachingPolicy`.
    `static Similarity` | `getDefaultSimilarity()` Expert: returns a default Similarity instance.
    `IndexReader` | `getIndexReader()` Return the `IndexReader` this searches.
    `QueryCache` | `getQueryCache()` Return the query cache of this `IndexSearcher`.
    `QueryCachingPolicy` | `getQueryCachingPolicy()` Return the query cache of this `IndexSearcher`.
    `Similarity` | `getSimilarity()` Expert: Get the `Similarity` to use to compute scores.
    `IndexSearcher.LeafSlice[]` | `getSlices()` Returns the leaf slices used for concurrent searching, or null if no `ExecutorService` was passed to the constructor.
    `IndexReaderContext` | `getTopReaderContext()` Returns this searchers the top-level `IndexReaderContext`.
    `Query` | `rewrite(Query original)` Expert: called to re-write queries into primitive queries.
    `protected void` | `search(List<LeafReaderContext> leaves, Weight weight, Collector collector)` Lower-level search API.
    `void` | `search(Query query, Collector results)` Lower-level search API.
    `<C extends Collector,T> T` | `search(Query query, CollectorManager<C,T> collectorManager)` Lower-level search API.
    `TopDocs` | `search(Query query, int n)` Finds the top `n` hits for `query`.
    `TopFieldDocs` | `search(Query query, int n, Sort sort)` Search implementation with arbitrary sorting.
    `TopFieldDocs` | `search(Query query, int n, Sort sort, boolean doDocScores)` Search implementation with arbitrary sorting, plus control over whether hit scores and max score should be computed.
    `TopDocs` | `searchAfter(ScoreDoc after, Query query, int numHits)` Finds the top `n` hits for `query` where all results are after a previous result (`after`).
    `TopDocs` | `searchAfter(ScoreDoc after, Query query, int n, Sort sort)` Finds the top `n` hits for `query` where all results are after a previous result (`after`).
    `TopFieldDocs` | `searchAfter(ScoreDoc after, Query query, int numHits, Sort sort, boolean doDocScores)` Finds the top `n` hits for `query` where all results are after a previous result (`after`), allowing control over whether hit scores and max score should be computed.
    `static void` | `setDefaultQueryCache(QueryCache defaultQueryCache)` Expert: set the default `QueryCache` instance.
    `static void` | `setDefaultQueryCachingPolicy(QueryCachingPolicy defaultQueryCachingPolicy)` Expert: set the default `QueryCachingPolicy` instance.
    `void` | `setQueryCache(QueryCache queryCache)` Set the `QueryCache` to use when scores are not needed.
    `void` | `setQueryCachingPolicy(QueryCachingPolicy queryCachingPolicy)` Set the `QueryCachingPolicy` to use for query caching.
    `void` | `setSimilarity(Similarity similarity)` Expert: Set the Similarity implementation used by this IndexSearcher.
    `protected IndexSearcher.LeafSlice[]` | `slices(List<LeafReaderContext> leaves)` Expert: Creates an array of leaf slices each holding a subset of the given leaves.
    `TermStatistics` | `termStatistics(Term term, TermStates context)` Returns `TermStatistics` for a term, or `null` if the term does not exist.
    `String` | `toString()`

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

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

- - ### Field Detail

    - #### readerContext

          protected final IndexReaderContext readerContext

    - #### leafContexts

          protected final List<LeafReaderContext> leafContexts

  - ### Constructor Detail

    - #### IndexSearcher

          public IndexSearcher(IndexReader r)

      Creates a searcher searching the provided index.

    - #### IndexSearcher

          public IndexSearcher(IndexReader r,
                               ExecutorService executor)

      Runs searches for each segment separately, using the provided ExecutorService. IndexSearcher will not close/awaitTermination this ExecutorService on close; you must do so, eventually, on your own. NOTE: if you are using `NIOFSDirectory`, do not use the shutdownNow method of ExecutorService as this uses Thread.interrupt under-the-hood which can silently close file descriptors (see LUCENE-2239).
      WARNING: This API is experimental and might change in incompatible ways in the next release.

    - #### IndexSearcher

          public IndexSearcher(IndexReaderContext context,
                               ExecutorService executor)

      Creates a searcher searching the provided top-level `IndexReaderContext`.

      Given a non-`null` `ExecutorService` this method runs searches for each segment separately, using the provided ExecutorService. IndexSearcher will not close/awaitTermination this ExecutorService on close; you must do so, eventually, on your own. NOTE: if you are using `NIOFSDirectory`, do not use the shutdownNow method of ExecutorService as this uses Thread.interrupt under-the-hood which can silently close file descriptors (see LUCENE-2239).

      See Also:
        `IndexReaderContext`, `IndexReader.getContext()`
      WARNING: This API is experimental and might change in incompatible ways in the next release.

    - #### IndexSearcher

          public IndexSearcher(IndexReaderContext context)

      Creates a searcher searching the provided top-level `IndexReaderContext`.
      See Also:
        `IndexReaderContext`, `IndexReader.getContext()`
      WARNING: This API is experimental and might change in incompatible ways in the next release.

  - ### Method Detail

    - #### getDefaultSimilarity

          public static Similarity getDefaultSimilarity()

      Expert: returns a default Similarity instance. In general, this method is only called to initialize searchers and writers. User code and query implementations should respect `getSimilarity()`.
      NOTE: This API is for internal purposes only and might change in incompatible ways in the next release.

    - #### getDefaultQueryCache

          public static QueryCache getDefaultQueryCache()

      Expert: Get the default `QueryCache` or `null` if the cache is disabled.
      NOTE: This API is for internal purposes only and might change in incompatible ways in the next release.

    - #### setDefaultQueryCache

          public static void setDefaultQueryCache(QueryCache defaultQueryCache)

      Expert: set the default `QueryCache` instance.
      NOTE: This API is for internal purposes only and might change in incompatible ways in the next release.

    - #### getDefaultQueryCachingPolicy

          public static QueryCachingPolicy getDefaultQueryCachingPolicy()

      Expert: Get the default `QueryCachingPolicy`.
      NOTE: This API is for internal purposes only and might change in incompatible ways in the next release.

    - #### setDefaultQueryCachingPolicy

          public static void setDefaultQueryCachingPolicy(QueryCachingPolicy defaultQueryCachingPolicy)

      Expert: set the default `QueryCachingPolicy` instance.
      NOTE: This API is for internal purposes only and might change in incompatible ways in the next release.

    - #### setQueryCache

          public void setQueryCache(QueryCache queryCache)

      Set the `QueryCache` to use when scores are not needed. A value of `null` indicates that query matches should never be cached. This method should be called before starting using this `IndexSearcher`.

      NOTE: When using a query cache, queries should not be modified after they have been passed to IndexSearcher.

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

    - #### getQueryCache

          public QueryCache getQueryCache()

      Return the query cache of this `IndexSearcher`. This will be either the `default query cache` or the query cache that was last set through `setQueryCache(QueryCache)`. A return value of `null` indicates that caching is disabled.
      WARNING: This API is experimental and might change in incompatible ways in the next release.

    - #### setQueryCachingPolicy

          public void setQueryCachingPolicy(QueryCachingPolicy queryCachingPolicy)

      Set the `QueryCachingPolicy` to use for query caching. This method should be called before starting using this `IndexSearcher`.
      See Also:
        `QueryCachingPolicy`
      WARNING: This API is experimental and might change in incompatible ways in the next release.

    - #### getQueryCachingPolicy

          public QueryCachingPolicy getQueryCachingPolicy()

      Return the query cache of this `IndexSearcher`. This will be either the `default policy` or the policy that was last set through `setQueryCachingPolicy(QueryCachingPolicy)`.
      WARNING: This API is experimental and might change in incompatible ways in the next release.

    - #### slices

          protected IndexSearcher.LeafSlice[] slices(List<LeafReaderContext> leaves)

      Expert: Creates an array of leaf slices each holding a subset of the given leaves. Each `IndexSearcher.LeafSlice` is executed in a single thread. By default there will be one `IndexSearcher.LeafSlice` per leaf (`LeafReaderContext`).

    - #### getIndexReader

          public IndexReader getIndexReader()

      Return the `IndexReader` this searches.

    - #### doc

          public Document doc(int docID)
                       throws IOException

      Sugar for `.getIndexReader().document(docID)`
      Throws:
        `IOException`
      See Also:
        `IndexReader.document(int)`

    - #### doc

          public void doc(int docID,
                          StoredFieldVisitor fieldVisitor)
                   throws IOException

      Sugar for `.getIndexReader().document(docID, fieldVisitor)`
      Throws:
        `IOException`
      See Also:
        `IndexReader.document(int, StoredFieldVisitor)`

    - #### doc

          public Document doc(int docID,
                              Set<String> fieldsToLoad)
                       throws IOException

      Sugar for `.getIndexReader().document(docID, fieldsToLoad)`
      Throws:
        `IOException`
      See Also:
        `IndexReader.document(int, Set)`

    - #### setSimilarity

          public void setSimilarity(Similarity similarity)

      Expert: Set the Similarity implementation used by this IndexSearcher.

    - #### getSimilarity

          public Similarity getSimilarity()

      Expert: Get the `Similarity` to use to compute scores. This returns the `Similarity` that has been set through `setSimilarity(Similarity)` or the default `Similarity` if none has been set explicitly.

    - #### count

          public int count(Query query)
                    throws IOException

      Count how many documents match the given query.
      Throws:
        `IOException`

    - #### getSlices

          public IndexSearcher.LeafSlice[] getSlices()

      Returns the leaf slices used for concurrent searching, or null if no `ExecutorService` was passed to the constructor.
      WARNING: This API is experimental and might change in incompatible ways in the next release.

    - #### searchAfter

          public TopDocs searchAfter(ScoreDoc after,
                                     Query query,
                                     int numHits)
                              throws IOException

      Finds the top `n` hits for `query` where all results are after a previous result (`after`).

      By passing the bottom result from a previous page as `after`, this method can be used for efficient 'deep-paging' across potentially large result sets.

      Throws:
        `BooleanQuery.TooManyClauses` - If a query would exceed `BooleanQuery.getMaxClauseCount()` clauses.
        `IOException`

    - #### search

          public TopDocs search(Query query,
                                int n)
                         throws IOException

      Finds the top `n` hits for `query`.
      Throws:
        `BooleanQuery.TooManyClauses` - If a query would exceed `BooleanQuery.getMaxClauseCount()` clauses.
        `IOException`

    - #### search

          public void search(Query query,
                             Collector results)
                      throws IOException

      Lower-level search API.

      `LeafCollector.collect(int)` is called for every matching document.

      Throws:
        `BooleanQuery.TooManyClauses` - If a query would exceed `BooleanQuery.getMaxClauseCount()` clauses.
        `IOException`

    - #### search

          public TopFieldDocs search(Query query,
                                     int n,
                                     Sort sort,
                                     boolean doDocScores)
                              throws IOException

      Search implementation with arbitrary sorting, plus control over whether hit scores and max score should be computed. Finds the top `n` hits for `query`, and sorting the hits by the criteria in `sort`. If `doDocScores` is `true` then the score of each hit will be computed and returned. If `doMaxScore` is `true` then the maximum score over all collected hits will be computed.
      Throws:
        `BooleanQuery.TooManyClauses` - If a query would exceed `BooleanQuery.getMaxClauseCount()` clauses.
        `IOException`

    - #### search

          public TopFieldDocs search(Query query,
                                     int n,
                                     Sort sort)
                              throws IOException

      Search implementation with arbitrary sorting.
      Parameters:
        `query` - The query to search for
        `n` - Return only the top n results
        `sort` - The `Sort` object
      Returns:
        The top docs, sorted according to the supplied `Sort` instance
      Throws:
        `IOException` - if there is a low-level I/O error

    - #### searchAfter

          public TopDocs searchAfter(ScoreDoc after,
                                     Query query,
                                     int n,
                                     Sort sort)
                              throws IOException

      Finds the top `n` hits for `query` where all results are after a previous result (`after`).

      By passing the bottom result from a previous page as `after`, this method can be used for efficient 'deep-paging' across potentially large result sets.

      Throws:
        `BooleanQuery.TooManyClauses` - If a query would exceed `BooleanQuery.getMaxClauseCount()` clauses.
        `IOException`

    - #### searchAfter

          public TopFieldDocs searchAfter(ScoreDoc after,
                                          Query query,
                                          int numHits,
                                          Sort sort,
                                          boolean doDocScores)
                                   throws IOException

      Finds the top `n` hits for `query` where all results are after a previous result (`after`), allowing control over whether hit scores and max score should be computed.

      By passing the bottom result from a previous page as `after`, this method can be used for efficient 'deep-paging' across potentially large result sets. If `doDocScores` is `true` then the score of each hit will be computed and returned. If `doMaxScore` is `true` then the maximum score over all collected hits will be computed.

      Throws:
        `BooleanQuery.TooManyClauses` - If a query would exceed `BooleanQuery.getMaxClauseCount()` clauses.
        `IOException`

    - #### search

          public <C extends Collector,T> T search(Query query,
                                                  CollectorManager<C,T> collectorManager)
                                           throws IOException

      Lower-level search API. Search all leaves using the given `CollectorManager`. In contrast to `search(Query, Collector)`, this method will use the searcher's `ExecutorService` in order to parallelize execution of the collection on the configured `leafSlices`.
      Throws:
        `IOException`
      See Also:
        `CollectorManager`
      WARNING: This API is experimental and might change in incompatible ways in the next release.

    - #### search

          protected void search(List<LeafReaderContext> leaves,
                                Weight weight,
                                Collector collector)
                         throws IOException

      Lower-level search API.

      `LeafCollector.collect(int)` is called for every document.

      NOTE: this method executes the searches on all given leaves exclusively. To search across all the searchers leaves use `leafContexts`.

      Parameters:
        `leaves` - the searchers leaves to execute the searches on
        `weight` - to match documents
        `collector` - to receive hits
      Throws:
        `BooleanQuery.TooManyClauses` - If a query would exceed `BooleanQuery.getMaxClauseCount()` clauses.
        `IOException`

    - #### rewrite

          public Query rewrite(Query original)
                        throws IOException

      Expert: called to re-write queries into primitive queries.
      Throws:
        `BooleanQuery.TooManyClauses` - If a query would exceed `BooleanQuery.getMaxClauseCount()` clauses.
        `IOException`

    - #### explain

          public Explanation explain(Query query,
                                     int doc)
                              throws IOException

      Returns an Explanation that describes how `doc` scored against `query`.

      This is intended to be used in developing Similarity implementations, and, for good performance, should not be displayed with every hit. Computing an explanation is as expensive as executing the query over the entire index.

      Throws:
        `IOException`

    - #### explain

          protected Explanation explain(Weight weight,
                                        int doc)
                                 throws IOException

      Expert: low-level implementation method Returns an Explanation that describes how `doc` scored against `weight`.

      This is intended to be used in developing Similarity implementations, and, for good performance, should not be displayed with every hit. Computing an explanation is as expensive as executing the query over the entire index.

      Applications should call `explain(Query, int)`.

      Throws:
        `BooleanQuery.TooManyClauses` - If a query would exceed `BooleanQuery.getMaxClauseCount()` clauses.
        `IOException`

    - #### createWeight

          public Weight createWeight(Query query,
                                     ScoreMode scoreMode,
                                     float boost)
                              throws IOException

      Creates a `Weight` for the given query, potentially adding caching if possible and configured.
      Throws:
        `IOException`
      WARNING: This API is experimental and might change in incompatible ways in the next release.

    - #### getTopReaderContext

          public IndexReaderContext getTopReaderContext()

      Returns this searchers the top-level `IndexReaderContext`.
      See Also:
        `IndexReader.getContext()`

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

    - #### termStatistics

          public TermStatistics termStatistics(Term term,
                                               TermStates context)
                                        throws IOException

      Returns `TermStatistics` for a term, or `null` if the term does not exist. This can be overridden for example, to return a term's statistics across a distributed collection.
      Throws:
        `IOException`
      WARNING: This API is experimental and might change in incompatible ways in the next release.

    - #### collectionStatistics

          public CollectionStatistics collectionStatistics(String field)
                                                    throws IOException

      Returns `CollectionStatistics` for a field, or `null` if the field does not exist (has no indexed terms) This can be overridden for example, to return a field's statistics across a distributed collection.
      Throws:
        `IOException`
      WARNING: This API is experimental and might change in incompatible ways in the next release.

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