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

    All Methods Instance Methods Concrete Methods
    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 Detail

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

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