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 the test-folder alias and the contains-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.