Differences between revisions 53 and 54
Revision 53 as of 2013-08-01 20:14:16
Size: 12728
Comment: Corrected typo in multiple fl= example
Revision 54 as of 2014-01-27 15:55:56
Size: 12472
Editor: YonikSeeley
Comment: replace incorrect paging info (scoreDoc, etc)
Deletions are marked like this. Additions are marked like this.
Line 49: Line 49:
<<Anchor(pageDocpageScore)>>

== pageDoc and pageScore ==
<!> [[Solr4.0]] See https://issues.apache.org/jira/browse/SOLR-1726 If you expect to be paging deeply into the results (say beyond page 10, assuming rows=10) and you are sorting by score, you may wish to add the pageDoc and pageScore parameters to your request. These two parameters tell Solr (and Lucene) what the last result (Lucene internal docid and score) of the previous page was, so that when scoring the query for the next set of pages, it can ignore any results that occur higher than that item. To get the Lucene internal doc id, you will need to add [docid] to the &fl list.

 . Example: {{{q=*:*&start=10&pageDoc=5&pageScore=1.345&fl=[docid],score}}}
<<Anchor(cursorMark)>>

== Deep paging with cursorMark ==
<!> [[Solr4.7]] See https://issues.apache.org/jira/browse/SOLR-5463 If you expect to be paging deeply into the results (say beyond page 10, assuming rows=10).
Pass cursorMark=* on the first request and then solr will return a nextCursorMark that you can use as the value for cursorMark in your next request.
Here's a [[http://heliosearch.org/solr/paging-and-deep-paging/|full cursorMark deep paging example]]

The following list of parameters are supported by SearchHandler. Although they are not mandatory, it is strongly encouraged that all Future SolrRequestHandlers support them as well. Some Utilities exist to make implementing them easy.

q

The q parameter is normally the main query for the request. See Solr query syntax for more information on different types of queries and syntaxes.

sort

Examples

sort

Meaning

by default, it is the same as score desc

score desc

sort from highest score to lowest score

price asc

sort in ascending order of the "price" field

inStock desc, price asc

sort by "inStock" descending, then "price" ascending

sum(x_f, y_f) desc

sort by the sum of x_f and y_f in a descending order

Sorting can be done on the "score" of the document, or on any multiValued="false" indexed="true" field provided that field is either non-tokenized (ie: has no Analyzer) or uses an Analyzer that only produces a single Term (ie: uses the KeywordTokenizer)

You can sort by index id using sort=_docid_ asc or sort=_docid_ desc

As of Solr3.1, sorting can also be done on arbitrary function queries (as in FunctionQuery) that produce a single value per document.

The common situation for sorting on a field that you do want to be tokenized for searching is to use a <copyField> to clone your field. Sort on one, search on the other.

NOTE:

  1. A sort ordering must include a field name (or the pseudo-field score), followed by whitespace (escaped as + or %20 in URL strings), followed by a sort direction (asc or desc).

  2. Multiple sort orderings can be separated by a comma, ie: sort=<field name>+<direction>[,<field name>+<direction>]...

start

This parameter is used to paginate results from a query. When specified, it indicates the offset in the complete result set for the queries where the set of returned documents should begin. (i.e. the first record appear in the result set is the offset)

The default value is "0".

rows

This parameter is used to paginate results from a query. It specify the maximum number of documents from the complete result set to return to the client for every request. You can consider it as the maximum number of result appear in the page.

The default value is "10", which is used if the parameter is not specified. If you want to tell Solr to return all possible results from the query without an upper bound, specify rows to be 10000000 or some other ridiculously large value that is higher than the possible number of rows that are expected.

Deep paging with cursorMark

<!> Solr4.7 See https://issues.apache.org/jira/browse/SOLR-5463 If you expect to be paging deeply into the results (say beyond page 10, assuming rows=10). Pass cursorMark=* on the first request and then solr will return a nextCursorMark that you can use as the value for cursorMark in your next request. Here's a full cursorMark deep paging example

fq

"fq" stands for Filter Query.

