LiveDocs (Lucene 10.5.0 core API)
Description: declaration: package: org.apache.lucene.util, interface: LiveDocs

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.

- ## Nested Class Summary

  ## Nested classes/interfaces inherited from interface org.apache.lucene.util.Bits

  `Bits.MatchAllBits, Bits.MatchNoBits`

- ## Field Summary

  ### Fields inherited from interface org.apache.lucene.util.Bits

  `EMPTY_ARRAY`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `int`
  `deletedCount()`
  Returns the number of deleted documents.
  `DocIdSetIterator`
  `deletedDocsIterator()`
  Returns an iterator over deleted document IDs.
  `DocIdSetIterator`
  `liveDocsIterator()`
  Returns an iterator over live document IDs.

  ### Methods inherited from interface org.apache.lucene.util.Bits

  `applyMask, get, length`

- ## 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