Class IndexSearcher
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: 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 IndexSearcherIndexSearcher instance; use your own (non-Lucene)
objects instead.
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic final classHolds information about a specific leaf context and the corresponding range of doc ids to search within.static classA class holding a subset of theIndexSearchers leaf contexts to be executed within a single thread.static classThrown when an attempt is made to add more thanIndexSearcher.TooManyClauses.getMaxClauseCount()clauses.static classThrown when a client attempts to execute a Query that has more thanIndexSearcher.TooManyClauses.getMaxClauseCount()total clauses cumulatively in all of its children. -
Field Summary
FieldsModifier and TypeFieldDescriptionprotected final List<LeafReaderContext> protected final IndexReaderContext -
Constructor Summary
ConstructorsConstructorDescriptionCreates a searcher searching the provided index.IndexSearcher(IndexReaderContext context) Creates a searcher searching the provided top-levelIndexReaderContext.IndexSearcher(IndexReaderContext context, Executor executor) Creates a searcher searching the provided top-levelIndexReaderContext.IndexSearcher(IndexReader r, Executor executor) Runs searches for each segment separately, using the provided Executor. -
Method Summary
Modifier and TypeMethodDescriptioncollectionStatistics(String field) ReturnsCollectionStatisticsfor a field, ornullif the field does not exist (has no indexed terms)intCount how many documents match the given query.createWeight(Query query, ScoreMode scoreMode, float boost) Creates aWeightfor the given query, potentially adding caching if possible and configured.Returns an Explanation that describes howdocscored againstquery.protected ExplanationExpert: low-level implementation method Returns an Explanation that describes howdocscored againstweight.static QueryCacheExpert: Get the defaultQueryCacheornullif the cache is disabled.static QueryCachingPolicyExpert: Get the defaultQueryCachingPolicy.static SimilarityExpert: returns a default Similarity instance.Return theIndexReaderthis searches.Expert: returns leaf contexts associated with this searcher.static intReturn the maximum number of clauses permitted, 1024 by default.Return the query cache of thisIndexSearcher.Return the query cache of thisIndexSearcher.Expert: Get theSimilarityto use to compute scores.final IndexSearcher.LeafSlice[]Returns the leaf slices used for concurrent searching.Returns theTaskExecutorthat this searcher relies on to execute concurrent operationsGet the configuredQueryTimeoutfor all searches that run through thisIndexSearcher, ornullif not set.Returns this searcher's top-levelIndexReaderContext.Expert: called to re-write queries into primitive queries.protected voidsearch(IndexSearcher.LeafReaderContextPartition[] partitions, Weight weight, Collector collector) Lower-level search API.Finds the topnhits forquery.Search implementation with arbitrary sorting.Search implementation with arbitrary sorting, plus control over whether hit scores and max score should be computed.voidDeprecated.<C extends Collector,T>
Tsearch(Query query, CollectorManager<C, T> collectorManager) Lower-level search API.searchAfter(ScoreDoc after, Query query, int numHits) Finds the topnhits forquerywhere all results are after a previous result (after).searchAfter(ScoreDoc after, Query query, int n, Sort sort) Finds the topnhits forquerywhere all results are after a previous result (after).searchAfter(ScoreDoc after, Query query, int numHits, Sort sort, boolean doDocScores) Finds the topnhits forquerywhere all results are after a previous result (after), allowing control over whether hit scores and max score should be computed.protected voidsearchLeaf(LeafReaderContext ctx, int minDocId, int maxDocId, Weight weight, Collector collector) Lower-level search APIstatic voidsetDefaultQueryCache(QueryCache defaultQueryCache) Expert: set the defaultQueryCacheinstance.static voidsetDefaultQueryCachingPolicy(QueryCachingPolicy defaultQueryCachingPolicy) Expert: set the defaultQueryCachingPolicyinstance.static voidsetMaxClauseCount(int value) Set the maximum number of clauses permitted per Query.voidsetQueryCache(QueryCache queryCache) Set theQueryCacheto use when scores are not needed.voidsetQueryCachingPolicy(QueryCachingPolicy queryCachingPolicy) Set theQueryCachingPolicyto use for query caching.voidsetSimilarity(Similarity similarity) Expert: Set the Similarity implementation used by this IndexSearcher.voidsetTimeout(QueryTimeout queryTimeout) Set aQueryTimeoutfor all searches that run through thisIndexSearcher.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.Returns aStoredFieldsreader for the stored fields of this index.termStatistics(Term term, int docFreq, long totalTermFreq) ReturnsTermStatisticsfor a term.booleantimedOut()Returns true if any search hit thetimeout.toString()
-
Field Details
-
readerContext
-
leafContexts
-
-
Constructor Details
-
IndexSearcher
Creates a searcher searching the provided index. -
IndexSearcher
Runs searches for each segment separately, using the provided Executor. NOTE: if you are usingNIOFSDirectory, 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
Creates a searcher searching the provided top-levelIndexReaderContext.Given a non-
nullExecutorthis method runs searches for each segment separately, using the provided Executor. NOTE: if you are usingNIOFSDirectory, 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:
- WARNING: This API is experimental and might change in incompatible ways in the next release.
-
IndexSearcher
Creates a searcher searching the provided top-levelIndexReaderContext.- See Also:
- WARNING: This API is experimental and might change in incompatible ways in the next release.
-
-
Method Details
-
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 respectgetSimilarity().- NOTE: This API is for internal purposes only and might change in incompatible ways in the next release.
-
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
Expert: Get the defaultQueryCacheornullif the cache is disabled.- NOTE: This API is for internal purposes only and might change in incompatible ways in the next release.
-
setDefaultQueryCache
Expert: set the defaultQueryCacheinstance.- NOTE: This API is for internal purposes only and might change in incompatible ways in the next release.
-
getDefaultQueryCachingPolicy
Expert: Get the defaultQueryCachingPolicy.- NOTE: This API is for internal purposes only and might change in incompatible ways in the next release.
-
setDefaultQueryCachingPolicy
Expert: set the defaultQueryCachingPolicyinstance.- 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 causeIndexSearcher.TooManyClausesto be thrown.- See Also:
-
setMaxClauseCount
public static void setMaxClauseCount(int value) Set the maximum number of clauses permitted per Query. Default value is 1024. -
setQueryCache
Set theQueryCacheto use when scores are not needed. A value ofnullindicates that query matches should never be cached. This method should be called before starting using thisIndexSearcher.NOTE: When using a query cache, queries should not be modified after they have been passed to IndexSearcher.
- See Also:
- WARNING: This API is experimental and might change in incompatible ways in the next release.
-
getQueryCache
Return the query cache of thisIndexSearcher. This will be either thedefault query cacheor the query cache that was last set throughsetQueryCache(QueryCache). A return value ofnullindicates that caching is disabled.- WARNING: This API is experimental and might change in incompatible ways in the next release.
-
setQueryCachingPolicy
Set theQueryCachingPolicyto use for query caching. This method should be called before starting using thisIndexSearcher.- See Also:
- WARNING: This API is experimental and might change in incompatible ways in the next release.
-
getQueryCachingPolicy
Return the query cache of thisIndexSearcher. This will be either thedefault policyor the policy that was last set throughsetQueryCachingPolicy(QueryCachingPolicy).- WARNING: This API is experimental and might change in incompatible ways in the next release.
-
slices
Expert: Creates an array of leaf slices each holding a subset of the given leaves. EachIndexSearcher.LeafSliceis 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 slicemaxDocsPerSlice- the maximum number of documents in a single slicemaxSegmentsPerSlice- the maximum number of segments in a single sliceallowSegmentPartitions- whether segments may be split into partitions according to the provided maxDocsPerSlice argument. Whentrue, 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
Return theIndexReaderthis searches. -
storedFields
Returns aStoredFieldsreader 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:
-
setSimilarity
Expert: Set the Similarity implementation used by this IndexSearcher. -
getSimilarity
Expert: Get theSimilarityto use to compute scores. This returns theSimilaritythat has been set throughsetSimilarity(Similarity)or the defaultSimilarityif none has been set explicitly. -
count
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
Returns the leaf slices used for concurrent searching. Overrideslices(List)to customize how slices are created.- WARNING: This API is experimental and might change in incompatible ways in the next release.
-
searchAfter
Finds the topnhits forquerywhere 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 exceedgetMaxClauseCount()clauses.IOException
-
getTimeout
Get the configuredQueryTimeoutfor all searches that run through thisIndexSearcher, ornullif not set. -
setTimeout
Set aQueryTimeoutfor all searches that run through thisIndexSearcher. -
search
Finds the topnhits forquery.- Throws:
IndexSearcher.TooManyClauses- If a query would exceedgetMaxClauseCount()clauses.IOException
-
search
Deprecated.This method is being deprecated in favor ofsearch(Query, CollectorManager)due to its support for concurrency in IndexSearcherLower-level search API.LeafCollector.collect(int)is called for every matching document.- Throws:
IndexSearcher.TooManyClauses- If a query would exceedgetMaxClauseCount()clauses.IOException
-
timedOut
public boolean timedOut()Returns true if any search hit thetimeout. -
search
Search implementation with arbitrary sorting, plus control over whether hit scores and max score should be computed. Finds the topnhits forquery, and sorting the hits by the criteria insort. IfdoDocScoresistruethen the score of each hit will be computed and returned. IfdoMaxScoreistruethen the maximum score over all collected hits will be computed.- Throws:
IndexSearcher.TooManyClauses- If a query would exceedgetMaxClauseCount()clauses.IOException
-
search
Search implementation with arbitrary sorting.- Parameters:
query- The query to search forn- Return only the top n resultssort- TheSortobject- Returns:
- The top docs, sorted according to the supplied
Sortinstance - Throws:
IOException- if there is a low-level I/O error
-
searchAfter
Finds the topnhits forquerywhere 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 exceedgetMaxClauseCount()clauses.IOException
-
searchAfter
public TopFieldDocs searchAfter(ScoreDoc after, Query query, int numHits, Sort sort, boolean doDocScores) throws IOException Finds the topnhits forquerywhere 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. IfdoDocScoresistruethen the score of each hit will be computed and returned. IfdoMaxScoreistruethen the maximum score over all collected hits will be computed.- Throws:
IndexSearcher.TooManyClauses- If a query would exceedgetMaxClauseCount()clauses.IOException
-
search
public <C extends Collector,T> T search(Query query, CollectorManager<C, T> collectorManager) throws IOExceptionLower-level search API. Search all leaves using the givenCollectorManager. In contrast tosearch(Query, Collector), this method will use the searcher'sExecutorin order to parallelize execution of the collection on the configuredgetSlices().- Throws:
IOException- See Also:
- 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 onweight- to match documentscollector- to receive hits- Throws:
IndexSearcher.TooManyClauses- If a query would exceedgetMaxClauseCount()clauses.IOException
-
searchLeaf
protected void searchLeaf(LeafReaderContext ctx, int minDocId, int maxDocId, Weight weight, Collector collector) throws IOException Lower-level search APILeafCollector.collect(int)is called for every document.- Parameters:
ctx- the leaf to execute the search againstminDocId- the lower bound of the doc id range to searchmaxDocId- the upper bound of the doc id range to searchweight- to match documentcollector- to receive hits- Throws:
IndexSearcher.TooManyClauses- If a query would exceedgetMaxClauseCount()clauses.IOException
-
rewrite
Expert: called to re-write queries into primitive queries.- Throws:
IndexSearcher.TooManyClauses- If a query would exceedgetMaxClauseCount()clauses.IOException
-
explain
Returns an Explanation that describes howdocscored againstquery.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
Expert: low-level implementation method Returns an Explanation that describes howdocscored againstweight.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 exceedgetMaxClauseCount()clauses.IOException
-
createWeight
Creates aWeightfor 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
Returns this searcher's top-levelIndexReaderContext.- See Also:
-
toString
-
termStatistics
ReturnsTermStatisticsfor 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
ReturnsCollectionStatisticsfor a field, ornullif 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
Returns theTaskExecutorthat this searcher relies on to execute concurrent operations- Returns:
- the task executor
-
search(Query, CollectorManager)due to its support for concurrency in IndexSearcher