Create and update documents with the Azure Cosmos DB for NoSQL SDK

The @azure/cosmos library includes methods to create, retrieve, update, and delete (CRUD) items within an Azure Cosmos DB for NoSQL container. Together, these methods perform some of the most common “CRUD” operations across various items within NoSQL API containers.

In this lab, you’ll use the JavaScript SDK to perform everyday CRUD operations on an item within an Azure Cosmos DB for NoSQL container.

Prepare your development environment

If you have not already cloned the lab code repository for Build copilots with Azure Cosmos DB and set up your local environment, view the Setup local lab environment instructions to do so.

Create an Azure Cosmos DB for NoSQL account

If you already created an Azure Cosmos DB for NoSQL account for the Build copilots with Azure Cosmos DB labs on this site, you can use it for this lab and skip ahead to the next section. Otherwise, view the Setup Azure Cosmos DB instructions to create an Azure Cosmos DB for NoSQL account that you will use throughout the lab modules and grant your user identity access to manage data in the account by assigning it to the Cosmos DB Built-in Data Contributor role.

Import the @azure/cosmos library

The @azure/cosmos library is available on npm for easy installation into your JavaScript projects.

  1. In Visual Studio Code, in the Explorer pane, browse to the javascript/03-sdk-crud folder.

  2. Open the context menu for the javascript/03-sdk-crud folder and then select Open in Integrated Terminal to open a new terminal instance.

    📝 This command will open the terminal with the starting directory already set to the javascript/03-sdk-crud folder.

  3. Initialize a new Node.js project:

     npm init -y

  4. Install the @azure/cosmos package using the following command:

     npm install @azure/cosmos

  5. Install the @azure/identity library, which allows us to use Azure authentication to connect to the Azure Cosmos DB workspace, using the following command:

     npm install @azure/identity

Use the @azure/cosmos library

Once the Azure Cosmos DB library from the Azure SDK for JavaScript has been imported, you can immediately use its classes to connect to an Azure Cosmos DB for NoSQL account. The CosmosClient class is the core class used to make the initial connection to an Azure Cosmos DB for NoSQL account.

  1. In Visual Studio Code, in the Explorer pane, browse to the javascript/03-sdk-crud folder.

  2. Open the empty JavaScript file named script.js.

  3. Add the following require statements to import the @azure/cosmos and @azure/identity libraries:

     const { CosmosClient } = require("@azure/cosmos");
 const { DefaultAzureCredential  } = require("@azure/identity");
 process.env.NODE_TLS_REJECT_UNAUTHORIZED = 0

  4. Add variables named endpoint and credential and set the endpoint value to the endpoint of the Azure Cosmos DB account you created earlier. The credential variable should be set to a new instance of the DefaultAzureCredential class:

     const endpoint = "<cosmos-endpoint>";
 const credential = new DefaultAzureCredential();

    📝 For example, if your endpoint is: https://dp420.documents.azure.com:443/, the statement would be: const endpoint = “https://dp420.documents.azure.com:443/”;.

  5. Add a new variable named client and initialize it as a new instance of the CosmosClient class using the endpoint and credential variables:

     const client = new CosmosClient({ endpoint, aadCredentials: credential });

  6. Add the following code to create a database and container if they do not already exist:

     async function main() {
     // Create database
     const { database } = await client.databases.createIfNotExists({ id: "cosmicworks" });
        
     // Create container
     const { container } = await database.containers.createIfNotExists({
         id: "products",
         partitionKey: { paths: ["/categoryId"] },
         throughput: 400
     });
 }
    
 main().catch((error) => console.error(error));

  7. Your script.js file should now look like this:

     const { CosmosClient } = require("@azure/cosmos");
 const { DefaultAzureCredential  } = require("@azure/identity");
 process.env.NODE_TLS_REJECT_UNAUTHORIZED = 0

 const endpoint = "<cosmos-endpoint>";
 const credential = new DefaultAzureCredential();

 const client = new CosmosClient({ endpoint, aadCredentials: credential });

 async function main() {
     // Create database
     const { database } = await client.databases.createIfNotExists({ id: "cosmicworks" });
        
     // Create container
     const { container } = await database.containers.createIfNotExists({
         id: "products",
         partitionKey: { paths: ["/categoryId"] },
         throughput: 400
     });
 }
    
 main().catch((error) => console.error(error));

  8. Save the script.js file.

  9. Before running the script, you must log into Azure using the az login command. At the terminal window, run:

     az login

  10. Run the script to create the database and container:

     node script.js

  11. Switch to your web browser window.

  12. Within the Azure Cosmos DB account resource, navigate to the Data Explorer pane.

  13. In the Data Explorer, expand the cosmicworks database node, then observe the new products container node within the NOSQL API navigation tree.

