Class IndexSearcher

    • Field Detail

      • maxClauseCount

        static int maxClauseCount
      • DEFAULT_QUERY_CACHE

        private static QueryCache DEFAULT_QUERY_CACHE
      • partialResult

        private volatile boolean partialResult
      • TOTAL_HITS_THRESHOLD

        private static final int TOTAL_HITS_THRESHOLD
        By default, we count hits accurately up to 1000. This makes sure that we don't spend most time on computing hit counts
        See Also:
        Constant Field Values
      • MAX_DOCS_PER_SLICE

        private static final int MAX_DOCS_PER_SLICE
        Thresholds for index slice allocation logic. To change the default, extend IndexSearcher and use custom values
        See Also:
        Constant Field Values
      • MAX_SEGMENTS_PER_SLICE

        private static final int MAX_SEGMENTS_PER_SLICE
        See Also:
        Constant Field Values
      • leafSlicesSupplier

        private final java.util.function.Supplier<IndexSearcher.LeafSlice[]> leafSlicesSupplier
        Used with executor - LeafSlice supplier where each slice holds a set of leafs executed within one thread. We are caching it instead of creating it eagerly to avoid calling a protected method from constructor, which is a bad practice. Always non-null, regardless of whether an executor is provided or not.
      • executor

        private final java.util.concurrent.Executor executor
      • defaultSimilarity

        private static final Similarity defaultSimilarity
      • similarity

        private Similarity similarity
        The Similarity implementation used by this searcher.
    • Constructor Detail

      • IndexSearcher

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

        public IndexSearcher​(IndexReader r,
                             java.util.concurrent.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).
      • IndexSearcher

        public IndexSearcher​(IndexReaderContext context,
                             java.util.concurrent.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()
    • 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().
      • getLeafContexts

        public java.util.List<LeafReaderContext> getLeafContexts()
        Expert: returns leaf contexts associated with this searcher. This is an internal method exposed for tests only.
      • getDefaultQueryCache

        public static QueryCache getDefaultQueryCache()
        Expert: Get the default QueryCache or null if the cache is disabled.
      • setDefaultQueryCache

        public static void setDefaultQueryCache​(QueryCache defaultQueryCache)
        Expert: set the default QueryCache instance.
      • setDefaultQueryCachingPolicy

        public static void setDefaultQueryCachingPolicy​(QueryCachingPolicy defaultQueryCachingPolicy)
        Expert: set the default QueryCachingPolicy instance.
      • 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
      • slices

        protected IndexSearcher.LeafSlice[] slices​(java.util.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​(java.util.List<LeafReaderContext> leaves,
                                                       int maxDocsPerSlice,
                                                       int maxSegmentsPerSlice)
        Static method to segregate LeafReaderContexts amongst multiple slices
      • doc

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

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

        public StoredFields storedFields()
                                  throws java.io.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:
        java.io.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 java.io.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:
        java.io.IOException
      • getSlices

        public final IndexSearcher.LeafSlice[] getSlices()
        Returns the leaf slices used for concurrent searching. Override slices(List) to customize how slices are created.
      • searchAfter

        public TopDocs searchAfter​(ScoreDoc after,
                                   Query query,
                                   int numHits)
                            throws java.io.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.
        java.io.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 java.io.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.
        java.io.IOException
      • search

        public TopFieldDocs search​(Query query,
                                   int n,
                                   Sort sort)
                            throws java.io.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:
        java.io.IOException - if there is a low-level I/O error
      • searchAfter

        public TopDocs searchAfter​(ScoreDoc after,
                                   Query query,
                                   int n,
                                   Sort sort)
                            throws java.io.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.
        java.io.IOException
      • searchAfter

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

        private TopFieldDocs searchAfter​(FieldDoc after,
                                         Query query,
                                         int numHits,
                                         Sort sort,
                                         boolean doDocScores)
                                  throws java.io.IOException
        Throws:
        java.io.IOException
      • search

        private <C extends Collector,​T> T search​(Weight weight,
                                                       CollectorManager<C,​T> collectorManager,
                                                       C firstCollector)
                                                throws java.io.IOException
        Throws:
        java.io.IOException
      • search

        protected void search​(java.util.List<LeafReaderContext> leaves,
                              Weight weight,
                              Collector collector)
                       throws java.io.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.
        java.io.IOException
      • rewrite

        private Query rewrite​(Query original,
                              boolean needsScores)
                       throws java.io.IOException
        Throws:
        java.io.IOException
      • getNumClausesCheckVisitor

        private static QueryVisitor getNumClausesCheckVisitor()
        Returns a QueryVisitor which recursively checks the total number of clauses that a query and its children cumulatively have and validates that the total number does not exceed the specified limit. Throws IndexSearcher.TooManyNestedClauses if the limit is exceeded.
      • explain

        public Explanation explain​(Query query,
                                   int doc)
                            throws java.io.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:
        java.io.IOException
      • explain

        protected Explanation explain​(Weight weight,
                                      int doc)
                               throws java.io.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.
        java.io.IOException
      • createWeight

        public Weight createWeight​(Query query,
                                   ScoreMode scoreMode,
                                   float boost)
                            throws java.io.IOException
        Creates a Weight for the given query, potentially adding caching if possible and configured.
        Throws:
        java.io.IOException
      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object
      • termStatistics

        public TermStatistics termStatistics​(Term term,
                                             int docFreq,
                                             long totalTermFreq)
                                      throws java.io.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:
        java.io.IOException
      • collectionStatistics

        public CollectionStatistics collectionStatistics​(java.lang.String field)
                                                  throws java.io.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:
        java.io.IOException
      • getExecutor

        @Deprecated
        public java.util.concurrent.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