|
Size: 12231
Comment: Add a link to the list of functions usable in fl
|
← Revision 51 as of 2013-03-07 20:54:31 ⇥
Size: 12465
Comment: Added note about debugQuery always resulting in calculated scores.
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 124: | Line 124: |
| Line 125: | Line 126: |
| Line 146: | Line 146: |
| ||`fl=my_alias:field_name`||returns "field_name" but displays it as "my_alias"|| | ||`fl=my_alias:field_name` ||returns "field_name" but displays it as "my_alias" || |
| Line 158: | Line 158: |
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. |
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.
Contents
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:
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).
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. When specified, it indicates 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"
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
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:
- 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
- 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
- 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.
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&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
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
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
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.