Common Query Parameters

Several query parsers share supported query parameters.

The following sections describe Solr’s common query parameters, which are supported by the search request handlers.

defType Parameter

Optional

Default: lucene

The defType parameter selects the query parser to process the main query parameter (q) in the request. Acceptable values include: lucene (Standard Query Parser), dismax (DisMax Query Parser), edismax (Extended DisMax (eDisMax) Query Parser), or one of the other query parsers.

sort Parameter

Optional

Default: score desc

The sort parameter specifies the order of the returned documents.

Here are some sample sort values:

Example Result

Example	Result
`score desc`	Sorts in descending order from the highest score to the lowest score.
`price asc`	Sorts in ascending order of the price field, from lowest to highest.
`div(popularity,price) desc`	Sorts in descending order of the result of the function `popularity / price`.
`inStock desc, price asc`	Sorts by the contents of the `inStock` field in descending order, then when multiple documents have the same value for the `inStock` field, those results are sorted in ascending order by the contents of the `price` field.
`categories asc`	Since `categories` is a multivalued field and we are sorting ascending, this sorts by the lowest value of the `categories` field in ascending order. This is equivalent to `field(categories,min) asc`

score desc

Sorts in descending order from the highest score to the lowest score.

price asc

Sorts in ascending order of the price field, from lowest to highest.

div(popularity,price) desc

Sorts in descending order of the result of the function popularity / price.

inStock desc, price asc

Sorts by the contents of the inStock field in descending order, then when multiple documents have the same value for the inStock field, those results are sorted in ascending order by the contents of the price field.

categories asc

Since categories is a multivalued field and we are sorting ascending, this sorts by the lowest value of the categories field in ascending order. This is equivalent to field(categories,min) asc

More specifically, Solr can sort query responses according to:

Document score
Function results
Single-valued primitive fields (numerics, string, boolean, dates, etc.) which have docValues="true" (or indexed="true", in which case the indexed terms will be used to build DocValue like structures on the fly at runtime).
Single-valued SortableTextField which implicitly uses docValues="true" by default to allow sorting on the original input string regardless of the analyzers used for Searching.
Single-valued TextField which have an analyzer (such as the KeywordTokenizer) that produces only a single term per document. Since TextField does not support docValues="true", 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 Schema to clone the field. Then search on the field and sort on its clone.
Multi-valued primitive fields with docValues="true" or SortableTextFields. In this case, a representative value is used for each document, depending on the sort direction. When ascending, the minimum value is used. When descending, the maximum value is used. This is equivalent to explicitly sorting using the 2 argument field() function: sort=field(name,min) asc and sort=field(name,max) desc.

You can specify multiple sort orderings by separating them with commas, e.g. inStock desc, price asc. When multiple sort criteria are 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. And so on.

If documents tie in all of the explicit sort criteria, Solr uses each document’s Lucene document ID as the final tie-breaker. This internal property is subject to change during segment merges and document updates, which can lead to unexpected result ordering changes. Users looking to avoid this behavior can define an additional sort criteria on a unique or rarely-shared field such as id to prevent ties from occurring (e.g., price desc,id asc).

A sort ordering must always 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 or desc, case insensitive).

start Parameter

Optional

Default: 0

The start parameter specifies an offset into a query’s result set and instructs Solr to begin displaying results from this offset.

In other words, setting the start parameter to a number other than 0, such as 3, causes Solr to skip over the first 3 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

Optional

Default: 10

The rows parameter specifies the number of documents from the complete result to return in the response. You can use the rows parameter to paginate results from a query.

canCancel Parameter

Optional

Default: false

The canCancel parameter specifies if the query can be cancelled during its execution using the task management interface.

queryUUID Parameter

Optional

Default: none

For cancellable queries, the queryUUID parameter allows specifying a custom UUID to identify the query with. Otherwise an auto-generated UUID will be assigned.

When using queryUUID, the responsibility of ensuring uniqueness of the UUID lies with the caller. If a query UUID is reused while the original query UUID is still active, it will cause an exception to be thrown for the second query.

It is recommended that to either use all custom UUIDs or depends completely on the system to generate UUID to avoid UUID conflicts.

fq (Filter Query) Parameter

Optional

