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.
Implements
Inherited Members
Namespace: Lucene.Net.Index
Assembly: Lucene.Net.dll
Syntax
public abstract class IndexReader : IDisposable
Properties
| Improve this Doc View SourceCombinedCoreAndDeletesKey
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 |
---|---|
System.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 IFieldCache/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 |
---|---|
System.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 |
---|---|
System.Boolean |
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 |
---|---|
System.Collections.Generic.IList<AtomicReaderContext> |
See Also
| Improve this Doc View SourceMaxDoc
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 |
---|---|
System.Int32 |
NumDeletedDocs
Returns the number of deleted documents.
Declaration
public int NumDeletedDocs { get; }
Property Value
Type | Description |
---|---|
System.Int32 |
NumDocs
Returns the number of documents in this index.
Declaration
public abstract int NumDocs { get; }
Property Value
Type | Description |
---|---|
System.Int32 |
RefCount
Expert: returns the current refCount for this reader
Declaration
public int RefCount { get; }
Property Value
Type | Description |
---|---|
System.Int32 |
Methods
| Improve this Doc View SourceAddReaderClosedListener(IndexReader.IReaderClosedListener)
Expert: adds a IndexReader.IReaderClosedListener. The provided listener will be invoked when this reader is closed.
Note
This API is experimental and might change in incompatible ways in the next release.
Declaration
public void AddReaderClosedListener(IndexReader.IReaderClosedListener listener)
Parameters
Type | Name | Description |
---|---|---|
IndexReader.IReaderClosedListener | 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 |
---|---|
System.IO.IOException | in case an System.IO.IOException occurs in DoClose() |
See Also
| Improve this Doc View SourceDispose()
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 |
---|---|
System.IO.IOException | If there is a low-level IO error |
Dispose(Boolean)
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 |
---|---|---|
System.Boolean | disposing |
|
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 |
---|---|
System.Int32 |
See Also
| Improve this Doc View SourceDoClose()
Implements close.
Declaration
protected abstract void DoClose()
Document(Int32)
Returns the stored fields of the n
th
Document 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 |
---|---|---|
System.Int32 | docID |
Returns
Type | Description |
---|---|
Document |
Exceptions
Type | Condition |
---|---|
System.IO.IOException | if there is a low-level IO error |
Document(Int32, 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(Int32). If you want to load a subset, use DocumentStoredFieldVisitor.
Declaration
public abstract void Document(int docID, StoredFieldVisitor visitor)
Parameters
Type | Name | Description |
---|---|---|
System.Int32 | docID | |
StoredFieldVisitor | visitor |
Document(Int32, ISet<String>)
Like Document(Int32) 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 |
---|---|---|
System.Int32 | docID | |
System.Collections.Generic.ISet<System.String> | fieldsToLoad |
Returns
Type | Description |
---|---|
Document |
EnsureOpen()
Throws System.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 sealed override bool Equals(object obj)
Parameters
Type | Name | Description |
---|---|---|
System.Object | obj |
Returns
Type | Description |
---|---|
System.Boolean |
Overrides
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 |
---|---|---|
System.String | field |
Returns
Type | Description |
---|---|
System.Int32 |
See Also
| Improve this Doc View SourceGetHashCode()
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 sealed override int GetHashCode()
Returns
Type | Description |
---|---|
System.Int32 |
Overrides
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 |
---|---|---|
System.String | field |
Returns
Type | Description |
---|---|
System.Int64 |
See Also
| Improve this Doc View SourceGetSumTotalTermFreq(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 |
---|---|---|
System.String | field |
Returns
Type | Description |
---|---|
System.Int64 |
See Also
| Improve this Doc View SourceGetTermVector(Int32, 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 |
---|---|---|
System.Int32 | docID | |
System.String | field |
Returns
Type | Description |
---|---|
Terms |
GetTermVectors(Int32)
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 |
---|---|---|
System.Int32 | 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(Boolean) 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
| Improve this Doc View SourceOpen(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 |
---|---|
System.IO.IOException | if there is a low-level IO error |
Open(IndexCommit, Int32)
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 |
System.Int32 | 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 |
Returns
Type | Description |
---|---|
DirectoryReader |
Exceptions
Type | Condition |
---|---|
System.IO.IOException | if there is a low-level IO error |
Open(IndexWriter, Boolean)
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 |
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 |
---|---|
System.IO.IOException | if there is a low-level IO error |
See Also
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 |
---|---|
System.IO.IOException | if there is a low-level IO error |
Open(Directory, Int32)
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 |
System.Int32 | 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 |
Returns
Type | Description |
---|---|
DirectoryReader |
Exceptions
Type | Condition |
---|---|
System.IO.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 |
RemoveReaderClosedListener(IndexReader.IReaderClosedListener)
Expert: remove a previously added IndexReader.IReaderClosedListener.
Note
This API is experimental and might change in incompatible ways in the next release.
Declaration
public void RemoveReaderClosedListener(IndexReader.IReaderClosedListener listener)
Parameters
Type | Name | Description |
---|---|---|
IndexReader.IReaderClosedListener | 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 |
---|---|
System.Int64 |
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(Boolean) 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 |
---|---|
System.Boolean |