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`