SortedSetDocValues (Lucene 10.5.0 core API)
Description: declaration: package: org.apache.lucene.index, class: SortedSetDocValues

Package org.apache.lucene.index

# Class SortedSetDocValues

java.lang.Object
org.apache.lucene.search.DocIdSetIterator
org.apache.lucene.index.SortedSetDocValues

Direct Known Subclasses:
  `FilterSortedSetDocValues`, `MultiDocValues.MultiSortedSetDocValues`

public abstract class SortedSetDocValues extends DocIdSetIterator
A multi-valued version of `SortedDocValues`.

Per-Document values in a SortedSetDocValues are deduplicated, dereferenced, and sorted into a dictionary of unique values. A pointer to the dictionary value (ordinal) can be retrieved for each document. Ordinals are dense and in increasing sorted order.

- ## Field Summary

  ### Fields inherited from class org.apache.lucene.search.DocIdSetIterator

  `NO_MORE_DOCS`

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `SortedSetDocValues()`
  Sole constructor.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `abstract boolean`
  `advanceExact(int target)`
  Advance the iterator to exactly `target` and return whether `target` has a value.
  `abstract int`
  `docValueCount()`
  Retrieves the number of unique ords for the current document.
  `abstract long`
  `getValueCount()`
  Returns the number of unique values.
  `TermsEnum`
  `intersect(CompiledAutomaton automaton)`
  Returns a `TermsEnum` over the values, filtered by a `CompiledAutomaton` The enum supports `TermsEnum.ord()`.
  `abstract BytesRef`
  `lookupOrd(long ord)`
  Retrieves the value for the specified ordinal.
  `long`
  `lookupTerm(BytesRef key)`
  If `key` exists, returns its ordinal, else returns `-insertionPoint-1`, like `Arrays.binarySearch`.
  `abstract long`
  `nextOrd()`
  Returns the next ordinal for the current document.
  `TermsEnum`
  `termsEnum()`
  Returns a `TermsEnum` over the values.

  ### Methods inherited from class org.apache.lucene.search.DocIdSetIterator

  `advance, all, cost, docID, docIDRunEnd, empty, intoBitSet, nextDoc, range, slowAdvance`

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

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

- ## Constructor Details

  - ### SortedSetDocValues

    protected SortedSetDocValues()
    Sole constructor. (For invocation by subclass constructors, typically implicit.)

- ## Method Details

  - ### nextOrd

    public abstract long nextOrd() throws IOException
    Returns the next ordinal for the current document. It is illegal to call this method after `advanceExact(int)` returned `false`. It is illegal to call this more than `docValueCount()` times for the currently-positioned doc.
    Returns:
      next ordinal for the document. ordinals are dense, start at 0, then increment by 1 for the next value in sorted order.
    Throws:
      `IOException`

  - ### docValueCount

    public abstract int docValueCount()
    Retrieves the number of unique ords for the current document. This must always be greater than zero. It is illegal to call this method after `advanceExact(int)` returned `false`.

  - ### lookupOrd

    public abstract BytesRef lookupOrd(long ord) throws IOException
    Retrieves the value for the specified ordinal. The returned `BytesRef` may be re-used across calls to lookupOrd so make sure to `copy it` if you want to keep it around.
    Parameters:
      `ord` - ordinal to lookup
    Throws:
      `IOException`
    See Also:
      - `nextOrd()`

  - ### getValueCount

    public abstract long getValueCount()
    Returns the number of unique values.
    Returns:
      number of unique values in this SortedDocValues. This is also equivalent to one plus the maximum ordinal.

  - ### lookupTerm

    public long lookupTerm(BytesRef key) throws IOException
    If `key` exists, returns its ordinal, else returns `-insertionPoint-1`, like `Arrays.binarySearch`.
    Parameters:
      `key` - Key to look up
    Throws:
      `IOException`

  - ### termsEnum

    public TermsEnum termsEnum() throws IOException
    Returns a `TermsEnum` over the values. The enum supports `TermsEnum.ord()` and `TermsEnum.seekExact(long)`.
    Throws:
      `IOException`

  - ### intersect

    public TermsEnum intersect(CompiledAutomaton automaton) throws IOException
    Returns a `TermsEnum` over the values, filtered by a `CompiledAutomaton` The enum supports `TermsEnum.ord()`.
    Throws:
      `IOException`

  - ### advanceExact

    public abstract boolean advanceExact(int target) throws IOException
    Advance the iterator to exactly `target` and return whether `target` has a value. `target` must be greater than or equal to the current `doc ID` and must be a valid doc ID, ie. ≥ 0 and < `maxDoc`. After this method returns, `DocIdSetIterator.docID()` returns `target`.

    Note: it is illegal to call `DocIdSetIterator.intoBitSet(int, org.apache.lucene.util.FixedBitSet, int)` or `DocIdSetIterator.docIDRunEnd()` when this method returns false.

    Throws:
      `IOException`