Skip to content

Commit 0b85a8d

Browse files
v-dirichardsv-dirichards
authored
Merge pull request #238425 from diberry/diberry/feature/cosmosdb-nosql-dev-guide
Azure Cosmos DB no sql JS Dev Guide
2 parents 04c4878 + 97c9d31 commit 0b85a8d

6 files changed

+829
-0
lines changed

‎articles/cosmos-db/nosql/TOC.yml

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -432,6 +432,24 @@
432432
href: how-to-dotnet-read-item.md
433433
- name: Query items
434434
href: how-to-dotnet-query-items.md
435+
- name: JavaScript
436+
items:
437+
- name: Get started
438+
href: how-to-javascript-get-started.md
439+
- name: Work with databases
440+
items:
441+
- name: Create a database
442+
href: how-to-javascript-create-database.md
443+
- name: Work with containers
444+
items:
445+
- name: Create a container
446+
href: how-to-javascript-create-container.md
447+
- name: Work with items
448+
items:
449+
- name: Create an item
450+
href: how-to-javascript-create-item.md
451+
- name: Query items
452+
href: how-to-javascript-query-items.md
435453
- name: Python
436454
items:
437455
- name: Get started

‎articles/cosmos-db/nosql/how-to-javascript-create-container.md

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
---
2+
title: Create a container in Azure Cosmos DB for NoSQL using JavaScript
3+
description: Learn how to create a container in your Azure Cosmos DB for NoSQL account using the JavaScript SDK.
4+
author: seesharprun
5+
ms.author: sidandrews
6+
ms.service: cosmos-db
7+
ms.subservice: nosql
8+
ms.devlang: javascript
9+
ms.topic: how-to
10+
ms.date: 05/17/2023
11+
ms.custom: devx-track-js, cosmos-db-dev-journey
12+
---
13+
14+
# Create a container in Azure Cosmos DB for NoSQL using JavaScript
15+
16+
[!INCLUDE[NoSQL](../includes/appliesto-nosql.md)]
17+
18+
Containers in Azure Cosmos DB store sets of items. Before you can create, query, or manage items, you must first create a container.
19+
20+
## Name a container
21+
22+
In Azure Cosmos DB, a container is analogous to a table in a relational database. When you create a container, the container name forms a segment of the URI used to access the container resource and any child items.
23+
24+
Here are some quick rules when naming a container:
25+
26+
- Keep container names between 3 and 63 characters long
27+
- Container names can only contain lowercase letters, numbers, or the dash (-) character.
28+
- Container names must start with a lowercase letter or number.
29+
30+
Once created, the URI for a container is in this format:
31+
32+
``https://<cosmos-account-name>.documents.azure.com/dbs/<database-name>/colls/<container-name>``
33+
34+
## Create a container
35+
36+
Get a [Database](how-to-javascript-create-database.md) object, then create a [Container](/javascript/api/@azure/cosmos/container):
37+
38+
* [createIfNotExists](/javascript/api/@azure/cosmos/containers#@azure-cosmos-containers-createifnotexists) - Creates a container if it doesn't exist. If it does exist, return container.
39+
* [create](/javascript/api/@azure/cosmos/containers#@azure-cosmos-containers-create) - Creates a container. If it does exist, return error statusCode.
40+
41+
```javascript
42+
const containerName = 'myContainer';
43+
44+
// Possible results:
45+
// Create then return container
46+
// Return existing container
47+
// Return error statusCode
48+
const { statusCode, container } = await database.containers.createIfNotExists({ id: containerName });
49+
50+
// Possible results:
51+
// Create then return container
52+
// Return error statusCode, reason includes container already exists
53+
const { statusCode, container} = await database.containers.create({ id: containerName });
54+
```
55+
56+
The statusCode is an HTTP response code. A successful response is in the 200-299 range.
57+
58+
## Access a container
59+
60+
A container is accessed from the [Container](/javascript/api/@azure/cosmos/container) object either directly or chained from the [CosmosClient](/javascript/api/@azure/cosmos/cosmosclient) or [Database](/javascript/api/@azure/cosmos/database) objects.
61+
62+
```javascript
63+
const databaseName = 'myDb';
64+
const containerName = 'myContainer';
65+
66+
// Chained - assumes database and container already exis
67+
const { container, statusCode } = await client.database(databaseName).container(containerName);
68+
69+
// Direct - assumes database and container already exist
70+
const { database, statusCode } = await client.database(databaseName);
71+
if(statusCode < 400){
72+
const { container, statusCode } = await database.container(containerName);
73+
}
74+
75+
// Query - assumes database and container already exist
76+
const { resources } = await client.database(databaseName).containers
77+
.query({
78+
query: `SELECT * FROM root r where r.id =@containerId`,
79+
parameters: [
80+
{
81+
name: '@containerId',
82+
value: containerName
83+
}
84+
]
85+
})
86+
.fetchAll();
87+
```
88+
89+
Access by object:
90+
* [Containers](/javascript/api/@azure/cosmos/containers) (plural): Create or query containers.
91+
* [Container](/javascript/api/@azure/cosmos/container) (singular): Delete container, work with items.
92+
93+
94+
95+
## Delete a container
96+
97+
Once you get the [Container](/javascript/api/@azure/cosmos/container) object, you can use the Container object to [delete](/javascript/api/@azure/cosmos/container#@azure-cosmos-container-delete) the container:
98+
99+
```javascript
100+
const { statusCode } = await container.delete();
101+
```
102+
103+
The statusCode is an HTTP response code. A successful response is in the 200-299 range.
104+
105+
## Next steps
106+
107+
Now that you've create a container, use the next guide to create items.
108+
109+
> [!div class="nextstepaction"]
110+
> [Create an item](how-to-javascript-create-item.md)

‎articles/cosmos-db/nosql/how-to-javascript-create-database.md

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
---
2+
title: Create a database in Azure Cosmos DB for NoSQL using JavaScript
3+
description: Learn how to create a database in your Azure Cosmos DB for NoSQL account using the JavaScript SDK.
4+
author: seesharprun
5+
ms.author: sidandrews
6+
ms.service: cosmos-db
7+
ms.subservice: nosql
8+
ms.devlang: javascript
9+
ms.topic: how-to
10+
ms.date: 05/17/2023
11+
ms.custom: devx-track-js, cosmos-db-dev-journey
12+
---
13+
14+
# Create a database in Azure Cosmos DB for NoSQL using JavaScript
15+
16+
[!INCLUDE[NoSQL](../includes/appliesto-nosql.md)]
17+
18+
Databases in Azure Cosmos DB are units of management for one or more containers. Before you can create or manage containers, you must first create a database.
19+
20+
## Name a database
21+
22+
In Azure Cosmos DB, a database is analogous to a namespace. When you create a database, the database name forms a segment of the URI used to access the database resource and any child resources.
23+
24+
Here are some quick rules when naming a database:
25+
26+
- Keep database names between 3 and 63 characters long
27+
- Database names can only contain lowercase letters, numbers, or the dash (-) character.
28+
- Database names must start with a lowercase letter or number.
29+
30+
Once created, the URI for a database is in this format:
31+
32+
``https://<cosmos-account-name>.documents.azure.com/dbs/<database-name>``
33+
34+
## Create a database
35+
36+
Once you create the [CosmosClient](/javascript/api/@azure/cosmos/cosmosclient), use the client to create a [Database](/javascript/api/@azure/cosmos/database) from two different calls:
37+
38+
* [createIfNotExists](/javascript/api/@azure/cosmos/databases#@azure-cosmos-databases-createifnotexists) - Creates a database if it doesn't exist. If it does exist, return database.
39+
* [create](/javascript/api/@azure/cosmos/databases#@azure-cosmos-databases-create) - Creates a database. If it does exist, return error statusCode.
40+
41+
```javascript
42+
const databaseName = 'myDb';
43+
44+
// Possible results:
45+
// Create then return database
46+
// Return existing database
47+
// Return error statusCode
48+
const {statusCode, database } = await client.databases.createIfNotExists({ id: databaseName });
49+
50+
// Possible results:
51+
// Create then return database
52+
// Return error statusCode, reason includes database already exists
53+
const {statusCode, database } = await client.databases.create({ id: databaseName });
54+
```
55+
56+
The statusCode is an HTTP response code. A successful response is in the 200-299 range.
57+
58+
## Access a database
59+
60+
A database is accessed from the [Database](/javascript/api/@azure/cosmos/database) object either directly or through a query result from the [CosmosClient](/javascript/api/@azure/cosmos/cosmosclient).
61+
62+
```javascript
63+
const databaseName = 'myDb';
64+
65+
// Direct - assumes database already exists
66+
const { database, statusCode } = await client.database(databaseName);
67+
68+
// Query - assumes database already exists
69+
const { resources } = await client.databases
70+
.query({
71+
query: `SELECT * FROM root r where r.id =@dbId`,
72+
parameters: [
73+
{
74+
name: '@dbId',
75+
value: databaseName
76+
}
77+
]
78+
})
79+
.fetchAll();
80+
```
81+
82+
Access by object:
83+
* [Databases](/javascript/api/@azure/cosmos/databases) (plural): Used for creating new databases, or querying/reading all databases.
84+
* [Database](/javascript/api/@azure/cosmos/database) (singular): Used for reading, updating, or deleting an existing database by ID or accessing containers belonging to that database.
85+
86+
## Delete a database
87+
88+
Once you get the [Database](/javascript/api/@azure/cosmos/database) object, you can use the Database object to [delete](/javascript/api/@azure/cosmos/database#@azure-cosmos-database-delete) the database:
89+
90+
```javascript
91+
const {statusCode } = await database.delete();
92+
```
93+
94+
The statusCode is an HTTP response code. A successful response is in the 200-299 range.
95+
96+
## Next steps
97+
98+
Now that you've created a database, use the next guide to create containers.
99+
100+
> [!div class="nextstepaction"]
101+
> [Create a container](how-to-javascript-create-container.md)

‎articles/cosmos-db/nosql/how-to-javascript-create-item.md

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
---
2+
title: Create an item in Azure Cosmos DB for NoSQL using JavaScript
3+
description: Learn how to create an item in your Azure Cosmos DB for NoSQL account using the JavaScript SDK.
4+
author: seesharprun
5+
ms.author: sidandrews
6+
ms.service: cosmos-db
7+
ms.subservice: nosql
8+
ms.devlang: javascript
9+
ms.topic: how-to
10+
ms.date: 05/17/2023
11+
ms.custom: devx-track-js, cosmos-db-dev-journey
12+
---
13+
14+
# Create an item in Azure Cosmos DB for NoSQL using JavaScript
15+
16+
[!INCLUDE[NoSQL](../includes/appliesto-nosql.md)]
17+
18+
Items in Azure Cosmos DB represent a specific entity stored within a container. In the API for NoSQL, an item consists of JSON-formatted data with a unique identifier.
19+
20+
## Item, item definition, and item response
21+
22+
In the JavaScript SDK, the three objects related to an item have different purposes.
23+
24+
|Name|Operations|
25+
|--|--|
26+
|[Item](/javascript/api/@azure/cosmos/item)|Functionality including **Read**, **Patch**, **Replace**, **Delete**.|
27+
|[ItemDefinition](/javascript/api/@azure/cosmos/itemdefinition)|Your custom data object. Includes `id` and `ttl` properties automatically.|
28+
|[ItemResponse](/javascript/api/@azure/cosmos/itemresponse)|Includes `statusCode`, `item`, and other properties.|
29+
30+
Use the properties of the **ItemResponse** object to understand the result of the operation.
31+
32+
* **statusCode**: HTTP status code. A successful response is in the 200-299 range.
33+
* **activityId**: Unique identifier for the operation such as create, read, replace, or delete.
34+
* **etag**: Entity tag associated with the data. Use for optimistic concurrency, caching, and conditional requests.
35+
* **item**: [Item](/javascript/api/@azure/cosmos/item) object used to perform operations such as read, replace, delete.
36+
* **resource**: Your custom data.
37+
38+
## Create a unique identifier for an item
39+
40+
The unique identifier is a distinct string that identifies an item within a container. The ``id`` property is the only required property when creating a new JSON document. For example, this JSON document is a valid item in Azure Cosmos DB:
41+
42+
```json
43+
{
44+
"id": "unique-string-2309509"
45+
}
46+
```
47+
48+
Within the scope of a container, two items can't share the same unique identifier.
49+
50+
> [!IMPORTANT]
51+
> The ``id`` property is case-sensitive. Properties named ``ID``, ``Id``, ``iD``, and ``_id`` will be treated as an arbitrary JSON property.
52+
53+
Once created, the URI for an item is in this format:
54+
55+
``https://<cosmos-account-name>.documents.azure.com/dbs/<database-name>/docs/<item-resource-identifier>``
56+
57+
When referencing the item using a URI, use the system-generated *resource identifier* instead of the ``id`` field. For more information about system-generated item properties in Azure Cosmos DB for NoSQL, see [properties of an item](../resource-model.md#properties-of-an-item)
58+
59+
## Create an item
60+
61+
Create an item with the container's [items](/javascript/api/@azure/cosmos/container#@azure-cosmos-container-items) object using the [create](/javascript/api/@azure/cosmos/items) method.
62+
63+
```javascript
64+
const { statusCode, item, resource, activityId, etag} = await container.items.create({
65+
id: '2',
66+
category: 'gear-surf-surfboards',
67+
name: 'Sunnox Surfboard',
68+
quantity: 8,
69+
sale: true
70+
});
71+
```
72+
73+
## Access an item
74+
75+
Access an item through the [Item](/javascript/api/@azure/cosmos/item) object. This can accessed from the [Container](/javascript/api/@azure/cosmos/container) object or changed from either the [Database](/javascript/api/@azure/cosmos/database) or [CosmosClient](/javascript/api/@azure/cosmos/cosmosclient) objects.
76+
77+
```javascript
78+
// Chained, then use a method of the Item object such as `read`
79+
const { statusCode, item, resource, activityId, etag} = await client.database(databaseId).container(containerId).item(itemId).read();
80+
```
81+
82+
Access by object:
83+
* [Items](/javascript/api/@azure/cosmos/items) (plural): Create, batch, watch change feed, read all, upsert, or query items.
84+
* [Item](/javascript/api/@azure/cosmos/item) (singular): Read, patch, replace, or delete an item.
85+
86+
## Replace an item
87+
88+
Replace the data with the [Item](/javascript/api/@azure/cosmos/item) object with the [replace](/javascript/api/@azure/cosmos/item#@azure-cosmos-item-replace) method.
89+
90+
```javascript
91+
const { statusCode, item, resource, activityId, etag} = await item.replace({
92+
id: '2',
93+
category: 'gear-surf-surfboards-retro',
94+
name: 'Sunnox Surfboard Retro',
95+
quantity: 5,
96+
sale: false
97+
});
98+
```
99+
100+
## Read an item
101+
102+
Read the most current data with the [Item](/javascript/api/@azure/cosmos/item) object's [read](/javascript/api/@azure/cosmos/item#@azure-cosmos-item-read) method.
103+
104+
```javascript
105+
const { statusCode, item, resource, activityId, etag} = await item.read();
106+
```
107+
108+
## Delete an item
109+
110+
Delete the item with the [Item](/javascript/api/@azure/cosmos/item) object's' [delete](/javascript/api/@azure/cosmos/item#@azure-cosmos-item-read) method.
111+
112+
```javascript
113+
const { statusCode, item, activityId, etag} = await item.delete();
114+
```
115+
116+
## Next steps
117+
118+
Now that you've created various items, use the next guide to query for item.
119+
120+
> [!div class="nextstepaction"]
121+
> [Read an item](how-to-javascript-query-items.md)

0 commit comments

Comments
 (0)