public class IndexSearcher
extends java.lang.Object
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.
Modifier and Type | Class and Description |
---|---|
static class |
IndexSearcher.LeafSlice
A class holding a subset of the
IndexSearcher s leaf contexts to be
executed within a single thread. |
Modifier and Type | Field and Description |
---|---|
private static QueryCachingPolicy |
DEFAULT_CACHING_POLICY |
private static QueryCache |
DEFAULT_QUERY_CACHE |
private static Similarity |
defaultSimilarity |
private java.util.concurrent.ExecutorService |
executor |
protected java.util.List<LeafReaderContext> |
leafContexts |
private IndexSearcher.LeafSlice[] |
leafSlices
used with executor - each slice holds a set of leafs executed within one thread
|
private QueryCache |
queryCache |
private QueryCachingPolicy |
queryCachingPolicy |
(package private) IndexReader |
reader |
protected IndexReaderContext |
readerContext |
private Similarity |
similarity
The Similarity implementation used by this searcher.
|
private static int |
TOTAL_HITS_THRESHOLD
By default we count hits accurately up to 1000.
|
Constructor and Description |
---|
IndexSearcher(IndexReader r)
Creates a searcher searching the provided index.
|
IndexSearcher(IndexReaderContext context)
Creates a searcher searching the provided top-level
IndexReaderContext . |
IndexSearcher(IndexReaderContext context,
java.util.concurrent.ExecutorService executor)
Creates a searcher searching the provided top-level
IndexReaderContext . |
IndexSearcher(IndexReader r,
java.util.concurrent.ExecutorService executor)
Runs searches for each segment separately, using the
provided ExecutorService.
|
Modifier and Type | Method and Description |
---|---|
CollectionStatistics |
collectionStatistics(java.lang.String field)
Returns
CollectionStatistics for a field, or null 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. |
int |
count(Query query)
Count how many documents match the given query.
|
Weight |
createWeight(Query query,
ScoreMode scoreMode,
float boost)
Creates a
Weight for the given query, potentially adding caching
if possible and configured. |
Document |
doc(int docID)
Sugar for
.getIndexReader().document(docID) |
Document |
doc(int docID,
java.util.Set<java.lang.String> fieldsToLoad)
Sugar for
.getIndexReader().document(docID, fieldsToLoad) |
void |
doc(int docID,
StoredFieldVisitor fieldVisitor)
Sugar for
.getIndexReader().document(docID, fieldVisitor) |
Explanation |
explain(Query query,
int doc)
Returns an Explanation that describes how
doc scored against
query . |
protected Explanation |
explain(Weight weight,
int doc)
Expert: low-level implementation method
Returns an Explanation that describes how
doc scored against
weight . |
static QueryCache |
getDefaultQueryCache()
Expert: Get the default
QueryCache or null if the cache is disabled. |
static QueryCachingPolicy |
getDefaultQueryCachingPolicy()
Expert: Get the default
QueryCachingPolicy . |
static Similarity |
getDefaultSimilarity()
Expert: returns a default Similarity instance.
|
IndexReader |
getIndexReader()
Return the
IndexReader this searches. |
QueryCache |
getQueryCache()
Return the query cache of this
IndexSearcher . |
QueryCachingPolicy |
getQueryCachingPolicy()
Return the query cache of this
IndexSearcher . |
Similarity |
getSimilarity()
Expert: Get the
Similarity to use to compute scores. |
IndexSearcher.LeafSlice[] |
getSlices()
Returns the leaf slices used for concurrent searching, or null if no
ExecutorService was
passed to the constructor. |
IndexReaderContext |
getTopReaderContext()
Returns this searchers the top-level
IndexReaderContext . |
Query |
rewrite(Query original)
Expert: called to re-write queries into primitive queries.
|
protected void |
search(java.util.List<LeafReaderContext> leaves,
Weight weight,
Collector collector)
Lower-level search API.
|
void |
search(Query query,
Collector results)
Lower-level search API.
|
<C extends Collector,T> |
search(Query query,
CollectorManager<C,T> collectorManager)
Lower-level search API.
|
TopDocs |
search(Query query,
int n)
Finds the top
n
hits for query . |
TopFieldDocs |
search(Query query,
int n,
Sort sort)
Search implementation with arbitrary sorting.
|
TopFieldDocs |
search(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.
|
private TopFieldDocs |
searchAfter(FieldDoc after,
Query query,
int numHits,
Sort sort,
boolean doDocScores) |
TopDocs |
searchAfter(ScoreDoc after,
Query query,
int numHits)
Finds the top
n
hits for query where all results are after a previous
result (after ). |
TopDocs |
searchAfter(ScoreDoc after,
Query query,
int n,
Sort sort)
Finds the top
n
hits for query where all results are after a previous
result (after ). |
TopFieldDocs |
searchAfter(ScoreDoc after,
Query query,
int numHits,
Sort sort,
boolean doDocScores)
Finds the top
n
hits for query 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 default
QueryCache instance. |
static void |
setDefaultQueryCachingPolicy(QueryCachingPolicy defaultQueryCachingPolicy)
Expert: set the default
QueryCachingPolicy instance. |
void |
setQueryCache(QueryCache queryCache)
Set the
QueryCache to use when scores are not needed. |
void |
setQueryCachingPolicy(QueryCachingPolicy queryCachingPolicy)
Set the
QueryCachingPolicy to use for query caching. |
void |
setSimilarity(Similarity similarity)
Expert: Set the Similarity implementation used by this IndexSearcher.
|
protected IndexSearcher.LeafSlice[] |
slices(java.util.List<LeafReaderContext> leaves)
Expert: Creates an array of leaf slices each holding a subset of the given leaves.
|
TermStatistics |
termStatistics(Term term,
TermStates context)
Returns
TermStatistics for a term, or null if
the term does not exist. |
java.lang.String |
toString() |
private static QueryCache DEFAULT_QUERY_CACHE
private static QueryCachingPolicy DEFAULT_CACHING_POLICY
private static final int TOTAL_HITS_THRESHOLD
final IndexReader reader
protected final IndexReaderContext readerContext
protected final java.util.List<LeafReaderContext> leafContexts
private final IndexSearcher.LeafSlice[] leafSlices
private final java.util.concurrent.ExecutorService executor
private static final Similarity defaultSimilarity
private QueryCache queryCache
private QueryCachingPolicy queryCachingPolicy
private Similarity similarity
public IndexSearcher(IndexReader r)
public IndexSearcher(IndexReader r, java.util.concurrent.ExecutorService executor)
NIOFSDirectory
, 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).public IndexSearcher(IndexReaderContext context, java.util.concurrent.ExecutorService executor)
IndexReaderContext
.
Given a non-null
ExecutorService
this method runs
searches for each segment separately, using the provided ExecutorService.
IndexSearcher will not close/awaitTermination this ExecutorService on
close; you must do so, eventually, on your own. NOTE: if you are using
NIOFSDirectory
, 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).
IndexReaderContext
,
IndexReader.getContext()
public IndexSearcher(IndexReaderContext context)
IndexReaderContext
.IndexReaderContext
,
IndexReader.getContext()
public static Similarity getDefaultSimilarity()
getSimilarity()
.public static QueryCache getDefaultQueryCache()
QueryCache
or null
if the cache is disabled.public static void setDefaultQueryCache(QueryCache defaultQueryCache)
QueryCache
instance.public static QueryCachingPolicy getDefaultQueryCachingPolicy()
QueryCachingPolicy
.public static void setDefaultQueryCachingPolicy(QueryCachingPolicy defaultQueryCachingPolicy)
QueryCachingPolicy
instance.public void setQueryCache(QueryCache queryCache)
QueryCache
to use when scores are not needed.
A value of null
indicates that query matches should never be
cached. This method should be called before starting using this
IndexSearcher
.
NOTE: When using a query cache, queries should not be modified after they have been passed to IndexSearcher.
QueryCache
public QueryCache getQueryCache()
IndexSearcher
. This will be either
the default query cache
or the query cache
that was last set through setQueryCache(QueryCache)
. A return
value of null
indicates that caching is disabled.public void setQueryCachingPolicy(QueryCachingPolicy queryCachingPolicy)
QueryCachingPolicy
to use for query caching.
This method should be called before starting using this
IndexSearcher
.QueryCachingPolicy
public QueryCachingPolicy getQueryCachingPolicy()
IndexSearcher
. This will be either
the default policy
or the policy
that was last set through setQueryCachingPolicy(QueryCachingPolicy)
.protected IndexSearcher.LeafSlice[] slices(java.util.List<LeafReaderContext> leaves)
IndexSearcher.LeafSlice
is executed in a single thread. By default there
will be one IndexSearcher.LeafSlice
per leaf (LeafReaderContext
).public IndexReader getIndexReader()
IndexReader
this searches.public Document doc(int docID) throws java.io.IOException
.getIndexReader().document(docID)
java.io.IOException
IndexReader.document(int)
public void doc(int docID, StoredFieldVisitor fieldVisitor) throws java.io.IOException
.getIndexReader().document(docID, fieldVisitor)
java.io.IOException
IndexReader.document(int, StoredFieldVisitor)
public Document doc(int docID, java.util.Set<java.lang.String> fieldsToLoad) throws java.io.IOException
.getIndexReader().document(docID, fieldsToLoad)
java.io.IOException
IndexReader.document(int, Set)
public void setSimilarity(Similarity similarity)
public Similarity getSimilarity()
Similarity
to use to compute scores. This returns the
Similarity
that has been set through setSimilarity(Similarity)
or the default Similarity
if none has been set explicitly.public int count(Query query) throws java.io.IOException
java.io.IOException
public IndexSearcher.LeafSlice[] getSlices()
ExecutorService
was
passed to the constructor.public TopDocs searchAfter(ScoreDoc after, Query query, int numHits) throws java.io.IOException
n
hits for query
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.
BooleanQuery.TooManyClauses
- If a query would exceed
BooleanQuery.getMaxClauseCount()
clauses.java.io.IOException
public TopDocs search(Query query, int n) throws java.io.IOException
n
hits for query
.BooleanQuery.TooManyClauses
- If a query would exceed
BooleanQuery.getMaxClauseCount()
clauses.java.io.IOException
public void search(Query query, Collector results) throws java.io.IOException
LeafCollector.collect(int)
is called for every matching document.
BooleanQuery.TooManyClauses
- If a query would exceed
BooleanQuery.getMaxClauseCount()
clauses.java.io.IOException
public TopFieldDocs search(Query query, int n, Sort sort, boolean doDocScores) throws java.io.IOException
n
hits for query
, and sorting
the hits by the criteria in sort
.
If doDocScores
is true
then the score of each hit will be computed and
returned. If doMaxScore
is
true
then the maximum score over all
collected hits will be computed.BooleanQuery.TooManyClauses
- If a query would exceed
BooleanQuery.getMaxClauseCount()
clauses.java.io.IOException
public TopFieldDocs search(Query query, int n, Sort sort) throws java.io.IOException
public TopDocs searchAfter(ScoreDoc after, Query query, int n, Sort sort) throws java.io.IOException
n
hits for query
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.
BooleanQuery.TooManyClauses
- If a query would exceed
BooleanQuery.getMaxClauseCount()
clauses.java.io.IOException
public TopFieldDocs searchAfter(ScoreDoc after, Query query, int numHits, Sort sort, boolean doDocScores) throws java.io.IOException
n
hits for query
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. If doDocScores
is true
then the score of each hit will be computed and
returned. If doMaxScore
is
true
then the maximum score over all
collected hits will be computed.
BooleanQuery.TooManyClauses
- If a query would exceed
BooleanQuery.getMaxClauseCount()
clauses.java.io.IOException
private TopFieldDocs searchAfter(FieldDoc after, Query query, int numHits, Sort sort, boolean doDocScores) throws java.io.IOException
java.io.IOException
public <C extends Collector,T> T search(Query query, CollectorManager<C,T> collectorManager) throws java.io.IOException
CollectorManager
. In contrast
to search(Query, Collector)
, this method will use the searcher's
ExecutorService
in order to parallelize execution of the collection
on the configured leafSlices
.java.io.IOException
CollectorManager
protected void search(java.util.List<LeafReaderContext> leaves, Weight weight, Collector collector) throws java.io.IOException
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
.
leaves
- the searchers leaves to execute the searches onweight
- to match documentscollector
- to receive hitsBooleanQuery.TooManyClauses
- If a query would exceed
BooleanQuery.getMaxClauseCount()
clauses.java.io.IOException
public Query rewrite(Query original) throws java.io.IOException
BooleanQuery.TooManyClauses
- If a query would exceed
BooleanQuery.getMaxClauseCount()
clauses.java.io.IOException
public Explanation explain(Query query, int doc) throws java.io.IOException
doc
scored against
query
.
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.
java.io.IOException
protected Explanation explain(Weight weight, int doc) throws java.io.IOException
doc
scored against
weight
.
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)
.
BooleanQuery.TooManyClauses
- If a query would exceed
BooleanQuery.getMaxClauseCount()
clauses.java.io.IOException
public Weight createWeight(Query query, ScoreMode scoreMode, float boost) throws java.io.IOException
Weight
for the given query, potentially adding caching
if possible and configured.java.io.IOException
public IndexReaderContext getTopReaderContext()
IndexReaderContext
.IndexReader.getContext()
public java.lang.String toString()
toString
in class java.lang.Object
public TermStatistics termStatistics(Term term, TermStates context) throws java.io.IOException
TermStatistics
for a term, or null
if
the term does not exist.
This can be overridden for example, to return a term's statistics
across a distributed collection.java.io.IOException
public CollectionStatistics collectionStatistics(java.lang.String field) throws java.io.IOException
CollectionStatistics
for a field, or null
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.java.io.IOException