FSTCompletionLookup (Lucene 10.5.1 suggest API)
Description: declaration: package: org.apache.lucene.search.suggest.fst, class: FSTCompletionLookup

Package org.apache.lucene.search.suggest.fst

# Class FSTCompletionLookup

java.lang.Object
org.apache.lucene.search.suggest.Lookup
org.apache.lucene.search.suggest.fst.FSTCompletionLookup

All Implemented Interfaces:
  `Accountable`

public class FSTCompletionLookup extends Lookup
An adapter from `Lookup` API to `FSTCompletion`.

This adapter differs from `FSTCompletion` in that it attempts to discretize any "weights" as passed from in `InputIterator.weight()` to match the number of buckets. For the rationale for bucketing, see `FSTCompletion`.

Note:Discretization requires an additional sorting pass.

The range of weights for bucketing/ discretization is determined by sorting the input by weight and then dividing into equal ranges. Then, scores within each range are assigned to that bucket.

Note that this means that even large differences in weights may be lost during automaton construction, but the overall distinction between "classes" of weights will be preserved regardless of the distribution of weights.

For fine-grained control over which weights are assigned to which buckets, use `FSTCompletion` directly or `TSTLookup`, for example.

See Also:
  - `FSTCompletion`
WARNING: This API is experimental and might change in incompatible ways in the next release.

- ## Nested Class Summary

  ## Nested classes/interfaces inherited from class org.apache.lucene.search.suggest.Lookup

  `Lookup.LookupPriorityQueue, Lookup.LookupResult`

- ## Field Summary

  ### Fields inherited from class org.apache.lucene.search.suggest.Lookup

  `CHARSEQUENCE_COMPARATOR`

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

  `NULL_ACCOUNTABLE`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `FSTCompletionLookup()`
  This constructor should only be used to read a previously saved suggester.
  `FSTCompletionLookup(Directory tempDir, String tempFileNamePrefix)`
  This constructor prepares for creating a suggested FST using the `build(InputIterator)` method.
  `FSTCompletionLookup(Directory tempDir, String tempFileNamePrefix, int buckets, boolean exactMatchFirst)`
  This constructor prepares for creating a suggested FST using the `build(InputIterator)` method.
  `FSTCompletionLookup(Directory tempDir, String tempFileNamePrefix, FSTCompletion completion, boolean exactMatchFirst)`
  This constructor takes a pre-built automaton.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `build(InputIterator iterator)`
  Builds up a new internal `Lookup` representation based on the given `InputIterator`.
  `Object`
  `get(CharSequence key)`
  Returns the bucket (weight) as a Long for the provided key if it exists, otherwise null if it does not.
  `Collection<Accountable>`
  `getChildResources()`
  `long`
  `getCount()`
  Get the number of entries the lookup was built with
  `boolean`
  `load(DataInput input)`
  Discard current lookup data and load it from a previously saved copy.
  `List<Lookup.LookupResult>`
  `lookup(CharSequence key, Set<BytesRef> contexts, boolean higherWeightsFirst, int num)`
  Look up a key and return possible completion for this key.
  `long`
  `ramBytesUsed()`
  `boolean`
  `store(DataOutput output)`
  Persist the constructed lookup data to a directory.

  ### Methods inherited from class org.apache.lucene.search.suggest.Lookup

  `build, load, lookup, lookup, store`

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

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

- ## Constructor Details

  - ### FSTCompletionLookup

    public FSTCompletionLookup()
    This constructor should only be used to read a previously saved suggester.

  - ### FSTCompletionLookup

    public FSTCompletionLookup(Directory tempDir, String tempFileNamePrefix)
    This constructor prepares for creating a suggested FST using the `build(InputIterator)` method. The number of weight discretization buckets is set to `FSTCompletion.DEFAULT_BUCKETS` and exact matches are promoted to the top of the suggestions list.

  - ### FSTCompletionLookup

    public FSTCompletionLookup(Directory tempDir, String tempFileNamePrefix, int buckets, boolean exactMatchFirst)
    This constructor prepares for creating a suggested FST using the `build(InputIterator)` method.
    Parameters:
      `buckets` - The number of weight discretization buckets (see `FSTCompletion` for details).
      `exactMatchFirst` - If `true` exact matches are promoted to the top of the suggestions list. Otherwise they appear in the order of discretized weight and alphabetical within the bucket.

  - ### FSTCompletionLookup

    public FSTCompletionLookup(Directory tempDir, String tempFileNamePrefix, FSTCompletion completion, boolean exactMatchFirst)
    This constructor takes a pre-built automaton.
    Parameters:
      `completion` - An instance of `FSTCompletion`.
      `exactMatchFirst` - If `true` exact matches are promoted to the top of the suggestions list. Otherwise they appear in the order of discretized weight and alphabetical within the bucket.

- ## Method Details

  - ### build

    public void build(InputIterator iterator) throws IOException
    Description copied from class: `Lookup`
    Builds up a new internal `Lookup` representation based on the given `InputIterator`. The implementation might re-sort the data internally.
    Specified by:
      `build` in class `Lookup`
    Throws:
      `IOException`

  - ### lookup

    public List<Lookup.LookupResult> lookup(CharSequence key, Set<BytesRef> contexts, boolean higherWeightsFirst, int num)
    Description copied from class: `Lookup`
    Look up a key and return possible completion for this key.
    Specified by:
      `lookup` in class `Lookup`
    Parameters:
      `key` - lookup key. Depending on the implementation this may be a prefix, misspelling, or even infix.
      `contexts` - contexts to filter the lookup by, or null if all contexts are allowed; if the suggestion contains any of the contexts, it's a match
      `higherWeightsFirst` - return only more popular results
      `num` - maximum number of results to return
    Returns:
      a list of possible completions, with their relative weight (e.g. popularity)

  - ### get

    public Object get(CharSequence key)
    Returns the bucket (weight) as a Long for the provided key if it exists, otherwise null if it does not.

  - ### store

    public boolean store(DataOutput output) throws IOException
    Description copied from class: `Lookup`
    Persist the constructed lookup data to a directory. Optional operation.
    Specified by:
      `store` in class `Lookup`
    Parameters:
      `output` - `DataOutput` to write the data to.
    Returns:
      true if successful, false if unsuccessful or not supported.
    Throws:
      `IOException` - when fatal IO error occurs.

  - ### load

    public boolean load(DataInput input) throws IOException
    Description copied from class: `Lookup`
    Discard current lookup data and load it from a previously saved copy. Optional operation.
    Specified by:
      `load` in class `Lookup`
    Parameters:
      `input` - the `DataInput` to load the lookup data.
    Returns:
      true if completed successfully, false if unsuccessful or not supported.
    Throws:
      `IOException` - when fatal IO error occurs.

  - ### ramBytesUsed

    public long ramBytesUsed()

  - ### getChildResources

    public Collection<Accountable> getChildResources()

  - ### getCount

    public long getCount()
    Description copied from class: `Lookup`
    Get the number of entries the lookup was built with
    Specified by:
      `getCount` in class `Lookup`
    Returns:
      total number of suggester entries