org.apache.lucene.queryParser

Class QueryParser

Implemented Interfaces:
QueryParserConstants
Known Direct Subclasses:
AnalyzingQueryParser, MultiFieldQueryParser

public class QueryParser
extends Object
implements QueryParserConstants

This class is generated by JavaCC. The most important method is parse(String). The syntax for query strings is as follows: A Query is a series of clauses. A clause may be prefixed by: A clause may be either: Thus, in BNF, the query grammar is:
   Query  ::= ( Clause )*
   Clause ::= ["+", "-"] [<TERM> ":"] ( <TERM> | "(" Query ")" )
 

Examples of appropriately formatted queries can be found in the query syntax documentation.

In RangeQuerys, QueryParser tries to detect date values, e.g. date:[6/1/2005 TO 6/4/2005] produces a range query that searches for "date" fields between 2005-06-01 and 2005-06-04. Note that the format of the accepted input depends on the locale. By default a date is converted into a search term using the deprecated DateField for compatibility reasons. To use the new DateTools to convert dates, a DateTools.Resolution has to be set.

The date resolution that shall be used for RangeQueries can be set using setDateResolution(DateTools.Resolution) or setDateResolution(String,DateTools.Resolution). The former sets the default date resolution for all fields, whereas the latter can be used to set field specific date resolutions. Field specific date resolutions take, if set, precedence over the default date resolution.

If you use neither DateField nor DateTools in your index, you can create your own query parser that inherits QueryParser and overwrites getRangeQuery(String,String,String,boolean) to use a different method for date conversion.

Note that QueryParser is not thread-safe.

Authors:
Brian Goetz
Peter Halacsy
Tatu Saloranta

Nested Class Summary

static class
QueryParser.Operator
The default operator for parsing queries.

Field Summary

static QueryParser.Operator
AND_OPERATOR
Alternative form of QueryParser.Operator.AND
static QueryParser.Operator
OR_OPERATOR
Alternative form of QueryParser.Operator.OR
Token
jj_nt
boolean
lookingAhead
Token
token
QueryParserTokenManager
token_source

Fields inherited from interface org.apache.lucene.queryParser.QueryParserConstants

AND, Boost, CARAT, COLON, DEFAULT, EOF, FUZZY_SLOP, LPAREN, MINUS, NOT, NUMBER, OR, PLUS, PREFIXTERM, QUOTED, RANGEEX_END, RANGEEX_GOOP, RANGEEX_QUOTED, RANGEEX_START, RANGEEX_TO, RANGEIN_END, RANGEIN_GOOP, RANGEIN_QUOTED, RANGEIN_START, RANGEIN_TO, RPAREN, RangeEx, RangeIn, STAR, TERM, WILDTERM, _ESCAPED_CHAR, _NUM_CHAR, _TERM_CHAR, _TERM_START_CHAR, _WHITESPACE, tokenImage

Constructor Summary

QueryParser(String f, Analyzer a)
Constructs a query parser.
QueryParser(CharStream stream)
QueryParser(QueryParserTokenManager tm)

Method Summary

Query
Clause(String field)
int
Conjunction()
int
Modifiers()
Query
Query(String field)
void
ReInit(CharStream stream)
void
ReInit(QueryParserTokenManager tm)
Query
Term(String field)
protected void
addClause(Vector clauses, int conj, int mods, Query q)
void
disable_tracing()
void
enable_tracing()
static String
escape(String s)
Returns a String where those characters that QueryParser expects to be escaped are escaped by a preceding \.
ParseException
generateParseException()
boolean
getAllowLeadingWildcard()
Analyzer
getAnalyzer()
protected Query
getBooleanQuery(Vector clauses)
Factory method for generating query, given a set of clauses.
protected Query
getBooleanQuery(Vector clauses, boolean disableCoord)
Factory method for generating query, given a set of clauses.
DateTools.Resolution
getDateResolution(String fieldName)
Returns the date resolution that is used by RangeQueries for the given field.
QueryParser.Operator
getDefaultOperator()
Gets implicit operator setting, which will be either AND_OPERATOR or OR_OPERATOR.
String
getField()
protected Query
getFieldQuery(String field, String queryText)
protected Query
getFieldQuery(String field, String queryText, int slop)
Base implementation delegates to getFieldQuery(String,String).
float
getFuzzyMinSim()
Get the minimal similarity for fuzzy queries.
int
getFuzzyPrefixLength()
Get the prefix length for fuzzy queries.
protected Query
getFuzzyQuery(String field, String termStr, float minSimilarity)
Factory method for generating a query (similar to getWildcardQuery(String,String)).
Locale
getLocale()
Returns current locale, allowing access by subclasses.
boolean
getLowercaseExpandedTerms()
Token
getNextToken()
int
getPhraseSlop()
Gets the default slop for phrases.
protected Query
getPrefixQuery(String field, String termStr)
Factory method for generating a query (similar to getWildcardQuery(String,String)).
protected Query
getRangeQuery(String field, String part1, String part2, boolean inclusive)
Token
getToken(int index)
boolean
getUseOldRangeQuery()
protected Query
getWildcardQuery(String field, String termStr)
Factory method for generating a query.
static void
main(String[] args)
Command line tool to test QueryParser, using SimpleAnalyzer.
Query
parse(String query)
Parses a query string, returning a Query.
void
setAllowLeadingWildcard(boolean allowLeadingWildcard)
Set to true to allow * and ? as the first character of a PrefixQuery and WildcardQuery.
void
setDateResolution(String fieldName, DateTools.Resolution dateResolution)
Sets the date resolution used by RangeQueries for a specific field.
void
setDateResolution(DateTools.Resolution dateResolution)
Sets the default date resolution used by RangeQueries for fields for which no specific date resolutions has been set.
void
setDefaultOperator(QueryParser.Operator op)
Sets the boolean operator of the QueryParser.
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
setLowercaseExpandedTerms(boolean lowercaseExpandedTerms)
Whether terms of wildcard, prefix, fuzzy and range queries are to be automatically lower-cased or not.
void
setPhraseSlop(int phraseSlop)
Sets the default slop for phrases.
void
setUseOldRangeQuery(boolean useOldRangeQuery)
By default QueryParser uses new ConstantScoreRangeQuery in preference to RangeQuery for range queries.

