{"id":1348,"library":"azure-data-tables","title":"Azure Data Tables Client Library","description":"The `azure-data-tables` library is the Python SDK for Azure Table Storage and Azure Cosmos DB for Table API. It provides synchronous and asynchronous clients for managing tables, entities, and performing queries. This library is part of the 'track 2' Azure SDK, offering a modern, consistent, and Pythonic interface. The current stable version is 12.7.0, with releases typically aligning with broader Azure SDK updates for bug fixes and minor features.","status":"active","version":"12.7.0","language":"en","source_language":"en","source_url":"https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/tables/azure-data-tables","tags":["Azure","tables","NoSQL","cloud","storage","Cosmos DB"],"install":[{"cmd":"pip install azure-data-tables","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Required for Azure Active Directory (AAD) authentication methods like DefaultAzureCredential.","package":"azure-identity","optional":true}],"imports":[{"note":"Old 'track 1' SDK (azure-cosmosdb-table or azure-storage-table) uses different client names and import paths. azure-data-tables is the modern 'track 2' library.","wrong":"from azure.cosmosdb.table import TableService","symbol":"TableServiceClient","correct":"from azure.data.tables import TableServiceClient"},{"symbol":"TableClient","correct":"from azure.data.tables import TableClient"},{"note":"Common Azure SDK exceptions are found in azure.core.exceptions.","symbol":"ResourceExistsError","correct":"from azure.core.exceptions import ResourceExistsError"}],"quickstart":{"code":"import os\nfrom azure.data.tables import TableServiceClient, TableEntity\nfrom azure.core.exceptions import ResourceExistsError\n\n# --- Configuration ---\n# Replace with your storage account connection string or set as an environment variable\n# Example: 'DefaultEndpointsProtocol=https;AccountName=<account>;AccountKey=<key>;EndpointSuffix=core.windows.net'\nconnection_string = os.environ.get('AZURE_TABLES_CONNECTION_STRING', 'YOUR_CONNECTION_STRING_HERE')\n\n# --- Client Initialization ---\n# For AAD auth, use TableServiceClient(endpoint=os.environ.get('AZURE_TABLES_ENDPOINT'), credential=DefaultAzureCredential())\n# Ensure 'AZURE_TABLES_ENDPOINT' is set (e.g., 'https://<accountname>.table.core.windows.net/')\n\ntry:\n    table_service_client = TableServiceClient.from_connection_string(conn_str=connection_string)\n    table_name = \"MyTestTable\"\n    table_client = table_service_client.get_table_client(table_name=table_name)\n\n    # --- Create Table (if it doesn't exist) ---\n    try:\n        print(f\"Creating table '{table_name}'...\")\n        table_client.create_table()\n        print(f\"Table '{table_name}' created.\")\n    except ResourceExistsError:\n        print(f\"Table '{table_name}' already exists.\")\n\n    # --- Add an Entity ---\n    print(\"Adding entity...\")\n    entity = TableEntity(PartitionKey=\"pk1\", RowKey=\"rk1\", name=\"Alice\", age=30)\n    table_client.upsert_entity(entity)\n    print(\"Entity added/updated.\")\n\n    # --- Query Entity ---\n    print(\"Querying entity...\")\n    queried_entity = table_client.get_entity(partition_key=\"pk1\", row_key=\"rk1\")\n    print(f\"Queried entity: {queried_entity['name']}, {queried_entity['age']}\")\n\n    # --- List Entities (simple query) ---\n    print(\"Listing entities...\")\n    entities = table_client.query_entities(filter=\"PartitionKey eq 'pk1'\")\n    for ent in entities:\n        print(f\" - PK: {ent['PartitionKey']}, RK: {ent['RowKey']}, Name: {ent.get('name')}\")\n\n    # --- Delete Entity ---\n    print(\"Deleting entity...\")\n    table_client.delete_entity(partition_key=\"pk1\", row_key=\"rk1\")\n    print(\"Entity deleted.\")\n\n    # --- Delete Table (cleanup) ---\n    # print(f\"Deleting table '{table_name}'...\")\n    # table_client.delete_table()\n    # print(f\"Table '{table_name}' deleted.\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n\n","lang":"python","description":"This quickstart demonstrates how to initialize a `TableServiceClient` using a connection string, create a table, add an entity, query for it, and then delete it. For production, consider using `azure-identity` with `DefaultAzureCredential` and an endpoint URL for authentication."},"warnings":[{"fix":"Rewrite client initialization (`TableServiceClient.from_connection_string` or `TableServiceClient(endpoint, credential)`), entity operations (`create_table`, `upsert_entity`, `get_entity`, `query_entities`, `delete_entity`), and exception handling to match the new API surface. Consult the official migration guide.","message":"Major API changes exist when migrating from older Azure Table Storage SDKs (e.g., `azure-storage-table` v1.x or `azure-cosmosdb-table`) to `azure-data-tables` (v12.x). This is a complete re-architecture following Azure SDK 'track 2' guidelines.","severity":"breaking","affected_versions":"All versions before 12.0.0 (i.e., v12.x compared to v1.x of older libraries)"},{"fix":"Always include `PartitionKey` and `RowKey` in your `TableEntity` objects. Ensure they are strings. Design your keys carefully to optimize queries and transactions.","message":"Azure Table Storage/Cosmos DB for Table API require every entity to have a `PartitionKey` and `RowKey`. These must be string types and together form the unique identifier for an entity within a table.","severity":"gotcha","affected_versions":"All"},{"fix":"Design your application with eventual consistency in mind. For operations requiring immediate consistency, consider using Cosmos DB with strong consistency levels, but be aware of higher costs.","message":"Azure Table Storage operations (especially queries) are eventually consistent. A write operation might not be immediately visible to subsequent read operations across all nodes.","severity":"gotcha","affected_versions":"All"},{"fix":"When using `submit_transaction`, ensure all entities in the transaction batch have identical `PartitionKey` values. If you need to update entities with different partition keys, you must perform separate operations.","message":"Entity Group Transactions (EGTs) are limited. All operations within an EGT (batch operation) must operate on entities that share the *same PartitionKey*.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}