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 useDirectoryReader.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 newIndexReader, it's relatively cheap to create a new IndexSearcher from it.NOTE: The
search(org.apache.lucene.search.Query, int)andsearchAfter(org.apache.lucene.search.ScoreDoc, org.apache.lucene.search.Query, int)methods are configured to only count top hits accurately up to1,000and may return alower boundof the hit count if the hit count is greater than or equal to1,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. TheTopDocs.scoreDocsarray is always accurate however. If this behavior doesn't suit your needs, you should create collectorManagers manually with eitherTopScoreDocCollectorManagerorTopFieldCollectorManagerand callsearch(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 theIndexSearcherIndexSearcherinstance; use your own (non-Lucene) objects instead.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static classIndexSearcher.LeafSliceA class holding a subset of theIndexSearchers leaf contexts to be executed within a single thread.static classIndexSearcher.TooManyClausesThrown when an attempt is made to add more thanIndexSearcher.TooManyClauses.getMaxClauseCount()clauses.static classIndexSearcher.TooManyNestedClausesThrown when a client attempts to execute a Query that has more thanIndexSearcher.TooManyClauses.getMaxClauseCount()total clauses cumulatively in all of its children.
-
Field Summary
Fields Modifier and Type Field Description protected List<LeafReaderContext>leafContextsprotected IndexReaderContextreaderContext
-
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-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
All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description CollectionStatisticscollectionStatistics(String field)ReturnsCollectionStatisticsfor a field, ornullif the field does not exist (has no indexed terms)intcount(Query query)Count how many documents match the given query.WeightcreateWeight(Query query, ScoreMode scoreMode, float boost)Creates aWeightfor the given query, potentially adding caching if possible and configured.Documentdoc(int docID)Deprecated.UsestoredFields()to access fields for one or more documentsDocumentdoc(int docID, Set<String> fieldsToLoad)Deprecated.UsestoredFields()to access fields for one or more documentsvoiddoc(int docID, StoredFieldVisitor fieldVisitor)Deprecated.UsestoredFields()to access fields for one or more documentsExplanationexplain(Query query, int doc)Returns an Explanation that describes howdocscored againstquery.protected Explanationexplain(Weight weight, int doc)Expert: low-level implementation method Returns an Explanation that describes howdocscored againstweight.static QueryCachegetDefaultQueryCache()Expert: Get the defaultQueryCacheornullif the cache is disabled.static QueryCachingPolicygetDefaultQueryCachingPolicy()Expert: Get the defaultQueryCachingPolicy.static SimilaritygetDefaultSimilarity()Expert: returns a default Similarity instance.ExecutorgetExecutor()Deprecated.usegetTaskExecutor()executor instead to execute concurrent tasksIndexReadergetIndexReader()Return theIndexReaderthis searches.List<LeafReaderContext>getLeafContexts()Expert: returns leaf contexts associated with this searcher.static intgetMaxClauseCount()Return the maximum number of clauses permitted, 1024 by default.QueryCachegetQueryCache()Return the query cache of thisIndexSearcher.QueryCachingPolicygetQueryCachingPolicy()Return the query cache of thisIndexSearcher.SimilaritygetSimilarity()Expert: Get theSimilarityto use to compute scores.IndexSearcher.LeafSlice[]getSlices()Returns the leaf slices used for concurrent searching.TaskExecutorgetTaskExecutor()Returns theTaskExecutorthat this searcher relies on to execute concurrent operationsQueryTimeoutgetTimeout()Get the configuredQueryTimeoutfor all searches that run through thisIndexSearcher, ornullif not set.IndexReaderContextgetTopReaderContext()Returns this searcher's top-levelIndexReaderContext.Queryrewrite(Query original)Expert: called to re-write queries into primitive queries.protected voidsearch(List<LeafReaderContext> leaves, Weight weight, Collector collector)Lower-level search API.TopDocssearch(Query query, int n)Finds the topnhits forquery.TopFieldDocssearch(Query query, int n, Sort sort)Search implementation with arbitrary sorting.TopFieldDocssearch(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.voidsearch(Query query, Collector results)Deprecated.This method is being deprecated in favor ofsearch(Query, CollectorManager)due to its support for concurrency in IndexSearcher<C extends Collector,T>
Tsearch(Query query, CollectorManager<C,T> collectorManager)Lower-level search API.TopDocssearchAfter(ScoreDoc after, Query query, int numHits)Finds the topnhits forquerywhere all results are after a previous result (after).TopDocssearchAfter(ScoreDoc after, Query query, int n, Sort sort)Finds the topnhits forquerywhere all results are after a previous result (after).TopFieldDocssearchAfter(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, 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)Static method to segregate LeafReaderContexts amongst multiple slicesStoredFieldsstoredFields()Returns aStoredFieldsreader for the stored fields of this index.TermStatisticstermStatistics(Term term, int docFreq, long totalTermFreq)ReturnsTermStatisticsfor a term.booleantimedOut()Returns true if any search hit thetimeout.StringtoString()
-
-
-
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, Executor executor)
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
public IndexSearcher(IndexReaderContext context, Executor executor)
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:
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-levelIndexReaderContext.- 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 respectgetSimilarity().- 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 defaultQueryCacheornullif 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 defaultQueryCacheinstance.- 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 defaultQueryCachingPolicy.- 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 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(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 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:
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 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
public void setQueryCachingPolicy(QueryCachingPolicy queryCachingPolicy)
Set theQueryCachingPolicyto use for query caching. This method should be called before starting using thisIndexSearcher.- 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 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
protected IndexSearcher.LeafSlice[] slices(List<LeafReaderContext> leaves)
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
-
slices
public static IndexSearcher.LeafSlice[] slices(List<LeafReaderContext> leaves, int maxDocsPerSlice, int maxSegmentsPerSlice)
Static method to segregate LeafReaderContexts amongst multiple slices
-
getIndexReader
public IndexReader getIndexReader()
Return theIndexReaderthis searches.
-
doc
@Deprecated public Document doc(int docID) throws IOException
Deprecated.UsestoredFields()to access fields for one or more documentsSugar for.getIndexReader().document(docID)- Throws:
IOException- See Also:
IndexReader.document(int)
-
doc
@Deprecated public void doc(int docID, StoredFieldVisitor fieldVisitor) throws IOException
Deprecated.UsestoredFields()to access fields for one or more documentsSugar for.getIndexReader().document(docID, fieldVisitor)- Throws:
IOException- See Also:
IndexReader.document(int, StoredFieldVisitor)
-
doc
@Deprecated public Document doc(int docID, Set<String> fieldsToLoad) throws IOException
Deprecated.UsestoredFields()to access fields for one or more documentsSugar for.getIndexReader().document(docID, fieldsToLoad)- Throws:
IOException- See Also:
IndexReader.document(int, Set)
-
storedFields
public StoredFields storedFields() throws IOException
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:
IndexReader.storedFields()
-
setSimilarity
public void setSimilarity(Similarity similarity)
Expert: Set the Similarity implementation used by this IndexSearcher.
-
getSimilarity
public Similarity 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
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. Overrideslices(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 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
public QueryTimeout getTimeout()
Get the configuredQueryTimeoutfor all searches that run through thisIndexSearcher, ornullif not set.
-
setTimeout
public void setTimeout(QueryTimeout queryTimeout)
Set aQueryTimeoutfor all searches that run through thisIndexSearcher.
-
search
public TopDocs search(Query query, int n) throws IOException
Finds the topnhits forquery.- Throws:
IndexSearcher.TooManyClauses- If a query would exceedgetMaxClauseCount()clauses.IOException
-
search
@Deprecated public void search(Query query, Collector results) throws IOException
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
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 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
public TopFieldDocs search(Query query, int n, Sort sort) throws IOException
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
public TopDocs searchAfter(ScoreDoc after, Query query, int n, Sort sort) throws IOException
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 IOException
Lower-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:
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.searchLeaf(LeafReaderContext, Weight, Collector)is called for every leaf partition.
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 onweight- to match documentscollector- to receive hits- Throws:
IndexSearcher.TooManyClauses- If a query would exceedgetMaxClauseCount()clauses.IOException
-
searchLeaf
protected void searchLeaf(LeafReaderContext ctx, 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 againstweight- to match documentcollector- to receive hits- Throws:
IndexSearcher.TooManyClauses- If a query would exceedgetMaxClauseCount()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 exceedgetMaxClauseCount()clauses.IOException
-
explain
public Explanation explain(Query query, int doc) throws IOException
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
protected Explanation explain(Weight weight, int doc) throws IOException
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
public Weight createWeight(Query query, ScoreMode scoreMode, float boost) throws IOException
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
public IndexReaderContext getTopReaderContext()
Returns this searcher's top-levelIndexReaderContext.- See Also:
IndexReader.getContext()
-
termStatistics
public TermStatistics termStatistics(Term term, int docFreq, long totalTermFreq) throws IOException
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
public CollectionStatistics collectionStatistics(String field) throws IOException
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.
-
getExecutor
@Deprecated public Executor getExecutor()
Deprecated.usegetTaskExecutor()executor instead to execute concurrent tasksReturns this searchers executor ornullif no executor was provided
-
getTaskExecutor
public TaskExecutor getTaskExecutor()
Returns theTaskExecutorthat this searcher relies on to execute concurrent operations- Returns:
- the task executor
-
-