Apache Solr Documentation

5.1 Ref Guide (PDF Download)
Solr Tutorial
Solr Community Wiki

Older Versions of this Guide (PDF)

5.2 Draft Ref Guide Topics

Meta-Documentation

This Unreleased Guide Will Cover Apache Solr 5.2

Skip to end of metadata
Go to start of metadata

The table below summarizes Solr's common query parameters, which are supported by the Standard, DisMax, and eDisMax Request Handlers.

Parameter

Description

defType

Selects the query parser to be used to process the query.

sort

Sorts the response to a query in either ascending or descending order based on the response's score or another specified characteristic.

start

Specifies an offset (by default, 0) into the responses at which Solr should begin displaying content.

rows

Controls how many rows of responses are displayed at a time (default value: 10)

fq

Applies a filter query to the search results.

fl

Limits the information included in a query response to a specified list of fields. The fields need to have been indexed as stored for this parameter to work correctly.

debug

Request additional debugging information in the response. Specifying the debug=timing parameter returns just the timing information; specifying the debug=results parameter returns "explain" information for each of the documents returned; specifying the debug=query parameter returns all of the debug information.

explainOther

Allows clients to specify a Lucene query to identify a set of documents. If non-blank, the explain info of each document which matches this query, relative to the main query (specified by the q parameter) will be returned along with the rest of the debugging information.

timeAllowed

Defines the time allowed for the query to be processed. If the time elapses before the query response is complete, partial information may be returned.

omitHeader

Excludes the header from the returned results, if set to true. The header contains information about the request, such as the time the request took to complete. The default is false.

wt

Specifies the Response Writer to be used to format the query response.

logParamsList

By default, Solr logs all parameters. Set this parameter to restrict which parameters are logged. Valid entries are the parameters to be logged, separated by commas (i.e., logParamsList=param1,param2). An empty list will log no parameters, so if logging all parameters is desired, do not define this additional parameter at all.

The following sections describe these parameters in detail.

The 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 param is specified, then by default, the The Standard Query Parser is used.  (eg: defType=lucene)

The 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 or ASC).

Solr can sort query responses according to document scores or the value of any indexed field with a single value (that is, any field whose attributes in schema.xml include multiValued="false" and indexed="true"), provided that:

  • the field is non-tokenized (that is, the field has no analyzer and its contents have been parsed into tokens, which would make the sorting inconsistent), or
  • the field uses an analyzer (such as the KeywordTokenizer) that produces only a single term.

If you want to be able to sort on a field whose contents you want to tokenize to facilitate searching, use the <copyField> directive in the schema.xml file to clone the field. Then search on the field and sort on its clone.

The table 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.

score desc

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

price asc

Sorts in ascending order of the price field

inStock desc, price asc

Sorts by the contents of the inStock field in descending order, then within those results sorts in ascending order by the contents of the price field.

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 or desc).
  • 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.

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

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

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

  • Filter queries can involve complicated Boolean queries. The above example could also be written as a single fq with two mandatory clauses like so:

  • 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 The Well-Configured Solr Instance.)
  • 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/.

The fl (Field List) Parameter

The fl parameter limits the information included in a query response to a specified list of fields. The fields need to have been indexed as stored for this parameter to work correctly.

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 stored fields in a document. You can also add psuedo-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 fields in each document. This is the default value of the fl parameter.

* score

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

Function Values

Functions can be computed for each document in the result and returned as a psuedo-field:

Document Transformers

Document Transformers can be used to modify the information returned about each documents in the results of a query:

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:

The 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")
  • 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.

The 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:

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.

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

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

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

The cache=false 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 example:

The logParamsList Parameter

By default, Solr logs all parameters of requests. From version 4.7, 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=).

Icon

This parameter does not only apply to query requests, but to any kind of request to Solr.

Labels
  • No labels
  1. This page really needs to mention the q param and:

    • how it's impacted by defType
    • how localparams can be used to override defType