public class MultiTermIndexIterator extends AbstractUnionDocumentIterator implements IndexIterator
This class adds to AbstractUnionDocumentIterator
an interval iterator generating the OR of the intervals returned for each of the documents involved.
The main difference with an OrDocumentIterator built on the same array of component iterators
is that this class implements IndexIterator and hence provides a count() (the sum
of counts of those component iterators positioned on the current document), frequency() and nextPosition(). The
frequency is by default the maximum frequency of a component iterator, but it can be set
at construction time.
The main raison d'être of this class is support for query expansion: a blind application
of OrDocumentIterator to an array of index iterators would mislead scorers such as BM25Scorer
because low-frequency terms (e.g., hapax legomena) would be responsible for most of the score.
Note that DocumentIteratorVisitor has a visit method for generic index iterator
and a visit method for instances of this class.
This approach provides additional flexibility—a scorer, for instance, might treat an instance of
this class as a standard IndexIterator, or it might choose to query which terms actually appear
and do something more sophisticated (for instance, using weights).
AbstractUnionDocumentIterator.IntHeapSemiIndirectPriorityQueue, AbstractUnionDocumentIterator.LongHeapSemiIndirectPriorityQueueAbstractCompositeDocumentIterator.AbstractCompositeIndexIntervalIterator, AbstractCompositeDocumentIterator.AbstractCompositeIntervalIterator| Modifier and Type | Field and Description |
|---|---|
protected int |
id
The id of this iterator.
|
protected String |
term
The term of this iterator.
|
front, frontSize, queue, refArraydocumentIterator, indexIterator, indexIteratorsWithoutPositions, ncurrentIterators, indices, intervalIterators, soleIndex, soleIntervalIterator, unmodifiableCurrentIteratorscurr, weightEND_OF_POSITIONSEND_OF_LIST| Modifier | Constructor and Description |
|---|---|
protected |
MultiTermIndexIterator(int defaultFrequency,
IndexIterator... indexIterator)
Creates a new document iterator that merges the given array of iterators.
|
| Modifier and Type | Method and Description |
|---|---|
<T> T |
accept(DocumentIteratorVisitor<T> visitor)
Accepts a visitor.
|
<T> T |
acceptDeep(DocumentIteratorVisitor<T> visitor) |
<T> T |
acceptDeepOnTruePaths(DocumentIteratorVisitor<T> visitor) |
<T> T |
acceptOnTruePaths(DocumentIteratorVisitor<T> visitor)
Invokes
AbstractUnionDocumentIterator.acceptOnTruePaths(DocumentIteratorVisitor) only on component
iterators positioned on the current document. |
int |
count()
The count is the sum of counts of those component iterators positioned on the current document.
|
long |
frequency()
The frequency is either the default frequency set at construction time, or the maximum frequency of the component iterators.
|
int |
front(IndexIterator[] indexIterator)
Fills the given array with the index iterators composing the current front.
|
static IndexIterator |
getInstance(Index index,
IndexIterator... indexIterator)
Returns an index iterator that merges the given array of iterators.
|
static IndexIterator |
getInstance(IndexIterator... indexIterator)
Returns an index iterator that merges the given array of iterators.
|
static IndexIterator |
getInstance(int defaultFrequency,
Index index,
IndexIterator... indexIterator)
Returns an index iterator that merges the given array of iterators.
|
static IndexIterator |
getInstance(int defaultFrequency,
IndexIterator... indexIterator)
Returns an index iterator that merges the given array of iterators.
|
protected IntervalIterator |
getIntervalIterator(Index index,
int n,
boolean allIndexIterators,
Object unused)
Creates an interval iterator suitable for this
AbstractIntervalDocumentIterator. |
int |
id()
Returns the id of this index iterator.
|
IndexIterator |
id(int id)
Sets the id of this index iterator.
|
Index |
index()
Returns the index over which this iterator is built.
|
IntervalIterator |
intervalIterator()
Returns the interval iterator of this document iterator for single-index queries.
|
IntervalIterator |
intervalIterator(Index index)
Returns the interval iterator of this document iterator for the given index.
|
long |
nextDocument()
Returns the next document provided by this document iterator, or
DocumentIterator.END_OF_LIST if no more documents are available. |
int |
nextPosition()
Returns the next position at which the term appears in the current document.
|
Payload |
payload()
Returns the payload, if any, associated with the current document.
|
long |
skipTo(long n)
Skips all documents smaller than
n. |
String |
term()
Returns the term whose inverted list is returned by this index iterator.
|
IndexIterator |
term(CharSequence term)
Sets the term whose inverted list is returned by this index iterator.
|
long |
termNumber()
Returns the number of the term whose inverted list is returned by this index iterator.
|
IndexIterator |
weight(double weight)
Sets the weight of this index iterator.
|
computeFront, intervalIteratorsdispose, toStringallIndexIterators, indices, indicesdocument, ensureOnADocument, mayHaveNext, weightclone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, waitdispose, document, indices, intervalIterators, mayHaveNext, weightprotected String term
protected int id
protected MultiTermIndexIterator(int defaultFrequency,
IndexIterator... indexIterator)
throws IOException
defaultFrequency - the default term frequency (or Integer.MIN_VALUE for the max).indexIterator - the iterators to be joined.IOExceptionpublic static IndexIterator getInstance(IndexIterator... indexIterator) throws IOException
index() will return the result of the same method on the first iterator.indexIterator - the iterators to be joined (at least one).IllegalArgumentException - if no iterators were provided.IOExceptionpublic static IndexIterator getInstance(Index index, IndexIterator... indexIterator) throws IOException
Note that the special case of the empty and of the singleton arrays
are handled efficiently. The frequency is computed as a max, and
index() will return index.
index - the index that wil be returned by index().indexIterator - the iterators to be joined.IOExceptionpublic static IndexIterator getInstance(int defaultFrequency, IndexIterator... indexIterator) throws IOException
defaultFrequency - the default term frequency (or Integer.MIN_VALUE for the max).indexIterator - the iterators to be joined (at least one).IllegalArgumentException - if no iterators were provided, or they run on different indices.IOExceptionpublic static IndexIterator getInstance(int defaultFrequency, Index index, IndexIterator... indexIterator) throws IOException
Note that the special case of the empty and of the singleton arrays are handled efficiently.
defaultFrequency - the default term frequency (or Integer.MIN_VALUE for the max).index - the index that wil be returned by index().indexIterator - the iterators to be joined.IllegalArgumentException - if there is some iterator on an index different from index.IOExceptionprotected IntervalIterator getIntervalIterator(Index index, int n, boolean allIndexIterators, Object unused)
AbstractIntervalDocumentIteratorAbstractIntervalDocumentIterator.getIntervalIterator in class AbstractIntervalDocumentIteratorindex - the reference index for the iterator, or null.n - the number of underlying or component iterators.allIndexIterators - whether all underlying or component iterators are index iterators.unused - an optional argument.AbstractIntervalDocumentIterator.public long skipTo(long n)
throws IOException
DocumentIteratorn.
Define the current document k associated with this document iterator
as follows:
DocumentIterator.nextDocument() and this method have never been called;
DocumentIterator.END_OF_LIST, if a call to this method or to
DocumentIterator.nextDocument() returned DocumentIterator.END_OF_LIST;
DocumentIterator.nextDocument() or this method, otherwise.
If k is larger than or equal to n, then
this method does nothing and returns k. Otherwise, a
call to this method is equivalent to
while( ( k = nextDocument() ) < n ); return k;
Thus, when a result k ≠ DocumentIterator.END_OF_LIST
is returned, the state of this iterator
will be exactly the same as after a call to DocumentIterator.nextDocument()
that returned k.
In particular, the first document larger than or equal to n (when returned
by this method) will not be returned by the next call to
DocumentIterator.nextDocument().
skipTo in interface DocumentIteratorskipTo in class AbstractUnionDocumentIteratorn - a document pointer.n if available, DocumentIterator.END_OF_LIST
otherwise.IOExceptionpublic long nextDocument()
throws IOException
DocumentIteratorDocumentIterator.END_OF_LIST if no more documents are available.nextDocument in interface DocumentIteratornextDocument in class AbstractUnionDocumentIteratorDocumentIterator.END_OF_LIST if no more documents are available.IOExceptionpublic int count()
throws IOException
count in interface IndexIteratorIOExceptionpublic int front(IndexIterator[] indexIterator)
This method is essentially a safe exposure of the front of the queue
merging the component index iterators.
After a call to nextDocument(), you can use this method to know
which terms actually appear in the current document. You can use the public
field AbstractCompositeDocumentIterator.n to size the argument
array appropriately.
indexIterator - an array, at least large as the number of component index iterators,
that will be partially filled with the index iterators corresponding to terms appearing in the current document.indexIterator.public long frequency()
throws IOException
frequency in interface IndexIteratorIOExceptionpublic IndexIterator term(CharSequence term)
IndexIteratorUsually, the term is automatically set by Index.documents(CharSequence)
or by IndexReader.documents(CharSequence), but you can
use this method to ensure that IndexIterator.term() doesn't throw
an exception.
term in interface IndexIteratorterm - a character sequence (that will be defensively copied)
that will be assumed to be the term whose inverted list is returned by this index iterator.public String term()
IndexIteratorUsually, the term is automatically set by IndexReader.documents(CharSequence) or IndexReader.documents(long), but you can
supply your own term with IndexIterator.term(CharSequence).
term in interface IndexIteratorIndexIterator.termNumber()public long termNumber()
IndexIteratorUsually, the term number is automatically set by IndexReader.documents(CharSequence) or IndexReader.documents(long).
termNumber in interface IndexIteratorIndexIterator.term()public IndexIterator id(int id)
IndexIteratorThe id is an integer associated with each index iterator. It has no specific semantics, and can be used differently in different contexts. A typical usage pattern, for instance, is using it to assign a unique number to the index iterators contained in a composite document iterator (say, numbering consecutively the leaves of the composite).
id in interface IndexIteratorid - the new id for this index iterator.public int id()
IndexIteratorid in interface IndexIteratorIndexIterator.id(int)public Index index()
IndexIteratorindex in interface IndexIteratorpublic Payload payload()
IndexIteratorpayload in interface IndexIteratorpublic IndexIterator weight(double weight)
DocumentIteratorweight in interface IndexIteratorweight in interface DocumentIteratorweight in class AbstractDocumentIteratorweight - the weight of this index iterator.DocumentIterator.weight(double)public <T> T accept(DocumentIteratorVisitor<T> visitor) throws IOException
DocumentIteratorA document iterator is usually structured as composite,
with operators as internal nodes and IndexIterators
as leaves. This method implements the visitor pattern.
accept in interface DocumentIteratoraccept in class AbstractCompositeDocumentIteratorvisitor - the visitor.null if the visit was interrupted.IOExceptionpublic <T> T acceptOnTruePaths(DocumentIteratorVisitor<T> visitor) throws IOException
AbstractUnionDocumentIteratorAbstractUnionDocumentIterator.acceptOnTruePaths(DocumentIteratorVisitor) only on component
iterators positioned on the current document.acceptOnTruePaths in interface DocumentIteratoracceptOnTruePaths in class AbstractUnionDocumentIteratorvisitor - a visitor.IOExceptionDocumentIterator.accept(DocumentIteratorVisitor),
CounterCollectionVisitorpublic <T> T acceptDeep(DocumentIteratorVisitor<T> visitor) throws IOException
IOExceptionpublic <T> T acceptDeepOnTruePaths(DocumentIteratorVisitor<T> visitor) throws IOException
IOExceptionpublic int nextPosition()
throws IOException
IndexIteratornextPosition in interface IndexIteratorIndexIterator.END_OF_POSITIONS if there are no more positions.IOExceptionpublic IntervalIterator intervalIterator()
DocumentIteratorThis is a commodity method that can be used only for queries built over a single index.
intervalIterator in interface DocumentIteratorDocumentIterator.intervalIterator(Index)public IntervalIterator intervalIterator(Index index)
DocumentIteratorAfter a call to DocumentIterator.nextDocument(), this iterator
can be used to retrieve the intervals in the current document (the
one returned by DocumentIterator.nextDocument()) for
the index index.
Note that if all indices have positions, it is guaranteed that at least one index will return an interval. However, for disjunctive queries it cannot be guaranteed that all indices will return an interval.
Indices without positions always return IntervalIterators.TRUE.
Thus, in presence of indices without positions it is possible that no
intervals at all are available.
intervalIterator in interface DocumentIteratorindex - an index (must be one over which the query was built).index.