Package org.apache.lucene.util

Class SparseLiveDocs

java.lang.Object
org.apache.lucene.util.SparseLiveDocs
All Implemented Interfaces:
Bits, LiveDocs
public final class SparseLiveDocs extends Object implements LiveDocs
LiveDocs implementation optimized for sparse deletions.

This implementation stores DELETED documents using SparseFixedBitSet, which provides:

  • O(1) random access via get(int)
  • O(deletedDocs) iteration via deletedDocsIterator()
  • Memory usage proportional to number of deleted documents, not total documents

This is most efficient when deletions are sparse. For denser deletions, DenseLiveDocs should be used instead.

Inverted semantics: Unlike typical live docs that store which documents are live, this stores which documents are DELETED. Therefore:

Immutability: This class is immutable once constructed. Instances are typically created using the SparseLiveDocs.Builder via builder(SparseFixedBitSet, int).

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

  • Method Details

    • builder

      public static SparseLiveDocs.Builder builder(SparseFixedBitSet deletedDocs, int maxDoc)
      Creates a builder for constructing SparseLiveDocs instances.
      Parameters:
      deletedDocs - bit set where set bits represent DELETED documents
      maxDoc - the maximum document ID (exclusive)
      Returns:
      a new builder instance

    • get

      public boolean get(int index)
      Description copied from interface: Bits
      Returns the value of the bit with the specified index.
      Specified by:
      get in interface Bits
      Parameters:
      index - index, should be non-negative and < Bits.length(). The result of passing negative or out of bounds values is undefined by this interface, just don't do it!
      Returns:
      true if the bit is set, false otherwise.

    • length

      public int length()
      Description copied from interface: Bits
      Returns the number of bits in this set
      Specified by:
      length in interface Bits

    • liveDocsIterator

      public DocIdSetIterator liveDocsIterator()
      Description copied from interface: LiveDocs
      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.

      Specified by:
      liveDocsIterator in interface LiveDocs
      Returns:
      an iterator over live document IDs

    • deletedDocsIterator

      public DocIdSetIterator deletedDocsIterator()
      Description copied from interface: LiveDocs
      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.

      Specified by:
      deletedDocsIterator in interface LiveDocs
      Returns:
      an iterator over deleted document IDs, or an empty iterator if no documents are deleted

    • deletedCount

      public int deletedCount()
      Description copied from interface: LiveDocs
      Returns the number of deleted documents.

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

      Specified by:
      deletedCount in interface LiveDocs
      Returns:
      the number of deleted documents in this segment

    • ramBytesUsed

      public long ramBytesUsed()
      Returns the memory usage in bytes.
      Returns:
      estimated memory usage in bytes

    • toString

      public String toString()
      Overrides:
      toString in class Object