This parameter can be used to specify a query that can be used to restrict the super set 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 from the main query. Caching means the same filter is used again for a later query (i.e. there's a cache hit). See SolrCaching to learn about the caches Solr uses.

NOTE:

  1. The fq param can be specified multiple times. Documents will only be included in the result if they are in the intersection of the document sets resulting from each fq. 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
  2. Filter Queries can be complicated boolean queries, so the above example could also be written as a single fq with two mandatory clauses...
      fq=+popularity:[10 TO *] +section:0
  3. 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 params if they are relatively independent.
  4. As with all parameters: when expressed in a URL, special characters need to be properly URL escaped.

Caching of filters

Each filter query is normally generated and cached independently in the filterCache, leading to improved request throughput for filters that are likely to be reused. Starting with Solr3.4, the local param cache=false can be added at the top-level of any filter query, and cause that filter to not be generated up front and cached, but instead executed in parallel with the query and all other filters. This can be beneficial for filters that will not be reused in other requests (thus avoiding polluting the filterCache) and for filters that are very expensive to evaluate for every document in the index.

  • Example: q=*:*&fq={!cache=false}inStock:true

  • Example: q=*:*&fq={!frange l=1 u=4 cache=false}sqrt(popularity)

There is also an optional "cost" local param that controls the order in which non-cached filter queries are evaluated, so knowledgable users can order less expensive non-cached filters before expensive non-cached filters.

  • Example: q=*:*&fq={!cache=false cost=5}inStock:true&fq={!frange l=1 u=4 cache=false cost=50}sqrt(popularity)

As an additional feature 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 only after they have matched the main query and all other filter queries. There can be multiple post filters, and they are also ordered by cost. The frange parser currently supports post filtering, useful when the referenced function query is very expensive.

  • Example: q=*:*&fq={!frange l=1 u=4 cache=false cost=150}sqrt(popularity)

fl

This parameter can be used to specify a set of fields to return, limiting the amount of information in the response. When returning the results to the client, only fields in this list will be included.

The set of fields to be returned can be specified as a space (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, and the string "*" can be used to indicate all stored fields the document has.

Examples

Field List

Meaning

id name price

Only return the "id", "name", and "price" fields

id,name,price

Same as above

id name, price

Same as above

id score

Return the "id" field and the score

*

Return all fields the each document has

* score

Return all fields each document has, along with the score

The default value is "*"

<!> Solr4.0 In 4.x, the fl parameter supports 'pseudo fields', see https://issues.apache.org/jira/browse/SOLR-2444

In 4.x, you can send fields as many parameters. For example: &fl=id,name,price is the same as: &fl=id&fl=name&fl=price

glob

Example

Meaning

id,tag*

return id and all fields that start with tag

functions

Example

Meaning

id,foo(c)

id and a function

See here for a list of available functions.

Transformers

Transformers manipulate documents before they are returned. Standard transformers include:

Example

Meaning

[docid]

the lucene document id (int)

[shard]

the id of the shard that produced the result

[explain]

inline explain info

[explain style=nl|text|html]

explain info with explicit style

[value v=? t=int|double|float|date]

explicit value

Custom Transformers can be registered in solrconfig.xml

Field alias

Any field, function, or transformer can be displayed with a different name in the output document:

Example

Meaning

id,price:crazy_price_field

return the stored field 'crazy_price_field' but display it as 'price'

id,price:sum(a,b)

return price as the sum of fields a+b

fl=my_alias:field_name

returns "field_name" but displays it as "my_alias"

Debugging

debugQuery

If this parameter is present (regardless of its value) then additional debugging information will be included in the response, including "explain" info for each of the documents returned. This debugging info is meant for human consumption... its XML format could change in the future.

The default behavior is not to include debugging info.

When debugQuery is enabled, the score value will always be calculated and the explanation given for every document in the results, even if the query parameters do not require scores, such as when sorting by a field in the index.

debug

<!> Solr4.0

Clients may also specify control over individual parts of debugging output by specifying debug= with one of four options:

  • timing -- Provide debug info about timing of components, etc. only
  • query -- Provide debug info about the query only
  • results -- Provide debug info about the results (currently explains)
  • true -- If true, this is the equivalent of &debugQuery=true

explainOther

This parameter allows clients to specify a Lucene query to identify a set of documents. If non-blank, the explain info of each document that matches this query, relative to the main query (specified by the q parameter) will be returned along with the rest of the debugging information. This is useful, for instance, for understanding why a particular document is not in the result set. For instance, the query http://localhost:8983/solr/select?q=ipod&debug=results&explainOther=id:MA* (run against <!> Solr4.0) shows the explanations for the query ipod and also shows the explanations for all documents that match id:MA* as if the main query were run (ipod) and produced the documents that the id:MA* query produced.

The default value is blank (i.e. no extra explain info will be returned)

debug.explain.structured

<!> Solr3.2

If "true", this parameter tells the DebugComponent that score Explanations should be returned as structured data, which the response writer can then output natively. When "false" the Explanation information is returned as a (more compact) single string with whitespace used for indenting to show the nested structure.

The default value is "false"

defType

The defType parameter can be used to specify the query parser to use with this request. See http://lucene.apache.org/solr/api/org/apache/solr/search/QParserPlugin.html and http://wiki.apache.org/solr/SolrPlugins#head-60a8c7a0663bd05a528899e7719ffe52522a21c2

timeAllowed

<!> Solr1.3

The time allowed for a search to finish. This value only applies to the search and not to requests in general. Time is in milliseconds. Values <= 0 mean no time restriction. Partial results may be returned (if there are any).

omitHeader

Range: {true|false}

Exclude the header from the returned results. The header contains information about the request, such as the time it took to complete. The default is false.

CommonQueryParameters (last edited 2014-04-03 07:13:56 by ShawnHeisey)