Azure Cosmos DB Items

An item in Azure Cosmos DB is the fundamental unit of data storage and manipulation. Items are schema-agnostic JSON documents, making Azure Cosmos DB a great choice for modern, flexible application development.

Understanding Items

Each item is stored within a container. A container can hold items of various shapes and sizes, providing immense flexibility. While Azure Cosmos DB is a NoSQL document database, it can also store key-value pairs, graph data, and column-family data.

Item Structure

Every item in Azure Cosmos DB is represented as a JSON document. A basic item includes:

An id property, which is a unique identifier within the container.
A partition key value (if the container is partitioned).
Other user-defined properties representing the data.

Here's an example of a JSON item:

{
    "id": "user123",
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "jane.doe@example.com",
    "address": {
        "street": "123 Main St",
        "city": "Anytown",
        "zipCode": "12345"
    },
    "registrationDate": "2023-10-27T10:00:00Z",
    "_rid": "s9Q8f54N47g=",
    "_ts": 1698386400,
    "_etag": "00000000-0000-0000-0000-000000000001"
}

Item Properties

Azure Cosmos DB automatically adds the following system-defined properties to each item:

_rid: A system-generated, unique identifier for the resource, including the item. It's used for internal operations.
_ts: A timestamp representing the last modified time of the item.
_etag: An entity tag (ETag) that is used for optimistic concurrency control.
_self: A self-link URI that refers to the item.

Note: The id property is crucial for uniquely identifying an item within its container. It must be unique and cannot be changed after creation.

Item Operations

You can perform various operations on items within an Azure Cosmos DB container:

Create: Add a new item to the container.
Read: Retrieve an item by its ID.
Update: Modify an existing item.
Delete: Remove an item from the container.
Query: Retrieve multiple items based on specific criteria using SQL or other query languages.

Creating an Item

When creating an item, you provide the JSON document. Azure Cosmos DB handles the rest, including assigning system properties and ensuring uniqueness of the id.

Reading an Item

To read an item, you typically use its id and the partition key value (if applicable).

Updating an Item

Updates can be done by replacing the entire item or partially updating its properties using mechanisms like patch operations.

Deleting an Item

Items can be deleted using their unique identifier.

Partitioning and Items

For partitioned containers, the partition key value is essential for routing requests to the correct physical partition. When performing operations like reading or updating an item, you must provide the partition key value associated with that item.

Important: The partition key value of an item cannot be changed after it's created. If you need to change the partition key value, you must create a new item with the desired partition key and then delete the original item.

Schema Flexibility

Azure Cosmos DB does not enforce a rigid schema. This means items within the same container can have different structures, properties, and data types. This flexibility is a core advantage for evolving applications.

Example: Heterogeneous Items

Consider a container storing product information. You might have:

A basic product with just a name and price.
An electronic product with additional specifications like power requirements and dimensions.
A clothing item with size and color options.

All these can coexist within the same Azure Cosmos DB container.