Class IndexReader
- All Implemented Interfaces:
Closeable,AutoCloseable
- Direct Known Subclasses:
CompositeReader,LeafReader
IndexWriter will not be visible until a new
IndexReader is opened. It's best to use DirectoryReader.open(IndexWriter) to
obtain an IndexReader, if your IndexWriter is in-process. When you need to
re-open to see changes to the index, it's best to use DirectoryReader.openIfChanged(DirectoryReader) since the new reader will share resources with
the previous one when possible. 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:
LeafReader: 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 (likeDirectoryReader) of this reader can only be used to get stored fields from the underlying LeafReaders, but it is not possible to directly retrieve postings. To do that, get the sub-readers viaCompositeReader.getSequentialSubReaders().
IndexReader instances for indexes on disk are usually constructed with a call to one of the
static DirectoryReader.open() methods, e.g. DirectoryReader.open(org.apache.lucene.store.Directory). DirectoryReader implements the
CompositeReader interface, 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.
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic interfaceA utility class that gives hooks in order to help build a cache based on the data that is contained in this index.static final classA cache key identifying a resource that is being cached on.static interfaceA listener that is called when a resource gets closed. -
Method Summary
Modifier and TypeMethodDescriptionfinal voidclose()Closes files associated with this index.final voiddecRef()Expert: decreases the refCount of this IndexReader instance.abstract intReturns the number of documents containing theterm.protected abstract voiddoClose()Implements close.protected final voidThrows AlreadyClosedException if this IndexReader or any of its child readers is closed, otherwise returns.final booleanabstract IndexReaderContextExpert: Returns the rootIndexReaderContextfor thisIndexReader's sub-reader tree.abstract intgetDocCount(String field) Returns the number of documents that have at least one term for this field.abstract IndexReader.CacheHelperOptional method: Return aIndexReader.CacheHelperthat can be used to cache based on the content of this reader.final intExpert: returns the current refCount for this readerabstract longgetSumDocFreq(String field) Returns the sum ofTermsEnum.docFreq()for all terms in this field.abstract longgetSumTotalTermFreq(String field) Returns the sum ofTermsEnum.totalTermFreq()for all terms in this field.booleanReturns true if any documents have been deleted.final inthashCode()final voidincRef()Expert: increments the refCount of this IndexReader instance.final List<LeafReaderContext> leaves()Returns the reader's leaves, or itself if this reader is atomic.abstract intmaxDoc()Returns one greater than the largest possible document number.protected voidFor test framework use only.final intReturns the number of deleted documents.abstract intnumDocs()Returns the number of documents in this index.final voidregisterParentReader(IndexReader reader) Expert: This method is called byIndexReaders which wrap other readers (e.g.abstract StoredFieldsReturns aStoredFieldsreader for the stored fields of this index.abstract TermVectorsReturns aTermVectorsreader for the term vectors of this index.abstract longtotalTermFreq(Term term) Returns the total number of occurrences oftermacross all documents (the sum of the freq() for each doc that has this term).final booleanExpert: increments the refCount of this IndexReader instance only if the IndexReader has not been closed yet and returnstrueiff the refCount was successfully incremented, otherwisefalse.
-
Method Details
-
registerParentReader
Expert: This method is called byIndexReaders which wrap other readers (e.g.CompositeReaderorFilterLeafReader) to register the parent at the child (this reader) on construction of the parent. When this reader is closed, it will mark all registered parents as closed, too. The references to parent readers are weak only, so they can be GCed once they are no longer in use.- WARNING: This API is experimental and might change in incompatible ways in the next release.
-
notifyReaderClosedListeners
For test framework use only.- Throws:
IOException- NOTE: This API is for internal purposes only and might change in incompatible ways in the next release.
-
getRefCount
public final int getRefCount()Expert: returns the current refCount for this reader -
incRef
public final void incRef()Expert: increments the refCount of this IndexReader instance. RefCounts are used to determine when a reader can be closed safely, i.e. as soon as there are no more references. Be sure to always call a correspondingdecRef(), in a finally clause; otherwise the reader may never be closed. Note thatclose()simply calls decRef(), which means that the IndexReader will not really be closed untildecRef()has been called for all outstanding references.- See Also:
-
tryIncRef
public final boolean tryIncRef()Expert: increments the refCount of this IndexReader instance only if the IndexReader has not been closed yet and returnstrueiff the refCount was successfully incremented, otherwisefalse. If this method returnsfalsethe reader is either already closed or is currently being closed. Either way this reader instance shouldn't be used by an application unlesstrueis returned.RefCounts are used to determine when a reader can be closed 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 closed. Note thatclose()simply calls decRef(), which means that the IndexReader will not really be closed untildecRef()has been called for all outstanding references.- See Also:
-
decRef
Expert: decreases the refCount of this IndexReader instance. If the refCount drops to 0, then this reader is closed. If an exception is hit, the refCount is unchanged.- Throws:
IOException- in case an IOException occurs in doClose()- See Also:
-
ensureOpen
Throws AlreadyClosedException if this IndexReader or any of its child readers is closed, otherwise returns.- Throws:
AlreadyClosedException
-
equals
IndexReadersubclasses are not allowed to implement equals/hashCode, so methods are declared final. -
hashCode
public final int hashCode()IndexReadersubclasses are not allowed to implement equals/hashCode, so methods are declared final. -
termVectors
Returns aTermVectorsreader for the term vectors of this index.This call never returns
null, even if no term vectors were indexed. The returned instance should only be used by a single thread.Example:
TopDocs hits = searcher.search(query, 10); TermVectors termVectors = reader.termVectors(); for (ScoreDoc hit : hits.scoreDocs) { Fields vector = termVectors.get(hit.doc); }- Throws:
IOException- If there is a low-level IO error
-
numDocs
public abstract int numDocs()Returns the number of documents in this index.NOTE: This operation may run in O(maxDoc). Implementations that can't return this number in constant-time should cache it.
-
maxDoc
public abstract int 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. -
numDeletedDocs
public final int numDeletedDocs()Returns the number of deleted documents.NOTE: This operation may run in O(maxDoc).
-
storedFields
Returns aStoredFieldsreader for the stored fields of this index.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 = reader.storedFields(); for (ScoreDoc hit : hits.scoreDocs) { Document doc = storedFields.document(hit.doc); }- Throws:
IOException- If there is a low-level IO error
-
hasDeletions
public boolean hasDeletions() -
close
Closes files associated with this index. Also saves any new deletions to disk. No other methods should be called after this has been called.- Specified by:
closein interfaceAutoCloseable- Specified by:
closein interfaceCloseable- Throws:
IOException- if there is a low-level IO error
-
doClose
Implements close.- Throws:
IOException
-
getContext
Expert: Returns the rootIndexReaderContextfor thisIndexReader's sub-reader tree.Iff this reader is composed of sub readers, i.e. this reader being a composite reader, this method returns a
CompositeReaderContextholding the reader's direct children as well as a view of the reader tree's atomic leaf contexts. All sub-IndexReaderContextinstances 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 anLeafReaderContext.Note: Any of the sub-
CompositeReaderContextinstances referenced from this top-level context do not supportCompositeReaderContext.leaves(). Only the top-level context maintains the convenience leaf-view for performance reasons. -
leaves
Returns the reader's leaves, or itself if this reader is atomic. This is a convenience method callingthis.getContext().leaves().- See Also:
-
getReaderCacheHelper
Optional method: Return aIndexReader.CacheHelperthat can be used to cache based on the content of this reader. Two readers that have different data or different sets of deleted documents will be considered different.A return value of
nullindicates that this reader is not suited for caching, which is typically the case for short-lived wrappers that alter the content of the wrapped reader.- WARNING: This API is experimental and might change in incompatible ways in the next release.
-
docFreq
Returns the number of documents containing theterm. This method returns 0 if the term or field does not exists. This method does not take into account deleted documents that have not yet been merged away.- Throws:
IOException- See Also:
-
totalTermFreq
Returns the total number of occurrences oftermacross all documents (the sum of the freq() for each doc that has this term). Note that, like other term measures, this measure does not take deleted documents into account.- Throws:
IOException
-
getSumDocFreq
Returns the sum ofTermsEnum.docFreq()for all terms in this field. Note that, just like other term measures, this measure does not take deleted documents into account.- Throws:
IOException- See Also:
-
getDocCount
Returns the number of documents that have at least one term for this field. Note that, just like other term measures, this measure does not take deleted documents into account.- Throws:
IOException- See Also:
-
getSumTotalTermFreq
Returns the sum ofTermsEnum.totalTermFreq()for all terms in this field. Note that, just like other term measures, this measure does not take deleted documents into account.- Throws:
IOException- See Also:
-