Perform create and read point operations on items with the SDK

You will now use the set of methods in the Container class to perform common operations on items within a NoSQL API container.

  1. Return to Visual Studio Code. If it is not still open, open the script.js code file within the javascript/03-sdk-crud folder.

  2. Create a new product item and assign it to a variable named saddle with the following properties. Make sure you add the following code into the main function:

    Property Value
    id 706cd7c6-db8b-41f9-aea2-0e0c7e8eb009
    categoryId 9603ca6c-9e28-4a02-9194-51cdb7fea816
    name Road Saddle
    price 45.99d
    tags { tan, new, crisp } 
     const saddle = {
     id: "706cd7c6-db8b-41f9-aea2-0e0c7e8eb009",
     categoryId: "9603ca6c-9e28-4a02-9194-51cdb7fea816",
     name: "Road Saddle",
     price: 45.99,
     tags: ["tan", "new", "crisp"]
 };

  3. Invoke the create method of the container’s items class, passing in the saddle variable as the method parameter:

     const { resource: item } = await container
     .items.create(saddle);

  4. Once you are done, your code file should now include:

     const { CosmosClient } = require("@azure/cosmos");
 const { DefaultAzureCredential  } = require("@azure/identity");
 process.env.NODE_TLS_REJECT_UNAUTHORIZED = 0

 const endpoint = "<cosmos-endpoint>";
 const credential = new DefaultAzureCredential();

 const client = new CosmosClient({ endpoint, aadCredentials: credential });

 async function main() {
     // Create database
     const { database } = await client.databases.createIfNotExists({ id: "cosmicworks" });
            
     // Create container
     const { container } = await database.containers.createIfNotExists({
         id: "products",
         partitionKey: { paths: ["/categoryId"] },
         throughput: 400
     });
    
     const saddle = {
         id: "706cd7c6-db8b-41f9-aea2-0e0c7e8eb009",
         categoryId: "9603ca6c-9e28-4a02-9194-51cdb7fea816",
         name: "Road Saddle",
         price: 45.99,
         tags: ["tan", "new", "crisp"]
     };
    
     const { resource: item } = await container
             .items.create(saddle);
 }
    
 main().catch((error) => console.error(error));

  5. Save and run the script again:

     node script.js

  6. Observe the new item in the Data Explorer.

  7. Return to Visual Studio Code.

  8. Return to the editor tab for the script.js code file.

  9. Delete the following lines of code:

     const saddle = {
     id: "706cd7c6-db8b-41f9-aea2-0e0c7e8eb009",
     categoryId: "9603ca6c-9e28-4a02-9194-51cdb7fea816",
     name: "Road Saddle",
     price: 45.99,
     tags: ["tan", "new", "crisp"]
 };

 const { resource: item } = await container
         .items.create(saddle);

  10. Create a string variable named item_id with a value of 706cd7c6-db8b-41f9-aea2-0e0c7e8eb009:

     const itemId = "706cd7c6-db8b-41f9-aea2-0e0c7e8eb009";

  11. Create a string variable named partition_key with a value of 9603ca6c-9e28-4a02-9194-51cdb7fea816:

     const partitionKey = "9603ca6c-9e28-4a02-9194-51cdb7fea816";

  12. Invoke the read method of the container’s item class, passing in the itemId and partitionKey variables as the method parameters:

     // Read the item
 const { resource: saddle } = await container.item(itemId, partitionKey).read();

    💡 The read method allows you to perform a point read operation on an item in the container. The method requires the itemId and partitionKey parameters to identify the item to read. As opposed to executing a query using Cosmos DB’s SQL query language to find the single item, the read method is more efficient and cost-effective way to retrieve a single item. Point reads can read the data directly and don’t require the query engine to process the request.

  13. Print the saddle object using a formatted output string:

     print(f'[{saddle["id"]}]\t{saddle["name"]} ({saddle["price"]})')

  14. Once you are done, your code file should now include:

     const { CosmosClient } = require("@azure/cosmos");
 const { DefaultAzureCredential  } = require("@azure/identity");
 process.env.NODE_TLS_REJECT_UNAUTHORIZED = 0

 const endpoint = "<cosmos-endpoint>";
 const credential = new DefaultAzureCredential();

 const client = new CosmosClient({ endpoint, aadCredentials: credential });

 async function main() {
     // Create database
     const { database } = await client.databases.createIfNotExists({ id: "cosmicworks" });
            
     // Create container
     const { container } = await database.containers.createIfNotExists({
         id: "products",
         partitionKey: { paths: ["/categoryId"] },
         throughput: 400
     });
    
     const itemId = "706cd7c6-db8b-41f9-aea2-0e0c7e8eb009";
     const partitionKey = "9603ca6c-9e28-4a02-9194-51cdb7fea816";
    
     // Read the item
     const { resource: saddle } = await container.item(itemId, partitionKey).read();
    
     console.log(`[${saddle.id}]\t${saddle.name} (${saddle.price})`);
 }
    
 main().catch((error) => console.error(error));

  15. Save and run the script again:

     node script.js

  16. Observe the output from the terminal. Specifically, observe the formatted output text with the id, name, and price from the item.