Field Details

AND_OPERATOR

public static final QueryParser.Operator AND_OPERATOR
Alternative form of QueryParser.Operator.AND

OR_OPERATOR

public static final QueryParser.Operator OR_OPERATOR
Alternative form of QueryParser.Operator.OR

jj_nt

public Token jj_nt

lookingAhead

public boolean lookingAhead

token

public Token token

token_source

public QueryParserTokenManager token_source

Constructor Details

QueryParser

public QueryParser(String f,
                   Analyzer a)
Constructs a query parser.
Parameters:
f - the default field for query terms.
a - used to find terms in the query text.

QueryParser

public QueryParser(CharStream stream)

QueryParser

public QueryParser(QueryParserTokenManager tm)

Method Details

Clause

public final Query Clause(String field)
            throws ParseException

Conjunction

public final int Conjunction()
            throws ParseException

Modifiers

public final int Modifiers()
            throws ParseException

Query

public final Query Query(String field)
            throws ParseException

ReInit

public void ReInit(CharStream stream)

ReInit

public void ReInit(QueryParserTokenManager tm)

Term

public final Query Term(String field)
            throws ParseException

addClause

protected void addClause(Vector clauses,
                         int conj,
                         int mods,
                         Query q)

disable_tracing

public final void disable_tracing()

enable_tracing

public final void enable_tracing()

escape

public static String escape(String s)
Returns a String where those characters that QueryParser expects to be escaped are escaped by a preceding \.

generateParseException

public ParseException generateParseException()

getAllowLeadingWildcard

public boolean getAllowLeadingWildcard()

getAnalyzer

public Analyzer getAnalyzer()
Returns:
Returns the analyzer.

getBooleanQuery

protected Query getBooleanQuery(Vector clauses)
            throws ParseException
Factory method for generating query, given a set of clauses. By default creates a boolean query composed of clauses passed in. Can be overridden by extending classes, to modify query being returned.
Parameters:
clauses - Vector that contains BooleanClause instances to join.
Returns:
Resulting Query object.
Throws:
ParseException - throw in overridden method to disallow

getBooleanQuery

protected Query getBooleanQuery(Vector clauses,
                                boolean disableCoord)
            throws ParseException
Factory method for generating query, given a set of clauses. By default creates a boolean query composed of clauses passed in. Can be overridden by extending classes, to modify query being returned.
Parameters:
clauses - Vector that contains BooleanClause instances to join.
disableCoord - true if coord scoring should be disabled.
Returns:
Resulting Query object.
Throws:
ParseException - throw in overridden method to disallow

getDateResolution

public DateTools.Resolution getDateResolution(String fieldName)
Returns the date resolution that is used by RangeQueries for the given field. Returns null, if no default or field specific date resolution has been set for the given field.

getDefaultOperator

public QueryParser.Operator getDefaultOperator()
Gets implicit operator setting, which will be either AND_OPERATOR or OR_OPERATOR.

getField

public String getField()
Returns:
Returns the field.

getFieldQuery

protected Query getFieldQuery(String field,
                              String queryText)
            throws ParseException
Throws:
ParseException - throw in overridden method to disallow

getFieldQuery

protected Query getFieldQuery(String field,
                              String queryText,
                              int slop)
            throws ParseException
Base implementation delegates to getFieldQuery(String,String). This method may be overridden, for example, to return a SpanNearQuery instead of a PhraseQuery.
Throws:
ParseException - throw in overridden method to disallow

getFuzzyMinSim

public float getFuzzyMinSim()
Get the minimal similarity for fuzzy queries.

getFuzzyPrefixLength

public int getFuzzyPrefixLength()
Get the prefix length for fuzzy queries.
Returns:
Returns the fuzzyPrefixLength.

