Package 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 collectorManagers manually with either `TopScoreDocCollectorManager` or `TopFieldCollectorManager` and call `search(Query, CollectorManager)`.

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
Description
`static final class`
`IndexSearcher.LeafReaderContextPartition`
Holds information about a specific leaf context and the corresponding range of doc ids to search within.
`static class`
`IndexSearcher.LeafSlice`
A class holding a subset of the `IndexSearcher`s leaf contexts to be executed within a single thread.
`static class`
`IndexSearcher.TooManyClauses`
Thrown when an attempt is made to add more than `IndexSearcher.TooManyClauses.getMaxClauseCount()` clauses.
`static class`
`IndexSearcher.TooManyNestedClauses`
Thrown when a client attempts to execute a Query that has more than `IndexSearcher.TooManyClauses.getMaxClauseCount()` total clauses cumulatively in all of its children.

## Field Summary

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

## Constructor Summary

Constructors
Constructor
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, Executor executor)`
Creates a searcher searching the provided top-level `IndexReaderContext`.
`IndexSearcher(IndexReader r, Executor executor)`
Runs searches for each segment separately, using the provided Executor.

## Method Summary

Modifier and Type
Method
Description
`CollectionStatistics`
`collectionStatistics(String field)`
Returns `CollectionStatistics` for a field, or `null` if the field does not exist (has no indexed terms)
`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.
`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.
`List<LeafReaderContext>`
`getLeafContexts()`
Expert: returns leaf contexts associated with this searcher.
`static int`
`getMaxClauseCount()`
Return the maximum number of clauses permitted, 1024 by default.
`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.
`final IndexSearcher.LeafSlice[]`
`getSlices()`
Returns the leaf slices used for concurrent searching.
`TaskExecutor`
`getTaskExecutor()`
Returns the `TaskExecutor` that this searcher relies on to execute concurrent operations
`QueryTimeout`
`getTimeout()`
Get the configured `QueryTimeout` for all searches that run through this `IndexSearcher`, or `null` if not set.
`IndexReaderContext`
`getTopReaderContext()`
Returns this searcher's top-level `IndexReaderContext`.
`Query`
`rewrite(Query original)`
Expert: called to re-write queries into primitive queries.
`protected void`
`search(IndexSearcher.LeafReaderContextPartition[] partitions, Weight weight, Collector collector)`
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.
`void`
`search(Query query, Collector collector)`
Deprecated.
This method is being deprecated in favor of `search(Query, CollectorManager)` due to its support for concurrency in IndexSearcher
`<C extends Collector, T>
T`
`search(Query query, CollectorManager<C,T> collectorManager)`
Lower-level search API.
`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.
`protected void`
`searchLeaf(LeafReaderContext ctx, int minDocId, int maxDocId, Weight weight, Collector collector)`
Lower-level search API
`static void`
`setDefaultQueryCache(QueryCache defaultQueryCache)`
Expert: set the default `QueryCache` instance.
`static void`
`setDefaultQueryCachingPolicy(QueryCachingPolicy defaultQueryCachingPolicy)`
Expert: set the default `QueryCachingPolicy` instance.
`static void`
`setMaxClauseCount(int value)`
Set the maximum number of clauses permitted per Query.
`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.
`void`
`setTimeout(QueryTimeout queryTimeout)`
Set a `QueryTimeout` for all searches that run through this `IndexSearcher`.
`protected IndexSearcher.LeafSlice[]`
`slices(List<LeafReaderContext> leaves)`
Expert: Creates an array of leaf slices each holding a subset of the given leaves.
`static IndexSearcher.LeafSlice[]`
`slices(List<LeafReaderContext> leaves, int maxDocsPerSlice, int maxSegmentsPerSlice, boolean allowSegmentPartitions)`
Static method to segregate LeafReaderContexts amongst multiple slices.
`StoredFields`
`storedFields()`
Returns a `StoredFields` reader for the stored fields of this index.
`TermStatistics`
`termStatistics(Term term, int docFreq, long totalTermFreq)`
Returns `TermStatistics` for a term.
`boolean`
`timedOut()`
Returns true if any search hit the `timeout`.
`String`
`toString()`

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

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

## Field Details

### readerContext

protected final IndexReaderContext readerContext

### leafContexts

protected final List<LeafReaderContext> leafContexts

## Constructor Details

### IndexSearcher

public IndexSearcher(IndexReader r)
Creates a searcher searching the provided index.

### IndexSearcher

public IndexSearcher(IndexReader r, Executor executor)
Runs searches for each segment separately, using the provided Executor. 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, Executor executor)
Creates a searcher searching the provided top-level `IndexReaderContext`.

Given a non-`null` `Executor` this method runs searches for each segment separately, using the provided Executor. 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 Details

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

### getLeafContexts

public List<LeafReaderContext> getLeafContexts()
Expert: returns leaf contexts associated with this searcher. This is an internal method exposed for tests only.

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.

### getMaxClauseCount

public static int getMaxClauseCount()
Return the maximum number of clauses permitted, 1024 by default. Attempts to add more than the permitted number of clauses cause `IndexSearcher.TooManyClauses` to be thrown.

See Also:
  - `setMaxClauseCount(int)`

### setMaxClauseCount

public static void setMaxClauseCount(int value)
Set the maximum number of clauses permitted per Query. Default value is 1024.

