You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
title: Working with arrays and objects in Azure Cosmos DB
3
-
description: Learn the SQL syntax to create arrays and objects in Azure Cosmos DB. This article also provides some examples to perform operations on array objects
4
-
author: seesharprun
2
+
title: Working with arrays and objects
3
+
titleSuffix: Azure Cosmos DB for NoSQL
4
+
description: Create arrays and objects and perform actions on them using the array syntax in Azure Cosmos DB for NoSQL.
5
+
author: jcodella
6
+
ms.author: jacodel
7
+
ms.reviewer: sidandrews
5
8
ms.service: cosmos-db
6
9
ms.subservice: nosql
7
-
ms.custom: ignite-2022
8
-
ms.topic: conceptual
9
-
ms.date: 02/02/2021
10
-
ms.author: sidandrews
11
-
ms.reviewer: jucocchi
10
+
ms.topic: reference
11
+
ms.date: 07/31/2023
12
+
ms.custom: query-reference
12
13
---
13
-
# Working with arrays and objects in Azure Cosmos DB
A key feature of the Azure Cosmos DB for NoSQL is array and object creation. This document uses examples that can be recreated using the [Family dataset](getting-started.md#upload-sample-data).
15
+
# Working with arrays and objects in Azure Cosmos DB for NoSQL
You can construct arrays, as shown in the following example:
39
+
You can construct arrays using static values, as shown in the following example.
45
40
46
41
```sql
47
-
SELECT [f.address.city, f.address.state] AS CityState
48
-
FROM Families f
42
+
SELECT
43
+
[p.priceInUSD, p.priceInCAD] AS priceData
44
+
FROM products p
49
45
```
50
46
51
-
The results are:
52
-
53
47
```json
54
48
[
55
49
{
56
-
"CityState": [
57
-
"Seattle",
58
-
"WA"
59
-
]
60
-
},
61
-
{
62
-
"CityState": [
63
-
"NY",
64
-
"NY"
50
+
"priceData": [
51
+
132.35,
52
+
174.5
65
53
]
66
54
}
67
55
]
68
56
```
69
57
70
-
You can also use the [ARRAY expression](subquery.md#array-expression) to construct an array from [subquery's](subquery.md) results. This query gets all the distinct given names of children in an array.
58
+
You can also use the [``ARRAY`` expression](subquery.md#array-expression) to construct an array from a [subquery's](subquery.md) results. This query gets all the distinct categories.
71
59
72
60
```sql
73
-
SELECTf.id, ARRAY(SELECT DISTINCT VALUE c.givenNameFROM c INf.children) as ChildNames
74
-
FROM f
61
+
SELECT
62
+
p.id,
63
+
ARRAY (SELECT DISTINCT VALUE c.nameFROM c INp.categories) AS categoryNames
64
+
FROM
65
+
products p
75
66
```
76
67
77
-
The results are:
78
-
79
68
```json
80
69
[
81
-
{
82
-
"id": "AndersenFamily",
83
-
"ChildNames": []
84
-
},
85
-
{
86
-
"id": "WakefieldFamily",
87
-
"ChildNames": [
88
-
"Jesse",
89
-
"Lisa"
90
-
]
91
-
}
70
+
{
71
+
"id": "a0151c77-ffc3-4fa6-a495-7b53d936faa6",
72
+
"categoryNames": [
73
+
"swim",
74
+
"gear"
75
+
]
76
+
}
92
77
]
93
78
```
94
79
95
-
## <aid="Iteration"></a>Iteration
96
-
97
-
The API for NoSQL provides support for iterating over JSON arrays, with the [IN keyword](keywords.md#in) in the FROM source. In the following example:
98
-
99
-
```sql
100
-
SELECT*
101
-
FROMFamilies.children
102
-
```
103
-
104
-
The results are:
80
+
## Iteration
105
81
106
-
```json
107
-
[
108
-
[
109
-
{
110
-
"firstName": "Henriette Thaulow",
111
-
"gender": "female",
112
-
"grade": 5,
113
-
"pets": [{ "givenName": "Fluffy"}]
114
-
}
115
-
],
116
-
[
117
-
{
118
-
"familyName": "Merriam",
119
-
"givenName": "Jesse",
120
-
"gender": "female",
121
-
"grade": 1
122
-
},
123
-
{
124
-
"familyName": "Miller",
125
-
"givenName": "Lisa",
126
-
"gender": "female",
127
-
"grade": 8
128
-
}
129
-
]
130
-
]
131
-
```
82
+
The API for NoSQL provides support for iterating over JSON arrays, with the [``IN`` keyword](keywords.md#in) in the ``FROM`` source.
132
83
133
-
The next query performs iteration over `children`in the `Families`container. The output array is different from the preceding query. This example splits `children`, and flattens the results into a single array:
84
+
As an example, the next query performs iteration over ``tags`` for each item in the container. The output splits the array value and flattens the results into a single array.
134
85
135
86
```sql
136
-
SELECT*
137
-
FROM c INFamilies.children
87
+
SELECT
88
+
*
89
+
FROM
90
+
products INproducts.categories
138
91
```
139
92
140
-
The results are:
141
-
142
93
```json
143
94
[
144
95
{
145
-
"firstName": "Henriette Thaulow",
146
-
"gender": "female",
147
-
"grade": 5,
148
-
"pets": [{ "givenName": "Fluffy" }]
149
-
},
150
-
{
151
-
"familyName": "Merriam",
152
-
"givenName": "Jesse",
153
-
"gender": "female",
154
-
"grade": 1
96
+
"name": "swim"
155
97
},
156
98
{
157
-
"familyName": "Miller",
158
-
"givenName": "Lisa",
159
-
"gender": "female",
160
-
"grade": 8
99
+
"name": "gear"
161
100
}
162
101
]
163
102
```
164
103
165
104
You can filter further on each individual entry of the array, as shown in the following example:
166
105
167
106
```sql
168
-
SELECTc.givenName
169
-
FROM c INFamilies.children
170
-
WHEREc.grade=8
107
+
SELECT VALUE
108
+
p.name
109
+
FROM
110
+
p INp.categories
111
+
WHERE
112
+
p.nameLIKE"ge%"
171
113
```
172
114
173
115
The results are:
174
116
175
117
```json
176
-
[{
177
-
"givenName": "Lisa"
178
-
}]
118
+
[
119
+
"gear"
120
+
]
179
121
```
180
122
181
-
You can also aggregate over the result of an array iteration. For example, the following query counts the number of children among all families:
123
+
You can also aggregate over the result of an array iteration. For example, the following query counts the number of tags:
182
124
183
125
```sql
184
-
SELECTCOUNT(1) AS Count
185
-
FROM child INFamilies.children
126
+
SELECT VALUE
127
+
COUNT(1)
128
+
FROM
129
+
p INp.categories
186
130
```
187
131
188
132
The results are:
189
133
190
134
```json
191
135
[
192
-
{
193
-
"Count": 3
194
-
}
136
+
2
195
137
]
196
138
```
197
139
198
140
> [!NOTE]
199
-
> When using the IN keyword for iteration, you cannot filter or project any properties outside of the array. Instead, you should use [JOINs](join.md).
200
-
201
-
For additional examples, read our [blog post on working with arrays in Azure Cosmos DB](https://devblogs.microsoft.com/cosmosdb/understanding-how-to-query-arrays-in-azure-cosmos-db/).
141
+
> When using the ``IN`` keyword for iteration, you cannot filter or project any properties outside of the array. Instead, you should use [self-joins](join.md).
202
142
203
143
## Next steps
204
144
205
-
-[Getting started](getting-started.md)
206
-
-[Azure Cosmos DB .NET samples](https://github.com/Azure/azure-cosmos-dotnet-v3)
In Azure Cosmos DB, queries may have multiple pages of results. This document explains criteria that Azure Cosmos DB's query engine uses to decide whether to split query results into multiple pages. You can optionally use continuation tokens to manage query results that span multiple pages.
19
+
In Azure Cosmos DB for NoSQL, queries may have multiple pages of results. This document explains criteria that Azure Cosmos DB for NoSQL's query engine uses to decide whether to split query results into multiple pages. You can optionally use continuation tokens to manage query results that span multiple pages.
18
20
19
21
## Understanding query executions
20
22
21
-
Sometimes query results will be split over multiple pages. Each page's results is generated by a separate query execution. When query results cannot be returned in one single execution, Azure Cosmos DB will automatically split results into multiple pages.
23
+
Sometimes query results are split over multiple pages. A separate query execution generates each page's results. When query results can't be returned in one single execution, Azure Cosmos DB for NoSQL automatically splits results into multiple pages.
22
24
23
-
You can specify the maximum number of items returned by a query by setting the `MaxItemCount`. The `MaxItemCount` is specified per request and tells the query engine to return that number of items or fewer. You can set `MaxItemCount` to `-1` if you don't want to place a limit on the number of results per query execution.
25
+
You can specify the maximum number of items returned by a query by setting the ``MaxItemCount``. The ``MaxItemCount`` is specified per request and tells the query engine to return that number of items or fewer. You can set ``MaxItemCount`` to ``-1`` if you don't want to place a limit on the number of results per query execution.
24
26
25
-
In addition, there are other reasons that the query engine might need to split query results into multiple pages. These include:
27
+
In addition, there are other reasons that the query engine might need to split query results into multiple pages. These reasons include:
26
28
27
29
- The container was throttled and there weren't available RUs to return more query results
28
30
- The query execution's response was too large
29
31
- The query execution's time was too long
30
-
- It was more efficient for the query engine to return results in additional executions
32
+
- It was more efficient for the query engine to return results in extra executions
31
33
32
-
The number of items returned per query execution will always be less than or equal to `MaxItemCount`. However, it is possible that other criteria might have limited the number of results the query could return. If you execute the same query multiple times, the number of pages might not be constant. For example, if a query is throttled there may be fewer available results per page, which means the query will have additional pages. In some cases, it is also possible that your query may return an empty page of results.
34
+
The number of items returned per query execution are less than or equal to ``MaxItemCount``. However, it's possible that other criteria might have limited the number of results the query could return. If you execute the same query multiple times, the number of pages might not be constant. For example, if a query is throttled there may be fewer available results per page, which means the query has extra pages. In some cases, it's also possible that your query may return an empty page of results.
33
35
34
36
## Handling multiple pages of results
35
37
36
-
To ensure accurate query results, you should progress through all pages. You should continue to execute queries until there are no additional pages.
38
+
To ensure accurate query results, you should progress through all pages. You should continue to execute queries until there are no extra pages.
37
39
38
40
Here are some examples for processing results from queries with multiple pages:
39
41
@@ -44,7 +46,7 @@ Here are some examples for processing results from queries with multiple pages:
44
46
45
47
## Continuation tokens
46
48
47
-
In the .NET SDK and Java SDK you can optionally use continuation tokens as a bookmark for your query's progress. Azure Cosmos DB query executions are stateless at the server side and can be resumed at any time using the continuation token. For the Python SDK, continuation tokens are only supported for single partition queries. The partition key must be specified in the options object because it's not sufficient to have it in the query itself.
49
+
In the .NET SDK and Java SDK, you can optionally use continuation tokens as a bookmark for your query's progress. Azure Cosmos DB for NoSQL query executions are stateless at the server side and can be resumed at any time using the continuation token. For the Python SDK, continuation tokens are only supported for single partition queries. The partition key must be specified in the options object because it's not sufficient to have it in the query itself.
48
50
49
51
Here are some example for using continuation tokens:
50
52
@@ -53,24 +55,26 @@ Here are some example for using continuation tokens:
If the query returns a continuation token, then there are additional query results.
58
+
If the query returns a continuation token, then there are extra query results.
57
59
58
-
In Azure Cosmos DB's REST API, you can manage continuation tokens with the `x-ms-continuation` header. As with querying with the .NET or Java SDK, if the `x-ms-continuation` response header is not empty, it means the query has additional results.
60
+
In Azure Cosmos DB for NoSQL's REST API, you can manage continuation tokens with the ``x-ms-continuation`` header. As with querying with the .NET or Java SDK, if the ``x-ms-continuation`` response header isn't empty, it means the query has extra results.
59
61
60
-
As long as you are using the same SDK version, continuation tokens never expire. You can optionally [restrict the size of a continuation token](/dotnet/api/microsoft.azure.documents.client.feedoptions.responsecontinuationtokenlimitinkb). Regardless of the amount of data or number of physical partitions in your container, queries return a single continuation token.
62
+
As long as you're using the same SDK version, continuation tokens never expire. You can optionally [restrict the size of a continuation token](/dotnet/api/microsoft.azure.documents.client.feedoptions.responsecontinuationtokenlimitinkb). Regardless of the amount of data or number of physical partitions in your container, queries return a single continuation token.
61
63
62
-
You cannot use continuation tokens for queries with [GROUP BY](group-by.md) or [DISTINCT](keywords.md#distinct) because these queries would require storing a significant amount of state. For queries with `DISTINCT`, you can use continuation tokens if you add `ORDER BY` to the query.
64
+
You can't use continuation tokens for queries with [GROUP BY](group-by.md) or [DISTINCT](keywords.md#distinct) because these queries would require storing a significant amount of state. For queries with ``DISTINCT``, you can use continuation tokens if you add ``ORDER BY`` to the query.
63
65
64
-
Here's an example of a query with `DISTINCT` that could use a continuation token:
66
+
Here's an example of a query with ``DISTINCT`` that could use a continuation token:
65
67
66
68
```sql
67
-
SELECT DISTINCT VALUE c.name
68
-
FROM c
69
-
ORDER BYc.name
69
+
SELECT DISTINCT VALUE
70
+
e.name
71
+
FROM
72
+
employees e
73
+
ORDER BY
74
+
e.name
70
75
```
71
76
72
77
## Next steps
73
78
74
-
-[Introduction to Azure Cosmos DB](../../introduction.md)
75
-
-[Azure Cosmos DB .NET samples](https://github.com/Azure/azure-cosmos-dotnet-v3)
0 commit comments