Package org.apache.lucene.util

Interface LiveDocs

All Superinterfaces:
Bits
All Known Implementing Classes:
DenseLiveDocs, SparseLiveDocs
public interface LiveDocs extends Bits
Extension of Bits that provides efficient iteration over deleted documents.

This interface enables efficient sequential access to deleted documents, which is beneficial when deletions are sparse (typically for low deletion rates). For sparse deletions, iterating deleted documents directly in O(deletedDocs) time is much more efficient than scanning all documents in O(maxDoc) time.

Implementations should provide optimal iteration strategies based on deletion density:

  • Sparse deletions: Use SparseFixedBitSet to store deleted docs, enabling O(deletedDocs) iteration
  • Dense deletions: Use FixedBitSet to store live docs, maintaining current behavior
WARNING: This API is experimental and might change in incompatible ways in the next release.

  • Method Details

    • liveDocsIterator

      DocIdSetIterator liveDocsIterator()
      Returns an iterator over live document IDs.

      The returned iterator provides sequential access to all live documents in ascending order. The iteration complexity depends on the implementation:

      • For sparse deletions: O(maxDoc) - may need to scan all documents
      • For dense deletions: O(liveDocs) - only visits live documents

      Callers can use DocIdSetIterator.cost() to determine the expected number of live documents.

      Returns:
      an iterator over live document IDs

    • deletedDocsIterator

      DocIdSetIterator deletedDocsIterator()
      Returns an iterator over deleted document IDs.

      The returned iterator provides sequential access to all deleted documents in ascending order. The iteration complexity depends on the implementation:

      • For sparse deletions: O(deletedDocs) - only visits deleted documents
      • For dense deletions: O(maxDoc) - may need to scan all documents

      Callers can use DocIdSetIterator.cost() to determine if sparse iteration would be beneficial for their use case.

      Returns:
      an iterator over deleted document IDs, or an empty iterator if no documents are deleted

    • deletedCount

      int deletedCount()
      Returns the number of deleted documents.

      This can be used to determine deletion density and choose appropriate algorithms.

      Returns:
      the number of deleted documents in this segment