Class IndexSearcher
- 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 collectors manually with either TopScoreDocCollector.create(int, int)
or TopFieldCollector.create(org.apache.lucene.search.Sort, int, int)
and call search(Query, Collector)
.
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 TypeClassDescriptionstatic class
A class holding a subset of theIndexSearcher
s leaf contexts to be executed within a single thread.private static class
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 it's children. -
Field Summary
FieldsModifier and TypeFieldDescriptionprivate static QueryCachingPolicy
private static QueryCache
private static final Similarity
private final Executor
protected final List<LeafReaderContext>
private final IndexSearcher.LeafSlice[]
used with executor - each slice holds a set of leafs executed within one threadprivate static final int
Thresholds for index slice allocation logic.private static final int
(package private) static int
private QueryCache
private QueryCachingPolicy
(package private) final IndexReader
protected final IndexReaderContext
private Similarity
The Similarity implementation used by this searcher.private final SliceExecutor
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
(IndexReaderContext context, Executor executor, SliceExecutor sliceExecutor) 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) Sugar for.getIndexReader().document(docID)
Sugar for.getIndexReader().document(docID, fieldsToLoad)
void
doc
(int docID, StoredFieldVisitor fieldVisitor) Sugar for.getIndexReader().document(docID, fieldVisitor)
Returns 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.Returns this searchers executor ornull
if no executor was providedReturn 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.private static SliceExecutor
getSliceExecutionControlPlane
(Executor executor) Return the SliceExecutionControlPlane instance to be used for this IndexSearcher instanceReturns the leaf slices used for concurrent searching, or null if noExecutor
was passed to the constructor.Returns this searchers the 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
Lower-level search API.<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.static 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.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 slicestermStatistics
(Term term, int docFreq, long totalTermFreq) ReturnsTermStatistics
for a term.toString()
-
Field Details
-
maxClauseCount
static int maxClauseCount -
DEFAULT_QUERY_CACHE
-
DEFAULT_CACHING_POLICY
-
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
-
leafSlices
used with executor - each slice holds a set of leafs executed within one thread -
executor
-
sliceExecutor
-
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
IndexSearcher(IndexReaderContext context, Executor executor, SliceExecutor sliceExecutor) -
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
Sugar for.getIndexReader().document(docID)
- Throws:
IOException
- See Also:
-
doc
Sugar for.getIndexReader().document(docID, fieldVisitor)
- Throws:
IOException
- See Also:
-
doc
Sugar for.getIndexReader().document(docID, fieldsToLoad)
- Throws:
IOException
- 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, or null if noExecutor
was passed to the constructor. -
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
-
search
Finds the topn
hits forquery
.- Throws:
IndexSearcher.TooManyClauses
- If a query would exceedgetMaxClauseCount()
clauses.IOException
-
search
Lower-level search API.LeafCollector.collect(int)
is called for every matching document.- Throws:
IndexSearcher.TooManyClauses
- If a query would exceedgetMaxClauseCount()
clauses.IOException
-
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 configuredleafSlices
.- 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.LeafCollector.collect(int)
is called for every document.
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
-
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 searchers the 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
Returns this searchers executor ornull
if no executor was provided -
getSliceExecutionControlPlane
Return the SliceExecutionControlPlane instance to be used for this IndexSearcher instance
-