TwoPhaseIterator (Lucene 10.5.1 core API)
Description: declaration: package: org.apache.lucene.search, class: TwoPhaseIterator

Package org.apache.lucene.search

# Class TwoPhaseIterator

java.lang.Object
org.apache.lucene.search.TwoPhaseIterator

Direct Known Subclasses:
  `DocValuesRangeIterator`

public abstract class TwoPhaseIterator extends Object
Returned by `Scorer.twoPhaseIterator()` to expose an approximation of a `DocIdSetIterator`. When the `approximation()`'s `DocIdSetIterator.nextDoc()` or `DocIdSetIterator.advance(int)` return, `matches()` needs to be checked in order to know whether the returned doc ID actually matches.

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

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected final DocIdSetIterator`
  `approximation`

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `TwoPhaseIterator(DocIdSetIterator approximation)`
  Takes the approximation to be returned by `approximation`.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `DocIdSetIterator`
  `approximation()`
  Return an approximation.
  `static DocIdSetIterator`
  `asDocIdSetIterator(TwoPhaseIterator twoPhaseIterator)`
  Return a `DocIdSetIterator` view of the provided `TwoPhaseIterator`.
  `int`
  `docIDRunEnd()`
  Returns the end of the run of consecutive doc IDs that match this `TwoPhaseIterator` and that contains the current doc ID of the approximation, that is: one plus the last doc ID of the run.
  `void`
  `intoBitSet(int upTo, FixedBitSet bitSet, int offset)`
  Load the doc IDs that both belong to the `approximation()` and `match`, and are in `[approximation().docID(), upTo)`, into `bitSet`, the document whose ID is `i` being stored at bit `i - offset`.
  `abstract float`
  `matchCost()`
  An estimate of the expected cost to determine that a single document `matches()`.
  `abstract boolean`
  `matches()`
  Return whether the current doc ID that `approximation()` is on matches.
  `static TwoPhaseIterator`
  `unwrap(DocIdSetIterator iterator)`
  If the given `DocIdSetIterator` has been created with `asDocIdSetIterator(org.apache.lucene.search.TwoPhaseIterator)`, then this will return the wrapped `TwoPhaseIterator`.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Field Details

  - ### approximation

    protected final DocIdSetIterator approximation

- ## Constructor Details

  - ### TwoPhaseIterator

    protected TwoPhaseIterator(DocIdSetIterator approximation)
    Takes the approximation to be returned by `approximation`. Not null.

- ## Method Details

  - ### asDocIdSetIterator

    public static DocIdSetIterator asDocIdSetIterator(TwoPhaseIterator twoPhaseIterator)
    Return a `DocIdSetIterator` view of the provided `TwoPhaseIterator`.

  - ### unwrap

    public static TwoPhaseIterator unwrap(DocIdSetIterator iterator)
    If the given `DocIdSetIterator` has been created with `asDocIdSetIterator(org.apache.lucene.search.TwoPhaseIterator)`, then this will return the wrapped `TwoPhaseIterator`. Otherwise this returns `null`.

  - ### approximation

    public DocIdSetIterator approximation()
    Return an approximation. The returned `DocIdSetIterator` is a superset of the matching documents, and each match needs to be confirmed with `matches()` in order to know whether it matches or not.

  - ### matches

    public abstract boolean matches() throws IOException
    Return whether the current doc ID that `approximation()` is on matches. This method should only be called when the iterator is positioned -- ie. not when `DocIdSetIterator.docID()` is `-1` or `DocIdSetIterator.NO_MORE_DOCS` -- and at most once.
    Throws:
      `IOException`

  - ### matchCost

    public abstract float matchCost()
    An estimate of the expected cost to determine that a single document `matches()`. This can be called before iterating the documents of `approximation()`. Returns an expected cost in number of simple operations like addition, multiplication, comparing two numbers and indexing an array. The returned value must be positive.

  - ### docIDRunEnd

    public int docIDRunEnd() throws IOException
    Returns the end of the run of consecutive doc IDs that match this `TwoPhaseIterator` and that contains the current doc ID of the approximation, that is: one plus the last doc ID of the run.

    Note: It is illegal to call this method when the approximation is exhausted or not positioned.

    The default implementation returns the current doc ID of the approximation.

    Throws:
      `IOException`

  - ### intoBitSet

    public void intoBitSet(int upTo, FixedBitSet bitSet, int offset) throws IOException
    Load the doc IDs that both belong to the `approximation()` and `match`, and are in `[approximation().docID(), upTo)`, into `bitSet`, the document whose ID is `i` being stored at bit `i - offset`. Upon return the `approximation()` is positioned on the first doc that is `>= upTo`, mirroring `DocIdSetIterator.intoBitSet(int, org.apache.lucene.util.FixedBitSet, int)`.

    The default implementation walks the `approximation()` and confirms each doc with `matches()` — i.e. it is functionally identical to the leap-frog evaluation, just writing into a bit set. Implementations that can confirm matches in bulk — for instance a vectorized scan over a columnar block — should override it; the bit set window is then collected in one shot rather than one doc at a time.

    Throws:
      `IOException`