Azure Cosmos DB SQL API Overview

Learn about the core concepts and features of the Azure Cosmos DB SQL API.

What is Azure Cosmos DB SQL API?

Azure Cosmos DB is a globally distributed, multi-model database service. The SQL API for Azure Cosmos DB provides a familiar, document database experience that leverages the popular SQL query language. It's designed for developers who are already familiar with SQL and want to build highly responsive, always-available applications.

Key Features and Concepts

1. Data Model: Documents

The SQL API stores data as JSON documents. These documents are schema-agnostic, meaning you don't need to predefine the structure of your data. Each document is a collection of key-value pairs.

2. Containers and Items

Data is organized into containers, which are logical groupings of items. In the SQL API, a container is analogous to a table in a relational database, but without a fixed schema. An item is a single JSON document within a container.

3. Databases

Containers are hosted within databases. A database is a management unit for a set of containers and provides namespace isolation.

4. Partitioning

To enable horizontal scalability, containers are partitioned. Each container has a partition key that determines how items are distributed across logical partitions. Choosing an effective partition key is crucial for performance and scalability.

5. Querying with SQL

The SQL API allows you to query your JSON documents using a familiar SQL syntax. You can perform operations like SELECT, FROM, WHERE, JOIN, GROUP BY, and ORDER BY on your data. The query engine is optimized for JSON data.

SELECT c.name, c.city FROM customers c WHERE c.country = 'USA' ORDER BY c.name ASC

6. Consistency Models

Azure Cosmos DB offers five well-defined consistency levels, allowing you to balance consistency, availability, and performance according to your application's needs:

7. Indexing

Azure Cosmos DB automatically indexes all data written to a container. The indexing policy can be customized to include or exclude paths and define indexing modes (consistent or lazy) for optimal performance.

8. Request Units (RUs)

Throughput in Azure Cosmos DB is provisioned and measured in Request Units (RUs). A RU is a normalized measure of the compute, memory, and I/O resources required to perform a database operation. You can provision throughput at the container or database level.

Note: Understanding partition keys and Request Units is fundamental to building scalable and performant applications with Azure Cosmos DB.

Getting Started

To get started with the Azure Cosmos DB SQL API, you'll typically need to:

  1. Create an Azure Cosmos DB account.
  2. Create a database within your account.
  3. Create a container within your database, defining its partition key.
  4. Start inserting JSON documents and querying them using the SQL API.

Explore the related documentation links in the sidebar to dive deeper into each of these aspects.

Important: The SQL API is one of many APIs offered by Azure Cosmos DB. If you require other data models (like MongoDB, Cassandra, Gremlin, or Table), consider the respective APIs.