Azure SDK for JavaScript

Azure Cosmos DB SDK for JavaScript

This documentation provides a comprehensive guide to using the Azure Cosmos DB SDK for JavaScript. Leverage the power of Cosmos DB's globally distributed, multi-model database service directly from your JavaScript applications.

The SDK simplifies common operations like creating containers, managing items, querying data, and handling transactions, all with a clean, asynchronous API.

Getting Started

To begin using the Cosmos DB SDK, you first need to install the necessary packages:

npm install @azure/cosmos
# or
yarn add @azure/cosmos
                

Next, you'll need to create a CosmosClient instance. You can authenticate using either a connection string or by providing your account key and endpoint.

// Using a connection string (recommended)
const { CosmosClient } = require("@azure/cosmos");
const connectionString = "YOUR_COSMOS_DB_CONNECTION_STRING";
const client = new CosmosClient(connectionString);

// Or using account key and endpoint
// const endpoint = "YOUR_COSMOS_DB_ENDPOINT";
// const key = "YOUR_COSMOS_DB_KEY";
// const client = new CosmosClient({ endpoint, key });

console.log("CosmosClient initialized.");
                

Core Concepts

• Database Accounts: The top-level resource in Cosmos DB.
• Databases: Logical containers for collections and users.
• Containers: Resources that store JSON documents, Key-Value pairs, Graph data, or Column-family data. Each container is identified by a unique name.
• Items: The individual data entities stored within a container (e.g., JSON documents).
• Partition Keys: A logical property that dictates how data is distributed across physical partitions.
• Request Units (RUs): A normalized measure of throughput that represents the computational effort required to perform database operations.

Usage Examples

1. Creating a Database and Container

Demonstrates how to create a new database if it doesn't exist, and then create a container within that database.

async function createDatabaseAndContainer() {
    const { CosmosClient } = require("@azure/cosmos");
    const endpoint = "YOUR_COSMOS_DB_ENDPOINT";
    const key = "YOUR_COSMOS_DB_KEY";
    const client = new CosmosClient({ endpoint, key });

    const databaseId = "myDatabase";
    const containerId = "myContainer";
    const partitionKeyPath = ["/category"]; // Example partition key

    try {
        // Create database if it doesn't exist
        const { database } = await client.databases.createIfNotExists({ id: databaseId });
        console.log(`Database '${database.id}' created or already exists.`);

        // Create container if it doesn't exist
        const { container } = await database.containers.createIfNotExists({
            id: containerId,
            partitionKey: { paths: partitionKeyPath }
        });
        console.log(`Container '${container.id}' created or already exists.`);

    } catch (error) {
        console.error("Error creating database or container:", error);
    }
}

// createDatabaseAndContainer();
                

2. Inserting an Item

Shows how to add a new JSON document to a container.

async function createItem(containerId, databaseId, item) {
    const { CosmosClient } = require("@azure/cosmos");
    const endpoint = "YOUR_COSMOS_DB_ENDPOINT";
    const key = "YOUR_COSMOS_DB_KEY";
    const client = new CosmosClient({ endpoint, key });

    const database = client.database(databaseId);
    const container = database.container(containerId);

    try {
        const { resource: createdItem } = await container.items.create(item);
        console.log(`Item created: ${createdItem.id}`);
        return createdItem;
    } catch (error) {
        console.error("Error creating item:", error);
        throw error;
    }
}

// const newItem = { id: "product1", name: "Laptop", category: "Electronics", price: 1200 };
// createItem("myContainer", "myDatabase", newItem);
                

3. Querying Items

Illustrates how to execute a SQL query against a container.

async function queryItems(containerId, databaseId, query) {
    const { CosmosClient } = require("@azure/cosmos");
    const endpoint = "YOUR_COSMOS_DB_ENDPOINT";
    const key = "YOUR_COSMOS_DB_KEY";
    const client = new CosmosClient({ endpoint, key });

    const database = client.database(databaseId);
    const container = database.container(containerId);

    try {
        const { resources: results } = await container.items.query(query).fetchAll();
        console.log("Query results:", results);
        return results;
    } catch (error) {
        console.error("Error querying items:", error);
        throw error;
    }
}

// const sqlQuery = "SELECT * FROM c WHERE c.category = 'Electronics'";
// queryItems("myContainer", "myDatabase", sqlQuery);
                

API Reference

For detailed information on all available methods, classes, and types, please refer to the official API reference documentation.

This includes methods for:

• Managing Databases and Containers (create, read, update, delete)
• CRUD operations for Items
• Executing complex queries (SQL, Gremlin, MongoDB, Cassandra)
• Handling transactions and stored procedures
• Managing users and permissions
• Configuring client options for performance and resilience