Skip to content

Commit 2ad71cf

Browse files
committed
Merge branch 'main' of https://github.com/MicrosoftDocs/azure-docs-pr into patch-2
2 parents bf12231 + cd0d776 commit 2ad71cf

8 files changed

+842
-1
lines changed

articles/advisor/advisor-release-notes.md

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,14 @@ ms.date: 04/18/2023
77
# What's new in Azure Advisor?
88

99
Learn what's new in the service. These items may be release notes, videos, blog posts, and other types of information. Bookmark this page to stay up to date with the service.
10+
## May 2023
11+
### Service retirement workbook
12+
13+
It is important to be aware of the upcoming Azure service and feature retirements to understand their impact on your workloads and plan migration. The [Service Retirement workbook](https://portal.azure.com/#view/Microsoft_Azure_Expert/AdvisorMenuBlade/~/workbooks) provides a single centralized resource level view of service retirements and helps you assess impact, evaluate options, and plan migration.
14+
The workbook includes 35 services and features planned for retirement. You can view planned retirement dates, list and map of impacted resources and get information to make the necessary actions.
15+
16+
To learn more, visit [Prepare migration of your workloads impacted by service retirements](advisor-how-to-plan-migration-workloads-service-retirement.md).
17+
1018
## April 2023
1119

1220
### VM/VMSS right-sizing recommendations with custom lookback period

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
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)
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)
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)