Default: none

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 than 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 separate fq parameters if they are relatively independent. (To learn about tuning cache sizes and making sure a filter cache actually exists, see Caches.)
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 a 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/.

cache Local Parameter

Solr caches the results of filter queries by default in the filter cache. To disable it, use the boolean cache local param, such as fq={!geofilt cache=false}…. Do this when you think a query is unlikely to be repeated.

Non-cached filter queries also support the cost local parameter to provide a hint as to the order in which they are evaluated. This allows you to order less expensive non-cached filters before expensive non-cached filters. At the Lucene layer, this maps to TwoPhaseIterator.matchCost if the query has a TPI.

Post 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.

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 without 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 its implicit cost=100) and only if it matches will the final very complex filter (with its 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)

fl (Field List) Parameter

Optional

Default: *

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). Combine the wildcard character with field name to make a glob pattern for matching multiple field names.

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

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 na* price	Return the id, name, name_exact, and price fields.
id na*e price	Return the id, name, and price fields.
id score	Return the id field and the score.
*	Return all the `stored` fields in each document, as well as any `docValues` fields that have `useDocValuesAsStored="true"`. This is the default value of the fl parameter.
* score	Return all the fields in each document, along with each field’s score.
*,dv_field_name	Return all the `stored` fields in each document, and any `docValues` fields that have `useDocValuesAsStored="true"` and the docValues from dv_field_name even if it has `useDocValuesAsStored="false"`

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 na* price

Return the id, name, name_exact, and price fields.

id na*e price

Return the id, name, and price fields.

id score

Return the id field and the score.

Return all the stored fields in each document, as well as any docValues fields that have useDocValuesAsStored="true". This is the default value of the fl parameter.

* score

Return all the fields in each document, along with each field’s score.

*,dv_field_name

Return all the stored fields in each document, and any docValues fields that have useDocValuesAsStored="true" and the docValues from dv_field_name even if it has useDocValuesAsStored="false"

Functions with fl

Function Queries 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: value.

For example, why_score is the display name below:

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

Optional

Default: none

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 by wt.
debug=all: return all available debug information about the request request. An alternative usage is 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

Optional

Default: none

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=supervillains&debug=all&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.

partialResults Parameter

Optional

Default: true

This parameter controls Solr’s behavior when a query execution limit is reached (e.g. timeAllowed or cpuAllowed).

When this parameter is set to true (default) then even though reaching a limit terminates further query processing Solr will still attempt to return partial results collected so far. These results may be incomplete in a non-deterministic way (e.g. only some matching documents, documents without fields, missing facets or pivots, no spellcheck results, etc).

When this parameter is set to false then reaching a limit will generate an exception and any partial results collected so far will be discarded.

timeAllowed Parameter

Optional

Default: none

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. In case of expiration, if omitHeader isn’t set to true the response header contains a special flag called partialResults. When using timeAllowed in combination with cursorMark, and the partialResults flag is present, some matching documents may have been skipped in the result set. Additionally, if the partialResults flag is present, cursorMark can match nextCursorMark even if there may be more results

{
  "responseHeader": {
    "status": 0,
    "zkConnected": true,
    "partialResults": true,
    "QTime": 20,
    "params": {
      "q": "*:*"
    }
  },
  "response": {
    "numFound": 77,
    "start": 0,
    "docs": [ "..." ]
  }
}

This value is only checked at the time of:

Query Expansion, and
Document collection
Doc Values reading

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. Regular search, JSON Facet and the Analytics component abandon requests in accordance with this parameter.

cpuAllowed Parameter

Optional

Default: none

This parameter specifies the amount of CPU time, in milliseconds, allowed for a search to complete. In contrast to the timeAllowed this parameter monitors the actual CPU usage by the thread that executes the query. The same CPU usage limit is applied to the query coordinator as to each replica that participates in the distributed search (although reaching this limit first in the query coordinator is unlikely). Should any replica locally exceed the allowed CPU time the whole distributed search will be terminated (by canceling requests to other shards).

Note: the same CPU limit is applied to each stage in the distributed query processing. Typically this involves two or more stages (e.g. getting top document id-s, retrieving their fields, additional stages may be required for faceting, grouping, etc). For example, setting cpuAllowed=500 gives a limit of at most 500 ms of CPU time for each of these stages - meaning that the total CPU usage by the query may reach a multiple of the cpuAllowed value depending on the number of stages.

