Package org.apache.lucene.facet.taxonomy

## Class TaxonomyFacetLabels.FacetLabelReader

- java.lang.Object
- - org.apache.lucene.facet.taxonomy.TaxonomyFacetLabels.FacetLabelReader

- Enclosing class:
    TaxonomyFacetLabels

      public class TaxonomyFacetLabels.FacetLabelReader
      extends Object

  Utility class to retrieve facet labels for multiple documents.
  WARNING: This API is experimental and might change in incompatible ways in the next release.

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `FacetLabelReader​(OrdinalsReader ordsReader, LeafReaderContext readerContext)` | Deprecated. Custom binary encodings for taxonomy ordinals are no longer supported starting with Lucene 9
    `FacetLabelReader​(SortedNumericDocValues ordinalValues)` | Construct from a specified `SortedNumericDocValues` field; useful for reading the default encoding.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `FacetLabel` | `nextFacetLabel​(int docId)` | Retrieves the next `FacetLabel` for the specified `docId`, or `null` if there are no more.
    `FacetLabel` | `nextFacetLabel​(int docId, String facetDimension)` | Retrieves the next `FacetLabel` for the specified `docId` under the requested `facetDimension`, or `null` if there are no more.

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

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

- - ### Constructor Detail

    - #### FacetLabelReader

          public FacetLabelReader​(SortedNumericDocValues ordinalValues)

      Construct from a specified `SortedNumericDocValues` field; useful for reading the default encoding.

    - #### FacetLabelReader

          @Deprecated
          public FacetLabelReader​(OrdinalsReader ordsReader,
                                  LeafReaderContext readerContext)
                           throws IOException

      Deprecated.
      Custom binary encodings for taxonomy ordinals are no longer supported starting with Lucene 9
      Construct using a custom `OrdinalsReader`; useful if using a custom binary format.

      Note: If using the default encoding, you can use `FacetLabelReader(SortedNumericDocValues)` directly

      Throws:
        `IOException`

  - ### Method Detail

    - #### nextFacetLabel

          public FacetLabel nextFacetLabel​(int docId)
                                    throws IOException

      Retrieves the next `FacetLabel` for the specified `docId`, or `null` if there are no more. This method has state: if the provided `docId` is the same as the previous invocation, it returns the next `FacetLabel` for that document. Otherwise, it advances to the new `docId` and provides the first `FacetLabel` for that document, or `null` if that document has no indexed facets. Each new `docId` must be in strictly monotonic (increasing) order.

      NOTE: The returned FacetLabels may not be in the same order in which they were indexed

      Parameters:
        `docId` - input docId provided in monotonic (non-decreasing) order
      Returns:
        the first or next `FacetLabel`, or `null` if there are no more
      Throws:
        `IOException` - when a low-level IO issue occurs
        `IllegalArgumentException` - if docId provided is less than docId supplied in an earlier invocation

    - #### nextFacetLabel

          public FacetLabel nextFacetLabel​(int docId,
                                           String facetDimension)
                                    throws IOException

      Retrieves the next `FacetLabel` for the specified `docId` under the requested `facetDimension`, or `null` if there are no more. This method has state: if the provided `docId` is the same as the previous invocation, it returns the next `FacetLabel` for that document. Otherwise, it advances to the new `docId` and provides the first `FacetLabel` for that document, or `null` if that document has no indexed facets. Each new `docId` must be in strictly monotonic (increasing) order.

      NOTE: This method loads the `int[] parents` array from the taxonomy index. The returned FacetLabels may not be in the same order in which they were indexed.

      Parameters:
        `docId` - input docId provided in non-decreasing order
      Returns:
        the first or next `FacetLabel`, or `null` if there are no more
      Throws:
        `IOException` - if `TaxonomyReader` has problems getting path for an ordinal
        `IllegalArgumentException` - if docId provided is less than docId supplied in an earlier invocation
        `IllegalArgumentException` - if facetDimension is null