Several query parsers share supported query parameters.
The following sections describe Solr’s common query parameters, which are supported by the Search RequestHandlers.
defType Parameter
The defType parameter selects the query parser that Solr should use to process the main query parameter (q
) in the request. For example:
defType=dismax
If no defType
parameter is specified, then by default, the The Standard Query Parser is used. (e.g., defType=lucene
)
sort Parameter
The sort
parameter arranges search results in either ascending (asc
) or descending (desc
) order. The parameter can be used with either numerical or alphabetical content. The directions can be entered in either all lowercase or all uppercase letters (i.e., both asc
and ASC
are accepted).
Solr can sort query responses according to:
-
Document scores
-
The value of any primitive field (numerics, string, boolean, dates, etc.) which has
docValues="true"
(ormultiValued="false"
andindexed="true"
, in which case the indexed terms will used to build DocValue like structures on the fly at runtime) -
A SortableTextField which implicitly uses
docValues="true"
by default to allow sorting on the original input string regardless of the analyzers used for Searching. -
A single-valued TextField that uses an analyzer (such as the KeywordTokenizer) that produces only a single term per document. TextField does not support
docValues="true"
, but a DocValue-like structure will be built on the fly at runtime.-
NOTE: If you want to be able to sort on a field whose contents you want to tokenize to facilitate searching, use a
copyField
directive in the the Schema to clone the field. Then search on the field and sort on its clone.
-
In the case of primitive fields, or SortableTextFields, that are multiValued="true"
the representative value used for each doc when sorting depends on the sort direction: The minimum value in each document is used for ascending (asc
) sorting, while the maximal value in each document is used for descending (desc
) sorting. This default behavior is equivilent to explicitly sorting using the 2 argument field()
function: sort=field(name,min) asc
and sort=field(name,max) desc
The table below explains how Solr responds to various settings of the sort
parameter.
Example | Result |
---|---|
If the sort parameter is omitted, sorting is performed as though the parameter were set to |
|
score desc |
Sorts in descending order from the highest score to the lowest score. |
price asc |
Sorts in ascending order of the price field |
div(popularity,price) desc |
Sorts in descending order of the result of the function |
inStock desc, price asc |
Sorts by the contents of the |
categories asc, price asc |
Sorts by the lowest value of the (multivalued) |
Regarding the sort parameter’s arguments:
-
A sort ordering must include a field name (or
score
as a pseudo field), followed by whitespace (escaped as + or%20
in URL strings), followed by a sort direction (asc
ordesc
). -
Multiple sort orderings can be separated by a comma, using this syntax:
sort=<field name><direction>,<field name><direction>],…
-
When more than one sort criteria is provided, the second entry will only be used if the first entry results in a tie. If there is a third entry, it will only be used if the first AND second entries are tied. This pattern continues with further entries.
-
start Parameter
When specified, the start
parameter specifies an offset into a query’s result set and instructs Solr to begin displaying results from this offset.
The default value is 0
. In other words, by default, Solr returns results without an offset, beginning where the results themselves begin.
Setting the start
parameter to some other number, such as 3
, causes Solr to skip over the preceding records and start at the document identified by the offset.
You can use the start
parameter this way for paging. For example, if the rows
parameter is set to 10, you could display three successive pages of results by setting start to 0, then re-issuing the same query and setting start to 10, then issuing the query again and setting start to 20.
rows Parameter
You can use the rows
parameter to paginate results from a query. The parameter specifies the maximum number of documents from the complete result set that Solr should return to the client at one time.
The default value is 10
. That is, by default, Solr returns 10 documents at a time in response to a query.
fq (Filter Query) Parameter
The fq
parameter defines a query that can be used to restrict the superset of documents that can be returned, without influencing score. It can be very useful for speeding up complex queries, since the queries specified with fq
are cached independently of the main query. When a later query uses the same filter, there’s a cache hit, and filter results are returned quickly from the cache.
When using the fq
parameter, keep in mind the following:
-
The
fq
parameter can be specified multiple times in a query. Documents will only be included in the result if they are in the intersection of the document sets resulting from each instance of the parameter. In the example below, only documents which have a popularity greater then 10 and have a section of 0 will match.fq=popularity:[10 TO *]&fq=section:0
-
Filter queries can involve complicated Boolean queries. The above example could also be written as a single
fq
with two mandatory clauses like so:fq=+popularity:[10 TO *] +section:0
-
The document sets from each filter query are cached independently. Thus, concerning the previous examples: use a single
fq
containing two mandatory clauses if those clauses appear together often, and use two separatefq
parameters if they are relatively independent. (To learn about tuning cache sizes and making sure a filter cache actually exists, see The Well-Configured Solr Instance.) -
It is also possible to use filter(condition) syntax inside the
fq
to cache clauses individually and - among other things - to achieve union of cached filter queries. -
As with all parameters: special characters in an URL need to be properly escaped and encoded as hex values. Online tools are available to help you with URL-encoding. For example: http://meyerweb.com/eric/tools/dencoder/.
fl (Field List) Parameter
The fl
parameter limits the information included in a query response to a specified list of fields. The fields must be either stored="true"
or docValues="true"`
.`
The field list can be specified as a space-separated or comma-separated list of field names. The string "score" can be used to indicate that the score of each document for the particular query should be returned as a field. The wildcard character *
selects all the fields in the document which are either stored="true"
or docValues="true"
and useDocValuesAsStored="true"
(which is the default when docValues are enabled). You can also add pseudo-fields, functions and transformers to the field list request.
This table shows some basic examples of how to use fl
:
Field List | Result |
---|---|
id name price |
Return only the id, name, and price fields. |
id,name,price |
Return only the id, name, and price fields. |
id name, price |
Return only the id, name, and price fields. |
id score |
Return the id field and the score. |
* |
Return all the |
* score |
Return all the fields in each document, along with each field’s score. |
*,dv_field_name |
Return all the |
Functions with fl
Functions can be computed for each document in the result and returned as a pseudo-field:
fl=id,title,product(price,popularity)
Document Transformers with fl
Document Transformers can be used to modify the information returned about each documents in the results of a query:
fl=id,title,[explain]
Field Name Aliases
You can change the key used to in the response for a field, function, or transformer by prefixing it with a `"displayName:`". For example:
fl=id,sales_price:price,secret_sauce:prod(price,popularity),why_score:[explain style=nl]
{
"response": {
"numFound": 2,
"start": 0,
"docs": [{
"id": "6H500F0",
"secret_sauce": 2100.0,
"sales_price": 350.0,
"why_score": {
"match": true,
"value": 1.052226,
"description": "weight(features:cache in 2) [DefaultSimilarity], result of:",
"details": [{
"..."
}]}}]}}
debug Parameter
The debug
parameter can be specified multiple times and supports the following arguments:
-
debug=query
: return debug information about the query only. -
debug=timing
: return debug information about how long the query took to process. -
debug=results
: return debug information about the score results (also known as "explain").-
By default, score explanations are returned as large string values, using newlines and tab indenting for structure & readability, but an additional
debug.explain.structured=true
parameter may be specified to return this information as nested data structures native to the response format requested bywt
.
-
-
debug=all
: return all available debug information about the request request. (alternatively usage:debug=true
)
For backwards compatibility with older versions of Solr, debugQuery=true
may instead be specified as an alternative way to indicate debug=all
The default behavior is not to include debugging information.
explainOther Parameter
The explainOther
parameter specifies a Lucene query in order to identify a set of documents. If this parameter is included and is set to a non-blank value, the query will return debugging information, along with the "explain info" of each document that matches the Lucene query, relative to the main query (which is specified by the q parameter). For example:
q=supervillians&debugQuery=on&explainOther=id:juggernaut
The query above allows you to examine the scoring explain info of the top matching documents, compare it to the explain info for documents matching id:juggernaut
, and determine why the rankings are not as you expect.
The default value of this parameter is blank, which causes no extra "explain info" to be returned.
timeAllowed Parameter
This parameter specifies the amount of time, in milliseconds, allowed for a search to complete. If this time expires before the search is complete, any partial results will be returned, but values such as numFound
, facet counts, and result stats may not be accurate for the entire result set.
This value is only checked at the time of:
-
Query Expansion, and
-
Document collection
As this check is periodically performed, the actual time for which a request can be processed before it is aborted would be marginally greater than or equal to the value of timeAllowed
. If the request consumes more time in other stages, custom components, etc., this parameter is not expected to abort the request.
segmentTerminateEarly Parameter
This parameter may be set to either true
or false
.
If set to true
, and if the mergePolicyFactory for this collection is a SortingMergePolicyFactory
which uses a sort
option compatible with the sort parameter specified for this query, then Solr will attempt to use an EarlyTerminatingSortingCollector
.
If early termination is used, a segmentTerminatedEarly
header will be included in the responseHeader
.
Similar to using the timeAllowed
Parameter, when early segment termination happens values such as numFound
, Facet counts, and result Stats may not be accurate for the entire result set.
The default value of this parameter is false
.
omitHeader Parameter
This parameter may be set to either true
or false
.
If set to true
, this parameter excludes the header from the returned results. The header contains information about the request, such as the time it took to complete. The default value for this parameter is false
.
wt Parameter
The wt
parameter selects the Response Writer that Solr should use to format the query’s response. For detailed descriptions of Response Writers, see Response Writers.
If you do not define the wt
parameter in your queries, JSON will be returned as the format of the response.
cache Parameter
Solr caches the results of all queries and filter queries by default. To disable result caching, set the cache=false
parameter.
You can also use the cost
option to control the order in which non-cached filter queries are evaluated. This allows you to order less expensive non-cached filters before expensive non-cached filters.
For very high cost filters, if cache=false
and cost>=100
and the query implements the PostFilter
interface, a Collector will be requested from that query and used to filter documents after they have matched the main query and all other filter queries. There can be multiple post filters; they are also ordered by cost.
For most queries the default behavior is cost=0
— but some types of queries such as {!frange}
default to cost=100
, because they are most efficient when used as a PostFilter
.
For example:
This is an example of 3 regular filters, where all matching documents generated by each are computed up front and cached independently:
q=some keywords
fq=quantity_in_stock:[5 TO *]
fq={!frange l=10 u=100}mul(popularity,price)
fq={!frange cost=200 l=0}pow(mul(sum(1, query('tag:smartphone')), div(1,avg_rating)), 2.3)
These are the same filters run w/o caching. The simple range query on the quantity_in_stock
field will be run in parallel with the main query like a traditional lucene filter, while the 2 frange
filters will only be checked against each document has already matched the main query and the quantity_in_stock
range query — first the simpler mul(popularity,price)
will be checked (because of it’s implicit cost=100
) and only if it matches will the final very complex filter (with it’s higher cost=200
) be checked.
q=some keywords
fq={!cache=false}quantity_in_stock:[5 TO *]
fq={!frange cache=false l=10 u=100}mul(popularity,price)
fq={!frange cache=false cost=200 l=0}pow(mul(sum(1, query('tag:smartphone')), div(1,avg_rating)), 2.3)
logParamsList Parameter
By default, Solr logs all parameters of requests. Set this parameter to restrict which parameters of a request are logged. This may help control logging to only those parameters considered important to your organization.
For example, you could define this like:
logParamsList=q,fq
And only the 'q' and 'fq' parameters will be logged.
If no parameters should be logged, you can send logParamsList
as empty (i.e., logParamsList=
).
This parameter not only applies to query requests, but to any kind of request to Solr. |
echoParams Parameter
The echoParams
parameter controls what information about request parameters is included in the response header.
The echoParams
parameter accepts the following values:
-
explicit
: This is the default value. Only parameters included in the actual request, plus the_
parameter (which is a 64-bit numeric timestamp) will be added to the params section of the response header. -
all
: Include all request parameters that contributed to the query. This will include everything defined in the request handler definition found insolrconfig.xml
as well as parameters included with the request, plus the_
parameter. If a parameter is included in the request handler definition AND the request, it will appear multiple times in the response header. -
none
: Entirely removes the "params" section of the response header. No information about the request parameters will be available in the response.
Here is an example of a JSON response where the echoParams parameter was not included, so the default of explicit
is active. The request URL that created this response included three parameters - q
, wt
, and indent
:
{
"responseHeader": {
"status": 0,
"QTime": 0,
"params": {
"q": "solr",
"indent": "true",
"wt": "json",
"_": "1458227751857"
}
},
"response": {
"numFound": 0,
"start": 0,
"docs": []
}
}
This is what happens if a similar request is sent that adds echoParams=all
to the three parameters used in the previous example:
{
"responseHeader": {
"status": 0,
"QTime": 0,
"params": {
"q": "solr",
"df": "text",
"preferLocalShards": "false",
"indent": "true",
"echoParams": "all",
"rows": "10",
"wt": "json",
"_": "1458228887287"
}
},
"response": {
"numFound": 0,
"start": 0,
"docs": []
}
}
We welcome feedback on Solr documentation. However, we cannot provide application support via comments. If you need help, please send a message to the Solr User mailing list.