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

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:

- `get(int)` returns `true` if doc is LIVE (bit is NOT set in deletedDocs)
- `deletedDocsIterator()` iterates documents where bit IS set in deletedDocs

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.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static final class`
  `SparseLiveDocs.Builder`
  Builder for creating SparseLiveDocs instances with optional pre-computed deleted count.

  ## 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
  `static SparseLiveDocs.Builder`
  `builder(SparseFixedBitSet deletedDocs, int maxDoc)`
  Creates a builder for constructing SparseLiveDocs instances.
  `int`
  `deletedCount()`
  Returns the number of deleted documents.
  `DocIdSetIterator`
  `deletedDocsIterator()`
  Returns an iterator over deleted document IDs.
  `boolean`
  `get(int index)`
  Returns the value of the bit with the specified `index`.
  `int`
  `length()`
  Returns the number of bits in this set
  `DocIdSetIterator`
  `liveDocsIterator()`
  Returns an iterator over live document IDs.
  `long`
  `ramBytesUsed()`
  Returns the memory usage in bytes.
  `String`
  `toString()`

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

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

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

  `applyMask`

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