Class IndexSearcher
- java.lang.Object
-
- org.apache.lucene.search.Searcher
-
- org.apache.lucene.search.IndexSearcher
-
- All Implemented Interfaces:
Closeable
,AutoCloseable
,Searchable
- Direct Known Subclasses:
AssertingIndexSearcher
,CheckHits.ExplanationAssertingSearcher
public class IndexSearcher extends Searcher
Implements search over a single IndexReader.Applications usually need only call the inherited
search(Query,int)
orsearch(Query,Filter,int)
methods. 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 useIndexReader.openIfChanged(org.apache.lucene.index.IndexReader)
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 (IndexReader.open(IndexWriter,boolean)
). Once you have a newIndexReader
, it's relatively cheap to create a new IndexSearcher from it.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 theIndexSearcher
IndexSearcher
instance; use your own (non-Lucene) objects instead.
-
-
Field Summary
Fields Modifier and Type Field Description protected int[]
docStarts
protected IndexReader[]
subReaders
protected IndexSearcher[]
subSearchers
-
Constructor Summary
Constructors Constructor Description IndexSearcher(IndexReader r)
Creates a searcher searching the provided index.IndexSearcher(IndexReader r, ExecutorService executor)
Runs searches for each segment separately, using the provided ExecutorService.IndexSearcher(IndexReader reader, IndexReader[] subReaders, int[] docStarts)
Expert: directly specify the reader, subReaders and their docID starts.IndexSearcher(IndexReader reader, IndexReader[] subReaders, int[] docStarts, ExecutorService executor)
Expert: directly specify the reader, subReaders and their docID starts, and an ExecutorService.IndexSearcher(Directory path)
Deprecated.useIndexSearcher(IndexReader)
instead.IndexSearcher(Directory path, boolean readOnly)
Deprecated.UseIndexSearcher(IndexReader)
instead.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description void
close()
Note that the underlying IndexReader is not closed, if IndexSearcher was constructed with IndexSearcher(IndexReader r).Weight
createNormalizedWeight(Query query)
Creates a normalized weight for a top-levelQuery
.Document
doc(int docID)
Returns the stored fields of documenti
.Document
doc(int docID, FieldSelector fieldSelector)
Get theDocument
at then
th position.int
docFreq(Term term)
Returns total docFreq for this term.Explanation
explain(Query query, int doc)
Returns an Explanation that describes howdoc
scored againstquery
.Explanation
explain(Weight weight, int doc)
Expert: low-level implementation method Returns an Explanation that describes howdoc
scored againstweight
.protected void
gatherSubReaders(List<IndexReader> allSubReaders, IndexReader r)
IndexReader
getIndexReader()
Return theIndexReader
this searches.Similarity
getSimilarity()
Expert: Return the Similarity implementation used by this Searcher.IndexReader[]
getSubReaders()
Returns the atomic subReaders used by this searcher.int
maxDoc()
Expert: Returns one greater than the largest possible document number.Query
rewrite(Query original)
Expert: called to re-write queries into primitive queries.TopDocs
search(Query query, int n)
Finds the topn
hits forquery
.TopFieldDocs
search(Query query, int n, Sort sort)
Search implementation with arbitrary sorting and no filter.void
search(Query query, Collector results)
Lower-level search API.TopDocs
search(Query query, Filter filter, int n)
Finds the topn
hits forquery
, applyingfilter
if non-null.TopFieldDocs
search(Query query, Filter filter, int n, Sort sort)
Search implementation with arbitrary sorting.void
search(Query query, Filter filter, Collector results)
Lower-level search API.TopDocs
search(Weight weight, Filter filter, int nDocs)
Expert: Low-level search implementation.TopFieldDocs
search(Weight weight, Filter filter, int nDocs, Sort sort)
Expert: Low-level search implementation with arbitrary sorting.protected TopFieldDocs
search(Weight weight, Filter filter, int nDocs, Sort sort, boolean fillFields)
Just likesearch(Weight, Filter, int, Sort)
, but you choose whether or not the fields in the returnedFieldDoc
instances should be set by specifying fillFields.void
search(Weight weight, Filter filter, Collector collector)
Lower-level search API.protected TopDocs
search(Weight weight, Filter filter, ScoreDoc after, int nDocs)
Expert: Low-level search implementation.TopDocs
searchAfter(ScoreDoc after, Query query, int n)
Finds the topn
hits forquery
where all results are after a previous result (after
).TopDocs
searchAfter(ScoreDoc after, Query query, Filter filter, int n)
Finds the topn
hits forquery
, applyingfilter
if non-null, where all results are after a previous result (after
).void
setDefaultFieldSortScoring(boolean doTrackScores, boolean doMaxScore)
By default, no scores are computed when sorting by field (usingsearch(Query,Filter,int,Sort)
).void
setSimilarity(Similarity similarity)
Expert: Set the Similarity implementation used by this Searcher.String
toString()
-
Methods inherited from class org.apache.lucene.search.Searcher
createWeight, docFreqs
-
-
-
-
Field Detail
-
subReaders
protected final IndexReader[] subReaders
-
docStarts
protected final int[] docStarts
-
subSearchers
protected final IndexSearcher[] subSearchers
-
-
Constructor Detail
-
IndexSearcher
@Deprecated public IndexSearcher(Directory path) throws CorruptIndexException, IOException
Deprecated.useIndexSearcher(IndexReader)
instead.Creates a searcher searching the index in the named directory, with readOnly=true- Parameters:
path
- directory where IndexReader will be opened- Throws:
CorruptIndexException
- if the index is corruptIOException
- if there is a low-level IO error
-
IndexSearcher
@Deprecated public IndexSearcher(Directory path, boolean readOnly) throws CorruptIndexException, IOException
Deprecated.UseIndexSearcher(IndexReader)
instead.Creates a searcher searching the index in the named directory. You should pass readOnly=true, since it gives much better concurrent performance, unless you intend to do write operations (delete documents or change norms) with the underlying IndexReader.- Parameters:
path
- directory where IndexReader will be openedreadOnly
- if true, the underlying IndexReader will be opened readOnly- Throws:
CorruptIndexException
- if the index is corruptIOException
- if there is a low-level IO error
-
IndexSearcher
public IndexSearcher(IndexReader r)
Creates a searcher searching the provided index.
-
IndexSearcher
public IndexSearcher(IndexReader r, ExecutorService executor)
Runs searches for each segment separately, using the provided ExecutorService. IndexSearcher will not shutdown/awaitTermination this ExecutorService on close; you must do so, eventually, on your own. 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(IndexReader reader, IndexReader[] subReaders, int[] docStarts)
Expert: directly specify the reader, subReaders and their docID starts.- WARNING: This API is experimental and might change in incompatible ways in the next release.
-
IndexSearcher
public IndexSearcher(IndexReader reader, IndexReader[] subReaders, int[] docStarts, ExecutorService executor)
Expert: directly specify the reader, subReaders and their docID starts, and an ExecutorService. In this case, each segment will be separately searched using the ExecutorService. IndexSearcher will not shutdown/awaitTermination this ExecutorService on close; you must do so, eventually, on your own. 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.
-
-
Method Detail
-
gatherSubReaders
protected void gatherSubReaders(List<IndexReader> allSubReaders, IndexReader r)
-
getIndexReader
public IndexReader getIndexReader()
Return theIndexReader
this searches.
-
getSubReaders
public IndexReader[] getSubReaders()
Returns the atomic subReaders used by this searcher.
-
maxDoc
public int maxDoc()
Expert: Returns one greater than the largest possible document number.- Specified by:
maxDoc
in interfaceSearchable
- Specified by:
maxDoc
in classSearcher
- See Also:
IndexReader.maxDoc()
-
docFreq
public int docFreq(Term term) throws IOException
Returns total docFreq for this term.- Specified by:
docFreq
in interfaceSearchable
- Specified by:
docFreq
in classSearcher
- Throws:
IOException
- See Also:
IndexReader.docFreq(Term)
-
doc
public Document doc(int docID) throws CorruptIndexException, IOException
Description copied from interface:Searchable
Returns the stored fields of documenti
.- Specified by:
doc
in interfaceSearchable
- Specified by:
doc
in classSearcher
- Throws:
CorruptIndexException
- if the index is corruptIOException
- if there is a low-level IO error- See Also:
IndexReader.document(int)
-
doc
public Document doc(int docID, FieldSelector fieldSelector) throws CorruptIndexException, IOException
Description copied from interface:Searchable
Get theDocument
at then
th position. TheFieldSelector
may be used to determine whatField
s to load and how they should be loaded. NOTE: If the underlying Reader (more specifically, the underlyingFieldsReader
) is closed before the lazyField
is loaded an exception may be thrown. If you want the value of a lazyField
to be available after closing you must explicitly load it or fetch the Document again with a new loader.- Specified by:
doc
in interfaceSearchable
- Specified by:
doc
in classSearcher
- Parameters:
docID
- Get the document at then
th positionfieldSelector
- TheFieldSelector
to use to determine what Fields should be loaded on the Document. May be null, in which case all Fields will be loaded.- Returns:
- The stored fields of the
Document
at the nth position - Throws:
CorruptIndexException
- if the index is corruptIOException
- if there is a low-level IO error- See Also:
IndexReader.document(int, FieldSelector)
,Fieldable
,FieldSelector
,SetBasedFieldSelector
,LoadFirstFieldSelector
-
setSimilarity
public void setSimilarity(Similarity similarity)
Expert: Set the Similarity implementation used by this Searcher.- Overrides:
setSimilarity
in classSearcher
- See Also:
Similarity.setDefault(Similarity)
-
getSimilarity
public Similarity getSimilarity()
Description copied from class:Searcher
Expert: Return the Similarity implementation used by this Searcher.This defaults to the current value of
Similarity.getDefault()
.- Overrides:
getSimilarity
in classSearcher
-
close
public void close() throws IOException
Note that the underlying IndexReader is not closed, if IndexSearcher was constructed with IndexSearcher(IndexReader r). If the IndexReader was supplied implicitly by specifying a directory, then the IndexReader is closed.- Specified by:
close
in interfaceAutoCloseable
- Specified by:
close
in interfaceCloseable
- Specified by:
close
in interfaceSearchable
- Specified by:
close
in classSearcher
- Throws:
IOException
-
searchAfter
public TopDocs searchAfter(ScoreDoc after, Query query, int n) throws IOException
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.
-
searchAfter
public TopDocs searchAfter(ScoreDoc after, Query query, Filter filter, int n) throws IOException
Finds the topn
hits forquery
, applyingfilter
if non-null, 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.
-
search
public TopDocs search(Query query, int n) throws IOException
Finds the topn
hits forquery
.- Overrides:
search
in classSearcher
- Throws:
BooleanQuery.TooManyClauses
IOException
-
search
public TopDocs search(Query query, Filter filter, int n) throws IOException
Finds the topn
hits forquery
, applyingfilter
if non-null.- Overrides:
search
in classSearcher
- Throws:
BooleanQuery.TooManyClauses
IOException
-
search
public void search(Query query, Filter filter, Collector results) throws IOException
Lower-level search API.Collector.collect(int)
is called for every matching document.
Collector-based access to remote indexes is discouraged.Applications should only use this if they need all of the matching documents. The high-level search API (
Searcher.search(Query, Filter, int)
) is usually more efficient, as it skips non-high-scoring hits.- Overrides:
search
in classSearcher
- Parameters:
query
- to match documentsfilter
- if non-null, used to permit documents to be collected.results
- to receive hits- Throws:
BooleanQuery.TooManyClauses
IOException
-
search
public void search(Query query, Collector results) throws IOException
Lower-level search API.Collector.collect(int)
is called for every matching document.Applications should only use this if they need all of the matching documents. The high-level search API (
Searcher.search(Query, int)
) is usually more efficient, as it skips non-high-scoring hits.Note: The
score
passed to this method is a raw score. In other words, the score will not necessarily be a float whose value is between 0 and 1.- Overrides:
search
in classSearcher
- Throws:
BooleanQuery.TooManyClauses
IOException
-
search
public TopFieldDocs search(Query query, Filter filter, int n, Sort sort) throws IOException
Search implementation with arbitrary sorting. Finds the topn
hits forquery
, applyingfilter
if non-null, and sorting the hits by the criteria insort
.NOTE: this does not compute scores by default; use
setDefaultFieldSortScoring(boolean, boolean)
to enable scoring.- Overrides:
search
in classSearcher
- Throws:
BooleanQuery.TooManyClauses
IOException
-
search
public TopFieldDocs search(Query query, int n, Sort sort) throws IOException
Search implementation with arbitrary sorting and no filter.- Overrides:
search
in classSearcher
- 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
-
search
public TopDocs search(Weight weight, Filter filter, int nDocs) throws IOException
Expert: Low-level search implementation. Finds the topn
hits forquery
, applyingfilter
if non-null.Applications should usually call
Searcher.search(Query,int)
orSearcher.search(Query,Filter,int)
instead.- Specified by:
search
in interfaceSearchable
- Specified by:
search
in classSearcher
- Throws:
BooleanQuery.TooManyClauses
IOException
-
search
protected TopDocs search(Weight weight, Filter filter, ScoreDoc after, int nDocs) throws IOException
Expert: Low-level search implementation. Finds the topn
hits forquery
, applyingfilter
if non-null, returning results afterafter
.
-
search
public TopFieldDocs search(Weight weight, Filter filter, int nDocs, Sort sort) throws IOException
Expert: Low-level search implementation with arbitrary sorting. Finds the topn
hits forquery
, applyingfilter
if non-null, and sorting the hits by the criteria insort
.Applications should usually call
Searcher.search(Query,Filter,int,Sort)
instead.- Specified by:
search
in interfaceSearchable
- Specified by:
search
in classSearcher
- Throws:
BooleanQuery.TooManyClauses
IOException
-
search
protected TopFieldDocs search(Weight weight, Filter filter, int nDocs, Sort sort, boolean fillFields) throws IOException
Just likesearch(Weight, Filter, int, Sort)
, but you choose whether or not the fields in the returnedFieldDoc
instances should be set by specifying fillFields.NOTE: this does not compute scores by default. If you need scores, create a
TopFieldCollector
instance by callingTopFieldCollector.create(org.apache.lucene.search.Sort, int, boolean, boolean, boolean, boolean)
and then pass that tosearch(Weight, Filter, Collector)
.- Throws:
IOException
-
search
public void search(Weight weight, Filter filter, Collector collector) throws IOException
Lower-level search API.Collector.collect(int)
is called for every document.
Collector-based access to remote indexes is discouraged.Applications should only use this if they need all of the matching documents. The high-level search API (
Searcher.search(Query,int)
) is usually more efficient, as it skips non-high-scoring hits.- Specified by:
search
in interfaceSearchable
- Specified by:
search
in classSearcher
- Parameters:
weight
- to match documentsfilter
- if non-null, used to permit documents to be collected.collector
- to receive hits- Throws:
BooleanQuery.TooManyClauses
IOException
-
rewrite
public Query rewrite(Query original) throws IOException
Expert: called to re-write queries into primitive queries.- Specified by:
rewrite
in interfaceSearchable
- Specified by:
rewrite
in classSearcher
- Throws:
BooleanQuery.TooManyClauses
IOException
-
explain
public Explanation explain(Query query, int doc) throws IOException
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.
- Overrides:
explain
in classSearcher
- Throws:
IOException
-
explain
public Explanation explain(Weight weight, int doc) throws IOException
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
Searcher.explain(Query, int)
.- Specified by:
explain
in interfaceSearchable
- Specified by:
explain
in classSearcher
- Throws:
BooleanQuery.TooManyClauses
IOException
-
setDefaultFieldSortScoring
public void setDefaultFieldSortScoring(boolean doTrackScores, boolean doMaxScore)
By default, no scores are computed when sorting by field (usingsearch(Query,Filter,int,Sort)
). You can change that, per IndexSearcher instance, by calling this method. Note that this will incur a CPU cost.- Parameters:
doTrackScores
- If true, then scores are returned for every matching document inTopFieldDocs
.doMaxScore
- If true, then the max score for all matching docs is computed.
-
createNormalizedWeight
public Weight createNormalizedWeight(Query query) throws IOException
Creates a normalized weight for a top-levelQuery
. The query is rewritten by this method andQuery.createWeight(org.apache.lucene.search.Searcher)
called, afterwards theWeight
is normalized. The returnedWeight
can then directly be used to get aScorer
.- Overrides:
createNormalizedWeight
in classSearcher
- Throws:
IOException
- NOTE: This API is for internal purposes only and might change in incompatible ways in the next release.
-
-