getFuzzyQuery

protected Query getFuzzyQuery(String field,
                              String termStr,
                              float minSimilarity)
            throws ParseException
Factory method for generating a query (similar to getWildcardQuery(String,String)). Called when parser parses an input term token that has the fuzzy suffix (~) appended.
Parameters:
field - Name of the field query will use.
termStr - Term token to use for building term for the query
Returns:
Resulting Query built for the term
Throws:
ParseException - throw in overridden method to disallow

getLocale

public Locale getLocale()
Returns current locale, allowing access by subclasses.

getLowercaseExpandedTerms

public boolean getLowercaseExpandedTerms()

getNextToken

public final Token getNextToken()

getPhraseSlop

public int getPhraseSlop()
Gets the default slop for phrases.

getPrefixQuery

protected Query getPrefixQuery(String field,
                               String termStr)
            throws ParseException
Factory method for generating a query (similar to getWildcardQuery(String,String)). Called when parser parses an input term token that uses prefix notation; that is, contains a single '*' wildcard character as its last character. Since this is a special case of generic wildcard term, and such a query can be optimized easily, this usually results in a different query object.

Depending on settings, a prefix term may be lower-cased automatically. It will not go through the default Analyzer, however, since normal Analyzers are unlikely to work properly with wildcard templates.

Can be overridden by extending classes, to provide custom handling for wild card queries, which may be necessary due to missing analyzer calls.

Parameters:
field - Name of the field query will use.
termStr - Term token to use for building term for the query (without trailing '*' character!)
Returns:
Resulting Query built for the term
Throws:
ParseException - throw in overridden method to disallow

getRangeQuery

protected Query getRangeQuery(String field,
                              String part1,
                              String part2,
                              boolean inclusive)
            throws ParseException
Throws:
ParseException - throw in overridden method to disallow

getToken

public final Token getToken(int index)

getUseOldRangeQuery

public boolean getUseOldRangeQuery()

getWildcardQuery

protected Query getWildcardQuery(String field,
                                 String termStr)
            throws ParseException
Factory method for generating a query. Called when parser parses an input term token that contains one or more wildcard characters (? and *), but is not a prefix term token (one that has just a single * character at the end)

Depending on settings, prefix term may be lower-cased automatically. It will not go through the default Analyzer, however, since normal Analyzers are unlikely to work properly with wildcard templates.

Can be overridden by extending classes, to provide custom handling for wildcard queries, which may be necessary due to missing analyzer calls.

Parameters:
field - Name of the field query will use.
termStr - Term token that contains one or more wild card characters (? or *), but is not simple prefix term
Returns:
Resulting Query built for the term
Throws:
ParseException - throw in overridden method to disallow

main

public static void main(String[] args)
            throws Exception
Command line tool to test QueryParser, using SimpleAnalyzer. Usage:
java org.apache.lucene.queryParser.QueryParser <input>

parse

public Query parse(String query)
            throws ParseException
Parses a query string, returning a Query.
Parameters:
query - the query string to be parsed.
Throws:
ParseException - if the parsing fails

setAllowLeadingWildcard

public void setAllowLeadingWildcard(boolean allowLeadingWildcard)
Set to true to allow * and ? as the first character of a PrefixQuery and WildcardQuery. Note that this can produce very slow queries on big indexes. Default: false.

setDateResolution

public void setDateResolution(String fieldName,
                              DateTools.Resolution dateResolution)
Sets the date resolution used by RangeQueries for a specific field.
Parameters:
dateResolution - date resolution to set

setDateResolution

public void setDateResolution(DateTools.Resolution dateResolution)
Sets the default date resolution used by RangeQueries for fields for which no specific date resolutions has been set. Field specific resolutions can be set with setDateResolution(String,DateTools.Resolution).
Parameters:
dateResolution - the default date resolution to set

setDefaultOperator

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

setFuzzyMinSim

public void setFuzzyMinSim(float fuzzyMinSim)
Set the minimum similarity for fuzzy queries. Default is 0.5f.

setFuzzyPrefixLength

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

setLocale

public void setLocale(Locale locale)
Set locale used by date range parsing.

setLowercaseExpandedTerms

public void setLowercaseExpandedTerms(boolean lowercaseExpandedTerms)
Whether terms of wildcard, prefix, fuzzy and range queries are to be automatically lower-cased or not. Default is true.

setPhraseSlop

public void setPhraseSlop(int phraseSlop)
Sets the default slop for phrases. If zero, then exact phrase matches are required. Default value is zero.

setUseOldRangeQuery

public void setUseOldRangeQuery(boolean useOldRangeQuery)
By default QueryParser uses new ConstantScoreRangeQuery in preference to RangeQuery for range queries. This implementation is generally preferable because it a) Runs faster b) Does not have the scarcity of range terms unduly influence score c) avoids any "TooManyBooleanClauses" exception. However, if your application really needs to use the old-fashioned RangeQuery and the above points are not required then set this option to true Default is false.

Copyright © 2000-2007 Apache Software Foundation. All Rights Reserved.