---
type: "fhirpath-function"
title: "FHIRPath Function: sort"
function: "sort"
category: "Filtering and projection"
section: "5.2.4"
source: "fhirpath/functions.json"
---
# FHIRPath Function: sort
{:.stu}
> **Note:** The contents of this section are Standard for Trial Use (STU)
{: .stu-note }

> This is a [scoped function](#scoped-functions): Each `keySelector` argument is evaluated for each item being compared (setting `$this` to the item for each evaluation). The results are compared to determine sort order. If there are multiple `keySelector` arguments, subsequent selectors are only evaluated for items where the previous `keySelector` comparison resulted in equality (i.e., the sort order hasn't been determined yet). This allows for multi-level sorting with minimal evaluations. <br/>As this function is used to modify the order of the collection the `$index` variable is undefined in this context, it could be anywhere during any evaluation depending on algorithms selected.
{:.stu}

Returns a collection containing the items in the input collection, sorted according to the specified key selector expressions. The function takes a variable number of key selector parameters, each of which can be optionally qualified with `asc` (ascending) or `desc` (descending). If no qualifier is provided, `asc` is the default.
{:.stu}

If no key selector parameters are provided, the sort uses the default ordering for the type of data in the input collection, using the same comparison semantics as defined for the equals (`=`) and comparison operators (`>`, `>=`, `<`, `<=`).
{:.stu}

Each key selector expression is evaluated for each item in the input collection using singleton evaluation semantics. If the key selector expression evaluates to a collection with more than one item, the evaluation will end and signal an error to the calling environment.
{:.stu}

comparing values returned by the no key selector using the same comparison semantics as defined for the equals (`=`) and comparison operators (`>`, `>=`, `<`, `<=`).
{:.stu}

An empty value is considered lower than all other values, meaning they will appear before others when sorted ascending.
{:.stu}

When comparing two items, if the values for the first key selector are equal, the comparison proceeds to the next key selector, and so on until all key selectors have been evaluated or a difference is found.
{:.stu}

Attempting to sort items with incompatible types will result in an error. Values that would result in comparison errors must be filtered from the collection prior to sorting.
{:.stu}

If the input collection is empty (`{ }`), the result is empty.
{:.stu}

The following examples illustrate the use of the `sort()` function:
{:.stu}

``` fhirpath
(3 | 1 | 2).sort() // (1 | 2 | 3) - natural numeric ordering
(3 | 1 | 2).sort($this) // (1 | 2 | 3) - explicit ascending
(3 | 1 | 2).sort($this desc) // (3 | 2 | 1) - descending
('c' | 'a' | 'b').sort() // ('a' | 'b' | 'c') - default string ordering
('c' | 'a' | 'b').sort($this desc) // ('c' | 'b' | 'a') - descending
Patient.name.sort(family desc, given.first()) // sort by family name descending, then by first given name ascending
Patient.telecom.sort(system, use desc) // sort by system ascending, then by use descending
```
{:.stu}

<a name="fn-repeat"></a>
## Summary
- **Category**: Filtering and projection
- **Section**: `5.2.4`
- **Return Type**: `collection`
- **Empty Input Result**: `empty`
- **Errors on Multiple Input**: `false`
## Description
Returns a collection containing the items in the input collection, sorted according to the specified key selector expressions. The function takes a variable number of key selector parameters, each of which can be optionally qualified with `asc` (ascending) or `desc` (descending). If no qualifier is provided, `asc` is the default.
## Arguments
- `keySelector` (optional): `expression` - Optional key selector expression with optional asc/desc qualifier
## Type Mapping
- `Any-Any`
## Example
```fhirpath
(3 | 1 | 2).sort() // (1 | 2 | 3) - natural numeric ordering
(3 | 1 | 2).sort($this) // (1 | 2 | 3) - explicit ascending
(3 | 1 | 2).sort($this desc) // (3 | 2 | 1) - descending
Patient.name.sort(family desc, given.first()) // sort by family name descending, then by first given name ascending
```