Show / Hide Table of Contents

    Class DirectoryReader

    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.

    Inheritance
    System.Object
    IndexReader
    CompositeReader
    BaseCompositeReader<AtomicReader>
    DirectoryReader
    FilterDirectoryReader
    Inherited Members
    BaseCompositeReader<AtomicReader>.GetTermVectors(Int32)
    BaseCompositeReader<AtomicReader>.NumDocs
    BaseCompositeReader<AtomicReader>.MaxDoc
    BaseCompositeReader<AtomicReader>.Document(Int32, StoredFieldVisitor)
    BaseCompositeReader<AtomicReader>.DocFreq(Term)
    BaseCompositeReader<AtomicReader>.TotalTermFreq(Term)
    BaseCompositeReader<AtomicReader>.GetSumDocFreq(String)
    BaseCompositeReader<AtomicReader>.GetDocCount(String)
    BaseCompositeReader<AtomicReader>.GetSumTotalTermFreq(String)
    BaseCompositeReader<AtomicReader>.ReaderIndex(Int32)
    BaseCompositeReader<AtomicReader>.ReaderBase(Int32)
    BaseCompositeReader<AtomicReader>.GetSequentialSubReaders()
    CompositeReader.ToString()
    CompositeReader.Context
    IndexReader.AddReaderClosedListener(IndexReader.IReaderClosedListener)
    IndexReader.RemoveReaderClosedListener(IndexReader.IReaderClosedListener)
    IndexReader.RegisterParentReader(IndexReader)
    IndexReader.RefCount
    IndexReader.IncRef()
    IndexReader.TryIncRef()
    IndexReader.DecRef()
    IndexReader.EnsureOpen()
    IndexReader.Equals(Object)
    IndexReader.GetHashCode()
    IndexReader.GetTermVector(Int32, String)
    IndexReader.NumDeletedDocs
    IndexReader.Document(Int32)
    IndexReader.Document(Int32, ISet<String>)
    IndexReader.HasDeletions
    IndexReader.Dispose()
    IndexReader.Dispose(Boolean)
    IndexReader.DoClose()
    IndexReader.Leaves
    IndexReader.CoreCacheKey
    IndexReader.CombinedCoreAndDeletesKey
    Namespace: Lucene.Net.Index
    Assembly: Lucene.Net.dll
    Syntax
    public abstract class DirectoryReader : BaseCompositeReader<AtomicReader>

    Constructors

    | Improve this Doc View Source

    DirectoryReader(Directory, AtomicReader[])

    Expert: Constructs a DirectoryReader on the given segmentReaders.

    Declaration
    protected DirectoryReader(Directory directory, AtomicReader[] segmentReaders)
    Parameters
    Type Name Description
    Directory directory
    AtomicReader[] segmentReaders

    the wrapped atomic index segment readers. This array is returned by 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().

    Fields

    | Improve this Doc View Source

    DEFAULT_TERMS_INDEX_DIVISOR

    Default termInfosIndexDivisor.

    Declaration
    public static readonly int DEFAULT_TERMS_INDEX_DIVISOR
    Field Value
    Type Description
    System.Int32
    | Improve this Doc View Source

    m_directory

    The index directory.

    Declaration
    protected readonly Directory m_directory
    Field Value
    Type Description
    Directory

    Properties

    | Improve this Doc View Source

    Directory

    Returns the directory this index resides in.

    Declaration
    public Directory Directory { get; }
    Property Value
    Type Description
    Directory
    | Improve this Doc View Source

    IndexCommit

    Expert: return the IndexCommit that this reader has opened.

    This is a Lucene.NET EXPERIMENTAL API, use at your own risk
    Declaration
    public abstract IndexCommit IndexCommit { get; }
    Property Value
    Type Description
    IndexCommit
    | Improve this Doc View Source

    Version

    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.

    Declaration
    public abstract long Version { get; }
    Property Value
    Type Description
    System.Int64

    Methods

    | Improve this Doc View Source

    DoOpenIfChanged()

    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.

    Declaration
    protected abstract DirectoryReader DoOpenIfChanged()
    Returns
    Type Description
    DirectoryReader

    null if there are no changes; else, a new DirectoryReader instance.

    | Improve this Doc View Source

    DoOpenIfChanged(IndexCommit)

    Implement this method to support OpenIfChanged(DirectoryReader, IndexCommit). If this reader does not support reopen from a specific IndexCommit, throw .

    Declaration
    protected abstract DirectoryReader DoOpenIfChanged(IndexCommit commit)
    Parameters
    Type Name Description
    IndexCommit commit
    Returns
    Type Description
    DirectoryReader

    null if there are no changes; else, a new DirectoryReader instance.

    | Improve this Doc View Source

    DoOpenIfChanged(IndexWriter, Boolean)

    Implement this method to support OpenIfChanged(DirectoryReader, IndexWriter, Boolean). If this reader does not support reopen from IndexWriter, throw .

    Declaration
    protected abstract DirectoryReader DoOpenIfChanged(IndexWriter writer, bool applyAllDeletes)
    Parameters
    Type Name Description
    IndexWriter writer
    System.Boolean applyAllDeletes
    Returns
    Type Description
    DirectoryReader

    null if there are no changes; else, a new DirectoryReader instance.

    | Improve this Doc View Source

    IndexExists(Directory)

    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

    Declaration
    public static bool IndexExists(Directory directory)
    Parameters
    Type Name Description
    Directory directory

    the directory to check for an index

    Returns
    Type Description
    System.Boolean

    true if an index exists; false otherwise

    | Improve this Doc View Source

    IsCurrent()

    Check whether any new changes have occurred to the index since this reader was opened.

    If this reader was created by calling an overload of Open(Directory), then this method checks if any further commits (see Commit()) have occurred in the directory.

    If instead this reader is a near real-time reader (ie, obtained by a call to Open(IndexWriter, Boolean), or by calling an overload of OpenIfChanged(DirectoryReader) on a near real-time reader), then this method checks if either a new commit has occurred, or any new uncommitted changes have taken place via the writer. Note that even if the writer has only performed merging, this method will still return false.

    In any event, if this returns false, you should call an overload of OpenIfChanged(DirectoryReader) to get a new reader that sees the changes.

    Declaration
    public abstract bool IsCurrent()
    Returns
    Type Description
    System.Boolean
    | Improve this Doc View Source

    ListCommits(Directory)

    Returns all commit points that exist in the Directory. Normally, because the default is KeepOnlyLastCommitDeletionPolicy, there would be only one commit point. But if you're using a custom IndexDeletionPolicy then there could be many commits. Once you have a given commit, you can open a reader on it by calling Open(IndexCommit) There must be at least one commit in the Directory, else this method throws IndexNotFoundException. Note that if a commit is in progress while this method is running, that commit may or may not be returned.

    Declaration
    public static IList<IndexCommit> ListCommits(Directory dir)
    Parameters
    Type Name Description
    Directory dir
    Returns
    Type Description
    IList<IndexCommit>

    a sorted list of IndexCommits, from oldest to latest.

    | Improve this Doc View Source

    Open(IndexCommit)

    Expert: returns an IndexReader reading the index in the given IndexCommit.

    Declaration
    public static DirectoryReader Open(IndexCommit commit)
    Parameters
    Type Name Description
    IndexCommit commit

    the commit point to open

    Returns
    Type Description
    DirectoryReader
    | Improve this Doc View Source

    Open(IndexCommit, Int32)

    Expert: returns an IndexReader reading the index in the given IndexCommit and termInfosIndexDivisor.

    Declaration
    public static DirectoryReader Open(IndexCommit commit, int termInfosIndexDivisor)
    Parameters
    Type Name Description
    IndexCommit commit

    the commit point to open

    System.Int32 termInfosIndexDivisor

    Subsamples which indexed terms are loaded into RAM. this has the same effect as setting TermIndexInterval (on IndexWriterConfig) except that setting must be done at indexing time while this setting can be set per reader. When set to N, then one in every N*termIndexInterval terms in the index is loaded into memory. By setting this to a value > 1 you can reduce memory usage, at the expense of higher latency when loading a TermInfo. The default value is 1. Set this to -1 to skip loading the terms index entirely. NOTE: divisor settings > 1 do not apply to all PostingsFormat implementations, including the default one in this release. It only makes sense for terms indexes that can efficiently re-sample terms at load time.

    Returns
    Type Description
    DirectoryReader
    | Improve this Doc View Source

    Open(IndexWriter, Boolean)

    Open a near real time IndexReader from the IndexWriter.

    @lucene.experimental

    Declaration
    public static DirectoryReader Open(IndexWriter writer, bool applyAllDeletes)
    Parameters
    Type Name Description
    IndexWriter writer

    The IndexWriter to open from

    System.Boolean 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.

    Returns
    Type Description
    DirectoryReader

    The new IndexReader

    Exceptions
    Type Condition
    CorruptIndexException

    if the index is corrupt

    See Also
    OpenIfChanged(DirectoryReader, IndexWriter, Boolean)
    | Improve this Doc View Source

    Open(Directory)

    Returns a IndexReader reading the index in the given Directory

    Declaration
    public static DirectoryReader Open(Directory directory)
    Parameters
    Type Name Description
    Directory directory

    the index directory

    Returns
    Type Description
    DirectoryReader
    | Improve this Doc View Source

    Open(Directory, Int32)

    Expert: Returns a IndexReader reading the index in the given Directory with the given termInfosIndexDivisor.

    Declaration
    public static DirectoryReader Open(Directory directory, int termInfosIndexDivisor)
    Parameters
    Type Name Description
    Directory directory

    the index directory

    System.Int32 termInfosIndexDivisor

    Subsamples which indexed terms are loaded into RAM. this has the same effect as setting TermIndexInterval (on IndexWriterConfig) except that setting must be done at indexing time while this setting can be set per reader. When set to N, then one in every N*termIndexInterval terms in the index is loaded into memory. By setting this to a value > 1 you can reduce memory usage, at the expense of higher latency when loading a TermInfo. The default value is 1. Set this to -1 to skip loading the terms index entirely. NOTE: divisor settings > 1 do not apply to all PostingsFormat implementations, including the default one in this release. It only makes sense for terms indexes that can efficiently re-sample terms at load time.

    Returns
    Type Description
    DirectoryReader
    | Improve this Doc View Source

    OpenIfChanged(DirectoryReader)

    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 a near-real-time (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 disposed (you are responsible for doing so); if a new reader is returned you also must eventually dispose it. Be sure to never dispose a reader while other threads are still using it; see SearcherManager to simplify managing this.

    Declaration
    public static DirectoryReader OpenIfChanged(DirectoryReader oldReader)
    Parameters
    Type Name Description
    DirectoryReader oldReader
    Returns
    Type Description
    DirectoryReader

    null if there are no changes; else, a new DirectoryReader instance which you must eventually dispose

    Exceptions
    Type Condition
    CorruptIndexException

    if the index is corrupt

    | Improve this Doc View Source

    OpenIfChanged(DirectoryReader, IndexCommit)

    If the IndexCommit differs from what the provided reader is searching, open and return a new reader; else, return null.

    Declaration
    public static DirectoryReader OpenIfChanged(DirectoryReader oldReader, IndexCommit commit)
    Parameters
    Type Name Description
    DirectoryReader oldReader
    IndexCommit commit
    Returns
    Type Description
    DirectoryReader
    See Also
    OpenIfChanged(DirectoryReader)
    | Improve this Doc View Source

    OpenIfChanged(DirectoryReader, IndexWriter, Boolean)

    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 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 MergedSegmentWarmer (on IndexWriterConfig) 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 disposed, any outstanding readers may continue to be used. However, if you attempt to reopen any of those readers, you'll hit an .

    This is a Lucene.NET EXPERIMENTAL API, use at your own risk
    Declaration
    public static DirectoryReader OpenIfChanged(DirectoryReader oldReader, IndexWriter writer, bool applyAllDeletes)
    Parameters
    Type Name Description
    DirectoryReader oldReader
    IndexWriter writer

    The IndexWriter to open from

    System.Boolean 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.

    Returns
    Type Description
    DirectoryReader

    DirectoryReader that covers entire index plus all changes made so far by this IndexWriter instance, or null if there are no new changes

    • Improve this Doc
    • View Source
    Back to top Copyright © 2020 Licensed to the Apache Software Foundation (ASF)