### 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, segments with more than MAX_DOCS_PER_SLICE will get their own thread.

It is possible to leverage intra-segment concurrency by splitting segments into multiple partitions. Such behaviour is not enabled by default as there is still a performance penalty for queries that require segment-level computation ahead of time, such as points/range queries. This is an implementation limitation that we expect to improve in future releases, see the corresponding github issue.

### slices

public static IndexSearcher.LeafSlice[] slices(List<LeafReaderContext> leaves, int maxDocsPerSlice, int maxSegmentsPerSlice, boolean allowSegmentPartitions)
Static method to segregate LeafReaderContexts amongst multiple slices. Creates slices according to the provided max number of documents per slice and max number of segments per slice. Splits segments into partitions when the last argument is true.

Parameters:
  `leaves` - the leaves to slice
  `maxDocsPerSlice` - the maximum number of documents in a single slice
  `maxSegmentsPerSlice` - the maximum number of segments in a single slice
  `allowSegmentPartitions` - whether segments may be split into partitions according to the provided maxDocsPerSlice argument. When `true`, if a segment holds more documents than the provided max docs per slice, it is split into equal size partitions that each gets its own slice assigned.
Returns:
  the array of slices

### getIndexReader

public IndexReader getIndexReader()
Return the `IndexReader` this searches.

### storedFields

public StoredFields storedFields() throws IOException
Returns a `StoredFields` reader for the stored fields of this index.

Sugar for `.getIndexReader().storedFields()`

This call never returns `null`, even if no stored fields were indexed. The returned instance should only be used by a single thread.

Example:

     TopDocs hits = searcher.search(query, 10);
     StoredFields storedFields = searcher.storedFields();
     for (ScoreDoc hit : hits.scoreDocs) {
       Document doc = storedFields.document(hit.doc);
     }

Throws:
  `IOException` - If there is a low-level IO error
See Also:
  - `IndexReader.storedFields()`

### 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. May be faster than counting number of hits by collecting all matches, as the number of hits is retrieved from the index statistics when possible.

Throws:
  `IOException`

### getSlices

public final IndexSearcher.LeafSlice[] getSlices()
Returns the leaf slices used for concurrent searching. Override `slices(List)` to customize how slices are created.

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:
  `IndexSearcher.TooManyClauses` - If a query would exceed `getMaxClauseCount()` clauses.
  `IOException`

### getTimeout

public QueryTimeout getTimeout()
Get the configured `QueryTimeout` for all searches that run through this `IndexSearcher`, or `null` if not set.

### setTimeout

public void setTimeout(QueryTimeout queryTimeout)
Set a `QueryTimeout` for all searches that run through this `IndexSearcher`.

### search

public TopDocs search(Query query, int n) throws IOException
Finds the top `n` hits for `query`.

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

### search

@Deprecated public void search(Query query, Collector collector) throws IOException
Deprecated.
This method is being deprecated in favor of `search(Query, CollectorManager)` due to its support for concurrency in IndexSearcher
Lower-level search API.

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

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

### timedOut

public boolean timedOut()
Returns true if any search hit the `timeout`.

### 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:
  `IndexSearcher.TooManyClauses` - If a query would exceed `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:
  `IndexSearcher.TooManyClauses` - If a query would exceed `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:
  `IndexSearcher.TooManyClauses` - If a query would exceed `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 `Executor` in order to parallelize execution of the collection on the configured `getSlices()`.

Throws:
  `IOException`
See Also:
  - `CollectorManager`
WARNING: This API is experimental and might change in incompatible ways in the next release.

### search

protected void search(IndexSearcher.LeafReaderContextPartition[] partitions, Weight weight, Collector collector) throws IOException
Lower-level search API.

`searchLeaf(LeafReaderContext, int, int, Weight, Collector)` is called for every leaf partition.

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

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

### searchLeaf

protected void searchLeaf(LeafReaderContext ctx, int minDocId, int maxDocId, Weight weight, Collector collector) throws IOException
Lower-level search API

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

Parameters:
  `ctx` - the leaf to execute the search against
  `minDocId` - the lower bound of the doc id range to search
  `maxDocId` - the upper bound of the doc id range to search
  `weight` - to match document
  `collector` - to receive hits
Throws:
  `IndexSearcher.TooManyClauses` - If a query would exceed `getMaxClauseCount()` clauses.
  `IOException`

### rewrite

public Query rewrite(Query original) throws IOException
Expert: called to re-write queries into primitive queries.

Throws:
  `IndexSearcher.TooManyClauses` - If a query would exceed `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:
  `IndexSearcher.TooManyClauses` - If a query would exceed `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 searcher's top-level `IndexReaderContext`.

See Also:
  - `IndexReader.getContext()`

### toString

public String toString()

Overrides:
  `toString` in class `Object`

### termStatistics

public TermStatistics termStatistics(Term term, int docFreq, long totalTermFreq) throws IOException
Returns `TermStatistics` for a term.

This can be overridden for example, to return a term's statistics across a distributed collection.

Parameters:
  `docFreq` - The document frequency of the term. It must be greater or equal to 1.
  `totalTermFreq` - The total term frequency.
Returns:
  A `TermStatistics` (never null).
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.

### getTaskExecutor

public TaskExecutor getTaskExecutor()
Returns the `TaskExecutor` that this searcher relies on to execute concurrent operations

Returns:
  the task executor