order-by Clause: Sort Results
Description
Sorts the returned items.
Applies To
GET method called on entity collections.
Does not apply to GET operations on individual entities. For example, the order-by clause in this query has no effect:
../tests/135?order-by={status[ASC];name[DESC]}
Remarks and examples
If the order-by clause is not used, the collection is sorted by entity ID.
If an order-by field is a reference field, the reference value is used.
Example: In the
tests?order-by={parent-id[DESC]}
clause, parent-id is a reference to a subject folder. The results are sorted by the value of the referenced item, the subject name, and not by the numeric value of the ID.
You can sort returned results by any fields of the entity.
Example: The
tests?order-by={status;name}
clause sorts the returned tests by the Status and Name fields.You can sort by fields in another entity type using aliases.
Example: In the
tests?fields=id,name,test-folder.id,test-folder.name&order-by={test-folder.name[ASC]}
clause, test-folder is an alias for test folders.Do not use more than one alias to reference to the same entity type. For example, in the
tests?order-by=contains-test-folder.name;test-folder.id
query, both thetest-folder
alias and thecontains-test-folder
alias refer to test folders. The query does not return your intended results. For more information about aliases, see Relations.Sorting direction. The default direction is ASC (ascending). If you do not specify the sorting direction, the default direction is used. If you want descending sorting, use DESC per order-by field.
Example: The
tests?order-by={status;name[DESC]}
clause sorts the returned defects by Status in ascending order and by Name in descending order.Case sensitivity. By default, case sensitivity of order-by fields is determined by the database settings. If you want case-insensitive sorting, use CI per order-by field.
Example: In the
tests?order-by={status;name[DESC,CI]}
clause, the case sensitivity of sorting by Status is determined by the database settings, and the sorting by Name is case insensitive.
Use logical names to identify the fields. See Field Names.