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

Package org.apache.lucene.util

# Class DocIdSetBuilder

java.lang.Object
org.apache.lucene.util.DocIdSetBuilder

public final class DocIdSetBuilder extends Object
A builder of `DocIdSet`s. At first it uses a sparse structure to gather documents, and then upgrades to a non-sparse bit set once enough hits match.

To add documents, you first need to call `grow(int)` in order to reserve space, and then call `DocIdSetBuilder.BulkAdder.add(int)` on the returned `DocIdSetBuilder.BulkAdder`.

NOTE: This API is for internal purposes only and might change in incompatible ways in the next release.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static interface`
  `DocIdSetBuilder.BulkAdder`
  Utility class to efficiently add many docs in one go.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `DocIdSetBuilder(int maxDoc)`
  Create a builder that can contain doc IDs between `0` and `maxDoc`.
  `DocIdSetBuilder(int maxDoc, PointValues values)`
  Create a `DocIdSetBuilder` instance that is optimized for accumulating docs that match the given `PointValues`.
  `DocIdSetBuilder(int maxDoc, Terms terms)`
  Create a `DocIdSetBuilder` instance that is optimized for accumulating docs that match the given `Terms`.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `add(DocIdSetIterator iter)`
  Add the content of the provided `DocIdSetIterator` to this builder.
  `DocIdSet`
  `build()`
  Build a `DocIdSet` from the accumulated doc IDs.
  `DocIdSetBuilder.BulkAdder`
  `grow(int numDocs)`
  Reserve space and return a `DocIdSetBuilder.BulkAdder` object that can be used to add up to `numDocs` documents.

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

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

- ## Constructor Details

  - ### DocIdSetBuilder

    public DocIdSetBuilder(int maxDoc)
    Create a builder that can contain doc IDs between `0` and `maxDoc`.

  - ### DocIdSetBuilder

    public DocIdSetBuilder(int maxDoc, Terms terms) throws IOException
    Create a `DocIdSetBuilder` instance that is optimized for accumulating docs that match the given `Terms`.
    Throws:
      `IOException`

  - ### DocIdSetBuilder

    public DocIdSetBuilder(int maxDoc, PointValues values) throws IOException
    Create a `DocIdSetBuilder` instance that is optimized for accumulating docs that match the given `PointValues`.
    Throws:
      `IOException`

- ## Method Details

  - ### add

    public void add(DocIdSetIterator iter) throws IOException
    Add the content of the provided `DocIdSetIterator` to this builder. NOTE: if you need to build a `DocIdSet` out of a single `DocIdSetIterator`, you should rather use `RoaringDocIdSet.Builder`.
    Throws:
      `IOException`

  - ### grow

    public DocIdSetBuilder.BulkAdder grow(int numDocs)
    Reserve space and return a `DocIdSetBuilder.BulkAdder` object that can be used to add up to `numDocs` documents.

  - ### build

    public DocIdSet build()
    Build a `DocIdSet` from the accumulated doc IDs.