QueryBuilder (Lucene 10.5.0 core API)
Description: declaration: package: org.apache.lucene.util, class: QueryBuilder

Package org.apache.lucene.util

# Class QueryBuilder

java.lang.Object
org.apache.lucene.util.QueryBuilder

public class QueryBuilder extends Object
Creates queries from the `Analyzer` chain.

Example usage:

       QueryBuilder builder = new QueryBuilder(analyzer);
       Query a = builder.createBooleanQuery("body", "just a test");
       Query b = builder.createPhraseQuery("body", "another test");
       Query c = builder.createMinShouldMatchQuery("body", "another test", 0.5f);

This can also be used as a subclass for query parsers to make it easier to interact with the analysis chain. Factory methods such as `newTermQuery` are provided so that the generated queries can be customized.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static final record`
  `QueryBuilder.TermAndBoost`
  Wraps a term and boost

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected Analyzer`
  `analyzer`
  `protected boolean`
  `autoGenerateMultiTermSynonymsPhraseQuery`
  `protected boolean`
  `enableGraphQueries`
  `protected boolean`
  `enablePositionIncrements`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `QueryBuilder(Analyzer analyzer)`
  Creates a new QueryBuilder using the given analyzer.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected void`
  `add(String field, BooleanQuery.Builder q, List<QueryBuilder.TermAndBoost> current, BooleanClause.Occur operator)`
  `protected Query`
  `analyzeBoolean(String field, TokenStream stream)`
  Creates simple boolean query from the cached tokenstream contents
  `protected Query`
  `analyzeGraphBoolean(String field, TokenStream source, BooleanClause.Occur operator)`
  Creates a boolean query from a graph token stream.
  `protected Query`
  `analyzeGraphPhrase(TokenStream source, String field, int phraseSlop)`
  Creates graph phrase query from the tokenstream contents
  `protected Query`
  `analyzeMultiBoolean(String field, TokenStream stream, BooleanClause.Occur operator)`
  Creates complex boolean query from the cached tokenstream contents
  `protected Query`
  `analyzeMultiPhrase(String field, TokenStream stream, int slop)`
  Creates complex phrase query from the cached tokenstream contents
  `protected Query`
  `analyzePhrase(String field, TokenStream stream, int slop)`
  Creates simple phrase query from the cached tokenstream contents
  `protected Query`
  `analyzeTerm(String field, TokenStream stream)`
  Creates simple term query from the cached tokenstream contents
  `Query`
  `createBooleanQuery(String field, String queryText)`
  Creates a boolean query from the query text.
  `Query`
  `createBooleanQuery(String field, String queryText, BooleanClause.Occur operator)`
  Creates a boolean query from the query text.
  `protected Query`
  `createFieldQuery(Analyzer analyzer, BooleanClause.Occur operator, String field, String queryText, boolean quoted, int phraseSlop)`
  Creates a query from the analysis chain.
  `protected Query`
  `createFieldQuery(TokenStream source, BooleanClause.Occur operator, String field, boolean quoted, int phraseSlop)`
  Creates a query from a token stream.
  `Query`
  `createMinShouldMatchQuery(String field, String queryText, float fraction)`
  Creates a minimum-should-match query from the query text.
  `Query`
  `createPhraseQuery(String field, String queryText)`
  Creates a phrase query from the query text.
  `Query`
  `createPhraseQuery(String field, String queryText, int phraseSlop)`
  Creates a phrase query from the query text.
  `Analyzer`
  `getAnalyzer()`
  Returns the analyzer.
  `boolean`
  `getAutoGenerateMultiTermSynonymsPhraseQuery()`
  Returns true if phrase query should be automatically generated for multi terms synonyms.
  `boolean`
  `getEnableGraphQueries()`
  Returns true if graph TokenStream processing is enabled (default).
  `boolean`
  `getEnablePositionIncrements()`
  Returns true if position increments are enabled.
  `protected BooleanQuery.Builder`
  `newBooleanQuery()`
  Builds a new BooleanQuery instance.
  `protected Query`
  `newGraphSynonymQuery(Iterator<Query> queries)`
  Builds a new GraphQuery for multi-terms synonyms.
  `protected MultiPhraseQuery.Builder`
  `newMultiPhraseQueryBuilder()`
  Builds a new MultiPhraseQuery instance.
  `protected Query`
  `newSynonymQuery(String field, QueryBuilder.TermAndBoost[] terms)`
  Builds a new SynonymQuery instance.
  `protected Query`
  `newTermQuery(Term term, float boost)`
  Builds a new TermQuery instance.
  `void`
  `setAnalyzer(Analyzer analyzer)`
  Sets the analyzer used to tokenize text.
  `void`
  `setAutoGenerateMultiTermSynonymsPhraseQuery(boolean enable)`
  Set to `true` if phrase queries should be automatically generated for multi terms synonyms.
  `void`
  `setEnableGraphQueries(boolean v)`
  Enable or disable graph TokenStream processing (enabled by default).
  `void`
  `setEnablePositionIncrements(boolean enable)`
  Set to `true` to enable position increments in result query.

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

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

- ## Field Details

  - ### analyzer

    protected Analyzer analyzer

  - ### enablePositionIncrements

    protected boolean enablePositionIncrements

  - ### enableGraphQueries

    protected boolean enableGraphQueries

  - ### autoGenerateMultiTermSynonymsPhraseQuery

    protected boolean autoGenerateMultiTermSynonymsPhraseQuery

- ## Constructor Details

  - ### QueryBuilder

    public QueryBuilder(Analyzer analyzer)
    Creates a new QueryBuilder using the given analyzer.

- ## Method Details

  - ### createBooleanQuery

    public Query createBooleanQuery(String field, String queryText)
    Creates a boolean query from the query text.

    This is equivalent to `createBooleanQuery(field, queryText, Occur.SHOULD)`

    Parameters:
      `field` - field name
      `queryText` - text to be passed to the analyzer
    Returns:
      `TermQuery` or `BooleanQuery`, based on the analysis of `queryText`

  - ### createBooleanQuery

    public Query createBooleanQuery(String field, String queryText, BooleanClause.Occur operator)
    Creates a boolean query from the query text.
    Parameters:
      `field` - field name
      `queryText` - text to be passed to the analyzer
      `operator` - operator used for clauses between analyzer tokens.
    Returns:
      `TermQuery` or `BooleanQuery`, based on the analysis of `queryText`

  - ### createPhraseQuery

    public Query createPhraseQuery(String field, String queryText)
    Creates a phrase query from the query text.

    This is equivalent to `createPhraseQuery(field, queryText, 0)`

    Parameters:
      `field` - field name
      `queryText` - text to be passed to the analyzer
    Returns:
      `TermQuery`, `BooleanQuery`, `PhraseQuery`, or `MultiPhraseQuery`, based on the analysis of `queryText`

  - ### createPhraseQuery

    public Query createPhraseQuery(String field, String queryText, int phraseSlop)
    Creates a phrase query from the query text.
    Parameters:
      `field` - field name
      `queryText` - text to be passed to the analyzer
      `phraseSlop` - number of other words permitted between words in query phrase
    Returns:
      `TermQuery`, `BooleanQuery`, `PhraseQuery`, or `MultiPhraseQuery`, based on the analysis of `queryText`

  - ### createMinShouldMatchQuery

    public Query createMinShouldMatchQuery(String field, String queryText, float fraction)
    Creates a minimum-should-match query from the query text.
    Parameters:
      `field` - field name
      `queryText` - text to be passed to the analyzer
      `fraction` - of query terms `[0..1]` that should match
    Returns:
      `TermQuery` or `BooleanQuery`, based on the analysis of `queryText`

  - ### getAnalyzer

    public Analyzer getAnalyzer()
    Returns the analyzer.
    See Also:
      - `setAnalyzer(Analyzer)`

  - ### setAnalyzer

    public void setAnalyzer(Analyzer analyzer)
    Sets the analyzer used to tokenize text.

  - ### getEnablePositionIncrements

    public boolean getEnablePositionIncrements()
    Returns true if position increments are enabled.
    See Also:
      - `setEnablePositionIncrements(boolean)`

  - ### setEnablePositionIncrements

    public void setEnablePositionIncrements(boolean enable)
    Set to `true` to enable position increments in result query.

    When set, result phrase and multi-phrase queries will be aware of position increments. Useful when e.g. a StopFilter increases the position increment of the token that follows an omitted token.

    Default: true.

  - ### getAutoGenerateMultiTermSynonymsPhraseQuery

    public boolean getAutoGenerateMultiTermSynonymsPhraseQuery()
    Returns true if phrase query should be automatically generated for multi terms synonyms.
    See Also:
      - `setAutoGenerateMultiTermSynonymsPhraseQuery(boolean)`

  - ### setAutoGenerateMultiTermSynonymsPhraseQuery

    public void setAutoGenerateMultiTermSynonymsPhraseQuery(boolean enable)
    Set to `true` if phrase queries should be automatically generated for multi terms synonyms. Default: false.

  - ### createFieldQuery

    protected Query createFieldQuery(Analyzer analyzer, BooleanClause.Occur operator, String field, String queryText, boolean quoted, int phraseSlop)
    Creates a query from the analysis chain.

    Expert: this is more useful for subclasses such as queryparsers. If using this class directly, just use `createBooleanQuery(String, String)` and `createPhraseQuery(String, String)`. This is a complex method and it is usually not necessary to override it in a subclass; instead, override methods like `newBooleanQuery()`, etc., if possible.

    Parameters:
      `analyzer` - analyzer used for this query
      `operator` - default boolean operator used for this query
      `field` - field to create queries against
      `queryText` - text to be passed to the analysis chain
      `quoted` - true if phrases should be generated when terms occur at more than one position
      `phraseSlop` - slop factor for phrase/multiphrase queries

  - ### setEnableGraphQueries

    public void setEnableGraphQueries(boolean v)
    Enable or disable graph TokenStream processing (enabled by default).
    WARNING: This API is experimental and might change in incompatible ways in the next release.

  - ### getEnableGraphQueries

    public boolean getEnableGraphQueries()
    Returns true if graph TokenStream processing is enabled (default).
    WARNING: This API is experimental and might change in incompatible ways in the next release.

  - ### createFieldQuery

    protected Query createFieldQuery(TokenStream source, BooleanClause.Occur operator, String field, boolean quoted, int phraseSlop)
    Creates a query from a token stream.
    Parameters:
      `source` - the token stream to create the query from
      `operator` - default boolean operator used for this query
      `field` - field to create queries against
      `quoted` - true if phrases should be generated when terms occur at more than one position
      `phraseSlop` - slop factor for phrase/multiphrase queries

  - ### analyzeTerm

    protected Query analyzeTerm(String field, TokenStream stream) throws IOException
    Creates simple term query from the cached tokenstream contents
    Throws:
      `IOException`

  - ### analyzeBoolean

    protected Query analyzeBoolean(String field, TokenStream stream) throws IOException
    Creates simple boolean query from the cached tokenstream contents
    Throws:
      `IOException`

  - ### add

    protected void add(String field, BooleanQuery.Builder q, List<QueryBuilder.TermAndBoost> current, BooleanClause.Occur operator)

  - ### analyzeMultiBoolean

    protected Query analyzeMultiBoolean(String field, TokenStream stream, BooleanClause.Occur operator) throws IOException
    Creates complex boolean query from the cached tokenstream contents
    Throws:
      `IOException`

  - ### analyzePhrase

    protected Query analyzePhrase(String field, TokenStream stream, int slop) throws IOException
    Creates simple phrase query from the cached tokenstream contents
    Throws:
      `IOException`

  - ### analyzeMultiPhrase

    protected Query analyzeMultiPhrase(String field, TokenStream stream, int slop) throws IOException
    Creates complex phrase query from the cached tokenstream contents
    Throws:
      `IOException`

  - ### analyzeGraphBoolean

    protected Query analyzeGraphBoolean(String field, TokenStream source, BooleanClause.Occur operator) throws IOException
    Creates a boolean query from a graph token stream. The articulation points of the graph are visited in order and the queries created at each point are merged in the returned boolean query.
    Throws:
      `IOException`

  - ### analyzeGraphPhrase

    protected Query analyzeGraphPhrase(TokenStream source, String field, int phraseSlop) throws IOException
    Creates graph phrase query from the tokenstream contents
    Throws:
      `IOException`

  - ### newBooleanQuery

    protected BooleanQuery.Builder newBooleanQuery()
    Builds a new BooleanQuery instance.

    This is intended for subclasses that wish to customize the generated queries.

    Returns:
      new BooleanQuery instance

  - ### newSynonymQuery

    protected Query newSynonymQuery(String field, QueryBuilder.TermAndBoost[] terms)
    Builds a new SynonymQuery instance.

    This is intended for subclasses that wish to customize the generated queries.

    Returns:
      new Query instance

  - ### newGraphSynonymQuery

    protected Query newGraphSynonymQuery(Iterator<Query> queries)
    Builds a new GraphQuery for multi-terms synonyms.

    This is intended for subclasses that wish to customize the generated queries.

    Returns:
      new Query instance

  - ### newTermQuery

    protected Query newTermQuery(Term term, float boost)
    Builds a new TermQuery instance.

    This is intended for subclasses that wish to customize the generated queries.

    Parameters:
      `term` - term
    Returns:
      new TermQuery instance

  - ### newMultiPhraseQueryBuilder

    protected MultiPhraseQuery.Builder newMultiPhraseQueryBuilder()
    Builds a new MultiPhraseQuery instance.

    This is intended for subclasses that wish to customize the generated queries.

    Returns:
      new MultiPhraseQuery instance