Items and Documents in Azure Cosmos DB

Azure Cosmos DB is a globally distributed, multi-model database service. It supports document, key-value, graph, and column-family data models. This article focuses on the fundamental building blocks of the document data model: items and documents.

What are Items and Documents?

In Azure Cosmos DB's SQL (Core) API, the term item is used to refer to a single record within a container. Items are typically represented as JSON documents. A document is a collection of key-value pairs, attributes, and their corresponding values. Documents can be nested, and the values can be primitive types, arrays, or even other JSON documents.

Think of it this way:

• Container: A collection of items (analogous to a table in a relational database or a collection in MongoDB).
• Item: A single record within a container.
• Document: The JSON representation of an item.

JSON Structure of Items

Items in Azure Cosmos DB are schemaless, meaning you can store documents with varying structures within the same container. Each item is a JSON object. Here's a simple example of an item:

{
    "id": "abc-123-xyz",
    "productName": "Azure Cosmos DB T-Shirt",
    "category": "Apparel",
    "price": 19.99,
    "tags": ["azure", "cosmosdb", "developer"],
    "inventory": {
        "quantity": 150,
        "location": "Warehouse A"
    },
    "releaseDate": "2023-10-27T00:00:00Z"
}
            

Key Properties

• id: A unique identifier for the item within its container. This is a mandatory property and is used to uniquely identify each item.
• Other Properties: You can define any number of custom properties as needed for your application data. These properties can be simple values (strings, numbers, booleans), arrays, or nested objects.

Item Operations

Azure Cosmos DB supports standard CRUD (Create, Read, Update, Delete) operations on items. These operations can be performed using various SDKs or the REST API.

Create Item

To create an item, you send a POST request to the container's endpoint with the item's JSON document in the request body. Azure Cosmos DB assigns a unique id if one is not provided (though it's best practice to provide it).

Read Item

Items can be retrieved using their unique id. A GET request to the item's specific resource link retrieves the document.

GET https://your-cosmos-db-account.documents.azure.com/dbs/your-db/colls/your-coll/docs/abc-123-xyz
            

Update Item

Items can be updated using a PUT or PATCH request. The entire document is typically sent in the request body for a PUT operation.

Delete Item

Items can be deleted by sending a DELETE request to the item's specific resource link.

Indexing

Azure Cosmos DB automatically indexes every item within a container. By default, the indexing policy indexes all properties. You can customize this policy to include or exclude specific paths, which can optimize performance and reduce index storage for large datasets. For more details, refer to the Indexing in Azure Cosmos DB article.

Schemaless Nature

The schemaless nature of items in Azure Cosmos DB offers significant flexibility. You can evolve your data schema over time without needing to perform complex schema migrations. Different items in the same container can have entirely different structures, allowing for diverse data types and rapid application development.

Next Steps

Understanding items and documents is fundamental to working with Azure Cosmos DB's document model. For further exploration, consider these topics:

• Containers
• Partitioning
• Indexing