Class IndexReader

IndexReader is an abstract class, providing an interface for accessing an index. Search of an index is done entirely through this abstract interface, so that any subclass which implements it is searchable.

There are two different types of IndexReaders:

• AtomicReader: These indexes do not consist of several sub-readers, they are atomic. They support retrieval of stored fields, doc values, terms, and postings.
• CompositeReader: Instances (like DirectoryReader) of this reader can only be used to get stored fields from the underlying AtomicReaders, but it is not possible to directly retrieve postings. To do that, get the sub-readers via GetSequentialSubReaders(). Alternatively, you can mimic an AtomicReader (with a serious slowdown), by wrapping composite readers with SlowCompositeReaderWrapper.

IndexReader instances for indexes on disk are usually constructed with a call to one of the static DirectoryReader.Open() methods, e.g. Open(Directory). DirectoryReader inherits the CompositeReader abstract class, it is not possible to directly get postings.

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

object

IndexReader

AtomicReader

CompositeReader

Implements

IDisposable

Inherited Members

object.Equals(object, object)

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: Lucene.Net.Index

Assembly: Lucene.Net.dll

Syntax

public abstract class IndexReader : IDisposable

Properties

CombinedCoreAndDeletesKey

Expert: Returns a key for this IndexReader that also includes deletions, so IFieldCache/CachingWrapperFilter can find it again. This key must not have Equals()/GetHashCode() methods, so "equals" means "identical".

Declaration

public virtual object CombinedCoreAndDeletesKey { get; }

Property Value

Type	Description
object

Context

Expert: Returns the root IndexReaderContext for this IndexReader's sub-reader tree.

Iff this reader is composed of sub readers, i.e. this reader being a composite reader, this method returns a CompositeReaderContext holding the reader's direct children as well as a view of the reader tree's atomic leaf contexts. All sub- IndexReaderContext instances referenced from this readers top-level context are private to this reader and are not shared with another context tree. For example, IndexSearcher uses this API to drive searching by one atomic leaf reader at a time. If this reader is not composed of child readers, this method returns an AtomicReaderContext.

Note: Any of the sub-CompositeReaderContext instances referenced from this top-level context do not support Leaves. Only the top-level context maintains the convenience leaf-view for performance reasons.

Declaration

public abstract IndexReaderContext Context { get; }

Property Value

Type	Description
IndexReaderContext

CoreCacheKey

Expert: Returns a key for this IndexReader, so FieldCache/CachingWrapperFilter can find it again. This key must not have Equals()/GetHashCode() methods, so "equals" means "identical".

Declaration

public virtual object CoreCacheKey { get; }

Property Value

Type	Description
object

HasDeletions

Returns true if any documents have been deleted. Implementers should consider overriding this property if MaxDoc or NumDocs are not constant-time operations.

Declaration

public virtual bool HasDeletions { get; }

Property Value

Type	Description
bool

Leaves

Returns the reader's leaves, or itself if this reader is atomic. This is a convenience method calling this.Context.Leaves.

Declaration

public IList<AtomicReaderContext> Leaves { get; }

Property Value

Type	Description
IList<AtomicReaderContext>

See Also

Leaves

MaxDoc

Returns one greater than the largest possible document number. this may be used to, e.g., determine how big to allocate an array which will have an element for every document number in an index.

Declaration

public abstract int MaxDoc { get; }

Property Value

Type	Description
int

NumDeletedDocs

Returns the number of deleted documents.

Declaration

public int NumDeletedDocs { get; }

Property Value

Type	Description
int

NumDocs

Returns the number of documents in this index.

Declaration

public abstract int NumDocs { get; }

Property Value

Type	Description
int

RefCount

Expert: returns the current refCount for this reader

Declaration

public int RefCount { get; }

Property Value

Type	Description
int

Methods

AddReaderDisposedListener(IReaderDisposedListener)

Expert: adds a IReaderDisposedListener. The provided listener will be invoked when this reader is disposed.

NOTE: This was addReaderClosedListener() in Lucene.

Note

This API is experimental and might change in incompatible ways in the next release.

Declaration

public void AddReaderDisposedListener(IReaderDisposedListener listener)

Parameters

Type	Name	Description
IReaderDisposedListener	listener

DecRef()

Expert: decreases the RefCount of this IndexReader instance. If the RefCount drops to 0, then this reader is disposed. If an exception is hit, the RefCount is unchanged.

Declaration

public void DecRef()

Exceptions

Type	Condition
IOException	in case an IOException occurs in DoClose()

See Also

IncRef()

Dispose()

Closes files associated with this index. Also saves any new deletions to disk. No other methods should be called after this has been called.

Declaration

public void Dispose()

Exceptions

Type	Condition
IOException	If there is a low-level IO error

Dispose(bool)

