Namespace Lucene.Net.Search.Suggest.Fst

Finite-state based autosuggest.

Classes

ExternalRefSorter

Builds and iterates over sequences stored on disk.

FSTCompletion

Finite state automata based implementation of "autocomplete" functionality.

FSTCompletionBuilder

Finite state automata based implementation of "autocomplete" functionality.

Implementation details

The construction step in the object finalizer works as follows:

A set of input terms and their buckets is given.
All terms in the input are prefixed with a synthetic pseudo-character (code) of the weight bucket the term fell into. For example a term abc with a discretized weight equal '1' would become 1abc.
The terms are then sorted by their raw value of UTF-8 character values (including the synthetic bucket code in front).
A finite state automaton (Lucene.Net.Util.Fst.FST) is constructed from the input. The root node has arcs labeled with all possible weights. We cache all these arcs, highest-weight first.

At runtime, in DoLookup(string, int), the automaton is utilized as follows:

For each possible term weight encoded in the automaton (cached arcs from the root above), starting with the highest one, we descend along the path of the input key. If the key is not a prefix of a sequence in the automaton (path ends prematurely), we exit immediately -- no completions.
Otherwise, we have found an internal automaton node that ends the key. The entire subautomaton (all paths) starting from this node form the key's completions. We start the traversal of this subautomaton. Every time we reach a final state (arc), we add a single suggestion to the list of results (the weight of this suggestion is constant and equal to the root path we started from). The tricky part is that because automaton edges are sorted and we scan depth-first, we can terminate the entire procedure as soon as we collect enough suggestions the user requested.
In case the number of suggestions collected in the step above is still insufficient, we proceed to the next (smaller) weight leaving the root node and repeat the same algorithm again.

Runtime behavior and performance characteristic

The algorithm described above is optimized for finding suggestions to short prefixes in a top-weights-first order. This is probably the most common use case: it allows presenting suggestions early and sorts them by the global frequency (and then alphabetically).

If there is an exact match in the automaton, it is returned first on the results list (even with by-weight sorting).

Note that the maximum lookup time for any prefix is the time of descending to the subtree, plus traversal of the subtree up to the number of requested suggestions (because they are already presorted by weight on the root level and alphabetically at any node level).

To order alphabetically only (no ordering by priorities), use identical term weights for all terms. Alphabetical suggestions are returned even if non-constant weights are used, but the algorithm for doing this is suboptimal.

"alphabetically" in any of the documentation above indicates UTF-8 representation order, nothing else.

NOTE: the FST file format is experimental and subject to suddenly change, requiring you to rebuild the FST suggest index.

FSTCompletionLookup

An adapter from Lookup API to FSTCompletion.

This adapter differs from FSTCompletion in that it attempts to discretize any "weights" as passed from in 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.

WFSTCompletionLookup

Suggester based on a weighted FST: it first traverses the prefix, then walks the n shortest paths to retrieve top-ranked suggestions.

NOTE: Input weights must be between 0 and MaxValue, any other values will be rejected.

Note

This API is experimental and might change in incompatible ways in the next release.

Interfaces

IBytesRefSorter

Collects Lucene.Net.Util.BytesRef and then allows one to iterate over their sorted order. Implementations of this interface will be called in a single-threaded scenario.