## org.apache.lucene.search
Class IndexSearcher

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

All Implemented Interfaces:
  Closeable, Searchable

Direct Known Subclasses:
  AssertingIndexSearcher, CheckHits.ExplanationAssertingSearcher

    public class IndexSearcher

extends Searcher

Implements search over a single IndexReader.

Applications usually need only call the inherited `search(Query,int)` or `search(Query,Filter,int)` methods. 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 `IndexReader.openIfChanged(org.apache.lucene.index.IndexReader)` 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 (`IndexReader.open(IndexWriter,boolean)`). Once you have a new `IndexReader`, it's relatively cheap to create a new IndexSearcher from it.

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.

Field Summary
`protected int[]` `docStarts`
`protected IndexReader[]` `subReaders`
`protected IndexSearcher[]` `subSearchers`

Constructor Summary
`IndexSearcher(Directory path)` Deprecated. use `IndexSearcher(IndexReader)` instead.
`IndexSearcher(Directory path, boolean readOnly)` Deprecated. Use `IndexSearcher(IndexReader)` instead.
`IndexSearcher(IndexReader r)` Creates a searcher searching the provided index.
`IndexSearcher(IndexReader r, ExecutorService executor)` Runs searches for each segment separately, using the provided ExecutorService.
`IndexSearcher(IndexReader reader, IndexReader[] subReaders, int[] docStarts)` Expert: directly specify the reader, subReaders and their docID starts.
`IndexSearcher(IndexReader reader, IndexReader[] subReaders, int[] docStarts, ExecutorService executor)` Expert: directly specify the reader, subReaders and their docID starts, and an ExecutorService.

