Azure Cosmos DB Table Client Library (Legacy)

1.0.6 · deprecated · verified Fri Apr 10

This is an older client library for interacting with Azure Cosmos DB Table API and Azure Table Storage. It provides functionalities for creating, managing, and querying tables and entities. As of version 1.0.6, it is considered a legacy library, with the actively maintained `azure-data-tables` package being the recommended replacement. The library is no longer actively developed.

Warnings

breaking This library (`azure-cosmosdb-table`) is considered legacy and has been largely superseded by the `azure-data-tables` library. Microsoft strongly recommends migrating to `azure-data-tables` for new development and existing applications for better performance, modern features (like full async support), and continued maintenance.
Fix: Migrate to `pip install azure-data-tables` and update import statements and client initialization. Refer to official Azure SDK migration guides.
gotcha The GitHub repository for `azure-cosmos-table-python` (which contains `azure-cosmosdb-table`) was archived on July 14, 2023, making it read-only. This confirms its end-of-life status, indicating no further updates or bug fixes will be provided for this library.
Fix: Switch to the actively maintained `azure-data-tables` library.
gotcha Prior to version 1.0.0, table-related classes were part of the `azure.storage` namespace. They were moved to `azure.cosmosdb.table` in this library. Users migrating from older `azure-storage` versions might encounter `ImportError`.
Fix: Update imports from `from azure.storage.table import ...` to `from azure.cosmosdb.table import ...`.
gotcha While this SDK can connect to both Azure Table Storage and Azure Cosmos DB's Table API, these underlying services have significant differences in performance, scalability, indexing, and cost models. Unawareness can lead to unexpected costs or performance issues.
Fix: Understand the distinctions between Azure Table Storage and Azure Cosmos DB's Table API. For new projects, `azure-data-tables` is the recommended client library which clearly targets both.
gotcha This library primarily offers synchronous APIs, lacking modern `async`/`await` support. This can impact performance and responsiveness in modern I/O-bound applications compared to the `azure-data-tables` library.
Fix: For asynchronous operations and better integration with modern Python async patterns, migrate to `azure-data-tables`, which offers full async/await support.

Install

pip install azure-cosmosdb-table Install via pip

Imports

TableService
```
from azure.cosmosdb.table import TableService
```
The Table SDK was split from the `azure-storage` namespace and moved to `azure.cosmosdb.table` in this library's version 1.0.0.
Entity
```
from azure.cosmosdb.table import Entity
```

Quickstart

This quickstart demonstrates how to initialize the `TableService` client, create a table, insert an entity, and retrieve an entity using connection string or account credentials. Remember to set `AZURE_STORAGE_CONNECTION_STRING` or `AZURE_STORAGE_ACCOUNT_NAME` and `AZURE_STORAGE_ACCOUNT_KEY` environment variables.

import os
from azure.cosmosdb.table import TableService, Entity

# Set these environment variables or replace with actual values
# AZURE_STORAGE_CONNECTION_STRING (preferred) or AZURE_STORAGE_ACCOUNT_NAME and AZURE_STORAGE_ACCOUNT_KEY
connection_string = os.environ.get("AZURE_STORAGE_CONNECTION_STRING", "DefaultEndpointsProtocol=https;AccountName=your_account_name;AccountKey=your_account_key;EndpointSuffix=core.windows.net")
account_name = os.environ.get("AZURE_STORAGE_ACCOUNT_NAME", "your_account_name")
account_key = os.environ.get("AZURE_STORAGE_ACCOUNT_KEY", "your_account_key")

# Initialize the TableService client
# If connection string is not valid, try with account name/key
if "DefaultEndpointsProtocol" in connection_string and "your_account_name" not in connection_string:
    table_service = TableService(connection_string=connection_string)
else:
    table_service = TableService(account_name=account_name, account_key=account_key)

table_name = "mytesttable"

try:
    # Create table if it doesn't exist
    print(f"Creating table '{table_name}' if it doesn't exist...")
    table_service.create_table(table_name)
    print(f"Table '{table_name}' created or already exists.")

    # Insert an entity
    task = {'PartitionKey': 'tasks', 'RowKey': '1', 'description': 'Learn Python SDK', 'priority': 100}
    print(f"Inserting entity: {task}")
    table_service.insert_entity(table_name, task)
    print("Entity inserted.")

    # Retrieve an entity
    print(f"Retrieving entity with PartitionKey='tasks', RowKey='1'")
    retrieved_task = table_service.get_entity(table_name, 'tasks', '1')
    print(f"Retrieved entity: {retrieved_task['description']}, Priority: {retrieved_task['priority']}")

except Exception as e:
    print(f"An error occurred: {e}")
    print("Please ensure your Azure Storage/Cosmos DB connection details are correct and the account has table API enabled.")

# Optional: Clean up the table
# try:
#     print(f"Deleting table '{table_name}'...")
#     table_service.delete_table(table_name)
#     print(f"Table '{table_name}' deleted.")
# except Exception as e:
#     print(f"Error deleting table: {e}")

view raw JSON →