Develop a JavaScript application for Cosmos DB with SQL API

To create or use Cosmos DB with the SQL API use a Cosmos DB resource. Learn how to create the Cosmos resource and use your database.

Locally develop with the CosmosDB emulator

Learn how to install the CosmosDB emulator and start the emulator for SQL API development.

Create a Cosmos DB resource for a SQL API database

You can create a resource with:

• Azure CLI
• Azure portal
• Visual Studio Code extension - Azure Databases

Create a Cosmos DB resource for SQL API

Use the following Azure CLI az cosmosdb create command in the Azure Cloud Shell to create a new Cosmos DB resource. This command may take a couple of minutes to complete.

az cosmosdb create \
--subscription YOUR-SUBSCRIPTION-ID-OR-NAME \
--resource-group YOUR-RESOURCE-GROUP \
--name YOUR-RESOURCE-NAME \
--kind YOUR-DB-KIND \
--ip-range-filter YOUR-CLIENT-IP

To enable firewall access from your local computer to your resource, replace 123.123.123.123 with your own client IP. To configure multiple IP addresses, use a comma-separated list.

Add firewall rule for your client IP address

If you need to add a client IP address to your resource after it is created so your client connection to the server with JavaScript is successful, use this procedure. Use the az cosmosdb update command to update the firewall rules.

az cosmosdb update \
    --subscription YOUR-SUBSCRIPTION-ID-OR-NAME \
    --resource-group YOUR-RESOURCE-GROUP \
    --name YOUR-RESOURCE_NAME \
    --ip-range-filter 123.123.123.123

To configure multiple IP addresses, use a comma-separated list.

az cosmosdb update \
    --subscription YOUR-SUBSCRIPTION-ID-OR-NAME \
    --resource-group YOUR-RESOURCE-GROUP \
    --name YOUR-RESOURCE_NAME \
    --ip-range-filter 123.123.123.123,456.456.456.456

Get the Cosmos DB keys for your resource

Retrieve the keys for this instance with the az cosmosdb keys list command:

az cosmosdb keys list \
    --subscription YOUR-SUBSCRIPTION-ID-OR-NAME \
    --resource-group YOUR-RESOURCE-GROUP \
    --name YOUR-RESOURCE-NAME

This returns 4 keys, 2 read-write and 2 read-only. There are two so that you can give 2 different systems or developers a key to use and recycle individually.

View and use your SQL API database on Azure Cosmos DB

While developing your SQL API database with JavaScript, use Cosmos explorer to work with your database.

The Cosmos explorer is also available in the Azure portal, for your resource, as the Data Explorer.

Use @azure/cosmos SDK to connect to database

Connect to your Azure Cosmos DB with SQL API using the following Azure SDK:

• @azure/cosmos

To connect and use your SQL API on Azure Cosmos DB with JavaScript, use the following procedure.

1. Make sure Node.js and npm are installed.

2. Create a Node.js project in a new folder:

   mkdir dataDemo && \
       cd dataDemo && \
       npm init -y && \
       npm install @azure/cosmos && \
       touch index.js && \
       code .
   

   The command:

   • creates a project folder named dataDemo
   • changes the Bash terminal into that folder
   • initializes the project, which creates the package.json file
   • creates the index.js script file
   • opens the project in Visual Studio Code