Method Summary
`void` `close()` Note that the underlying IndexReader is not closed, if IndexSearcher was constructed with IndexSearcher(IndexReader r).
`Weight` `createNormalizedWeight(Query query)` Creates a normalized weight for a top-level `Query`.
`Document` `doc(int docID)` Returns the stored fields of document `i`.
`Document` `doc(int docID, FieldSelector fieldSelector)` Get the `Document` at the `n`th position.
`int` `docFreq(Term term)` Returns total docFreq for this term.
`Explanation` `explain(Query query, int doc)` Returns an Explanation that describes how `doc` scored against `query`.
`Explanation` `explain(Weight weight, int doc)` Expert: low-level implementation method Returns an Explanation that describes how `doc` scored against `weight`.
`protected void` `gatherSubReaders(List<IndexReader> allSubReaders, IndexReader r)`
`IndexReader` `getIndexReader()` Return the `IndexReader` this searches.
`Similarity` `getSimilarity()` Expert: Return the Similarity implementation used by this Searcher.
`IndexReader[]` `getSubReaders()` Returns the atomic subReaders used by this searcher.
`int` `maxDoc()` Expert: Returns one greater than the largest possible document number.
`Query` `rewrite(Query original)` Expert: called to re-write queries into primitive queries.
`void` `search(Query query, Collector results)` Lower-level search API.
`void` `search(Query query, Filter filter, Collector results)` Lower-level search API.
`TopDocs` `search(Query query, Filter filter, int n)` Finds the top `n` hits for `query`, applying `filter` if non-null.
`TopFieldDocs` `search(Query query, Filter filter, int n, Sort sort)` Search implementation with arbitrary sorting.
`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 and no filter.
`void` `search(Weight weight, Filter filter, Collector collector)` Lower-level search API.
`TopDocs` `search(Weight weight, Filter filter, int nDocs)` Expert: Low-level search implementation.
`TopFieldDocs` `search(Weight weight, Filter filter, int nDocs, Sort sort)` Expert: Low-level search implementation with arbitrary sorting.
`protected TopFieldDocs` `search(Weight weight, Filter filter, int nDocs, Sort sort, boolean fillFields)` Just like `search(Weight, Filter, int, Sort)`, but you choose whether or not the fields in the returned `FieldDoc` instances should be set by specifying fillFields.
`protected TopDocs` `search(Weight weight, Filter filter, ScoreDoc after, int nDocs)` Expert: Low-level search implementation.
`TopDocs` `searchAfter(ScoreDoc after, Query query, Filter filter, int n)` Finds the top `n` hits for `query`, applying `filter` if non-null, where all results are after a previous result (`after`).
`TopDocs` `searchAfter(ScoreDoc after, Query query, int n)` Finds the top `n` hits for `query` where all results are after a previous result (`after`).
`void` `setDefaultFieldSortScoring(boolean doTrackScores, boolean doMaxScore)` By default, no scores are computed when sorting by field (using `search(Query,Filter,int,Sort)`).
`void` `setSimilarity(Similarity similarity)` Expert: Set the Similarity implementation used by this Searcher.
`String` `toString()`

Methods inherited from class org.apache.lucene.search.Searcher
`createWeight, docFreqs`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Field Detail

### subReaders

    protected final IndexReader[] subReaders

### docStarts

    protected final int[] docStarts

### subSearchers

    protected final IndexSearcher[] subSearchers

Constructor Detail

### IndexSearcher

    @Deprecated
    public IndexSearcher(Directory path)
                  throws CorruptIndexException,
                         IOException

  Deprecated. use `IndexSearcher(IndexReader)` instead.

  Creates a searcher searching the index in the named directory, with readOnly=true

  Parameters:
    `path` - directory where IndexReader will be opened
  Throws:
    `CorruptIndexException` - if the index is corrupt
    `IOException` - if there is a low-level IO error

### IndexSearcher

    @Deprecated
    public IndexSearcher(Directory path,
                                    boolean readOnly)
                  throws CorruptIndexException,
                         IOException

  Deprecated. Use `IndexSearcher(IndexReader)` instead.

  Creates a searcher searching the index in the named directory. You should pass readOnly=true, since it gives much better concurrent performance, unless you intend to do write operations (delete documents or change norms) with the underlying IndexReader.

  Parameters:
    `path` - directory where IndexReader will be opened
    `readOnly` - if true, the underlying IndexReader will be opened readOnly
  Throws:
    `CorruptIndexException` - if the index is corrupt
    `IOException` - if there is a low-level IO error

### 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 shutdown/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(IndexReader reader,
                         IndexReader[] subReaders,
                         int[] docStarts)

  Expert: directly specify the reader, subReaders and their docID starts.

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

### IndexSearcher

    public IndexSearcher(IndexReader reader,
                         IndexReader[] subReaders,
                         int[] docStarts,
                         ExecutorService executor)

  Expert: directly specify the reader, subReaders and their docID starts, and an ExecutorService. In this case, each segment will be separately searched using the ExecutorService. IndexSearcher will not shutdown/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.

Method Detail

### gatherSubReaders

    protected void gatherSubReaders(List<IndexReader> allSubReaders,
                                    IndexReader r)

### getIndexReader

    public IndexReader getIndexReader()

  Return the `IndexReader` this searches.

### getSubReaders

    public IndexReader[] getSubReaders()

  Returns the atomic subReaders used by this searcher.

### maxDoc

    public int maxDoc()

  Expert: Returns one greater than the largest possible document number.

  Specified by:
    `maxDoc` in interface `Searchable`
  Specified by:
    `maxDoc` in class `Searcher`
  See Also:
    `IndexReader.maxDoc()`

### docFreq

    public int docFreq(Term term)
                throws IOException

  Returns total docFreq for this term.

  Specified by:
    `docFreq` in interface `Searchable`
  Specified by:
    `docFreq` in class `Searcher`
  Throws:
    `IOException`
  See Also:
    `IndexReader.docFreq(Term)`

### doc

    public Document doc(int docID)
                 throws CorruptIndexException,
                        IOException

  Description copied from interface: `Searchable`
  Returns the stored fields of document `i`.

  Specified by:
    `doc` in interface `Searchable`
  Specified by:
    `doc` in class `Searcher`
  Throws:
    `CorruptIndexException` - if the index is corrupt
    `IOException` - if there is a low-level IO error
  See Also:
    `IndexReader.document(int)`

### doc

    public Document doc(int docID,
                        FieldSelector fieldSelector)
                 throws CorruptIndexException,
                        IOException

  Description copied from interface: `Searchable`
  Get the `Document` at the `n`th position. The `FieldSelector` may be used to determine what `Field`s to load and how they should be loaded. NOTE: If the underlying Reader (more specifically, the underlying `FieldsReader`) is closed before the lazy `Field` is loaded an exception may be thrown. If you want the value of a lazy `Field` to be available after closing you must explicitly load it or fetch the Document again with a new loader.

  Specified by:
    `doc` in interface `Searchable`
  Specified by:
    `doc` in class `Searcher`
  Parameters:
    `docID` - Get the document at the `n`th position
    `fieldSelector` - The `FieldSelector` to use to determine what Fields should be loaded on the Document. May be null, in which case all Fields will be loaded.
  Returns:
    The stored fields of the `Document` at the nth position
  Throws:
    `CorruptIndexException` - if the index is corrupt
    `IOException` - if there is a low-level IO error
  See Also:
    `IndexReader.document(int, FieldSelector)`, `Fieldable`, `FieldSelector`, `SetBasedFieldSelector`, `LoadFirstFieldSelector`

### setSimilarity

    public void setSimilarity(Similarity similarity)

  Expert: Set the Similarity implementation used by this Searcher.

  Overrides:
    `setSimilarity` in class `Searcher`
  See Also:
    `Similarity.setDefault(Similarity)`

### getSimilarity

    public Similarity getSimilarity()

  Description copied from class: `Searcher`
  Expert: Return the Similarity implementation used by this Searcher.

  This defaults to the current value of `Similarity.getDefault()`.

  Overrides:
    `getSimilarity` in class `Searcher`

### close

    public void close()
               throws IOException

  Note that the underlying IndexReader is not closed, if IndexSearcher was constructed with IndexSearcher(IndexReader r). If the IndexReader was supplied implicitly by specifying a directory, then the IndexReader is closed.

  Specified by:
    `close` in interface `Closeable`
  Specified by:
    `close` in interface `Searchable`
  Specified by:
    `close` in class `Searcher`
  Throws:
    `IOException`

### searchAfter

    public TopDocs searchAfter(ScoreDoc after,
                               Query query,
                               int n)
                        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`
    `IOException`

