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

    All Methods Instance Methods Concrete Methods
    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 Detail

    - #### 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 Detail

    - #### 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