3. Copy the following JavaScript code into index.js:

   const CosmosClient = require("@azure/cosmos").CosmosClient;
   
   // CHANGE THESE VALUES
   const COSMOS_DB_RESOURCE_NAME = "YOUR-RESOURCE-NAME";
   const COSMOS_DB_RESOURCE_KEY = "YOUR-RESOURCE-KEY";
   
   let client = null;      // Cosmos DB SQL API connection object
   let db = null;          // DB object
   let container = null;   // Container object
   
   // data
   const DATABASE_DOCS = [
       { name: "Joe", job: "banking" },
       { name: "Jack", job: "security" },
       { name: "Jill", job: "pilot" }];
   
   const ALL_DOCS = null;
   
   // Azure Cosmos DB config
   const config = {
       COSMOSDB_SQL_API_URI: `https://${COSMOS_DB_RESOURCE_NAME}.documents.azure.com:443/`,
       COSMOSDB_SQL_API_KEY: COSMOS_DB_RESOURCE_KEY,
       COSMOSDB_SQL_API_DATABASE_NAME: "DemoDb",
       COSMOSDB_SQL_API_CONTAINER_NAME: "DemoContainer"
   }
   
   // Unique Id = Guid
   const newGuid = () => {
       const s4 = () => Math.floor((1 + Math.random()) * 0x10000).toString(16).substring(1);
       return `${s4() + s4()}-${s4()}-${s4()}-${s4()}-${s4() + s4() + s4()}`;
   }
   
   // insert array
   const insert = async (newItems) => {
   
       const results = [];
       for (const item of newItems) {
   
           item.id = newGuid();
           const result = await container.items.create(item);
           results.push(result.item);
       }
       return results;
   };
   // find all or by id
   const find = async (query) => {
   
       if (query == null) {
           query = "SELECT * from c"
       } else {
           query = `SELECT * from c where c.id = ${query}`
       }
   
       const result = await container.items
           .query(query)
           .fetchAll();
   
       return result && result.resources ? result.resources : [];
   }
   // remove all or by id
   const remove = async (id) => {
   
       // remove 1
       if (id) {
           await container.item(id).delete();
       } else {
   
           // get all items
           const items = await find();
   
           // remove all
           for await (const item of items) {
               await container.item(item.id).delete();
           }
       }
   
       return;
   }
   // connection with SDK
   const connect = () => {
       try {
   
           const connectToCosmosDB = {
               endpoint: config.COSMOSDB_SQL_API_URI,
               key: config.COSMOSDB_SQL_API_KEY
           }
   
           return new CosmosClient(connectToCosmosDB);
   
       } catch (err) {
           console.log('Cosmos DB SQL API - can\'t connected - err');
           console.log(err);
       }
   }
   const connectToDatabase = async () => {
   
       client = connect();
   
       if (client) {
   
           // get DB
           const databaseResult = await client.databases.createIfNotExists({ id: config.COSMOSDB_SQL_API_DATABASE_NAME });
           db = databaseResult.database;
   
           if (db) {
               // get Container
               const containerResult = await db.containers.createIfNotExists({ id: config.COSMOSDB_SQL_API_CONTAINER_NAME });
               container = containerResult.container;
               return !!db;
           }
       } else {
           throw new Error("can't connect to database");
       }
   
   
   }
   
   // use Database
   const dbProcess = async (docs) => {
   
       // connect
       const db = await connectToDatabase();
       if (!db) throw Error("db not working")
       console.log("connected to " + config.COSMOSDB_SQL_API_DATABASE_NAME + "/" + config.COSMOSDB_SQL_API_CONTAINER_NAME)
   
       // insert new docs
       const insertResult = await insert(docs);
       console.log("inserted " + insertResult.length)
   
       // get all docs
       const findResult = await find(ALL_DOCS);
       console.log("found " + findResult.length);
   
       // remove all then make sure they are gone
       await remove(ALL_DOCS);
       const findResult3 = await find(ALL_DOCS);
       console.log("removed all, now have " + findResult3.length);
   
       return;
   
   }
   
   dbProcess(DATABASE_DOCS)
   .then(() => {
       console.log("done")
   }).catch(err => {
       console.log(err)
   })
   

4. Replace the following variables in the script:

   • YOUR-RESOURCE-NAME - the name you used when creating your Cosmos DB resource
   • YOUR-RESOURCE-KEY - one of the read/write keys for your resource

5. Run the script.

   node index.js
   

   The results are:

   connected to DemoDb/DemoContainer4
   inserted 3
   found 3
   removed all, now have 0
   done
   

Next steps

• How to deploy a JavaScript web app
• Cosmos DB for SQL API documentation
• Cosmos DB for SQL API quickstart