Perform update and delete point operations with the SDK

While learning the SDK, it’s not uncommon to use an online Azure Cosmos DB account or the emulator to update an item and oscillate back-and-forth between the Data Explorer and your IDE of choice as you perform an operation and check to see if your change has been applied. Here, you will do just that as you update and delete an item using the SDK.

  1. Return to your web browser window or tab.

  2. Within the Azure Cosmos DB account resource, navigate to the Data Explorer pane.

  3. In the Data Explorer, expand the cosmicworks database node, then expand the new products container node within the NOSQL API navigation tree.

  4. Select the Items node. Select the only item within the container and then observe the values of the name and price properties of the item.

    Property Value
    Name Road Saddle
    Price $45.99

    📝 At this point in time, these values should not have been changed since you have created the item. You will change these values in this exercise.

  5. Return to Visual Studio Code. Return to the editor tab for the script.js code file.

  6. Delete the following line of code:

     console.log(`[${saddle.id}]\t${saddle.name} (${saddle.price})`);

  7. Change the saddle variable by setting the value of the price property to 32.55:

     // Update the item
 saddle.price = 32.55;

  8. Modify the saddle variable again by setting the value of the name property to Road LL Saddle:

     saddle.name = "Road LL Saddle";

  9. Invoke the replace method of the container’s item class, passing in the saddle variable as a method parameter:

     await container.item(saddle.id, partitionKey).replace(saddle);

  10. Once you are done, your code file should now include:

     const { CosmosClient } = require("@azure/cosmos");
 const { DefaultAzureCredential  } = require("@azure/identity");
 process.env.NODE_TLS_REJECT_UNAUTHORIZED = 0

 const endpoint = "<cosmos-endpoint>";
 const credential = new DefaultAzureCredential();

 const client = new CosmosClient({ endpoint, aadCredentials: credential });

 async function main() {
     // Create database
     const { database } = await client.databases.createIfNotExists({ id: "cosmicworks" });
            
     // Create container
     const { container } = await database.containers.createIfNotExists({
         id: "products",
         partitionKey: { paths: ["/categoryId"] },
         throughput: 400
     });
    
     const itemId = "706cd7c6-db8b-41f9-aea2-0e0c7e8eb009";
     const partitionKey = "9603ca6c-9e28-4a02-9194-51cdb7fea816";
    
     // Read the item
     const { resource: saddle } = await container.item(itemId, partitionKey).read();

     // Update the item
     saddle.price = 32.55;
     saddle.name = "Road LL Saddle";
    
     await container.item(saddle.id, partitionKey).replace(saddle);
 }
    
 main().catch((error) => console.error(error));

  11. Save and run the script again:

     node script.js

  12. Return to your web browser window or tab.

  13. Within the Azure Cosmos DB account resource, navigate to the Data Explorer pane.

  14. In the Data Explorer, expand the cosmicworks database node, then expand the new products container node within the NOSQL API navigation tree.

  15. Select the Items node. Select the only item within the container and then observe the values of the name and price properties of the item.

    Property Value
    Name Road LL Saddle
    Price $32.55

    📝 At this point in time, these values should have been changed since you have observed the item.

  16. Return to Visual Studio Code. Return to the editor tab for the script.js code file.

  17. Delete the following lines of code:

     // Read the item
 const { resource: saddle } = await container.item(itemId, partitionKey).read();

 // Update the item
 saddle.price = 32.55;
 saddle.name = "Road LL Saddle";

 await container.item(saddle.id, partitionKey).replace(saddle);

  18. Invoke the delete method of the container’s item class, passing in the itemId and partitionKey variables as method parameters:

     // Delete the item
 await container.item(itemId, partitionKey).delete();

  19. Save and run the script again:

     node script.js

  20. Close the integrated terminal.

  21. Return to your web browser window or tab.

  22. Within the Azure Cosmos DB account resource, navigate to the Data Explorer pane.

  23. In the Data Explorer, expand the cosmicworks database node, then expand the new products container node within the NOSQL API navigation tree.

  24. Select the Items node. Observe that the items list is now empty.

  25. Close your web browser window or tab.

  26. Close Visual Studio Code.