public abstract class DirectoryReader extends BaseCompositeReader<LeafReader>
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.
IndexReader.CacheHelper, IndexReader.CacheKey, IndexReader.ClosedListener
Modifier and Type | Field and Description |
---|---|
protected Directory |
directory
The index directory.
|
Modifier | Constructor and Description |
---|---|
protected |
DirectoryReader(Directory directory,
LeafReader[] segmentReaders)
Expert: Constructs a
DirectoryReader on the given subReaders. |
Modifier and Type | Method and Description |
---|---|
Directory |
directory()
Returns the directory this index resides in.
|
protected abstract DirectoryReader |
doOpenIfChanged()
Implement this method to support
openIfChanged(DirectoryReader) . |
protected abstract DirectoryReader |
doOpenIfChanged(IndexCommit commit)
Implement this method to support
openIfChanged(DirectoryReader,IndexCommit) . |
protected abstract DirectoryReader |
doOpenIfChanged(IndexWriter writer,
boolean applyAllDeletes)
Implement this method to support
openIfChanged(DirectoryReader,IndexWriter,boolean) . |
abstract IndexCommit |
getIndexCommit()
Expert: return the IndexCommit that this reader has opened.
|
abstract long |
getVersion()
Version number when this IndexReader was opened.
|
static boolean |
indexExists(Directory directory)
Returns
true if an index likely exists at
the specified directory. |
abstract boolean |
isCurrent()
Check whether any new changes have occurred to the
index since this reader was opened.
|
static List<IndexCommit> |
listCommits(Directory dir)
Returns all commit points that exist in the Directory.
|
static DirectoryReader |
open(Directory directory)
Returns a IndexReader reading the index in the given
Directory
|
static DirectoryReader |
open(IndexCommit commit)
Expert: returns an IndexReader reading the index in the given
IndexCommit . |
static DirectoryReader |
open(IndexWriter writer)
Open a near real time IndexReader from the
IndexWriter . |
static DirectoryReader |
open(IndexWriter writer,
boolean applyAllDeletes,
boolean writeAllDeletes)
Expert: open a near real time IndexReader from the
IndexWriter ,
controlling whether past deletions should be applied. |
static DirectoryReader |
openIfChanged(DirectoryReader oldReader)
If the index has changed since the provided reader was
opened, open and return a new reader; else, return
null.
|
static DirectoryReader |
openIfChanged(DirectoryReader oldReader,
IndexCommit commit)
If the IndexCommit differs from what the
provided reader is searching, open and return a new
reader; else, return null.
|
static DirectoryReader |
openIfChanged(DirectoryReader oldReader,
IndexWriter writer)
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). |
static DirectoryReader |
openIfChanged(DirectoryReader oldReader,
IndexWriter writer,
boolean applyAllDeletes)
Expert: Opens a new reader, if there are any changes, controlling whether past deletions should be applied.
|
docFreq, document, getDocCount, getSequentialSubReaders, getSumDocFreq, getSumTotalTermFreq, getTermVectors, maxDoc, numDocs, readerBase, readerIndex, totalTermFreq
getContext, toString
close, decRef, doClose, document, document, ensureOpen, equals, getReaderCacheHelper, getRefCount, getTermVector, hasDeletions, hashCode, incRef, leaves, numDeletedDocs, registerParentReader, tryIncRef
protected final Directory directory
protected DirectoryReader(Directory directory, LeafReader[] segmentReaders) throws IOException
DirectoryReader
on the given subReaders.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()
.IOException
public static DirectoryReader open(Directory directory) throws IOException
directory
- the index directoryIOException
- if there is a low-level IO errorpublic static DirectoryReader open(IndexWriter writer) throws IOException
IndexWriter
.writer
- The IndexWriter to open fromCorruptIndexException
- if the index is corruptIOException
- if there is a low-level IO erroropenIfChanged(DirectoryReader,IndexWriter,boolean)
public static DirectoryReader open(IndexWriter writer, boolean applyAllDeletes, boolean writeAllDeletes) throws IOException
IndexWriter
,
controlling whether past deletions should be applied.writer
- The IndexWriter to open fromapplyAllDeletes
- 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 heapIOException
open(IndexWriter)
public static DirectoryReader open(IndexCommit commit) throws IOException
IndexCommit
.commit
- the commit point to openIOException
- if there is a low-level IO errorpublic static DirectoryReader openIfChanged(DirectoryReader oldReader) throws IOException
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.
CorruptIndexException
- if the index is corruptIOException
- if there is a low-level IO errorpublic static DirectoryReader openIfChanged(DirectoryReader oldReader, IndexCommit commit) throws IOException
IOException
openIfChanged(DirectoryReader)
public static DirectoryReader openIfChanged(DirectoryReader oldReader, IndexWriter writer) throws IOException
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
.
writer
- The IndexWriter to open fromIOException
- if there is a low-level IO errorpublic static DirectoryReader openIfChanged(DirectoryReader oldReader, IndexWriter writer, boolean applyAllDeletes) throws IOException
writer
- The IndexWriter to open fromapplyAllDeletes
- 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.IOException
- if there is a low-level IO erroropenIfChanged(DirectoryReader,IndexWriter)
public static List<IndexCommit> listCommits(Directory dir) throws IOException
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.IndexCommit
s, from oldest
to latest.IOException
public static boolean indexExists(Directory directory) throws IOException
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 committingdirectory
- the directory to check for an indextrue
if an index exists; false
otherwiseIOException
public final Directory directory()
protected abstract DirectoryReader doOpenIfChanged() throws IOException
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.IOException
- if there is a low-level IO errorprotected abstract DirectoryReader doOpenIfChanged(IndexCommit commit) throws IOException
openIfChanged(DirectoryReader,IndexCommit)
.
If this reader does not support reopen from a specific IndexCommit
,
throw UnsupportedOperationException
.IOException
- if there is a low-level IO errorprotected abstract DirectoryReader doOpenIfChanged(IndexWriter writer, boolean applyAllDeletes) throws IOException
openIfChanged(DirectoryReader,IndexWriter,boolean)
.
If this reader does not support reopen from IndexWriter
,
throw UnsupportedOperationException
.IOException
- if there is a low-level IO errorpublic abstract long getVersion()
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
.
public abstract boolean isCurrent() throws IOException
If this reader was created by calling open(org.apache.lucene.store.Directory)
,
then this method checks if any further commits
(see IndexWriter.commit()
) have occurred in the
directory.
If instead this reader is a near real-time reader
(ie, obtained by a call to open(IndexWriter)
, or by calling openIfChanged(org.apache.lucene.index.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
openIfChanged(org.apache.lucene.index.DirectoryReader)
to get a new reader that sees the
changes.
IOException
- if there is a low-level IO errorpublic abstract IndexCommit getIndexCommit() throws IOException
IOException
Copyright © 2000-2021 Apache Software Foundation. All Rights Reserved.