All other considerations regarding partial results listed for the timeAllowed parameter apply here, too.

segmentTerminateEarly Parameter

Optional

Default: 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 be able to skip documents on a per-segment basis that are definitively not candidates for the current page of results.

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.

multiThreaded Parameter

Optional

Default: false

This parameter set to true or false controls if Solr may use more than one thread to satisfy the request. A true value presently allows the IndexSearcher to search across Lucene’s segments in parallel, and the indexSearcherExecutorThreads value can be customised in the solr.xml file. This parameter is ignored in the presence of &segmentsTerminateEarly=true (future work may enable it). This is a new parameter and is considered experimental and subject to change or removal in subsequent releases. Please share your feedback and experiences with it on our mailing lists.

omitHeader Parameter

Optional

Default: false

If set to true, the omitHeader parameter excludes the header from the returned results. The header contains information about the request, such as the time it took to complete.

When using parameters such as timeAllowed, and shards.tolerant, which can lead to partial results, it is advisable to keep the header, so that the partialResults flag can be checked, and values such as numFound, nextCursorMark, Facet counts, and result Stats can be interpreted in the context of partial results.

wt Parameter

Optional

Default: json

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.

logParamsList Parameter

Optional

Default: all parameters

By default, Solr logs all query parameters on each request. The logParamsList parameter allows users to override this behavior, by specifying a comma-separated "allowlist" of parameter names that should be logged. This may help control logging to only those parameters considered important to your organization.

logParamsList only governs the logging of query parameters. It does not apply to parameters specified in the request path, body, etc.

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

Optional

Default: none or default in solrconfig.xml

The echoParams parameter controls what information about request parameters is included in the response header.

The echoParams parameter accepts the following values:

explicit: Only parameters included in the actual request 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 in solrconfig.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.

The default value is none, though many solrconfig.xml handlers set default to be explicit. Here is an example of a JSON response where the echoParams parameter was set in that SearchHandler’s default, so it itself was not echoed, but only three parameters from the request itself - 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",
      "indent": "true",
      "echoParams": "all",
      "rows": "10",
      "wt": "json",
      "_": "1458228887287"
    }
  },
  "response": {
    "numFound": 0,
    "start": 0,
    "docs": []
  }
}

minExactCount Parameter

Optional

Default: none

When this parameter is used, Solr will count the number of hits accurately at least until this value. After that, Solr can skip over documents that don’t have a score high enough to enter in the top N. This can greatly improve performance of search queries. On the other hand, when this parameter is used, the numFound may not be exact, and may instead be an approximation. The numFoundExact boolean attribute is included in all responses, indicating if the numFound value is exact or an approximation. If it’s an approximation, the real number of hits for the query is guaranteed to be greater or equal numFound.

More about approximate document counting and minExactCount:

The documents returned in the response are guaranteed to be the docs with the top scores. This parameter will not make Solr skip documents that are to be returned in the response, it will only allow Solr to skip counting docs that, while they match the query, their score is low enough to not be in the top N.
Providing minExactCount doesn’t guarantee that Solr will use approximate hit counting (and thus, provide the speedup). Some types of queries, or other parameters (like if facets are requested) will require accurate counting.
Approximate counting can only be used when sorting by score desc first (which is the default sort in Solr). Other fields can be used after score desc, but if any other type of sorting is used before score, then the approximation won’t be applied.
When doing distributed queries across multiple shards, each shard will accurately count hits until minExactCount (which means the query could be hitting numShards * minExactCount docs and numFound in the response would still be accurate) For example:

q=quick brown fox&minExactCount=100&rows=10

"response": {
    "numFound": 153,
    "start": 0,
    "numFoundExact": false,
    "docs": [{"doc1"}]
}

Since numFoundExact=false, we know the number of documents matching the query is greater or equal to 153. If we specify a higher value for minExactCount:

q=quick brown fox&minExactCount=200&rows=10

"response": {
    "numFound": 163,
    "start": 0,
    "numFoundExact": true,
    "docs": [{"doc1"}]
}

In this case we know that 163 is the exact number of hits for the query. Both queries must have returned the same number of documents in the top 10.