Skip to content

Commit 3d780c3

Browse files
seesharprunseesharprun
committed
Add ORDER BY 
1 parent eb3c1d1 commit 3d780c3

File tree

1 file changed

+42
-104
lines changed

1 file changed

+42
-104
lines changed

‎articles/cosmos-db/nosql/query/order-by.md‎

Lines changed: 42 additions & 104 deletions
Original file line numberDiff line numberDiff line change
@@ -1,134 +1,72 @@
11
---
2-
title: ORDER BY clause in Azure Cosmos DB
3-
description: Learn about SQL ORDER BY clause for Azure Cosmos DB. Use SQL as an Azure Cosmos DB JSON query language.
4-
author: seesharprun
2+
title: ORDER BY
3+
titleSuffix: Azure Cosmos DB for NoSQL
4+
description: An Azure Cosmos DB for NoSQL clause that specifies a sort order for the query results.
5+
author: jcodella
6+
ms.author: jacodel
7+
ms.reviewer: sidandrews
58
ms.service: cosmos-db
69
ms.subservice: nosql
7-
ms.custom: ignite-2022
8-
ms.topic: conceptual
9-
ms.date: 04/27/2022
10-
ms.author: sidandrews
11-
ms.reviewer: jucocchi
10+
ms.topic: reference
11+
ms.date: 07/31/2023
12+
ms.custom: query-reference
1213
---
13-
# ORDER BY clause in Azure Cosmos DB
14+
15+
# ORDER BY (NoSQL query)
16+
1417
[!INCLUDE[NoSQL](../../includes/appliesto-nosql.md)]
1518

16-
The optional `ORDER BY` clause specifies the sorting order for results returned by the query.
19+
The optional ``ORDER BY`` clause specifies the sorting order for results returned by the query.
1720