Closes files associated with this index. This method implements the disposable pattern. It may be overridden to dispose any managed or unmanaged resources, but be sure to call base.Dispose(disposing) to close files associated with the underlying IndexReader.

Declaration

protected virtual void Dispose(bool disposing)

Parameters

Type	Name	Description
bool	disposing	true indicates to dispose all managed and unmanaged resources, false indicates dispose unmanaged resources only

DoClose()

Implements close.

Declaration

protected abstract void DoClose()

DocFreq(Term)

Returns the number of documents containing the term. This method returns 0 if the term or field does not exist. This method does not take into account deleted documents that have not yet been merged away.

Declaration

public abstract int DocFreq(Term term)

Parameters

Type	Name	Description
Term	term

Returns

Type	Description
int

See Also

DocFreq

Document(int)

Returns the stored fields of the n^thDocument in this index. This is just sugar for using DocumentStoredFieldVisitor.

NOTE: for performance reasons, this method does not check if the requested document is deleted, and therefore asking for a deleted document may yield unspecified results. Usually this is not required, however you can test if the doc is deleted by checking the IBits returned from GetLiveDocs(IndexReader).

NOTE: only the content of a field is returned, if that field was stored during indexing. Metadata like boost, omitNorm, IndexOptions, tokenized, etc., are not preserved.

Declaration

public Document Document(int docID)

Parameters

Type	Name	Description
int	docID

Returns

Type	Description
Document

Exceptions

Type	Condition
IOException	if there is a low-level IO error

Document(int, StoredFieldVisitor)

Expert: visits the fields of a stored document, for custom processing/loading of each field. If you simply want to load all fields, use Document(int). If you want to load a subset, use DocumentStoredFieldVisitor.

Declaration

public abstract void Document(int docID, StoredFieldVisitor visitor)

Parameters

Type	Name	Description
int	docID
StoredFieldVisitor	visitor

Document(int, ISet<string>)

Like Document(int) but only loads the specified fields. Note that this is simply sugar for DocumentStoredFieldVisitor(ISet<string>).

Declaration

public Document Document(int docID, ISet<string> fieldsToLoad)

Parameters

Type	Name	Description
int	docID
ISet<string>	fieldsToLoad

Returns

Type	Description
Document

EnsureOpen()

Throws ObjectDisposedException if this IndexReader or any of its child readers is disposed, otherwise returns.

Declaration

protected void EnsureOpen()

Equals(object)

Determines whether two object instances are equal.

For caching purposes, IndexReader subclasses are not allowed to implement Equals/GetHashCode, so methods are declared sealed. To lookup instances from caches use CoreCacheKey and CombinedCoreAndDeletesKey.

Declaration

public override sealed bool Equals(object obj)

Parameters

Type	Name	Description
object	obj

Returns

Type	Description
bool

Overrides

object.Equals(object)

GetDocCount(string)

Returns the number of documents that have at least one term for this field, or -1 if this measure isn't stored by the codec. Note that, just like other term measures, this measure does not take deleted documents into account.

Declaration

public abstract int GetDocCount(string field)

Parameters

Type	Name	Description
string	field

Returns

Type	Description
int

See Also

DocCount

GetHashCode()

Serves as the default hash function.

For caching purposes, IndexReader subclasses are not allowed to implement Equals/GetHashCode, so methods are declared sealed. To lookup instances from caches use CoreCacheKey and CombinedCoreAndDeletesKey.

Declaration

public override sealed int GetHashCode()

Returns

Type	Description
int

Overrides

object.GetHashCode()

GetSumDocFreq(string)

Returns the sum of DocFreq for all terms in this field, or -1 if this measure isn't stored by the codec. Note that, just like other term measures, this measure does not take deleted documents into account.

Declaration

public abstract long GetSumDocFreq(string field)

Parameters

Type	Name	Description
string	field

Returns

Type	Description
long

See Also

SumDocFreq

GetSumTotalTermFreq(string)

Returns the sum of TotalTermFreq for all terms in this field, or -1 if this measure isn't stored by the codec (or if this fields omits term freq and positions). Note that, just like other term measures, this measure does not take deleted documents into account.

Declaration

public abstract long GetSumTotalTermFreq(string field)

Parameters

Type	Name	Description
string	field

Returns

Type	Description
long

See Also

SumTotalTermFreq

GetTermVector(int, string)

Retrieve term vector for this document and field, or null if term vectors were not indexed. The returned Fields instance acts like a single-document inverted index (the docID will be 0).

Declaration

public Terms GetTermVector(int docID, string field)

Parameters

Type	Name	Description
int	docID
string	field

Returns

Type	Description
Terms

GetTermVectors(int)

Retrieve term vectors for this document, or null if term vectors were not indexed. The returned Fields instance acts like a single-document inverted index (the docID will be 0).

Declaration

public abstract Fields GetTermVectors(int docID)

Parameters

Type	Name	Description
int	docID

Returns

Type	Description
Fields

