You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@solr.apache.org by ep...@apache.org on 2024/03/11 21:09:58 UTC
(solr) branch branch_9x updated: Add default/optional tables to common-query-parameters.adoc (#2340)
This is an automated email from the ASF dual-hosted git repository.
epugh pushed a commit to branch branch_9x
in repository https://gitbox.apache.org/repos/asf/solr.git
The following commit(s) were added to refs/heads/branch_9x by this push:
new 0b8a17b1f55 Add default/optional tables to common-query-parameters.adoc (#2340)
0b8a17b1f55 is described below
commit 0b8a17b1f55a08315d0f0583dde945b9d54f9471
Author: Drini Cami <cd...@gmail.com>
AuthorDate: Mon Mar 11 17:09:21 2024 -0400
Add default/optional tables to common-query-parameters.adoc (#2340)
---
.../query-guide/pages/common-query-parameters.adoc | 135 ++++++++++++++++-----
1 file changed, 106 insertions(+), 29 deletions(-)
diff --git a/solr/solr-ref-guide/modules/query-guide/pages/common-query-parameters.adoc b/solr/solr-ref-guide/modules/query-guide/pages/common-query-parameters.adoc
index 201c6c86a24..1c2d2381f6d 100644
--- a/solr/solr-ref-guide/modules/query-guide/pages/common-query-parameters.adoc
+++ b/solr/solr-ref-guide/modules/query-guide/pages/common-query-parameters.adoc
@@ -20,18 +20,24 @@ Several query parsers share supported query parameters.
The following sections describe Solr's common query parameters, which are supported by the xref:configuration-guide:requesthandlers-searchcomponents.adoc#search-handlers[search request handlers].
+
== 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:
+[%autowidth,frame=none]
+|===
+|Optional |Default: `lucene`
+|===
-`defType=dismax`
+The `defType` parameter selects the xref:query-syntax-and-parsers.adoc[query parser] to process the main query parameter (`q`) in the request. Acceptable values include: `lucene` (xref:standard-query-parser.adoc[]), `dismax` (xref:dismax-query-parser.adoc[]), `edismax` (xref:edismax-query-parser.adoc[]), or one of the xref:query-syntax-and-parsers.adoc[other query parsers].
-If no `defType` parameter is specified, then by default, the xref:standard-query-parser.adoc[] is used.
-(e.g., `defType=lucene`)
== sort Parameter
+[%autowidth,frame=none]
+|===
+|Optional |Default: `score desc`
+|===
+
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).
@@ -77,43 +83,59 @@ Users looking to avoid this behavior can define an additional sort criteria on a
== 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.
+[%autowidth,frame=none]
+|===
+|Optional |Default: `0`
+|===
-The default value is `0`.
-In other words, by default, Solr returns results without an offset, beginning where the results themselves begin.
+The `start` parameter specifies an offset into a query's result set and instructs Solr to begin displaying results from this offset.
-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.
+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
-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.
+[%autowidth,frame=none]
+|===
+|Optional |Default: `10`
+|===
-The default value is `10`.
-That is, by default, Solr returns 10 documents at a time in response to a query.
+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
-This parameter defines if this query is cancellable during execution using the
+[%autowidth,frame=none]
+|===
+|Optional |Default: `false`
+|===
+
+The `canCancel` parameter specifies if the query can be cancelled during its execution using the
xref:deployment-guide:task-management.adoc[task management] interface.
== queryUUID Parameter
-For cancellable queries, this allows specifying a custom UUID to identify the query with.
-If `canCancel` is specified and `queryUUID` is not set, an auto generated UUID will be assigned to the query.
+[%autowidth,frame=none]
+|===
+|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.
-If `queryUUID` is specified, this UUID will be used for identifying the query.
-Note that if 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 throws for the second query.
+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 the user either uses all custom UUIDs or depends completely on the system to generate UUID.
-Mixing the two can lead to conflict of UUIDs.
+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
+[%autowidth,frame=none]
+|===
+|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.
@@ -180,6 +202,11 @@ fq={!frange cache=false cost=200 l=0}pow(mul(sum(1, query('tag:smartphone')), di
== fl (Field List) Parameter
+[%autowidth,frame=none]
+|===
+|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"``.`
@@ -256,6 +283,11 @@ fl=id,sales_price:price,secret_sauce:prod(price,popularity),why_score:[explain s
== debug Parameter
+[%autowidth,frame=none]
+|===
+|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.
@@ -271,13 +303,18 @@ The default behavior is not to include debugging information.
== explainOther Parameter
+[%autowidth,frame=none]
+|===
+|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:
[source,text]
----
-q=supervillains&debugQuery=on&explainOther=id:juggernaut
+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.
@@ -286,6 +323,11 @@ The default value of this parameter is blank, which causes no extra "explain inf
== partialResults Parameter
+[%autowidth,frame=none]
+|===
+|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).
@@ -294,6 +336,11 @@ When this parameter is set to `false` then reaching a limit will generate an exc
== timeAllowed Parameter
+[%autowidth,frame=none]
+|===
+|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`, xref:faceting.adoc[facet] counts, and result xref:stats-component.adoc[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`.
@@ -332,6 +379,11 @@ Regular search, JSON Facet and the Analytics component abandon requests in accor
== cpuAllowed Parameter
+[%autowidth,frame=none]
+|===
+|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).
@@ -343,7 +395,10 @@ All other considerations regarding partial results listed for the `timeAllowed`
== segmentTerminateEarly Parameter
-This parameter may be set to either `true` or `false`.
+[%autowidth,frame=none]
+|===
+|Optional |Default: `false`
+|===
If set to `true`, and if xref:configuration-guide:index-segments-merging.adoc#mergepolicyfactory[the mergePolicyFactory] for this collection is a {solr-javadocs}/core/org/apache/solr/index/SortingMergePolicyFactory.html[`SortingMergePolicyFactory`] which uses a `sort` option compatible with <<sort Parameter,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.
@@ -351,19 +406,25 @@ If early termination is used, a `segmentTerminatedEarly` header will be included
Similar to using <<timeAllowed Parameter,the `timeAllowed` Parameter>>, when early segment termination happens values such as `numFound`, xref:faceting.adoc[Facet] counts, and result xref:stats-component.adoc[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`.
+[%autowidth,frame=none]
+|===
+|Optional |Default: `false`
+|===
-If set to `true`, this parameter excludes the header from the returned results.
+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.
-The default value for this parameter is `false`.
+
When using parameters such as <<timeallowed-parameter,`timeAllowed`>>, and xref:deployment-guide:solrcloud-distributed-requests.adoc#shards-tolerant-parameter[`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`, xref:faceting.adoc[Facet] counts, and result xref:stats-component.adoc[Stats] can be interpreted in the context of partial results.
== wt Parameter
+[%autowidth,frame=none]
+|===
+|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 xref:response-writers.adoc[].
@@ -371,8 +432,13 @@ If you do not define the `wt` parameter in your queries, JSON will be returned a
== logParamsList Parameter
+[%autowidth,frame=none]
+|===
+|Optional |Default: all parameters
+|===
+
By default, Solr logs all query parameters on each request.
-This parameter allows users to override this behavior, by specifying a comma-separated "allowlist" of parameter names that should be logged.
+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.
NOTE: `logParamsList` only governs the logging of query parameters.
@@ -390,6 +456,11 @@ TIP: This parameter not only applies to query requests, but to any kind of reque
== echoParams Parameter
+[%autowidth,frame=none]
+|===
+|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:
@@ -453,6 +524,12 @@ This is what happens if a similar request is sent that adds `echoParams=all` to
----
== minExactCount Parameter
+
+[%autowidth,frame=none]
+|===
+|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.