1821
## Syntax
19-
20-
```sql
22+
23+
```sql
2124
ORDER BY <sort_specification>
2225
<sort_specification> ::= <sort_expression> [, <sort_expression>]
23-
<sort_expression> ::= {<scalar_expression> [ASC | DESC]} [ ,...n ]
26+
<sort_expression> ::= {<scalar_expression> [ASC | DESC]} [ ,...n ]
2427
```
2528

2629
## Arguments
27-
28-
- `<sort_specification>`
29-
30-
Specifies a property or expression on which to sort the query result set. A sort column can be specified as a name or property alias.
31-
32-
Multiple properties can be specified. Property names must be unique. The sequence of the sort properties in the `ORDER BY` clause defines the organization of the sorted result set. That is, the result set is sorted by the first property and then that ordered list is sorted by the second property, and so on.
33-
34-
The property names referenced in the `ORDER BY` clause must correspond to either a property in the select list or to a property defined in the collection specified in the `FROM` clause without any ambiguities.
35-
36-
- `<sort_expression>`
37-
38-
Specifies one or more properties or expressions on which to sort the query result set.
39-
40-
- `<scalar_expression>`
41-
42-
See the [Scalar expressions](scalar-expressions.md) section for details.
43-
44-
- `ASC | DESC`
45-
46-
Specifies that the values in the specified column should be sorted in ascending or descending order. `ASC` sorts from the lowest value to highest value. `DESC` sorts from highest value to lowest value. `ASC` is the default sort order. Null values are treated as the lowest possible values.
47-
48-
## Remarks
49-
50-
The `ORDER BY` clause requires that the indexing policy include an index for the fields being sorted. The Azure Cosmos DB query runtime supports sorting against a property name or [computed properties](./computed-properties.md). Azure Cosmos DB supports multiple `ORDER BY` properties. In order to run a query with multiple ORDER BY properties, you should define a [composite index](../../index-policy.md#composite-indexes) on the fields being sorted.
5130

52-
> [!Note]
53-
> If the properties being sorted might be undefined for some documents and you want to retrieve them in an ORDER BY query, you must explicitly include this path in the index. The default indexing policy won't allow for the retrieval of the documents where the sort property is undefined. [Review example queries on documents with some missing fields](#documents-with-missing-fields).
31+
| | Description |
32+
| --- | --- |
33+
| **``<sort_specification>``** | Specifies a property or expression on which to sort the query result set. A sort column can be specified as a name or property alias. Multiple properties can be specified. Property names must be unique. The sequence of the sort properties in the ``ORDER BY`` clause defines the organization of the sorted result set. That is, the result set is sorted by the first property and then that ordered list is sorted by the second property, and so on. The property names referenced in the ``ORDER BY`` clause must correspond to either a property in the select list or to a property defined in the collection specified in the ``FROM`` clause without any ambiguities. |
34+
| **``<sort_expression>``** | Specifies one or more properties or expressions on which to sort the query result set. |
35+
| **``<scalar_expression>``** | Expression representing the value to be computed. |
36+
| **``ASC`` or ``DESC``** | Specifies that the values in the specified column should be sorted in ascending or descending order. ``ASC`` sorts from the lowest value to highest value. ``DESC`` sorts from highest value to lowest value. If this argument isn't specified, ``ASC`` (ascending) is the default sort order. ``null`` values are treated as the lowest possible values. |
37+
38+
> [!NOTE]
39+
> For more information on scalar expressions, see [scalar expressions](scalar-expressions.md)
5440
5541
## Examples
5642

57-
For example, here's a query that retrieves families in ascending order of the resident city's name:
43+
For the examples in this section, this reference set of items is used. Each item contains a `name` property with `first` and `last` subproperties.
5844

59-
```sql
60-
SELECT f.id, f.address.city
61-
FROM Families f
62-
ORDER BY f.address.city
63-
```
64-
65-
The results are:
66-
67-
```json
68-
[
69-
{
70-
"id": "WakefieldFamily",
71-
"city": "NY"
72-
},
73-
{
74-
"id": "AndersenFamily",
75-
"city": "Seattle"
76-
}
77-
]
78-
```
79-
80-
The following query retrieves family `id`s in order of their item creation date. Item `creationDate` is a number representing the *epoch time*, or elapsed time since Jan. 1, 1970 in seconds.
45+
:::code language="json" source="~/cosmos-db-nosql-query-samples/scripts/order-by/seed.json" range="1-2,4-10,12-18,20-26" highlight="3-6,10-13,17-20":::
8146

82-
```sql
83-
SELECT f.id, f.creationDate
84-
FROM Families f
85-
ORDER BY f.creationDate DESC
86-
```
87-
88-
The results are:
89-
90-
```json
91-
[
92-
{
93-
"id": "AndersenFamily",
94-
"creationDate": 1431620472
95-
},
96-
{
97-
"id": "WakefieldFamily",
98-
"creationDate": 1431620462
99-
}
100-
]
101-
```
102-
103-
Additionally, you can order by multiple properties. A query that orders by multiple properties requires a [composite index](../../index-policy.md#composite-indexes). Consider the following query:
47+
In this first example, the ``ORDER BY`` clause is used to sort a field by the default sort order, ascending.
10448

105-
```sql
106-
SELECT f.id, f.creationDate
107-
FROM Families f
108-
ORDER BY f.address.city ASC, f.creationDate DESC
109-
```
49+
:::code language="sql" source="~/cosmos-db-nosql-query-samples/scripts/order-by/query.sql" range="1-6,9-10" highlight="7-8":::
11050

111-
This query retrieves the family `id` in ascending order of the city name. If multiple items have the same city name, the query will order by the `creationDate` in descending order.
51+
:::code language="json" source="~/cosmos-db-nosql-query-samples/scripts/order-by/result.json":::
11252

113-
## Documents with missing fields
53+
In this next example, the sort order is explicitly specified to be descending.
11454

115-
Queries with `ORDER BY` will return all items, including items where the property in the ORDER BY clause isn't defined.
55+
:::code language="sql" source="~/cosmos-db-nosql-query-samples/scripts/order-by-desc/query.sql" range="1-6,9-10" highlight="7-8":::
11656

117-
For example, if you run the below query that includes `lastName` in the `Order By` clause, the results will include all items, even those that don't have a `lastName` property defined.
57+
:::code language="json" source="~/cosmos-db-nosql-query-samples/scripts/order-by-desc/result.json":::
11858

119-
```sql
120-
SELECT f.id, f.lastName
121-
FROM Families f
122-
ORDER BY f.lastName
123-
```
59+
In this final example, the items are sorted using two fields, in a specific order using explicitly specified ordering. A query that sorts using two or more fields requires a [composite index](../../index-policy.md#composite-indexes).
60+
61+
:::code language="sql" source="~/cosmos-db-nosql-query-samples/scripts/order-by-multiple/query.sql" range="1-6,9-11" highlight="7-9":::
12462

125-
> [!Note]
126-
> Only the .NET SDK 3.4.0 or later and Java SDK 4.13.0 or later support ORDER BY with mixed types. Therefore, if you want to sort by a combination of undefined and defined values, you should use this version (or later).
63+
## Remarks
12764

128-
You can't control the order that different types appear in the results. In the above example, we showed how undefined values were sorted before string values. If instead, for example, you wanted more control over the sort order of undefined values, you could assign any undefined properties a string value of "aaaaaaaaa" or "zzzzzzzz" to ensure they were either first or last.
65+
- Queries with ``ORDER BY`` return all items, including items where the property in the ORDER BY clause isn't defined. Typically, you can't control the order that different ``undefined`` types appear in the results. To control the sort order of undefined values, assign any ``undefined`` properties an arbitrary value to ensure they sort either before or after the defined values.
66+
- The ``ORDER BY`` clause requires that the indexing policy includes an index for the fields being sorted. The query runtime supports sorting against a property name or [computed properties](./computed-properties.md). The runtime also supports multiple ``ORDER BY`` properties. In order to run a query with multiple ``ORDER BY`` properties, define a [composite index](../../index-policy.md#composite-indexes) on the fields being sorted.
67+
- If the properties being sorted might be ``undefined`` for some items and you want to retrieve them in an ``ORDER BY`` query, you must explicitly include this path in the index. The default indexing policy doesn't allow for the retrieval of the items where the sort property is ``undefined``.
12968

13069
## Next steps
13170

132-
- [Getting started](getting-started.md)
133-
- [Indexing policies in Azure Cosmos DB](../../index-policy.md)
134-
- [OFFSET LIMIT clause](offset-limit.md)
71+
- [``GROUP BY`` clause](group-by.md)
72+
- [``OFFSET LIMIT`` clause](offset-limit.md)

0 commit comments

Comments
 (0)