PhraseWildcardQuery (Lucene 10.5.0 sandbox API)
Description: declaration: package: org.apache.lucene.sandbox.search, class: PhraseWildcardQuery

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 final String`
  `field`
  `protected final int`
  `maxMultiTermExpansions`
  `protected static final Query`
  `NO_MATCH_QUERY`
  `protected final List<PhraseWildcardQuery.PhraseTerm>`
  `phraseTerms`
  `protected final boolean`
  `segmentOptimizationEnabled`
  `protected final int`
  `slop`

- ## Constructor Summary

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

- ## Method Summary

  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()`
  `final 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 Details

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

  - ### PhraseWildcardQuery

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

- ## Method Details

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