- Direct Known Subclasses:
QueryProfilerIndexSearcher
,SuggestIndexSearcher
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 IndexSearcher
IndexSearcher
instance; use your own (non-Lucene)
objects instead.
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionprivate static class
Supplier forIndexSearcher.LeafSlice
slices which computes and caches the value on first invocation and returns cached value on subsequent invocation.static class
A class holding a subset of theIndexSearcher
s leaf contexts to be executed within a single thread.static class
Thrown when an attempt is made to add more thanIndexSearcher.TooManyClauses.getMaxClauseCount()
clauses.static class
Thrown 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 TypeFieldDescriptionprivate static QueryCachingPolicy
private static QueryCache
private static final Similarity
private final Executor
protected final List
<LeafReaderContext> private final Supplier
<IndexSearcher.LeafSlice[]> Used with executor - LeafSlice supplier where each slice holds a set of leafs executed within one thread.private static final int
Thresholds for index slice allocation logic.private static final int
(package private) static int
private boolean
private QueryCache
private QueryCachingPolicy
private QueryTimeout
(package private) final IndexReader
protected final IndexReaderContext
private Similarity
The Similarity implementation used by this searcher.private final TaskExecutor
private static final int
By default, we count hits accurately up to 1000. -
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) ReturnsCollectionStatistics
for a field, ornull
if the field does not exist (has no indexed terms)int
Count how many documents match the given query.createWeight
(Query query, ScoreMode scoreMode, float boost) Creates aWeight
for the given query, potentially adding caching if possible and configured.doc
(int docID) Deprecated.Deprecated.UsestoredFields()
to access fields for one or more documentsvoid
doc
(int docID, StoredFieldVisitor fieldVisitor) Deprecated.UsestoredFields()
to access fields for one or more documentsReturns an Explanation that describes howdoc
scored againstquery
.protected Explanation
Expert: low-level implementation method Returns an Explanation that describes howdoc
scored againstweight
.static QueryCache
Expert: Get the defaultQueryCache
ornull
if the cache is disabled.static QueryCachingPolicy
Expert: Get the defaultQueryCachingPolicy
.static Similarity
Expert: returns a default Similarity instance.Deprecated.usegetTaskExecutor()
executor instead to execute concurrent tasksReturn theIndexReader
this searches.Expert: returns leaf contexts associated with this searcher.static int
Return the maximum number of clauses permitted, 1024 by default.private static QueryVisitor
Returns a QueryVisitor which recursively checks the total number of clauses that a query and its children cumulatively have and validates that the total number does not exceed the specified limit.Return the query cache of thisIndexSearcher
.Return the query cache of thisIndexSearcher
.Expert: Get theSimilarity
to use to compute scores.final IndexSearcher.LeafSlice[]
Returns the leaf slices used for concurrent searching.Returns theTaskExecutor
that this searcher relies on to execute concurrent operationsGet the configuredQueryTimeout
for all searches that run through thisIndexSearcher
, ornull
if not set.Returns this searcher's top-levelIndexReaderContext
.Expert: called to re-write queries into primitive queries.private Query
protected void
search
(List<LeafReaderContext> leaves, Weight weight, Collector collector) Lower-level search API.Finds the topn
hits forquery
.Search implementation with arbitrary sorting.Search implementation with arbitrary sorting, plus control over whether hit scores and max score should be computed.void
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.private <C extends Collector,
T>
Tsearch
(Weight weight, CollectorManager<C, T> collectorManager, C firstCollector) private TopFieldDocs
searchAfter
(FieldDoc after, Query query, int numHits, Sort sort, boolean doDocScores) searchAfter
(ScoreDoc after, Query query, int numHits) Finds the topn
hits forquery
where all results are after a previous result (after
).searchAfter
(ScoreDoc after, Query query, int n, Sort sort) Finds the topn
hits forquery
where all results are after a previous result (after
).searchAfter
(ScoreDoc after, Query query, int numHits, Sort sort, boolean doDocScores) Finds the topn
hits forquery
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, Weight weight, Collector collector) Lower-level search APIstatic void
setDefaultQueryCache
(QueryCache defaultQueryCache) Expert: set the defaultQueryCache
instance.static void
setDefaultQueryCachingPolicy
(QueryCachingPolicy defaultQueryCachingPolicy) Expert: set the defaultQueryCachingPolicy
instance.static void
setMaxClauseCount
(int value) Set the maximum number of clauses permitted per Query.void
setQueryCache
(QueryCache queryCache) Set theQueryCache
to use when scores are not needed.void
setQueryCachingPolicy
(QueryCachingPolicy queryCachingPolicy) Set theQueryCachingPolicy
to use for query caching.void
setSimilarity
(Similarity similarity) Expert: Set the Similarity implementation used by this IndexSearcher.void
setTimeout
(QueryTimeout queryTimeout) Set aQueryTimeout
for 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 slicesReturns aStoredFields
reader for the stored fields of this index.termStatistics
(Term term, int docFreq, long totalTermFreq) ReturnsTermStatistics
for a term.boolean
timedOut()
Returns true if any search hit thetimeout
.toString()
-
Field Details
-
maxClauseCount
static int maxClauseCount -
DEFAULT_QUERY_CACHE
-
DEFAULT_CACHING_POLICY
-
queryTimeout
-
partialResult
private volatile boolean partialResult -
TOTAL_HITS_THRESHOLD
private static final int TOTAL_HITS_THRESHOLDBy default, we count hits accurately up to 1000. This makes sure that we don't spend most time on computing hit counts- See Also:
-
MAX_DOCS_PER_SLICE
private static final int MAX_DOCS_PER_SLICEThresholds for index slice allocation logic. To change the default, extendIndexSearcher
and use custom values- See Also:
-
MAX_SEGMENTS_PER_SLICE
private static final int MAX_SEGMENTS_PER_SLICE- See Also:
-
reader
-
readerContext
-
leafContexts
-
leafSlicesSupplier
Used with executor - LeafSlice supplier where each slice holds a set of leafs executed within one thread. We are caching it instead of creating it eagerly to avoid calling a protected method from constructor, which is a bad practice. Always non-null, regardless of whether an executor is provided or not. -
executor
-
taskExecutor
-
defaultSimilarity
-
queryCache
-
queryCachingPolicy
-
similarity
The Similarity implementation used by this searcher.
-
-
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). -
IndexSearcher
Creates a searcher searching the provided top-levelIndexReaderContext
.Given a non-
null
Executor
this 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:
-
IndexSearcher
Creates a searcher searching the provided top-levelIndexReaderContext
.- See Also:
-
-
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()
. -
getLeafContexts
Expert: returns leaf contexts associated with this searcher. This is an internal method exposed for tests only. -
getDefaultQueryCache
Expert: Get the defaultQueryCache
ornull
if the cache is disabled. -
setDefaultQueryCache
Expert: set the defaultQueryCache
instance. -
getDefaultQueryCachingPolicy
Expert: Get the defaultQueryCachingPolicy
. -
setDefaultQueryCachingPolicy
Expert: set the defaultQueryCachingPolicy
instance. -
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.TooManyClauses
to 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 theQueryCache
to use when scores are not needed. A value ofnull
indicates 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:
-
getQueryCache
Return the query cache of thisIndexSearcher
. This will be either thedefault query cache
or the query cache that was last set throughsetQueryCache(QueryCache)
. A return value ofnull
indicates that caching is disabled. -
setQueryCachingPolicy
Set theQueryCachingPolicy
to use for query caching. This method should be called before starting using thisIndexSearcher
.- See Also:
-
getQueryCachingPolicy
Return the query cache of thisIndexSearcher
. This will be either thedefault policy
or the policy that was last set throughsetQueryCachingPolicy(QueryCachingPolicy)
. -
slices
Expert: Creates an array of leaf slices each holding a subset of the given leaves. EachIndexSearcher.LeafSlice
is 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
Return theIndexReader
this searches. -
doc
Deprecated.UsestoredFields()
to access fields for one or more documentsSugar for.getIndexReader().document(docID)
- Throws:
IOException
- See Also:
-
doc
Deprecated.UsestoredFields()
to access fields for one or more documentsSugar for.getIndexReader().document(docID, fieldVisitor)
- Throws:
IOException
- See Also:
-
doc
Deprecated.UsestoredFields()
to access fields for one or more documentsSugar for.getIndexReader().document(docID, fieldsToLoad)
- Throws:
IOException
- See Also:
-
storedFields
Returns aStoredFields
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:
-
setSimilarity
Expert: Set the Similarity implementation used by this IndexSearcher. -
getSimilarity
Expert: Get theSimilarity
to use to compute scores. This returns theSimilarity
that has been set throughsetSimilarity(Similarity)
or the defaultSimilarity
if 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. -
searchAfter
Finds the topn
hits forquery
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 exceedgetMaxClauseCount()
clauses.IOException
-
getTimeout
Get the configuredQueryTimeout
for all searches that run through thisIndexSearcher
, ornull
if not set. -
setTimeout
Set aQueryTimeout
for all searches that run through thisIndexSearcher
. -
search
Finds the topn
hits 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 topn
hits forquery
, and sorting the hits by the criteria insort
. IfdoDocScores
istrue
then the score of each hit will be computed and returned. IfdoMaxScore
istrue
then 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
- TheSort
object- Returns:
- The top docs, sorted according to the supplied
Sort
instance - Throws:
IOException
- if there is a low-level I/O error
-
searchAfter
Finds the topn
hits forquery
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 exceedgetMaxClauseCount()
clauses.IOException
-
searchAfter
public TopFieldDocs searchAfter(ScoreDoc after, Query query, int numHits, Sort sort, boolean doDocScores) throws IOException Finds the topn
hits forquery
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. IfdoDocScores
istrue
then the score of each hit will be computed and returned. IfdoMaxScore
istrue
then the maximum score over all collected hits will be computed.- Throws:
IndexSearcher.TooManyClauses
- If a query would exceedgetMaxClauseCount()
clauses.IOException
-
searchAfter
private TopFieldDocs searchAfter(FieldDoc after, Query query, int numHits, Sort sort, boolean doDocScores) throws IOException - Throws:
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'sExecutor
in order to parallelize execution of the collection on the configuredgetSlices()
.- Throws:
IOException
- See Also:
-
search
private <C extends Collector,T> T search(Weight weight, CollectorManager<C, T> collectorManager, C firstCollector) throws IOException- Throws:
IOException
-
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
Expert: called to re-write queries into primitive queries.- Throws:
IndexSearcher.TooManyClauses
- If a query would exceedgetMaxClauseCount()
clauses.IOException
-
rewrite
- Throws:
IOException
-
getNumClausesCheckVisitor
Returns a QueryVisitor which recursively checks the total number of clauses that a query and its children cumulatively have and validates that the total number does not exceed the specified limit. ThrowsIndexSearcher.TooManyNestedClauses
if the limit is exceeded. -
explain
Returns an Explanation that describes howdoc
scored 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 howdoc
scored 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 aWeight
for the given query, potentially adding caching if possible and configured.- Throws:
IOException
-
getTopReaderContext
Returns this searcher's top-levelIndexReaderContext
.- See Also:
-
toString
-
termStatistics
ReturnsTermStatistics
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
-
collectionStatistics
ReturnsCollectionStatistics
for a field, ornull
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
-
getExecutor
Deprecated.usegetTaskExecutor()
executor instead to execute concurrent tasksReturns this searchers executor ornull
if no executor was provided -
getTaskExecutor
Returns theTaskExecutor
that this searcher relies on to execute concurrent operations- Returns:
- the task executor
-
storedFields()
to access fields for one or more documents