Azure Cosmos DB Table API

Introduction to Azure Cosmos DB Table API

The Azure Cosmos DB Table API provides a NoSQL key-value store that is schema-agnostic and highly scalable. It's designed to store and query large amounts of structured, semi-structured, and unstructured data. This API is compatible with the Azure Table storage service, making it easy to migrate existing applications or develop new ones using familiar patterns.

With Azure Cosmos DB, you get the benefits of the Table API's simple data model alongside the global distribution, high availability, and low latency capabilities of Azure Cosmos DB.

Getting Started with Table API

To get started with the Table API, you'll need an Azure Cosmos DB account. Once your account is set up, you can create a database and a table within it.

Creating a Table

Tables in the Table API are collections of entities. Each entity is a set of properties.

Data Model: Entities and Properties

The Table API stores data in tables, which are collections of entities. An entity is a record and is analogous to a row in a database. An entity consists of a set of properties.

• Entities: Each entity has a unique identifier composed of a PartitionKey and a RowKey.
• Properties: Properties are name-value pairs. Property names are strings, and property values can be of various data types (e.g., String, Integer, Boolean, DateTime, GUID, Binary).
• PartitionKey: Entities with the same PartitionKey are co-located within a partition. This is crucial for performance and scalability. A good PartitionKey design distributes read and write operations evenly across partitions.
• RowKey: Within a partition, entities are uniquely identified by their RowKey. The RowKey must be unique within a partition.

A special property, the Timestamp (system property), is automatically managed by Azure Cosmos DB for optimistic concurrency.

Common Operations

The Table API supports standard data operations, including:

• Create Entity: Adds a new entity to a table.
• Read Entity: Retrieves a single entity using its PartitionKey and RowKey.
• Query Entities: Retrieves multiple entities based on filter criteria. Queries can be filtered by PartitionKey and other properties.
• Update Entity: Modifies an existing entity.
• Delete Entity: Removes an entity from a table.
• Batch Operations: Allows executing multiple operations (insert, update, delete) in a single atomic request.

SDK Usage Examples

Inserting an Entity (Python SDK)

from azure.cosmos.table import TableServiceClient, Entity

# Assumes connection_string and table_client are already initialized

entity = {
    'PartitionKey': 'users',
    'RowKey': 'user123',
    'Email': 'user123@example.com',
    'FirstName': 'Jane',
    'LastName': 'Doe',
    'Age': 30
}

table_client.upsert_entity(entity)
print("Entity inserted successfully.")
                

Querying Entities (Python SDK)

# Retrieve all entities in the 'users' partition
query = "PartitionKey eq 'users'"
entities = table_client.query_entities(query)

for entity in entities:
    print(f"Name: {entity['FirstName']} {entity['LastName']}, Email: {entity['Email']}")

# Retrieve a specific entity
single_entity = table_client.get_entity(partition_key='users', row_key='user123')
print(f"Retrieved: {single_entity}")
                

Best Practices for Table API

• PartitionKey Design: Choose a PartitionKey that distributes your data and requests evenly. Avoid "hot" partitions.
• RowKey Design: Use RowKeys that facilitate efficient querying. For range queries, consider sequential or time-based RowKeys.
• Batching: Utilize batch operations for multiple inserts, updates, or deletes to improve efficiency and reduce request overhead.
• Indexing: Azure Cosmos DB Table API automatically indexes PartitionKey and RowKey. Consider indexing other frequently queried properties for better performance.
• Select Properties: When querying, project only the properties you need to reduce network traffic and improve performance.
• Throughput Management: Monitor your request units (RUs) and adjust throughput at the database level as needed.

API Reference Overview

The Table API exposes a RESTful interface and is accessible via SDKs for various programming languages. Key entities and operations include:

For detailed information on specific parameters and request/response formats, please refer to the official Azure Cosmos DB Table API REST documentation.