Package org.apache.lucene.search

Class IndexSearcher

    • Constructor Detail

      • 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:
        IndexReaderContext, IndexReader.getContext()
        WARNING: This API is experimental and might change in incompatible ways in the next release.

    • Method Detail

      • 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(int)

      • 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:
        QueryCache
        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:
        QueryCachingPolicy
        WARNING: This API is experimental and might change in incompatible ways in the next release.

      • 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:
        IndexReader.storedFields()

      • setSimilarity

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

      • 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 IndexSearcher.LeafSlice[] getSlices()
        Returns the leaf slices used for concurrent searching, or null if no Executor was passed to the constructor.
        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

      • 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 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

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

      • 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

        public Executor getExecutor()
        Returns this searchers executor or null if no executor was provided