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)