(solr) branch branch_9x updated: Reorganize sort section in common-query-parameters.adoc (#2371)

[ep...@apache.org]

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 cd0ee923179 Reorganize sort section in common-query-parameters.adoc (#2371)
cd0ee923179 is described below

commit cd0ee9231792c37443e66760ec6f75a26bda8862
Author: Drini Cami <cd...@gmail.com>
AuthorDate: Tue Mar 26 14:11:07 2024 -0400

    Reorganize sort section in common-query-parameters.adoc (#2371)
---
 .../query-guide/pages/common-query-parameters.adoc | 58 ++++++++++------------
 1 file changed, 26 insertions(+), 32 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 1c2d2381f6d..66f7d8ed572 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
@@ -38,49 +38,43 @@ The `defType` parameter selects the xref:query-syntax-and-parsers.adoc[query par
 |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).
+The `sort` parameter specifies the order of the returned documents.
 
-Solr can sort query responses according to:
-
-* Document scores
-* xref:function-queries.adoc#sort-by-function[Function results]
-* The value of any primitive field (numerics, string, boolean, dates, etc.) which has `docValues="true"` (or `multiValued="false"` and `indexed="true"`, in which case the indexed terms will be used to build DocValue like structures on the fly at runtime)
-* A SortableTextField which implicitly uses `docValues="true"` by default to allow sorting on the original input string regardless of the analyzers used for Searching.
-* A single-valued TextField that uses an analyzer (such as the KeywordTokenizer) that produces only a single term per document.
-TextField does not support `docValues="true"`, but 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, xref:indexing-guide:copy-fields.adoc[use a `copyField` directive] in the Schema to clone the field.
-Then search on the field and sort on its clone.
-
-In the case of primitive fields, or SortableTextFields, that are `multiValued="true"` the representative value used for each doc when sorting depends on the sort direction: The minimum value in each document is used for ascending (`asc`) sorting, while the maximal value in each document is used for descending (`desc`) sorting.
-This default behavior is equivalent to explicitly sorting using the 2 argument xref:function-queries.adoc#field-function[`field()`] function: `sort=field(name,min) asc` and `sort=field(name,max) desc`
-
-The table below explains how Solr responds to various settings of the `sort` parameter.
+Here are some sample sort values:
 
 [%autowidth.stretch,options="header"]
 |===
-|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
-|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, price asc |Sorts by the lowest value of the (multivalued) `categories` field in ascending order, then when multiple documents have the same lowest `categories` value, those results are sorted in ascending order by the contents of the price field.
+| 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`
 |===
 
-Regarding the sort parameter's arguments:
+More specifically, Solr can sort query responses according to:
 
-* 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`).
+* Document score
+* xref:function-queries.adoc#sort-by-function[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, xref:indexing-guide:copy-fields.adoc[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 xref:function-queries.adoc#field-function[`field()`] function: `sort=field(name,min) asc` and `sort=field(name,max) 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.
-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.
+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`).
 
+NOTE: 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
 
 [%autowidth,frame=none]