Package org.apache.lucene.index

Class DirectoryReader

  • All Implemented Interfaces:
    Closeable, AutoCloseable
    Direct Known Subclasses:
    FilterDirectoryReader, StandardDirectoryReader
    public abstract class DirectoryReader
extends BaseCompositeReader<LeafReader>
    DirectoryReader is an implementation of CompositeReader that can read indexes in a Directory.

    DirectoryReader instances are usually constructed with a call to one of the static open() methods, e.g. open(Directory).

    For efficiency, in this API documents are often referred to via document numbers, non-negative integers which each name a unique document in the index. These document numbers are ephemeral -- they may change as documents are added to and deleted from an index. Clients should thus not rely on a given document having the same number between sessions.

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

    • Field Detail

      • directory

        protected final Directory directory
        The index directory.

    • Constructor Detail

      • DirectoryReader

        protected DirectoryReader​(Directory directory,
                          LeafReader[] segmentReaders,
                          Comparator<LeafReader> leafSorter)
                   throws IOException
        Expert: Constructs a DirectoryReader on the given subReaders.
        Parameters:
        segmentReaders - the wrapped atomic index segment readers. This array is returned by BaseCompositeReader.getSequentialSubReaders() and used to resolve the correct subreader for docID-based methods. Please note: This array is not cloned and not protected for modification outside of this reader. Subclasses of DirectoryReader should take care to not allow modification of this internal array, e.g. doOpenIfChanged().
        leafSorter - – a comparator for sorting leaf readers. If not null, this comparator is used for sorting leaf readers.
        Throws:
        IOException

    • Method Detail

      • open

        public static DirectoryReader open​(Directory directory)
                            throws IOException
        Returns a IndexReader reading the index in the given Directory
        Parameters:
        directory - the index directory
        Throws:
        IOException - if there is a low-level IO error

      • open

        public static DirectoryReader open​(Directory directory,
                                   Comparator<LeafReader> leafSorter)
                            throws IOException
        Returns a IndexReader for the the index in the given Directory
        Parameters:
        directory - the index directory
        leafSorter - a comparator for sorting leaf readers. Providing leafSorter is useful for indices on which it is expected to run many queries with particular sort criteria (e.g. for time-based indices this is usually a descending sort on timestamp). In this case leafSorter should sort leaves according to this sort criteria. Providing leafSorter allows to speed up this particular type of sort queries by early terminating while iterating through segments and segments' documents.
        Throws:
        IOException - if there is a low-level IO error

      • open

        public static DirectoryReader open​(IndexWriter writer,
                                   boolean applyAllDeletes,
                                   boolean writeAllDeletes)
                            throws IOException
        Expert: open a near real time IndexReader from the IndexWriter, controlling whether past deletions should be applied.
        Parameters:
        writer - The IndexWriter to open from
        applyAllDeletes - If true, all buffered deletes will be applied (made visible) in the returned reader. If false, the deletes are not applied but remain buffered (in IndexWriter) so that they will be applied in the future. Applying deletes can be costly, so if your app can tolerate deleted documents being returned you might gain some performance by passing false.
        writeAllDeletes - If true, new deletes will be written down to index files instead of carried over from writer to reader directly in heap
        Throws:
        IOException
        See Also:
        open(IndexWriter)
        WARNING: This API is experimental and might change in incompatible ways in the next release.

      • open

        public static DirectoryReader open​(IndexCommit commit,
                                   int minSupportedMajorVersion,
                                   Comparator<LeafReader> leafSorter)
                            throws IOException
        Expert: returns an IndexReader reading the index on the given IndexCommit. This method allows to open indices that were created wih a Lucene version older than N-1 provided that all codecs for this index are available in the classpath and the segment file format used was created with Lucene 7 or newer. Users of this API must be aware that Lucene doesn't guarantee semantic compatibility for indices created with versions older than N-1. All backwards compatibility aside from the file format is optional and applied on a best effort basis.
        Parameters:
        commit - the commit point to open
        minSupportedMajorVersion - the minimum supported major index version
        leafSorter - a comparator for sorting leaf readers. Providing leafSorter is useful for indices on which it is expected to run many queries with particular sort criteria (e.g. for time-based indices, this is usually a descending sort on timestamp). In this case leafSorter should sort leaves according to this sort criteria. Providing leafSorter allows to speed up this particular type of sort queries by early terminating while iterating through segments and segments' documents
        Throws:
        IOException - if there is a low-level IO error

      • openIfChanged

        public static DirectoryReader openIfChanged​(DirectoryReader oldReader)
                                     throws IOException
        If the index has changed since the provided reader was opened, open and return a new reader; else, return null. The new reader, if not null, will be the same type of reader as the previous one, ie an NRT reader will open a new NRT reader, a MultiReader will open a new MultiReader, etc.

        This method is typically far less costly than opening a fully new DirectoryReader as it shares resources (for example sub-readers) with the provided DirectoryReader, when possible.

        The provided reader is not closed (you are responsible for doing so); if a new reader is returned you also must eventually close it. Be sure to never close a reader while other threads are still using it; see SearcherManager to simplify managing this.

        Returns:
        null if there are no changes; else, a new DirectoryReader instance which you must eventually close
        Throws:
        CorruptIndexException - if the index is corrupt
        IOException - if there is a low-level IO error

      • openIfChanged

        public static DirectoryReader openIfChanged​(DirectoryReader oldReader,
                                            IndexWriter writer)
                                     throws IOException
        Expert: If there changes (committed or not) in the IndexWriter versus what the provided reader is searching, then open and return a new IndexReader searching both committed and uncommitted changes from the writer; else, return null (though, the current implementation never returns null).

        This provides "near real-time" searching, in that changes made during an IndexWriter session can be quickly made available for searching without closing the writer nor calling IndexWriter.commit().

        It's near real-time because there is no hard guarantee on how quickly you can get a new reader after making changes with IndexWriter. You'll have to experiment in your situation to determine if it's fast enough. As this is a new and experimental feature, please report back on your findings so we can learn, improve and iterate.

        The very first time this method is called, this writer instance will make every effort to pool the readers that it opens for doing merges, applying deletes, etc. This means additional resources (RAM, file descriptors, CPU time) will be consumed.

        For lower latency on reopening a reader, you should call IndexWriterConfig.setMergedSegmentWarmer(org.apache.lucene.index.IndexWriter.IndexReaderWarmer) to pre-warm a newly merged segment before it's committed to the index. This is important for minimizing index-to-search delay after a large merge.

        If an addIndexes* call is running in another thread, then this reader will only search those segments from the foreign index that have been successfully copied over, so far.

        NOTE: Once the writer is closed, any outstanding readers may continue to be used. However, if you attempt to reopen any of those readers, you'll hit an AlreadyClosedException.

        Parameters:
        writer - The IndexWriter to open from
        Returns:
        DirectoryReader that covers entire index plus all changes made so far by this IndexWriter instance, or null if there are no new changes
        Throws:
        IOException - if there is a low-level IO error
        WARNING: This API is experimental and might change in incompatible ways in the next release.

      • openIfChanged

        public static DirectoryReader openIfChanged​(DirectoryReader oldReader,
                                            IndexWriter writer,
                                            boolean applyAllDeletes)
                                     throws IOException
        Expert: Opens a new reader, if there are any changes, controlling whether past deletions should be applied.
        Parameters:
        writer - The IndexWriter to open from
        applyAllDeletes - If true, all buffered deletes will be applied (made visible) in the returned reader. If false, the deletes are not applied but remain buffered (in IndexWriter) so that they will be applied in the future. Applying deletes can be costly, so if your app can tolerate deleted documents being returned you might gain some performance by passing false.
        Throws:
        IOException - if there is a low-level IO error
        See Also:
        openIfChanged(DirectoryReader,IndexWriter)
        WARNING: This API is experimental and might change in incompatible ways in the next release.

      • indexExists

        public static boolean indexExists​(Directory directory)
                           throws IOException
        Returns true if an index likely exists at the specified directory. Note that if a corrupt index exists, or if an index in the process of committing
        Parameters:
        directory - the directory to check for an index
        Returns:
        true if an index exists; false otherwise
        Throws:
        IOException

      • directory

        public final Directory directory()
        Returns the directory this index resides in.

      • doOpenIfChanged

        protected abstract DirectoryReader doOpenIfChanged()
                                            throws IOException
        Implement this method to support openIfChanged(DirectoryReader). If this reader does not support reopen, return null, so client code is happy. This should be consistent with isCurrent() (should always return true) if reopen is not supported.
        Returns:
        null if there are no changes; else, a new DirectoryReader instance.
        Throws:
        IOException - if there is a low-level IO error

      • getVersion

        public abstract long getVersion()
        Version number when this IndexReader was opened.

        This method returns the version recorded in the commit that the reader opened. This version is advanced every time a change is made with IndexWriter.

      • getIndexCommit

        public abstract IndexCommit getIndexCommit()
                                    throws IOException
        Expert: return the IndexCommit that this reader has opened.
        Throws:
        IOException
        WARNING: This API is experimental and might change in incompatible ways in the next release.