### searchAfter

    public TopDocs searchAfter(ScoreDoc after,
                               Query query,
                               Filter filter,
                               int n)
                        throws IOException

  Finds the top `n` hits for `query`, applying `filter` if non-null, 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`
    `IOException`

### search

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

  Finds the top `n` hits for `query`.

  Overrides:
    `search` in class `Searcher`
  Throws:
    `BooleanQuery.TooManyClauses`
    `IOException`

### search

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

  Finds the top `n` hits for `query`, applying `filter` if non-null.

  Overrides:
    `search` in class `Searcher`
  Throws:
    `BooleanQuery.TooManyClauses`
    `IOException`

### search

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

  Lower-level search API.

  `Collector.collect(int)` is called for every matching document.
  Collector-based access to remote indexes is discouraged.

  Applications should only use this if they need all of the matching documents. The high-level search API (`Searcher.search(Query, Filter, int)`) is usually more efficient, as it skips non-high-scoring hits.

  Overrides:
    `search` in class `Searcher`
  Parameters:
    `query` - to match documents
    `filter` - if non-null, used to permit documents to be collected.
    `results` - to receive hits
  Throws:
    `BooleanQuery.TooManyClauses`
    `IOException`

### search

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

  Lower-level search API.

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

  Applications should only use this if they need all of the matching documents. The high-level search API (`Searcher.search(Query, int)`) is usually more efficient, as it skips non-high-scoring hits.

  Note: The `score` passed to this method is a raw score. In other words, the score will not necessarily be a float whose value is between 0 and 1.

  Overrides:
    `search` in class `Searcher`
  Throws:
    `BooleanQuery.TooManyClauses`
    `IOException`

### search

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

  Search implementation with arbitrary sorting. Finds the top `n` hits for `query`, applying `filter` if non-null, and sorting the hits by the criteria in `sort`.

  NOTE: this does not compute scores by default; use `setDefaultFieldSortScoring(boolean, boolean)` to enable scoring.

  Overrides:
    `search` in class `Searcher`
  Throws:
    `BooleanQuery.TooManyClauses`
    `IOException`

### search

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

  Search implementation with arbitrary sorting and no filter.

  Overrides:
    `search` in class `Searcher`
  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`

### search

    public TopDocs search(Weight weight,
                          Filter filter,
                          int nDocs)
                   throws IOException

  Expert: Low-level search implementation. Finds the top `n` hits for `query`, applying `filter` if non-null.

  Applications should usually call `Searcher.search(Query,int)` or `Searcher.search(Query,Filter,int)` instead.

  Specified by:
    `search` in interface `Searchable`
  Specified by:
    `search` in class `Searcher`
  Throws:
    `BooleanQuery.TooManyClauses`
    `IOException`

