org.apache.lucene.search

## Class PhraseWildcardQuery

- java.lang.Object
- - org.apache.lucene.search.Query
  - - org.apache.lucene.search.PhraseWildcardQuery

    public class PhraseWildcardQuery
    extends Query

A generalized version of `PhraseQuery`, built with one or more `MultiTermQuery` that provides term expansions for multi-terms (one of the expanded terms must match).

Its main advantage is to control the total number of expansions across all `MultiTermQuery` and across all segments.

Use the `PhraseWildcardQuery.Builder` to build a `PhraseWildcardQuery`.

This query is similar to `MultiPhraseQuery`, but it handles, controls and optimizes the multi-term expansions.

This query is equivalent to building an ordered `SpanNearQuery` with a list of `SpanTermQuery` and `SpanMultiTermQueryWrapper`. But it optimizes the multi-term expansions and the segment accesses. It first resolves the single-terms to early stop if some does not match. Then it expands each multi-term sequentially, stopping immediately if one does not match. It detects the segments that do not match to skip them for the next expansions. This often avoid expanding the other multi-terms on some or even all segments. And finally it controls the total number of expansions.

Immutable.

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

### Nested Class Summary

Nested Classes
`static class` `PhraseWildcardQuery.Builder` Builds a `PhraseWildcardQuery`.
`protected static class` `PhraseWildcardQuery.MultiTerm` Phrase term with expansions.
`protected static class` `PhraseWildcardQuery.PhraseTerm` All `PhraseWildcardQuery.PhraseTerm` are light and immutable.
`protected class` `PhraseWildcardQuery.SegmentTermsSizeComparator` Compares segments based of the number of terms they contain.
`protected static class` `PhraseWildcardQuery.SingleTerm` Phrase term with no expansion.
`static class` `PhraseWildcardQuery.TermBytesTermState` Holds a pair of term bytes - term state.
`protected static class` `PhraseWildcardQuery.TermData` Holds the `TermState` for all the collected `Term`, for a specific phrase term, for all segments.
`protected static class` `PhraseWildcardQuery.TermsData` Holds the `TermState` and `TermStatistics` for all the matched and collected `Term`, for all phrase terms, for all segments.
`static class` `PhraseWildcardQuery.TermStats` Accumulates the doc freq and total term freq.
`protected static class` `PhraseWildcardQuery.TestCounters` Test counters incremented when assertions are enabled.

### Field Summary

Fields
`protected String` `field`
`protected int` `maxMultiTermExpansions`
`protected static Query` `NO_MATCH_QUERY`
`protected List<PhraseWildcardQuery.PhraseTerm>` `phraseTerms`
`protected boolean` `segmentOptimizationEnabled`
`protected int` `slop`

### Constructor Summary

Constructors
`protected` `PhraseWildcardQuery(String field, List<PhraseWildcardQuery.PhraseTerm> phraseTerms, int slop, int maxMultiTermExpansions, boolean segmentOptimizationEnabled)`

### Method Summary

All Methods Instance Methods Concrete Methods
`protected void` `checkTermsHavePositions(Terms terms)`
`protected int` `collectMultiTermData(PhraseWildcardQuery.MultiTerm multiTerm, IndexSearcher searcher, List<LeafReaderContext> segments, int remainingMultiTerms, int maxExpansionsForTerm, PhraseWildcardQuery.TermsData termsData)` Collects the `TermState` and `TermStatistics` for a multi-term with expansion.
`protected List<PhraseWildcardQuery.TermBytesTermState>` `collectMultiTermDataForSegment(PhraseWildcardQuery.MultiTerm multiTerm, LeafReaderContext leafReaderContext, int remainingExpansions, MutableValueBool shouldStopSegmentIteration, Map<BytesRef,PhraseWildcardQuery.TermStats> termStatsMap)` Collects the `TermState` list and `TermStatistics` for a multi-term on a specific index segment.
`protected void` `collectMultiTermStats(IndexSearcher searcher, Map<BytesRef,PhraseWildcardQuery.TermStats> termStatsMap, PhraseWildcardQuery.TermsData termsData, PhraseWildcardQuery.TermData termData)` Collect the term stats across all segments.
`protected int` `collectSingleTermData(PhraseWildcardQuery.SingleTerm singleTerm, IndexSearcher searcher, List<LeafReaderContext> segments, PhraseWildcardQuery.TermsData termsData)` Collects the `TermState` and `TermStatistics` for a single-term without expansion.
`protected PhraseWildcardQuery.TermsData` `createTermsData(int numSegments)` Creates new `PhraseWildcardQuery.TermsData`.
`protected TermsEnum` `createTermsEnum(PhraseWildcardQuery.MultiTerm multiTerm, LeafReaderContext leafReaderContext)` Creates the `TermsEnum` for the given `PhraseWildcardQuery.MultiTerm` and segment.
`protected Map<BytesRef,PhraseWildcardQuery.TermStats>` `createTermStatsMap(PhraseWildcardQuery.MultiTerm multiTerm)` Creates a `PhraseWildcardQuery.TermStats` map for a `PhraseWildcardQuery.MultiTerm`.
`Weight` `createWeight(IndexSearcher searcher, ScoreMode scoreMode, float boost)`
`protected Weight` `earlyStopWeight()`
`boolean` `equals(Object o)`
`String` `getField()`
`int` `hashCode()`
`protected Weight` `noMatchWeight()`
`Query` `rewrite(IndexReader reader)`
`protected boolean` `shouldOptimizeSegments()`
`String` `toString(String omittedField)`
`void` `visit(QueryVisitor visitor)`

