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

Package org.apache.lucene.index

# Class OrdinalMap

java.lang.Object
org.apache.lucene.index.OrdinalMap

All Implemented Interfaces:
  `Accountable`

public class OrdinalMap extends Object implements Accountable
Maps per-segment ordinals to/from global ordinal space, using a compact packed-ints representation.

NOTE: this is a costly operation, as it must merge sort all terms, and may require non-trivial RAM once done. It's better to operate in segment-private ordinal space instead when possible.

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

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `final IndexReader.CacheKey`
  `owner`
  Cache key of whoever asked for this awful thing

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

  `NULL_ACCOUNTABLE`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static OrdinalMap`
  `build(IndexReader.CacheKey owner, SortedDocValues[] values, float acceptableOverheadRatio)`
  Create an ordinal map that uses the number of unique values of each `SortedDocValues` instance as a weight.
  `static OrdinalMap`
  `build(IndexReader.CacheKey owner, SortedSetDocValues[] values, float acceptableOverheadRatio)`
  Create an ordinal map that uses the number of unique values of each `SortedSetDocValues` instance as a weight.
  `static OrdinalMap`
  `build(IndexReader.CacheKey owner, TermsEnum[] subs, long[] weights, float acceptableOverheadRatio)`
  Creates an ordinal map that allows mapping ords to/from a merged space from `subs`.
  `Collection<Accountable>`
  `getChildResources()`
  Returns nested resources of this class.
  `int`
  `getFirstSegmentNumber(long globalOrd)`
  Given a global ordinal, returns the index of the first segment that contains this term.
  `long`
  `getFirstSegmentOrd(long globalOrd)`
  Given global ordinal, returns the ordinal of the first segment which contains this ordinal (the corresponding to the segment return `getFirstSegmentNumber(long)`).
  `LongValues`
  `getGlobalOrds(int segmentIndex)`
  Given a segment number, return a `LongValues` instance that maps segment ordinals to global ordinals.
  `long`
  `getValueCount()`
  Returns the total number of unique terms in global ord space.
  `long`
  `ramBytesUsed()`
  Returns an estimate of the JVM heap memory used by this object in bytes.

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

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

- ## Field Details

  - ### owner

    public final IndexReader.CacheKey owner
    Cache key of whoever asked for this awful thing

- ## Method Details

  - ### build

    public static OrdinalMap build(IndexReader.CacheKey owner, SortedDocValues[] values, float acceptableOverheadRatio) throws IOException
    Create an ordinal map that uses the number of unique values of each `SortedDocValues` instance as a weight.
    Throws:
      `IOException`
    See Also:
      - `build(IndexReader.CacheKey, TermsEnum[], long[], float)`

  - ### build

    public static OrdinalMap build(IndexReader.CacheKey owner, SortedSetDocValues[] values, float acceptableOverheadRatio) throws IOException
    Create an ordinal map that uses the number of unique values of each `SortedSetDocValues` instance as a weight.
    Throws:
      `IOException`
    See Also:
      - `build(IndexReader.CacheKey, TermsEnum[], long[], float)`

  - ### build

    public static OrdinalMap build(IndexReader.CacheKey owner, TermsEnum[] subs, long[] weights, float acceptableOverheadRatio) throws IOException
    Creates an ordinal map that allows mapping ords to/from a merged space from `subs`.
    Parameters:
      `owner` - a cache key
      `subs` - TermsEnums that support `TermsEnum.ord()`. They need not be dense (e.g. can be FilteredTermsEnums}.
      `weights` - a weight for each sub. This is ideally correlated with the number of unique terms that each sub introduces compared to the other subs
    Throws:
      `IOException` - if an I/O error occurred.

  - ### getGlobalOrds

    public LongValues getGlobalOrds(int segmentIndex)
    Given a segment number, return a `LongValues` instance that maps segment ordinals to global ordinals.

  - ### getFirstSegmentOrd

    public long getFirstSegmentOrd(long globalOrd)
    Given global ordinal, returns the ordinal of the first segment which contains this ordinal (the corresponding to the segment return `getFirstSegmentNumber(long)`).

  - ### getFirstSegmentNumber

    public int getFirstSegmentNumber(long globalOrd)
    Given a global ordinal, returns the index of the first segment that contains this term.

  - ### getValueCount

    public long getValueCount()
    Returns the total number of unique terms in global ord space.

  - ### ramBytesUsed

    public long ramBytesUsed()
    Description copied from interface: `Accountable`
    Returns an estimate of the JVM heap memory used by this object in bytes. The method name uses "ram" for historical reasons; only JVM heap memory should be reported. Off-heap resources such as memory-mapped files or native direct buffers should not be included. Negative values are illegal.
    Specified by:
      `ramBytesUsed` in interface `Accountable`

  - ### getChildResources

    public Collection<Accountable> getChildResources()
    Description copied from interface: `Accountable`
    Returns nested resources of this class. The result should be a point-in-time snapshot (to avoid race conditions).
    Specified by:
      `getChildResources` in interface `Accountable`
    See Also:
      - `Accountables`