### search

    protected TopDocs search(Weight weight,
                             Filter filter,
                             ScoreDoc after,
                             int nDocs)
                      throws IOException

  Expert: Low-level search implementation. Finds the top `n` hits for `query`, applying `filter` if non-null, returning results after `after`.

  Throws:
    `BooleanQuery.TooManyClauses`
    `IOException`

### search

    public TopFieldDocs search(Weight weight,
                               Filter filter,
                               int nDocs,
                               Sort sort)
                        throws IOException

  Expert: Low-level search implementation with arbitrary sorting. Finds the top `n` hits for `query`, applying `filter` if non-null, and sorting the hits by the criteria in `sort`.

  Applications should usually call `Searcher.search(Query,Filter,int,Sort)` instead.

  Specified by:
    `search` in interface `Searchable`
  Specified by:
    `search` in class `Searcher`
  Throws:
    `BooleanQuery.TooManyClauses`
    `IOException`

### search

    protected TopFieldDocs search(Weight weight,
                                  Filter filter,
                                  int nDocs,
                                  Sort sort,
                                  boolean fillFields)
                           throws IOException

  Just like `search(Weight, Filter, int, Sort)`, but you choose whether or not the fields in the returned `FieldDoc` instances should be set by specifying fillFields.

  NOTE: this does not compute scores by default. If you need scores, create a `TopFieldCollector` instance by calling `TopFieldCollector.create(org.apache.lucene.search.Sort, int, boolean, boolean, boolean, boolean)` and then pass that to `search(Weight, Filter, Collector)`.

  Throws:
    `IOException`

### search

    public void search(Weight weight,
                       Filter filter,
                       Collector collector)
                throws IOException

  Lower-level search API.

  `Collector.collect(int)` is called for every document.
  Collector-based access to remote indexes is discouraged.

  Applications should only use this if they need all of the matching documents. The high-level search API (`Searcher.search(Query,int)`) is usually more efficient, as it skips non-high-scoring hits.

  Specified by:
    `search` in interface `Searchable`
  Specified by:
    `search` in class `Searcher`
  Parameters:
    `weight` - to match documents
    `filter` - if non-null, used to permit documents to be collected.
    `collector` - to receive hits
  Throws:
    `BooleanQuery.TooManyClauses`
    `IOException`

### rewrite

    public Query rewrite(Query original)
                  throws IOException

  Expert: called to re-write queries into primitive queries.

  Specified by:
    `rewrite` in interface `Searchable`
  Specified by:
    `rewrite` in class `Searcher`
  Throws:
    `BooleanQuery.TooManyClauses`
    `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.

  Overrides:
    `explain` in class `Searcher`
  Throws:
    `IOException`

### explain

    public 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 `Searcher.explain(Query, int)`.

  Specified by:
    `explain` in interface `Searchable`
  Specified by:
    `explain` in class `Searcher`
  Throws:
    `BooleanQuery.TooManyClauses`
    `IOException`

### setDefaultFieldSortScoring

    public void setDefaultFieldSortScoring(boolean doTrackScores,
                                           boolean doMaxScore)

  By default, no scores are computed when sorting by field (using `search(Query,Filter,int,Sort)`). You can change that, per IndexSearcher instance, by calling this method. Note that this will incur a CPU cost.

  Parameters:
    `doTrackScores` - If true, then scores are returned for every matching document in `TopFieldDocs`.
    `doMaxScore` - If true, then the max score for all matching docs is computed.

### createNormalizedWeight

    public Weight createNormalizedWeight(Query query)
                                  throws IOException

  Creates a normalized weight for a top-level `Query`. The query is rewritten by this method and `Query.createWeight(org.apache.lucene.search.Searcher)` called, afterwards the `Weight` is normalized. The returned `Weight` can then directly be used to get a `Scorer`.

  Overrides:
    `createNormalizedWeight` in class `Searcher`
  Throws:
    `IOException`
  NOTE: This API is for internal purposes only and might change in incompatible ways in the next release.

### toString

    public String toString()

  Overrides:
    `toString` in class `Object`