A sorting specification in a query consists of one or more sorting expressions. Each sorting expression is an optional sort order followed by an attribute name or a function over an attribute. Multiple expressions are separated by a single SPACE character.
Using more than one sort expression will give you multilevel sorting. In this case, the most significant expression is the first, while subsequent expressions detail sorting within groups of equal values for the previous expression.
Sorting ::= SortExpr ( ' ' SortExpr )*
SortExpr ::= [SortOrder] SortObject
SortObject ::= SortAttribute | Function
Function ::= LOWERCASE '(' SortAttribute ')' |
RAW '(' SortAttribute ')' |
UCA '(' SortAttribute [ ',' Locale [ ',' Strength] ] ')'
LOWERCASE ::= 'lowercase'
UCA ::= 'uca'
RAW ::= 'raw'
Locale ::= An identifier following unicode locale identifiers, fx 'en_US'.
Strength :: 'PRIMARY' | 'SECONDARY' | 'TERTIARY' | 'QUATERNARY' | 'IDENTICAL'
SortOrder ::= '+' | '-'
SortAttribute ::= ID /* A valid attribute name */
See Geo search for sorting by distance. Refer to YQL Vespa reference for how to set sorting parameters in YQL.
+ denotes ascending sorting order,
while - gives descending order.
Ascending order is defined as lowest values first for numerical attributes.
Strings are sorted according to the sort function chosen.
Descending order is the reverse of ascending order.
Note: + in query URLs must be encoded as %2B -
for consistency, - can be encoded as %2D.
If +/- is omitted, the default is used,
either the system-wide default of +
or any override in schema.
Default sort order is + or ascending,
except for [rank] or the special builtin [relevance],
which has - or descending.
The sorting attribute in a sort expression is the name of an attribute in the index. Attribute names will often be the same as field names. In the schema, an attribute is indicated by the indexing language fragment for a field having an attribute statement.
When sorting on attributes, it is recommended to use the built-in unranked rank-profile. This allows the search kernel to execute the query significantly faster than execution the ranking framework for many hits and then finally ignore this score and sort by the specified sorting specification.
When sorting on a multivalue attribute (array or weightedset) one of the values for the document is selected to be used for sorting. Ascending sort order uses the lowest value while descending sort order uses the highest value. A document without any values is considered worse than a document with values, regardless of sort order.
Refer to function.
Three special attributes are available for sorting in addition to the index specific attributes:
| [relevance] | The document's relevance score for this query. This is the same as the default ordering when no sort specification is given ([rank] is a legacy alias for the same thing). |
|---|---|
| [source] | The document's source name. This is only relevant when querying multiple sources. |
| [docid] | The document's identification in the search backend. This will typically give you the documents in indexing order. Keep in mind that this id is unique only to the backend node. The same document might have different id on a different node. The same way a different document might have the same id on another node. This is just intended as a cheap way of getting an almost stable sort order. |
These special attributes are most useful as secondary sort expressions in a multilevel sort. This will allow you to sort groups of equal values for the primary expression in either relevancy or indexing order. Without this additional sort expression, the order within each equal group is not deterministic.
It is only possible to sort on attributes. Trying to sort on an index or summary field, without an associated attribute, will not work.
Also note that match-phase is enabled when sorting.
When sorting on a single-value numeric attribute with fast-search
Vespa will by default activate an optimization which makes delivering sorted results much faster,
but with inaccurate total-hit count.
To disable this optimization,
set the query parameter sorting.degrading to false
(in the request or a query profile).
See the reference for details.
Sort by surname in ascending order:
+surname
Sort by surname in ascending order after lowercasing the surname:
+lowercase(surname)
Sort by surname in ascending English US locale collation order.
+uca(surname,en_US)
Sort by surname in ascending Norwegian 'Bokmål' locale collation order:
+uca(surname,nb_NO)
Sort by surname in ascending Norwegian 'Bokmål' locale collation order, but more attributes of a character are used to distinguish. Now it is case-sensitive and 'aa' and 'å' are different:
+uca(surname,nb_NO,TERTIARY)
Sort by surname, with the youngest ones first when the names are equal:
+surname -yearofbirth
Sort in ascending order yearofbirth groups, and sort by relevancy within each group of equal values with the highest relevance first:
+yearofbirth -[relevance]