### Methods inherited from class org.apache.lucene.search.Query

`classHash, sameClassAs, toString`

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

`clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

### Field Detail

#### NO_MATCH_QUERY

    protected static final Query NO_MATCH_QUERY

#### field

    protected final String field

#### phraseTerms

    protected final List<PhraseWildcardQuery.PhraseTerm> phraseTerms

#### slop

    protected final int slop

#### maxMultiTermExpansions

    protected final int maxMultiTermExpansions

#### segmentOptimizationEnabled

    protected final boolean segmentOptimizationEnabled

### Constructor Detail

#### PhraseWildcardQuery

    protected PhraseWildcardQuery(String field,
                                  List<PhraseWildcardQuery.PhraseTerm> phraseTerms,
                                  int slop,
                                  int maxMultiTermExpansions,
                                  boolean segmentOptimizationEnabled)

### Method Detail

#### getField

    public String getField()

#### rewrite

    public Query rewrite(IndexReader reader)
                  throws IOException

Overrides:
  `rewrite` in class `Query`
Throws:
  `IOException`

#### visit

    public void visit(QueryVisitor visitor)

Overrides:
  `visit` in class `Query`

#### createWeight

    public Weight createWeight(IndexSearcher searcher,
                               ScoreMode scoreMode,
                               float boost)
                        throws IOException

Overrides:
  `createWeight` in class `Query`
Throws:
  `IOException`

#### createTermsData

    protected PhraseWildcardQuery.TermsData createTermsData(int numSegments)

Creates new `PhraseWildcardQuery.TermsData`.

#### earlyStopWeight

    protected Weight earlyStopWeight()

#### noMatchWeight

    protected Weight noMatchWeight()

#### equals

    public boolean equals(Object o)

Specified by:
  `equals` in class `Query`

#### hashCode

    public int hashCode()

Specified by:
  `hashCode` in class `Query`

#### toString

    public final String toString(String omittedField)

Specified by:
  `toString` in class `Query`

#### collectSingleTermData

    protected int collectSingleTermData(PhraseWildcardQuery.SingleTerm singleTerm,
                                        IndexSearcher searcher,
                                        List<LeafReaderContext> segments,
                                        PhraseWildcardQuery.TermsData termsData)
                                 throws IOException

Collects the `TermState` and `TermStatistics` for a single-term without expansion.

Parameters:
  `termsData` - receives the collected data.
Throws:
  `IOException`

#### collectMultiTermData

    protected int collectMultiTermData(PhraseWildcardQuery.MultiTerm multiTerm,
                                       IndexSearcher searcher,
                                       List<LeafReaderContext> segments,
                                       int remainingMultiTerms,
                                       int maxExpansionsForTerm,
                                       PhraseWildcardQuery.TermsData termsData)
                                throws IOException

Collects the `TermState` and `TermStatistics` for a multi-term with expansion.

Parameters:
  `remainingMultiTerms` - the number of remaining multi-terms to process, including the current one, excluding the multi-terms already processed.
  `termsData` - receives the collected data.
Throws:
  `IOException`

#### shouldOptimizeSegments

    protected boolean shouldOptimizeSegments()

#### createTermStatsMap

    protected Map<BytesRef,PhraseWildcardQuery.TermStats> createTermStatsMap(PhraseWildcardQuery.MultiTerm multiTerm)

Creates a `PhraseWildcardQuery.TermStats` map for a `PhraseWildcardQuery.MultiTerm`.

#### collectMultiTermDataForSegment

    protected List<PhraseWildcardQuery.TermBytesTermState> collectMultiTermDataForSegment(PhraseWildcardQuery.MultiTerm multiTerm,
                                                                                          LeafReaderContext leafReaderContext,
                                                                                          int remainingExpansions,
                                                                                          MutableValueBool shouldStopSegmentIteration,
                                                                                          Map<BytesRef,PhraseWildcardQuery.TermStats> termStatsMap)
                                                                                   throws IOException

Collects the `TermState` list and `TermStatistics` for a multi-term on a specific index segment.

Parameters:
  `remainingExpansions` - the number of remaining expansions allowed for the segment.
  `shouldStopSegmentIteration` - to be set to true to stop the segment iteration calling this method repeatedly.
  `termStatsMap` - receives the collected `PhraseWildcardQuery.TermStats` across all segments.
Throws:
  `IOException`

#### createTermsEnum

    protected TermsEnum createTermsEnum(PhraseWildcardQuery.MultiTerm multiTerm,
                                        LeafReaderContext leafReaderContext)
                                 throws IOException

Creates the `TermsEnum` for the given `PhraseWildcardQuery.MultiTerm` and segment.

Returns:
  null if there is no term for this query field in the segment.
Throws:
  `IOException`

#### collectMultiTermStats

    protected void collectMultiTermStats(IndexSearcher searcher,
                                         Map<BytesRef,PhraseWildcardQuery.TermStats> termStatsMap,
                                         PhraseWildcardQuery.TermsData termsData,
                                         PhraseWildcardQuery.TermData termData)
                                  throws IOException

Collect the term stats across all segments.

Parameters:
  `termStatsMap` - input map of already collected `PhraseWildcardQuery.TermStats`.
  `termsData` - receives the `TermStatistics` computed for all `PhraseWildcardQuery.TermStats`.
  `termData` - receives all the collected `Term`.
Throws:
  `IOException`

#### checkTermsHavePositions

    protected void checkTermsHavePositions(Terms terms)