IncRef()

Expert: increments the RefCount of this IndexReader instance. RefCounts are used to determine when a reader can be disposed safely, i.e. as soon as there are no more references. Be sure to always call a corresponding DecRef(), in a finally clause; otherwise the reader may never be disposed. Note that Dispose(bool) simply calls DecRef(), which means that the IndexReader will not really be disposed until DecRef() has been called for all outstanding references.

Declaration

public void IncRef()

See Also

DecRef()

TryIncRef()

Open(IndexCommit)

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

Declaration

[Obsolete("Use DirectoryReader.Open(IndexCommit)")]
public static DirectoryReader Open(IndexCommit commit)

Parameters

Type	Name	Description
IndexCommit	commit	the commit point to open

Returns

Type	Description
DirectoryReader

Exceptions

Type	Condition
IOException	if there is a low-level IO error

Open(IndexCommit, int)

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

Declaration

[Obsolete("Use DirectoryReader.Open(IndexCommit, int)/>")]
public static DirectoryReader Open(IndexCommit commit, int termInfosIndexDivisor)

Parameters

Type	Name	Description
IndexCommit	commit	the commit point to open
int	termInfosIndexDivisor	Subsamples which indexed terms are loaded into RAM. this has the same effect as TermIndexInterval (which can be set in 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.

Returns

Type	Description
DirectoryReader

Exceptions

Type	Condition
IOException	if there is a low-level IO error

Open(IndexWriter, bool)

Open a near real time IndexReader from the IndexWriter.

Declaration

[Obsolete("Use DirectoryReader.Open(IndexWriter, bool)")]
public static DirectoryReader Open(IndexWriter writer, bool applyAllDeletes)

Parameters

Type	Name	Description
IndexWriter	writer	The IndexWriter to open from
bool	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
IOException	if there is a low-level IO error

See Also

OpenIfChanged(DirectoryReader, IndexWriter, bool)

Open(Directory)

Returns a IndexReader reading the index in the given Directory

Declaration

[Obsolete("Use DirectoryReader.Open(Directory)")]
public static DirectoryReader Open(Directory directory)

Parameters

Type	Name	Description
Directory	directory	the index directory

Returns

Type	Description
DirectoryReader

Exceptions

Type	Condition
IOException	if there is a low-level IO error

Open(Directory, int)

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

Declaration

[Obsolete("Use DirectoryReader.Open(Directory, int)")]
public static DirectoryReader Open(Directory directory, int termInfosIndexDivisor)

Parameters

Type	Name	Description
Directory	directory	the index directory
int	termInfosIndexDivisor	Subsamples which indexed terms are loaded into RAM. this has the same effect as TermIndexInterval (which can be set 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.

Returns

Type	Description
DirectoryReader

Exceptions

Type	Condition
IOException	if there is a low-level IO error

RegisterParentReader(IndexReader)

Expert: this method is called by IndexReaders which wrap other readers (e.g. CompositeReader or FilterAtomicReader) to register the parent at the child (this reader) on construction of the parent. When this reader is disposed, it will mark all registered parents as disposed, too. The references to parent readers are weak only, so they can be GCed once they are no longer in use.

Note

This API is experimental and might change in incompatible ways in the next release.

Declaration

public void RegisterParentReader(IndexReader reader)

Parameters

Type	Name	Description
IndexReader	reader

RemoveReaderDisposedListener(IReaderDisposedListener)

Expert: remove a previously added IReaderDisposedListener.

NOTE: This was removeReaderClosedListener() in Lucene.

Note

This API is experimental and might change in incompatible ways in the next release.

Declaration

public void RemoveReaderDisposedListener(IReaderDisposedListener listener)

Parameters

Type	Name	Description
IReaderDisposedListener	listener

TotalTermFreq(Term)

Returns the total number of occurrences of term across all documents (the sum of the Freq for each doc that has this term). This will be -1 if the codec doesn't support this measure. Note that, like other term measures, this measure does not take deleted documents into account.

Declaration

public abstract long TotalTermFreq(Term term)

Parameters

Type	Name	Description
Term	term

Returns

Type	Description
long

TryIncRef()

Expert: increments the RefCount of this IndexReader instance only if the IndexReader has not been disposed yet and returns true iff the RefCount was successfully incremented, otherwise false. If this method returns false the reader is either already disposed or is currently being disposed. Either way this reader instance shouldn't be used by an application unless true is returned.

RefCounts are used to determine when a reader can be disposed safely, i.e. as soon as there are no more references. Be sure to always call a corresponding DecRef(), in a finally clause; otherwise the reader may never be disposed. Note that Dispose(bool) simply calls DecRef(), which means that the IndexReader will not really be disposed until DecRef() has been called for all outstanding references.

Declaration

public bool TryIncRef()

Returns

Type	Description
bool

See Also

DecRef()

IncRef()

Implements

IDisposable