org.apache.lucene.search.suggest.analyzing

## Class AnalyzingSuggester

- java.lang.Object
- - org.apache.lucene.search.suggest.Lookup
  - - org.apache.lucene.search.suggest.analyzing.AnalyzingSuggester

Direct Known Subclasses:
  FuzzySuggester

    public class AnalyzingSuggester
    extends Lookup

Suggester that first analyzes the surface form, adds the analyzed form to a weighted FST, and then does the same thing at lookup time. This means lookup is based on the analyzed form while suggestions are still the surface form(s).

This can result in powerful suggester functionality. For example, if you use an analyzer removing stop words, then the partial text "ghost chr..." could see the suggestion "The Ghost of Christmas Past". Note that your `StopFilter` instance must NOT preserve position increments for this example to work, so you should call `setEnablePositionIncrements(false)` on it.

If SynonymFilter is used to map wifi and wireless network to hotspot then the partial text "wirele..." could suggest "wifi router". Token normalization like stemmers, accent removal, etc., would allow suggestions to ignore such variations.

When two matching suggestions have the same weight, they are tie-broken by the analyzed form. If their analyzed form is the same then the order is undefined.

There are some limitations:

- A lookup from a query like "net" in English won't be any different than "net " (ie, user added a trailing space) because analyzers don't reflect when they've seen a token separator and when they haven't.
- If you're using `StopFilter`, and the user will type "fast apple", but so far all they've typed is "fast a", again because the analyzer doesn't convey whether it's seen a token separator after the "a", `StopFilter` will remove that "a" causing far more matches than you'd expect.
- Lookups with the empty string return no results instead of all results.

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
`static int` `EXACT_FIRST` Include this flag in the options parameter to `AnalyzingSuggester(Analyzer,Analyzer,int,int,int)` to always return the exact match first, regardless of score.
`static int` `PRESERVE_SEP` Include this flag in the options parameter to `AnalyzingSuggester(Analyzer,Analyzer,int,int,int)` to preserve token separators when matching.

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

`CHARSEQUENCE_COMPARATOR`

### Constructor Summary

Constructors
Constructor and Description
`AnalyzingSuggester(Analyzer analyzer)` Calls `AnalyzingSuggester(analyzer, analyzer, EXACT_FIRST | PRESERVE_SEP, 256, -1)`
`AnalyzingSuggester(Analyzer indexAnalyzer, Analyzer queryAnalyzer)` Calls `AnalyzingSuggester(indexAnalyzer, queryAnalyzer, EXACT_FIRST | PRESERVE_SEP, 256, -1)`
`AnalyzingSuggester(Analyzer indexAnalyzer, Analyzer queryAnalyzer, int options, int maxSurfaceFormsPerAnalyzedForm, int maxGraphExpansions)` Creates a new suggester.

### Method Summary

Methods
`void` `build(TermFreqIterator iterator)` Builds up a new internal `Lookup` representation based on the given `TermFreqIterator`.
`Object` `get(CharSequence key)` Returns the weight associated with an input string, or null if it does not exist.
`protected List<FSTUtil.Path<PairOutputs.Pair<Long,BytesRef>>>` `getFullPrefixPaths(List<FSTUtil.Path<PairOutputs.Pair<Long,BytesRef>>> prefixPaths, Automaton lookupAutomaton, FST<PairOutputs.Pair<Long,BytesRef>> fst)` Returns all prefix paths to initialize the search.
`boolean` `load(InputStream input)` Discard current lookup data and load it from a previously saved copy.
`List<Lookup.LookupResult>` `lookup(CharSequence key, boolean onlyMorePopular, int num)` Look up a key and return possible completion for this key.
`long` `sizeInBytes()` Returns byte size of the underlying FST.
`boolean` `store(OutputStream output)` Persist the constructed lookup data to a directory.

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

`build`

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

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

### Field Detail

#### EXACT_FIRST

    public static final int EXACT_FIRST

Include this flag in the options parameter to `AnalyzingSuggester(Analyzer,Analyzer,int,int,int)` to always return the exact match first, regardless of score. This has no performance impact but could result in low-quality suggestions.

See Also:
  Constant Field Values

#### PRESERVE_SEP

    public static final int PRESERVE_SEP

Include this flag in the options parameter to `AnalyzingSuggester(Analyzer,Analyzer,int,int,int)` to preserve token separators when matching.

See Also:
  Constant Field Values

### Constructor Detail

#### AnalyzingSuggester

    public AnalyzingSuggester(Analyzer analyzer)

Calls `AnalyzingSuggester(analyzer, analyzer, EXACT_FIRST | PRESERVE_SEP, 256, -1)`

#### AnalyzingSuggester

    public AnalyzingSuggester(Analyzer indexAnalyzer,
                      Analyzer queryAnalyzer)

Calls `AnalyzingSuggester(indexAnalyzer, queryAnalyzer, EXACT_FIRST | PRESERVE_SEP, 256, -1)`

#### AnalyzingSuggester

    public AnalyzingSuggester(Analyzer indexAnalyzer,
                      Analyzer queryAnalyzer,
                      int options,
                      int maxSurfaceFormsPerAnalyzedForm,
                      int maxGraphExpansions)

Creates a new suggester.

Parameters:
  `indexAnalyzer` - Analyzer that will be used for analyzing suggestions while building the index.
  `queryAnalyzer` - Analyzer that will be used for analyzing query text during lookup
  `options` - see `EXACT_FIRST`, `PRESERVE_SEP`
  `maxSurfaceFormsPerAnalyzedForm` - Maximum number of surface forms to keep for a single analyzed form. When there are too many surface forms we discard the lowest weighted ones.
  `maxGraphExpansions` - Maximum number of graph paths to expand from the analyzed form. Set this to -1 for no limit.

### Method Detail

#### sizeInBytes

    public long sizeInBytes()

Returns byte size of the underlying FST.

#### build

    public void build(TermFreqIterator iterator)
               throws IOException

Description copied from class: `Lookup`
Builds up a new internal `Lookup` representation based on the given `TermFreqIterator`. The implementation might re-sort the data internally.

Specified by:
  `build` in class `Lookup`
Throws:
  `IOException`

#### store

    public boolean store(OutputStream 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` - `OutputStream` 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(InputStream 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 `InputStream` to load the lookup data.
Returns:
  true if completed successfully, false if unsuccessful or not supported.
Throws:
  `IOException` - when fatal IO error occurs.

#### lookup

    public List<Lookup.LookupResult> lookup(CharSequence key,
                                   boolean onlyMorePopular,
                                   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.
  `onlyMorePopular` - 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)

#### getFullPrefixPaths

    protected List<FSTUtil.Path<PairOutputs.Pair<Long,BytesRef>>> getFullPrefixPaths(List<FSTUtil.Path<PairOutputs.Pair<Long,BytesRef>>> prefixPaths,
                                                                         Automaton lookupAutomaton,
                                                                         FST<PairOutputs.Pair<Long,BytesRef>> fst)
                                                                              throws IOException

Returns all prefix paths to initialize the search.

Throws:
  `IOException`

#### get

    public Object get(CharSequence key)

Returns the weight associated with an input string, or null if it does not exist.