lucene-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Cassandra Targett (Confluence)" <>
Subject [CONF] Apache Solr Reference Guide > Other Parsers
Date Fri, 27 Sep 2013 21:58:00 GMT
Space: Apache Solr Reference Guide (
Page: Other Parsers (

Change Comment:
note about block join parsers per Yonik's suggestion

Edited by Cassandra Targett:
In addition to the main query parsers discussed earlier, there are several other query parsers
that can be used instead of or in conjunction with the main parsers for specific purposes.
This section details the other parsers, and gives examples for how they might be used.

Many of these parsers are expressed the same way as [solr:Local Parameters in Queries].  

Query parsers discussed in this section:

* [Block Join Query Parsers|#Block Join Query Parsers]
* [Boost Query Parser|#Boost Query Parser]
* [Field Query Parser|#Field Query Parser]
* [Function Query Parser|#Function Query Parser]
* [Function Range Query Parser|#Function Range Query Parser]
* [Join Query Parser|#Join Query Parser]
* [Lucene Query Parser|#Lucene Query Parser]
* [Max Score Query Parser|#Max Score Query Parser]

* [Nested Query Parser|#Nested Query Parser]
* [Old Lucene Query Parser|#Old Lucene Query Parser]
* [Prefix Query Parser|#Prefix Query Parser]
* [Raw Query Parser|#Raw Query Parser]
* [Spatial Filter Query Parser|#Spatial Filter Query Parser]
* [Surround Query Parser|#Surround Query Parser]
* [Switch Query Parser|#Switch Query Parser]
* [Term Query Parser|#Term Query Parser]

h2. Block Join Query Parsers

There are two query parsers that support block joins. These parsers allow indexing and searching
for relational content. Uses include any place where you want to index sub-documents to a
parent document, such as a blog post parent document and comments as child documents. Or products
as parent documents and sizes, colors, or other variations as child documents. In terms of
performance, indexing the relationships between documents may be more efficient than attempting
to do joins only at query time, since the relationships are already stored in the index and
do not need to be computed.

Note that these parsers are new and the described functionality may change in future releases.

To use these parsers, documents must be indexed as child documents. Currently documents can
only be indexed with the relational structure with the [XML update handler|Uploading Data
with Index Handlers#XML Formatted Index Updates]. The XML structure allows {{<doc>}}
elements inside {{<doc>}} elements. You must also include a field that identifies the
parent document as a parent; it can be any field that suits this purpose, and it will be used
with the query parser syntaxes defined below.

For example, here are two documents and their child documents:

  <field name="id">1</field>
  <field name="title">Solr adds block join support</field>
  <field name="content_type">parentDocument</field>
     <field name="id">2</field>   
     <field name="comments">SolrCloud supports it too!</field>
    <field name="id">3</field>
    <field name="title">Lucene and Solr 4.5 is out</field>
    <field name="content_type">parentDocument</field>
     <field name="id">4</field>
     <field name="comments">Lots of new features</field>

In this example, we have indexed the parent documents with the field {{content_type}}, which
has the value "parentDocument". We could have also used a boolean field, such as {{isParent}},
with a value of "true", or any other similar approach.

h3. Block Join Children Query Parser

This parser takes a query that matches some parent documents and returns their children. The
syntax for this parser is: {{q=\{!child of=<allParents>}<someParents>}}. The parameter
{{allParents}} is a filter that matches only parent documents; here you would define the field
and value that you used to identify a document as a parent. The parameter {{someParents}}
identifies a query that will match some or all of the parent documents. The output is the

Using the example documents above, we can construct a query such as {{q=\{!child of="content_type:parentDocument"}title:lucene}}.
We only get one document in response:

<result name="response" numFound="1" start="0">
      <str name="id">12344</str>
      <str name="comments">Lots of new features</str>

h3. Block Join Parent Query Parser

This parser takes a query that matches child documents and returns their parents. The syntax
for this parser is similar: {{q=\{!parent which=<allParents>}<someChildren>}}.
Again the parameter The parameter {{allParents}} is a filter that matches only parent documents;
here you would define the field and value that you used to identify a document as a parent.
The parameter {{someChildren}} is a query that matches some or all of the child documents.
Note that the query for {{someChildren}} should match only child documents or you may get
an exception.

Again using the example documents above, we can construct a query such as {{q=\{!parent which="content_type:parentDocument"}comments:SolrCloud}}.
We get this document in response:

<result name="response" numFound="1" start="0">
      <str name="id">12341</str>
      <arr name="title"><str>Solr adds block join support</str></arr>
      <arr name="content_type"><str>parentDocument</str></arr>

h2. Boost Query Parser

{{BoostQParser}} extends the {{QParserPlugin}} and creates a boosted query from the input
value. The main value is the query to be boosted. Parameter {{b}} is the function query to
use as the boost. The query to be boosted may be of any type.


Creates a query "foo"  which is boosted (scores are multiplied) by the function query {{log(popularity)}}:
{!boost b=log(popularity)}foo

Creates a query "foo" which is boosted by the date boosting function referenced in {{ReciprocalFloatFunction}}:
{!boost b=recip(ms(NOW,mydatefield),3.16e-11,1,1)}foo

h2. Field Query Parser

The {{FieldQParser}} extends the {{QParserPlugin}} and creates a field query from the input
value, applying text analysis and constructing a phrase query if appropriate. The parameter
{{f}} is the field to be queried. 


{!field f=myfield}Foo Bar

This example creates a phrase query with "foo" followed by "bar" (assuming the analyzer for
{{myfield}} is a text field with an analyzer that splits on whitespace and lowercase terms).
This is generally equivalent to the Lucene query parser expression {{myfield:"Foo Bar"}}.

h2. Function Query Parser

The {{FunctionQParser}} extends the {{QParserPlugin}} and creates a function query from the
input value. This is only one way to use function queries in Solr; for another, more integrated,
approach, see the section on [solr:Function Queries].


h2. Function Range Query Parser

The {{FunctionRangeQParser}} extends the {{QParserPlugin}} and creates a range query over
a function. This is also referred to as {{frange}}, as seen in the examples below. 

Other parameters:
|| Parameter || Description ||
| l | The lower bound, optional|
| u | The upper bound, optional |
| incl | Include the lower bound: true/false, optional, default=true |
| incu | Include the upper bound: true/false, optional, default=true |


{!frange l=1000 u=50000}myfield

 fq={!frange l=0 u=2.2} sum(user_ranking,editor_ranking)

Both of these examples are restricting the results by a range of values found in a declared
field or a function query. In the second example, we're doing a sum calculation, and then
defining only values between 0 and 2.2 should be returned to the user.

For more information about range queries over functions, see Yonik Seeley's introductory blog
post [Ranges over Functions in Solr 1.4|],
hosted at

h2. Join Query Parser

{{JoinQParser}} extends the {{QParserPlugin}}. It allows normalizing relationships between
documents with a join operation. This is different from in concept of a join in a relational
database because no information is being truly joined. An appropriate SQL analogy would be
an "inner query". 


Find all products containing the word "ipod", join them against manufacturer docs and return
the list of manufacturers: 

Find all manufacturer docs named "belkin", join them against product docs, and filter the
list to only products with a price less than $12:

For more information about join queries, see the Solr Wiki page on [Joins|].
Erick Erickson has also written a blog post about join performance called [Solr and Joins|],
hosted by

h2. Lucene Query Parser

The {{LuceneQParser}} extends the {{QParserPlugin}} by parsing Solr's variant on the Lucene
QueryParser syntax. This is effectively the same query parser that is used in Lucene. It uses
the operators {{q.op}}, the default operator ("OR" or "AND") and {{df}}, the default field

{!lucene q.op=AND df=text}myfield:foo +bar -baz

For more information about the syntax for the Lucene Query Parser, see the [Lucene javadocs|].

h2. Max Score Query Parser

The {{MaxScoreQParser}} extends the {{LuceneQParser}} but returns the Max score from the clauses.
 It does this by wrapping all {{SHOULD}} clauses in a {{DisjunctionMaxQuery}} with tie=1.0.
Any {{MUST}} or {{PROHIBITED}} clauses are passed through as-is.  Non-boolean queries, e.g.
NumericRange falls-through to the {{LuceneQParser}} parser behavior.

{!maxscore tie=0.01}C OR (D AND E)

h2. Nested Query Parser

The {{NestedParser}} extends the {{QParserPlugin}} and creates a nested query, with the ability
for that query to redefine its type via local parameters. This is useful in specifying defaults
in configuration and letting clients indirectly reference them.

{!query defType=func v=$q1}

If the {{q1}} parameter is price, then the query would be a function query on the price field.
If the {{q1}} parameter is {\!lucene\}inStock:true}} then a term query is created from the
Lucene syntax string that matches documents with {{inStock=true}}. These parameters would
be defined in {{solrconfig.xml}}, in the {{defaults}} section:

<lst name="defaults"
   <str name="q1">{!lucene}inStock:true</str>

For more information about the possibilities of nested queries, see Yonik Seeley's blog post
[Nested Queries in Solr|], hosted by

h2. Old Lucene Query Parser

{{OldLuceneQParser}} extends the {{QParserPlugin}} by parsing Solr's variant of Lucene's QueryParser
syntax, including the deprecated sort specification after the query.

{!lucenePlusSort} myfield:foo +bar -baz;price asc

h2. Prefix Query Parser

{{PrefixQParser}} extends the {{QParserPlugin}} by creating a prefix query from the input
value. Currently no analysis or value transformation is done to create this prefix query.
The parameter is {{f}}, the field. The string after the prefix declaration is treated as a
wildcard query.

{!prefix f=myfield}foo

This would be generally equivalent to the Lucene query parser expression {{myfield:foo\*}}.

h2. Raw Query Parser

{{RawQParser}} extends the {{QParserPlugin}} by creating a term query from the input value
without any text analysis or transformation. This is useful in debugging, or when raw terms
are returned from the terms component (this is not the default). The only parameter is {{f}},
which defines the field to search. 


{!raw f=myfield}Foo Bar

This example constructs the query: {{TermQuery(Term("myfield","Foo Bar"))}}.

For easy filter construction to drill down in faceting, the [TermQParserPlugin|#Term Query
Parser] is recommended. For full analysis on all fields, including text fields, you may want
to use the [FieldQParserPlugin|#Field Query Parser].

h2. Spatial Filter Query Parser

{{SpatialFilterQParser}} extends the {{QParserPlugin}} by creating a spatial Filter based
on the type of spatial point used. The field must implement [SpatialQueryable|].
All units are in Kilometers.

This query parser takes the following parameters:

|| Parameter || Description ||
| sfield | The field on which to filter. Required. |
| pt | The point to use as a reference.  Must match the dimension of the field. Required.
| d | The distance in km. Required. |

The distance measure used currently depends on the FieldType. {{LatLonType}} defaults to using
haversine, {{PointType}} defaults to Euclidean  (2-norm).

This example shows the syntax:

{!geofilt sfield=<location_field> pt=<lat,lon> d=<distance>}

Here are some examples with values configured:
fq={!geofilt sfield=store pt=10.312,-20.556 d=3.5}

fq={!geofilt sfield=store}&pt=10.312,-20&d=3.5


If using {{geofilt}} with {{LatLonType}}, it is capable of producing scores equal to the computed
distance from the point to the field, making it useful as a component of the main query or
a boosting query.

There is more information about spatial searches available in the section [Spatial Search].

h2. Surround Query Parser

{{SurroundQParser}} extends the {{QParserPlugin}}. This provides support for the Surround
query syntax, which provides proximity search functionality. There are two operators: {{w}}
creates an ordered span query and {{n}} creates an unordered one. Both operators take a numeric
value to indicate distance between two terms. The default is 1, and the maximum is 99. Note
that the query string is not analyzed in any way.


{!surround 3w(foo, bar)}

This example would find documents where the terms "foo" and "bar" were no more than 3 terms
away from each other (i.e., no more than 2 terms between them).

This query parser will also accept boolean operators (AND, OR, and NOT, in either upper- or
lowercase), wildcards, quoting for phrase searches, and boosting. The {{w}} and {{n}} operators
can also be expressed in upper- or lowercase.

More information about Surround queries can be found at [].

h2. Switch Query Parser

{{SwitchQParser}} is a {{QParserPlugin}} that acts like a "switch" or "case" statement.

The primary input string is trimmed and then prefixed with {{case.}} for use as a key to lookup
a "switch case" in the parser's local params. If a matching local param is found the resulting
param value will then be parsed as a subquery, and returned as the parse result.

The {{case}} local param can be optionally be specified as a switch case to match missing
(or blank) input strings. The {{default}} local param can optionally be specified as a default
case to use if the input string does not match any other switch case local params. If default
is not specified, then any input which does not match a switch case local param will result
in a syntax error. 

In the examples below, the result of each query is "XXX":

{!switch case.yak=qqq}foo
{!switch case.yak=zzz} bar  // extra whitespace is trimmed
{!switch default=XXX}asdf   // fallback to the default
{!switch case=XXX case.yak=qqq}          // blank input uses 'case'

A practical usage of this {{QParsePlugin}}, is in specifying {{appends}} fq params in the
configuration of a SearchHandler, to provide a fixed set of filter options for clients using
custom parameter names. Using the example configuration below, clients can optionally specify
the custom parameters {{in_stock}} and {{shipping}} to override the default filtering behavior,
but are limited to the specific set of legal values (shipping=any|free, in_stock=yes|no|all).

 <requestHandler name="/select" class="solr.SearchHandler">
   <lst name="defaults">
     <str name="in_stock">yes</str>
     <str name="shipping">any</str>
   <lst name="appends">
     <str name="fq">{!switch case.all='*:*'
     <str name="fq">{!switch case.any='*:*'

h2. Term Query Parser

{{TermQParser}} extends the {{QParserPlugin}} by creating a single term query from the input
value equivalent to {{readableToIndexed()}}. This is useful for generating filter queries
from the external human readable terms returned by the faceting or terms components. The only
parameter is {{f}}, for the field.

{!term f=weight}1.5

For text fields, no analysis is done since raw terms are already returned from the faceting
and terms components. To apply analysis to text fields as well, see the [Field Query Parser|#Field
Query Parser], above.

If no analysis or transformation is desired for any type of field, see the [Raw Query Parser|#Raw
Query Parser], above.


Stop watching space:
Change email notification preferences:


View raw message