Package org.apache.lucene.search

Class IndexSearcher

java.lang.Object
org.apache.lucene.search.IndexSearcher
public class IndexSearcher extends Object
Implements search over a single IndexReader.

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: IndexSearcher 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 instance; use your own (non-Lucene) objects instead.

  • Field Details

  • Constructor Details

    • IndexSearcher

      public IndexSearcher(IndexReader r)
      Creates a searcher searching the provided index.

    • IndexSearcher

      public IndexSearcher(IndexReader r, Executor executor)
      Runs searches for each segment separately, using the provided Executor. 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).
      WARNING: This API is experimental and might change in incompatible ways in the next release.

    • IndexSearcher

      public IndexSearcher(IndexReaderContext context, Executor executor)
      Creates a searcher searching the provided top-level IndexReaderContext.

      Given a non-null Executor this method runs searches for each segment separately, using the provided Executor. 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).

      See Also:
      WARNING: This API is experimental and might change in incompatible ways in the next release.

    • IndexSearcher

      public IndexSearcher(IndexReaderContext context)
      Creates a searcher searching the provided top-level IndexReaderContext.
      See Also:
      WARNING: This API is experimental and might change in incompatible ways in the next release.

  • Method Details

    • getDefaultSimilarity

      public static Similarity 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 respect getSimilarity().
      NOTE: This API is for internal purposes only and might change in incompatible ways in the next release.

    • getLeafContexts

      public List<LeafReaderContext> getLeafContexts()
      Expert: returns leaf contexts associated with this searcher. This is an internal method exposed for tests only.
      NOTE: This API is for internal purposes only and might change in incompatible ways in the next release.

    • getDefaultQueryCache

      public static QueryCache getDefaultQueryCache()
      Expert: Get the default QueryCache or null if the cache is disabled.
      NOTE: This API is for internal purposes only and might change in incompatible ways in the next release.

    • setDefaultQueryCache

      public static void setDefaultQueryCache(QueryCache defaultQueryCache)
      Expert: set the default QueryCache instance.
      NOTE: This API is for internal purposes only and might change in incompatible ways in the next release.

    • getDefaultQueryCachingPolicy

      public static QueryCachingPolicy getDefaultQueryCachingPolicy()
      Expert: Get the default QueryCachingPolicy.
      NOTE: This API is for internal purposes only and might change in incompatible ways in the next release.

    • setDefaultQueryCachingPolicy

      public static void setDefaultQueryCachingPolicy(QueryCachingPolicy defaultQueryCachingPolicy)
      Expert: set the default QueryCachingPolicy instance.
      NOTE: This API is for internal purposes only and might change in incompatible ways in the next release.

    • 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 cause IndexSearcher.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

      public void setQueryCache(QueryCache queryCache)
      Set the 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.

      See Also:
      WARNING: This API is experimental and might change in incompatible ways in the next release.

    • getQueryCache

      public QueryCache getQueryCache()
      Return the query cache of this 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.
      WARNING: This API is experimental and might change in incompatible ways in the next release.

    • setQueryCachingPolicy

      public void setQueryCachingPolicy(QueryCachingPolicy queryCachingPolicy)
      Set the QueryCachingPolicy to use for query caching. This method should be called before starting using this IndexSearcher.
      See Also:
      WARNING: This API is experimental and might change in incompatible ways in the next release.

    • getQueryCachingPolicy

      public QueryCachingPolicy getQueryCachingPolicy()
      Return the query cache of this IndexSearcher. This will be either the default policy or the policy that was last set through setQueryCachingPolicy(QueryCachingPolicy).
      WARNING: This API is experimental and might change in incompatible ways in the next release.

    • slices

      protected IndexSearcher.LeafSlice[] slices(List<LeafReaderContext> leaves)
      Expert: Creates an array of leaf slices each holding a subset of the given leaves. Each IndexSearcher.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

      public IndexReader getIndexReader()
      Return the IndexReader this searches.

    • doc

      @Deprecated public Document doc(int docID) throws IOException
      Deprecated.
      Use storedFields() to access fields for one or more documents
      Sugar for .getIndexReader().document(docID)
      Throws:
      IOException
      See Also:

    • doc

      @Deprecated public void doc(int docID, StoredFieldVisitor fieldVisitor) throws IOException
      Deprecated.
      Use storedFields() to access fields for one or more documents
      Sugar for .getIndexReader().document(docID, fieldVisitor)
      Throws:
      IOException
      See Also:

    • doc

      @Deprecated public Document doc(int docID, Set<String> fieldsToLoad) throws IOException
      Deprecated.
      Use storedFields() to access fields for one or more documents
      Sugar for .getIndexReader().document(docID, fieldsToLoad)
      Throws:
      IOException
      See Also:

    • storedFields

      public StoredFields storedFields() throws IOException
      Returns a StoredFields 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

      public void setSimilarity(Similarity similarity)
      Expert: Set the Similarity implementation used by this IndexSearcher.

    • getSimilarity

      public Similarity getSimilarity()
      Expert: Get the 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.

    • count

      public int count(Query query) throws IOException
      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

      public final IndexSearcher.LeafSlice[] getSlices()
      Returns the leaf slices used for concurrent searching. Override slices(List) to customize how slices are created.
      WARNING: This API is experimental and might change in incompatible ways in the next release.

    • searchAfter

      public TopDocs searchAfter(ScoreDoc after, Query query, int numHits) throws IOException
      Finds the top 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.

      Throws:
      IndexSearcher.TooManyClauses - If a query would exceed getMaxClauseCount() clauses.
      IOException

    • getTimeout

      public QueryTimeout getTimeout()
      Get the configured QueryTimeout for all searches that run through this IndexSearcher, or null if not set.

    • setTimeout

      public void setTimeout(QueryTimeout queryTimeout)
      Set a QueryTimeout for all searches that run through this IndexSearcher.

    • search

      public TopDocs search(Query query, int n) throws IOException
      Finds the top n hits for query.
      Throws:
      IndexSearcher.TooManyClauses - If a query would exceed getMaxClauseCount() clauses.
      IOException

    • search

      @Deprecated public void search(Query query, Collector results) throws IOException
      Deprecated.
      This method is being deprecated in favor of search(Query, CollectorManager) due to its support for concurrency in IndexSearcher
      Lower-level search API.

      LeafCollector.collect(int) is called for every matching document.

      Throws:
      IndexSearcher.TooManyClauses - If a query would exceed getMaxClauseCount() clauses.
      IOException

    • timedOut

      public boolean timedOut()
      Returns true if any search hit the timeout.

    • search

      public TopFieldDocs search(Query query, int n, Sort sort, boolean doDocScores) throws IOException
      Search implementation with arbitrary sorting, plus control over whether hit scores and max score should be computed. Finds the top 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.
      Throws:
      IndexSearcher.TooManyClauses - If a query would exceed getMaxClauseCount() clauses.
      IOException

    • search

      public TopFieldDocs search(Query query, int n, Sort sort) throws IOException
      Search implementation with arbitrary sorting.
      Parameters:
      query - The query to search for
      n - Return only the top n results
      sort - The Sort object
      Returns:
      The top docs, sorted according to the supplied Sort instance
      Throws:
      IOException - if there is a low-level I/O error

    • searchAfter

      public TopDocs searchAfter(ScoreDoc after, Query query, int n, Sort sort) throws IOException
      Finds the top 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.

      Throws:
      IndexSearcher.TooManyClauses - If a query would exceed getMaxClauseCount() clauses.
      IOException

    • searchAfter

      public TopFieldDocs searchAfter(ScoreDoc after, Query query, int numHits, Sort sort, boolean doDocScores) throws IOException
      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.

      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.

      Throws:
      IndexSearcher.TooManyClauses - If a query would exceed getMaxClauseCount() clauses.
      IOException

    • search

      public <C extends Collector, T> T search(Query query, CollectorManager<C,T> collectorManager) throws IOException
      Lower-level search API. Search all leaves using the given CollectorManager. In contrast to search(Query, Collector), this method will use the searcher's Executor in order to parallelize execution of the collection on the configured getSlices().
      Throws:
      IOException
      See Also:
      WARNING: This API is experimental and might change in incompatible ways in the next release.

    • 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 on
      weight - to match documents
      collector - to receive hits
      Throws:
      IndexSearcher.TooManyClauses - If a query would exceed getMaxClauseCount() clauses.
      IOException

    • rewrite

      public Query rewrite(Query original) throws IOException
      Expert: called to re-write queries into primitive queries.
      Throws:
      IndexSearcher.TooManyClauses - If a query would exceed getMaxClauseCount() clauses.
      IOException

    • explain

      public Explanation explain(Query query, int doc) throws IOException
      Returns an Explanation that describes how 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.

      Throws:
      IOException

    • explain

      protected Explanation explain(Weight weight, int doc) throws IOException
      Expert: low-level implementation method Returns an Explanation that describes how 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).

      Throws:
      IndexSearcher.TooManyClauses - If a query would exceed getMaxClauseCount() clauses.
      IOException

    • createWeight

      public Weight createWeight(Query query, ScoreMode scoreMode, float boost) throws IOException
      Creates a Weight for the given query, potentially adding caching if possible and configured.
      Throws:
      IOException
      WARNING: This API is experimental and might change in incompatible ways in the next release.

    • getTopReaderContext

      public IndexReaderContext getTopReaderContext()
      Returns this searcher's top-level IndexReaderContext.
      See Also:

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • termStatistics

      public TermStatistics termStatistics(Term term, int docFreq, long totalTermFreq) throws IOException
      Returns TermStatistics 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
      WARNING: This API is experimental and might change in incompatible ways in the next release.

    • collectionStatistics

      public CollectionStatistics collectionStatistics(String field) throws IOException
      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.

      Throws:
      IOException
      WARNING: This API is experimental and might change in incompatible ways in the next release.

    • getExecutor

      @Deprecated public Executor getExecutor()
      Deprecated.
      use getTaskExecutor() executor instead to execute concurrent tasks
      Returns this searchers executor or null if no executor was provided

    • getTaskExecutor

      public TaskExecutor getTaskExecutor()
      Returns the TaskExecutor that this searcher relies on to execute concurrent operations
      Returns:
      the task executor