StandardQueryParser (Lucene 10.5.0 queryparser API)
Description: declaration: package: org.apache.lucene.queryparser.flexible.standard, class: StandardQueryParser

Package org.apache.lucene.queryparser.flexible.standard

# Class StandardQueryParser

java.lang.Object
org.apache.lucene.queryparser.flexible.core.QueryParserHelper
org.apache.lucene.queryparser.flexible.standard.StandardQueryParser

All Implemented Interfaces:
  `CommonQueryParserConfiguration`

Direct Known Subclasses:
  `PrecedenceQueryParser`

public class StandardQueryParser extends QueryParserHelper implements CommonQueryParserConfiguration
The `StandardQueryParser` is a pre-assembled query parser that supports most features of the classic Lucene query parser, allows dynamic configuration of some of its features (like multi-field expansion or wildcard query restrictions) and adds support for new query types and expressions.

The `StandardSyntaxParser` is an extension of the `QueryParserHelper` with reasonable defaults for syntax tree parsing (`StandardSyntaxParser`, node processor pipeline (`StandardQueryNodeProcessorPipeline` and node tree to `Query` builder (`StandardQueryTreeBuilder`).

Typical usage, including configuration tweaks:

     StandardQueryParser qpHelper = new StandardQueryParser();
     StandardQueryConfigHandler config =  qpHelper.getQueryConfigHandler();
     config.setAllowLeadingWildcard(true);
     config.setAnalyzer(new WhitespaceAnalyzer());
     Query query = qpHelper.parse("apache AND lucene", "defaultField");

## Supported query syntax

Standard query parser borrows most of its syntax from the classic query parser but adds more features and expressions on top of that syntax.

A query consists of clauses, field specifications, grouping and Boolean operators and interval functions. We will discuss them in order.

### Basic clauses

A query must contain one or more clauses. A clause can be a literal term, a phrase, a wildcard expression or other expression that

The following are some examples of simple one-clause queries:

- `test`

  selects documents containing the word test (term clause).

- `"test equipment"`

  phrase search; selects documents containing the phrase test equipment (phrase clause).

- `"test failure"~4`

  proximity search; selects documents containing the words test and failure within 4 words (positions) from each other. The provided "proximity" is technically translated into "edit distance" (maximum number of atomic word-moving operations required to transform the document's phrase into the query phrase).

- `tes*`

  prefix wildcard matching; selects documents containing words starting with tes, such as: test, testing or testable.

- `/.est(s|ing)/`

  documents containing words matching the provided regular expression, such as resting or nests.

- `nest~2`

  fuzzy term matching; documents containing words within 2-edits distance (2 additions, removals or replacements of a letter) from nest, such as test, net or rests.

### Field specifications

Most clauses can be prefixed by a field name and a colon: the clause will then apply to that field only. If the field specification is omitted, the query parser will expand the clause over all fields specified by a call to `setMultiFields(CharSequence[])` or will use the default field provided in the call to `parse(String, String)`.

The following are some examples of field-prefixed clauses:

- `title:test`

  documents containing test in the `title` field.

- `title:(die OR hard)`

  documents containing die or hard in the `title` field.

### Boolean operators and grouping

You can combine clauses using Boolean AND, OR and NOT operators to form more complex expressions, for example:

- `test AND results`

  selects documents containing both the word test and the word results.

- `test OR suite OR results`

  selects documents with at least one of test, suite or results.

- `title:test AND NOT title:complete`

  selects documents containing test and not containing complete in the `title` field.

- `title:test AND (pass* OR fail*)`

  grouping; use parentheses to specify the precedence of terms in a Boolean clause. Query will match documents containing test in the `title` field and a word starting with pass or fail in the default search fields.

- `title:(pass fail skip)`

  shorthand notation; documents containing at least one of pass, fail or skip in the `title` field.

- `title:(+test +"result unknown")`

  shorthand notation; documents containing both pass and result unknown in the `title` field.

Note the Boolean operators must be written in all caps, otherwise they are parsed as regular terms.

### Range operators

To search for ranges of textual or numeric values, use square or curly brackets, for example:

- `name:[Jones TO Smith]`

  inclusive range; selects documents whose `name` field has any value between Jones and Smith, including boundaries.

- `score:{2.5 TO 7.3}`

  exclusive range; selects documents whose `score` field is between 2.5 and 7.3, excluding boundaries.

- `score:{2.5 TO *]`

  one-sided range; selects documents whose `score` field is larger than 2.5.

### Term boosting

Terms, quoted terms, term range expressions and grouped clauses can have a floating-point weight boost applied to them to increase their score relative to other clauses. For example:

- `jones^2 OR smith^0.5`

  prioritize documents with `jones` term over matches on the `smith` term.

- `field:(a OR b NOT c)^2.5 OR field:d`

  apply the boost to a sub-query.

### Special character escaping

Most search terms can be put in double quotes making special-character escaping not necessary. If the search term contains the quote character (or cannot be quoted for some reason), any character can be quoted with a backslash. For example:

- `\:\(quoted\+term\)\:`

  a single search term `(quoted+term):` with escape sequences. An alternative quoted form would be simpler: `":(quoted+term):"` .

### Minimum-should-match constraint for Boolean disjunction groups

A minimum-should-match operator can be applied to a disjunction Boolean query (a query with only "OR"-subclauses) and forces the query to match documents with at least the provided number of these subclauses. For example:

- `(blue crab fish)@2`

  matches all documents with at least two terms from the set [blue, crab, fish] (in any order).

- `((yellow OR blue) crab fish)@2`

  sub-clauses of a Boolean query can themselves be complex queries; here the min-should-match selects documents that match at least two of the provided three sub-clauses.

### Interval function clauses

Interval functions are a powerful tool to express search needs in terms of one or more * contiguous fragments of text and their relationship to one another. All interval clauses start with the `fn:` prefix (possibly prefixed by a field specification). For example:

- `fn:ordered(quick brown fox)`

  matches all documents (in the default field or in multi-field expansion) with at least one ordered sequence of `quick`, `brown` and `fox` terms.

- `title:fn:maxwidth(5 fn:atLeast(2 quick brown fox))`

  matches all documents in the `title` field where at least two of the three terms (`quick`, `brown` and `fox`) occur within five positions of each other.

Please refer to the interval functions package for more information on which functions are available and how they work.

See Also:
  - `StandardQueryParser`
  - `StandardQueryConfigHandler`
  - `StandardSyntaxParser`
  - `StandardQueryNodeProcessorPipeline`
  - `StandardQueryTreeBuilder`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `StandardQueryParser()`
  Constructs a `StandardQueryParser` object.
  `StandardQueryParser(Analyzer analyzer)`
  Constructs a `StandardQueryParser` object and sets an `Analyzer` to it.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `getAllowLeadingWildcard()`
  `Analyzer`
  `getAnalyzer()`
  `DateTools.Resolution`
  `getDateResolution()`
  Returns the default `DateTools.Resolution` used for certain field when no `DateTools.Resolution` is defined for this field.
  `Map<CharSequence,DateTools.Resolution>`
  `getDateResolutionMap()`
  Returns the field to `DateTools.Resolution` map used to normalize each date field.
  `StandardQueryConfigHandler.Operator`
  `getDefaultOperator()`
  Gets implicit operator setting, which will be either `StandardQueryConfigHandler.Operator.AND` or `StandardQueryConfigHandler.Operator.OR`.
  `boolean`
  `getEnablePositionIncrements()`
  `Map<String,Float>`
  `getFieldsBoost()`
  Returns the field to boost map used to set boost for each field.
  `float`
  `getFuzzyMinSim()`
  Get the minimal similarity for fuzzy queries.
  `int`
  `getFuzzyPrefixLength()`
  Get the prefix length for fuzzy queries.
  `Locale`
  `getLocale()`
  Returns current locale, allowing access by subclasses.
  `CharSequence[]`
  `getMultiFields()`
  Returns the fields used to expand the query when the field for a certain query is `null`
  `MultiTermQuery.RewriteMethod`
  `getMultiTermRewriteMethod()`
  `int`
  `getPhraseSlop()`
  Gets the default slop for phrases.
  `Map<String,PointsConfig>`
  `getPointsConfigMap()`
  `TimeZone`
  `getTimeZone()`
  `Query`
  `parse(String query, String defaultField)`
  Overrides `QueryParserHelper.parse(String, String)` so it casts the return object to `Query`.
  `void`
  `setAllowLeadingWildcard(boolean allowLeadingWildcard)`
  Set to `true` to allow leading wildcard characters.
  `void`
  `setAnalyzer(Analyzer analyzer)`
  `void`
  `setDateResolution(DateTools.Resolution dateResolution)`
  Sets the default `DateTools.Resolution` used for certain field when no `DateTools.Resolution` is defined for this field.
  `void`
  `setDateResolutionMap(Map<CharSequence,DateTools.Resolution> dateRes)`
  Sets the `DateTools.Resolution` used for each field
  `void`
  `setDefaultOperator(StandardQueryConfigHandler.Operator operator)`
  Sets the boolean operator of the QueryParser.
  `void`
  `setEnablePositionIncrements(boolean enabled)`
  Set to `true` to enable position increments in result query.
  `void`
  `setFieldsBoost(Map<String,Float> boosts)`
  Sets the boost used for each field.
  `void`
  `setFuzzyMinSim(float fuzzyMinSim)`
  Set the minimum similarity for fuzzy queries.
  `void`
  `setFuzzyPrefixLength(int fuzzyPrefixLength)`
  Set the prefix length for fuzzy queries.
  `void`
  `setLocale(Locale locale)`
  Set locale used by date range parsing.
  `void`
  `setMultiFields(CharSequence[] fields)`
  Set the fields a query should be expanded to when the field is `null`
  `void`
  `setMultiTermRewriteMethod(MultiTermQuery.RewriteMethod method)`
  By default QueryParser uses `MultiTermQuery.CONSTANT_SCORE_BLENDED_REWRITE` when creating a `PrefixQuery`, `WildcardQuery` or `TermRangeQuery`.
  `void`
  `setPhraseSlop(int defaultPhraseSlop)`
  Sets the default slop for phrases.
  `void`
  `setPointsConfigMap(Map<String,PointsConfig> pointsConfigMap)`
  `void`
  `setTimeZone(TimeZone timeZone)`
  `String`
  `toString()`

  ### Methods inherited from class org.apache.lucene.queryparser.flexible.core.QueryParserHelper

  `getQueryBuilder, getQueryConfigHandler, getQueryNodeProcessor, getSyntaxParser, setQueryBuilder, setQueryConfigHandler, setQueryNodeProcessor, setSyntaxParser`

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

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

- ## Constructor Details

  - ### StandardQueryParser

    public StandardQueryParser()
    Constructs a `StandardQueryParser` object.

  - ### StandardQueryParser

    public StandardQueryParser(Analyzer analyzer)
    Constructs a `StandardQueryParser` object and sets an `Analyzer` to it. The same as:

         StandardQueryParser qp = new StandardQueryParser();
         qp.getQueryConfigHandler().setAnalyzer(analyzer);

    Parameters:
      `analyzer` - the analyzer to be used by this query parser helper

- ## Method Details

  - ### toString

    public String toString()
    Overrides:
      `toString` in class `Object`

  - ### parse

    public Query parse(String query, String defaultField) throws QueryNodeException
    Overrides `QueryParserHelper.parse(String, String)` so it casts the return object to `Query`. For more reference about this method, check `QueryParserHelper.parse(String, String)`.
    Overrides:
      `parse` in class `QueryParserHelper`
    Parameters:
      `query` - the query string
      `defaultField` - the default field used by the text parser
    Returns:
      the object built from the query
    Throws:
      `QueryNodeException` - if something wrong happens along the three phases

  - ### getDefaultOperator

    public StandardQueryConfigHandler.Operator getDefaultOperator()
    Gets implicit operator setting, which will be either `StandardQueryConfigHandler.Operator.AND` or `StandardQueryConfigHandler.Operator.OR`.

  - ### setDefaultOperator

    public void setDefaultOperator(StandardQueryConfigHandler.Operator operator)
    Sets the boolean operator of the QueryParser. In default mode ( `StandardQueryConfigHandler.Operator.OR`) terms without any modifiers are considered optional: for example `capital of Hungary` is equal to `capital OR of OR Hungary`.
    In `StandardQueryConfigHandler.Operator.AND` mode terms are considered to be in conjunction: the above mentioned query is parsed as `capital AND of AND Hungary`

  - ### setAllowLeadingWildcard

    public void setAllowLeadingWildcard(boolean allowLeadingWildcard)
    Set to `true` to allow leading wildcard characters.

    When set, `*` or `?` are allowed as the first character of a PrefixQuery and WildcardQuery. Note that this can produce very slow queries on big indexes.

    Default: false.

    Specified by:
      `setAllowLeadingWildcard` in interface `CommonQueryParserConfiguration`

  - ### setEnablePositionIncrements

    public void setEnablePositionIncrements(boolean enabled)
    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: false.

    Specified by:
      `setEnablePositionIncrements` in interface `CommonQueryParserConfiguration`

  - ### getEnablePositionIncrements

    public boolean getEnablePositionIncrements()
    Specified by:
      `getEnablePositionIncrements` in interface `CommonQueryParserConfiguration`
    See Also:
      - `setEnablePositionIncrements(boolean)`

  - ### setMultiTermRewriteMethod

    public void setMultiTermRewriteMethod(MultiTermQuery.RewriteMethod method)
    Description copied from interface: `CommonQueryParserConfiguration`
    By default QueryParser uses `MultiTermQuery.CONSTANT_SCORE_BLENDED_REWRITE` when creating a `PrefixQuery`, `WildcardQuery` or `TermRangeQuery`. This implementation is generally preferable because it a) Runs faster b) Does not have the scarcity of terms unduly influence score c) avoids any `IndexSearcher.TooManyClauses` exception. However, if your application really needs to use the old-fashioned `BooleanQuery` expansion rewriting and the above points are not relevant then use this to change the rewrite method. As another alternative, if you prefer all terms to be rewritten as a filter up-front, you can use `MultiTermQuery.CONSTANT_SCORE_REWRITE`. For more information on the different rewrite methods available, see `MultiTermQuery` documentation.
    Specified by:
      `setMultiTermRewriteMethod` in interface `CommonQueryParserConfiguration`

  - ### getMultiTermRewriteMethod

    public MultiTermQuery.RewriteMethod getMultiTermRewriteMethod()
    Specified by:
      `getMultiTermRewriteMethod` in interface `CommonQueryParserConfiguration`
    See Also:
      - `setMultiTermRewriteMethod(org.apache.lucene.search.MultiTermQuery.RewriteMethod)`

  - ### setMultiFields

    public void setMultiFields(CharSequence[] fields)
    Set the fields a query should be expanded to when the field is `null`
    Parameters:
      `fields` - the fields used to expand the query

  - ### getMultiFields

    public CharSequence[] getMultiFields()
    Returns the fields used to expand the query when the field for a certain query is `null`
    Returns:
      the fields used to expand the query

  - ### setFuzzyPrefixLength

    public void setFuzzyPrefixLength(int fuzzyPrefixLength)
    Set the prefix length for fuzzy queries. Default is 0.
    Specified by:
      `setFuzzyPrefixLength` in interface `CommonQueryParserConfiguration`
    Parameters:
      `fuzzyPrefixLength` - The fuzzyPrefixLength to set.

  - ### setPointsConfigMap

    public void setPointsConfigMap(Map<String,PointsConfig> pointsConfigMap)

  - ### getPointsConfigMap

    public Map<String,PointsConfig> getPointsConfigMap()

  - ### setLocale

    public void setLocale(Locale locale)
    Set locale used by date range parsing.
    Specified by:
      `setLocale` in interface `CommonQueryParserConfiguration`

  - ### getLocale

    public Locale getLocale()
    Returns current locale, allowing access by subclasses.
    Specified by:
      `getLocale` in interface `CommonQueryParserConfiguration`

  - ### setTimeZone

    public void setTimeZone(TimeZone timeZone)
    Specified by:
      `setTimeZone` in interface `CommonQueryParserConfiguration`

  - ### getTimeZone

    public TimeZone getTimeZone()
    Specified by:
      `getTimeZone` in interface `CommonQueryParserConfiguration`

  - ### setPhraseSlop

    public void setPhraseSlop(int defaultPhraseSlop)
    Sets the default slop for phrases. If zero, then exact phrase matches are required. Default value is zero.
    Specified by:
      `setPhraseSlop` in interface `CommonQueryParserConfiguration`

  - ### setAnalyzer

    public void setAnalyzer(Analyzer analyzer)

  - ### getAnalyzer

    public Analyzer getAnalyzer()
    Specified by:
      `getAnalyzer` in interface `CommonQueryParserConfiguration`

  - ### getAllowLeadingWildcard

    public boolean getAllowLeadingWildcard()
    Specified by:
      `getAllowLeadingWildcard` in interface `CommonQueryParserConfiguration`
    See Also:
      - `setAllowLeadingWildcard(boolean)`

  - ### getFuzzyMinSim

    public float getFuzzyMinSim()
    Get the minimal similarity for fuzzy queries.
    Specified by:
      `getFuzzyMinSim` in interface `CommonQueryParserConfiguration`

  - ### getFuzzyPrefixLength

    public int getFuzzyPrefixLength()
    Get the prefix length for fuzzy queries.
    Specified by:
      `getFuzzyPrefixLength` in interface `CommonQueryParserConfiguration`
    Returns:
      Returns the fuzzyPrefixLength.

  - ### getPhraseSlop

    public int getPhraseSlop()
    Gets the default slop for phrases.
    Specified by:
      `getPhraseSlop` in interface `CommonQueryParserConfiguration`

  - ### setFuzzyMinSim

    public void setFuzzyMinSim(float fuzzyMinSim)
    Set the minimum similarity for fuzzy queries. Default is defined on `FuzzyQuery.defaultMaxEdits`.
    Specified by:
      `setFuzzyMinSim` in interface `CommonQueryParserConfiguration`

  - ### setFieldsBoost

    public void setFieldsBoost(Map<String,Float> boosts)
    Sets the boost used for each field.
    Parameters:
      `boosts` - a collection that maps a field to its boost

  - ### getFieldsBoost

    public Map<String,Float> getFieldsBoost()
    Returns the field to boost map used to set boost for each field.
    Returns:
      the field to boost map

  - ### setDateResolution

    public void setDateResolution(DateTools.Resolution dateResolution)
    Sets the default `DateTools.Resolution` used for certain field when no `DateTools.Resolution` is defined for this field.
    Specified by:
      `setDateResolution` in interface `CommonQueryParserConfiguration`
    Parameters:
      `dateResolution` - the default `DateTools.Resolution`

  - ### getDateResolution

    public DateTools.Resolution getDateResolution()
    Returns the default `DateTools.Resolution` used for certain field when no `DateTools.Resolution` is defined for this field.
    Returns:
      the default `DateTools.Resolution`

  - ### getDateResolutionMap

    public Map<CharSequence,DateTools.Resolution> getDateResolutionMap()
    Returns the field to `DateTools.Resolution` map used to normalize each date field.
    Returns:
      the field to `DateTools.Resolution` map

  - ### setDateResolutionMap

    public void setDateResolutionMap(Map<CharSequence,DateTools.Resolution> dateRes)
    Sets the `DateTools.Resolution` used for each field
    Parameters:
      `dateRes` - a collection that maps a field to its `DateTools.Resolution`