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:

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.

Use the Cosmos explorer, found at https://cosmos.azure.com/, to view and 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:

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