public class IndexSearcher extends 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:
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 |
---|---|
protected List<LeafReaderContext> |
leafContexts |
protected IndexSearcher.LeafSlice[] |
leafSlices
used with executor - each slice holds a set of leafs executed within one thread
|
protected IndexReaderContext |
readerContext |
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,
ExecutorService executor)
Creates a searcher searching the provided top-level
IndexReaderContext . |
IndexSearcher(IndexReader r,
ExecutorService executor)
Runs searches for each segment separately, using the
provided ExecutorService.
|
Modifier and Type | Method and Description |
---|---|
CollectionStatistics |
collectionStatistics(String field)
Returns
CollectionStatistics for a field. |
int |
count(Query query)
Count how many documents match the given query.
|
Weight |
createNormalizedWeight(Query query,
boolean needsScores)
Creates a normalized weight for a top-level
Query . |
Weight |
createWeight(Query query,
boolean needsScores)
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,
Set<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(boolean needsScores)
Expert: Get the
Similarity to use to compute scores. |
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(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,
boolean doMaxScore)
Search implementation with arbitrary sorting, plus
control over whether hit scores and max score
should be computed.
|
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,
boolean doMaxScore)
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(List<LeafReaderContext> leaves)
Expert: Creates an array of leaf slices each holding a subset of the given leaves.
|
TermStatistics |
termStatistics(Term term,
TermContext context)
Returns
TermStatistics for a term. |
String |
toString() |
protected final IndexReaderContext readerContext
protected final List<LeafReaderContext> leafContexts
protected final IndexSearcher.LeafSlice[] leafSlices
public IndexSearcher(IndexReader r)
public IndexSearcher(IndexReader r, 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, 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(boolean)
.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(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 IOException
.getIndexReader().document(docID)
IOException
IndexReader.document(int)
public void doc(int docID, StoredFieldVisitor fieldVisitor) throws IOException
.getIndexReader().document(docID, fieldVisitor)
IOException
IndexReader.document(int, StoredFieldVisitor)
public Document doc(int docID, Set<String> fieldsToLoad) throws IOException
.getIndexReader().document(docID, fieldsToLoad)
IOException
IndexReader.document(int, Set)
public void setSimilarity(Similarity similarity)
public Similarity getSimilarity(boolean needsScores)
Similarity
to use to compute scores. When
needsScores
is false
, this method will return a simple
Similarity
that does not leverage scoring factors such as norms.
When needsScores
is true
, this returns the
Similarity
that has been set through setSimilarity(Similarity)
or the getDefaultSimilarity()
default Similarity
if none
has been set explicitly.public int count(Query query) throws IOException
IOException
public TopDocs searchAfter(ScoreDoc after, Query query, int numHits) throws 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.IOException
public TopDocs search(Query query, int n) throws IOException
n
hits for query
.BooleanQuery.TooManyClauses
- If a query would exceed
BooleanQuery.getMaxClauseCount()
clauses.IOException
public void search(Query query, Collector results) throws IOException
LeafCollector.collect(int)
is called for every matching document.
BooleanQuery.TooManyClauses
- If a query would exceed
BooleanQuery.getMaxClauseCount()
clauses.IOException
public TopFieldDocs search(Query query, int n, Sort sort, boolean doDocScores, boolean doMaxScore) throws 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.IOException
public TopFieldDocs search(Query query, int n, Sort sort) throws IOException
query
- The query to search forn
- Return only the top n resultssort
- The Sort
objectSort
instanceIOException
- if there is a low-level I/O errorpublic TopDocs searchAfter(ScoreDoc after, Query query, int n, Sort sort) throws 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.IOException
public TopFieldDocs searchAfter(ScoreDoc after, Query query, int numHits, Sort sort, boolean doDocScores, boolean doMaxScore) throws 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.IOException
public <C extends Collector,T> T search(Query query, CollectorManager<C,T> collectorManager) throws 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
.IOException
CollectorManager
protected void search(List<LeafReaderContext> leaves, Weight weight, Collector collector) throws 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.IOException
public Query rewrite(Query original) throws IOException
BooleanQuery.TooManyClauses
- If a query would exceed
BooleanQuery.getMaxClauseCount()
clauses.IOException
public Explanation explain(Query query, int doc) throws 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.
IOException
protected Explanation explain(Weight weight, int doc) throws 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.IOException
public Weight createNormalizedWeight(Query query, boolean needsScores) throws IOException
Query
.
The query is rewritten by this method and Query.createWeight(org.apache.lucene.search.IndexSearcher, boolean)
called,
afterwards the Weight
is normalized. The returned Weight
can then directly be used to get a Scorer
.IOException
public Weight createWeight(Query query, boolean needsScores) throws IOException
Weight
for the given query, potentially adding caching
if possible and configured.IOException
public IndexReaderContext getTopReaderContext()
IndexReaderContext
.IndexReader.getContext()
public TermStatistics termStatistics(Term term, TermContext context) throws IOException
TermStatistics
for a term.
This can be overridden for example, to return a term's statistics
across a distributed collection.IOException
public CollectionStatistics collectionStatistics(String field) throws IOException
CollectionStatistics
for a field.
This can be overridden for example, to return a field's statistics
across a distributed collection.IOException
Copyright © 2000-2016 Apache Software Foundation. All Rights Reserved.