Package org.apache.lucene.sandbox.search

## Class PhraseWildcardQuery

- java.lang.Object
- - org.apache.lucene.search.Query
  - - org.apache.lucene.sandbox.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
    Modifier and Type | Class | Description
    --- | --- | ---
    `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
    Modifier and Type | Field | Description
    --- | --- | ---
    `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
    Modifier | Constructor | Description
    --- | --- | ---
    `protected` | `PhraseWildcardQuery​(String field, List<PhraseWildcardQuery.PhraseTerm> phraseTerms, int slop, int maxMultiTermExpansions, boolean segmentOptimizationEnabled)` |

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `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​(IndexSearcher indexSearcher)` |
    `protected boolean` | `shouldOptimizeSegments()` |
    `String` | `toString​(String omittedField)` |
    `void` | `visit​(QueryVisitor visitor)` |

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

      `classHash, rewrite, 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​(IndexSearcher indexSearcher)
                        throws IOException

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

    - #### visit

          public void visit​(QueryVisitor visitor)

      Specified by:
        `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)