Azure Cosmos DB – SQL API

The SQL API provides a rich, JSON‑document oriented query language to interact with data stored in Azure Cosmos DB. It enables you to execute familiar SQL‑like syntax against semi‑structured JSON while benefiting from global distribution, low latency, and automatic scaling.

Getting started

Below is a minimal example of creating a container and inserting a document using the .NET SDK.


// Install-Package Microsoft.Azure.Cosmos
using Microsoft.Azure.Cosmos;

var client = new CosmosClient("", "");
var database = await client.CreateDatabaseIfNotExistsAsync("SampleDB");
var container = await database.Database.CreateContainerIfNotExistsAsync(
    id: "Items",
    partitionKeyPath: "/category",
    throughput: 400);

var item = new { id = "001", name = "Cosmic Widget", category = "gadgets", price = 19.99 };
await container.Container.CreateItemAsync(item, new PartitionKey(item.category));
Read full tutorial

SQL query fundamentals

Cosmos DB's SQL query language supports SELECT, JOIN, aggregates, and sub‑queries. Below is an example that retrieves all items with a price greater than 10 and orders them by price descending.


SELECT c.id, c.name, c.price
FROM c
WHERE c.price > 10
ORDER BY c.price DESC

For more complex queries, see the Query language documentation.

Performance tips

  • Use appropriate partition keys to distribute load.
  • Leverage indexed paths to speed up queries.
  • Prefer parameterized queries to avoid injection and improve query plan reuse.
  • Enable throughput autoscale for variable workloads.