Azure Data Tables Client Library

Warnings

• breaking 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.
  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.
• gotcha 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.
  Fix: Always include `PartitionKey` and `RowKey` in your `TableEntity` objects. Ensure they are strings. Design your keys carefully to optimize queries and transactions.
• gotcha Azure Table Storage operations (especially queries) are eventually consistent. A write operation might not be immediately visible to subsequent read operations across all nodes.
  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.
• gotcha Entity Group Transactions (EGTs) are limited. All operations within an EGT (batch operation) must operate on entities that share the *same PartitionKey*.
  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.

Install

• pip install azure-data-tables Install stable version

Imports

• TableServiceClient

  from azure.data.tables import TableServiceClient

  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.
• TableClient

  from azure.data.tables import TableClient

• ResourceExistsError

  from azure.core.exceptions import ResourceExistsError

  Common Azure SDK exceptions are found in azure.core.exceptions.

Quickstart

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.

import os
from azure.data.tables import TableServiceClient, TableEntity
from azure.core.exceptions import ResourceExistsError

# --- Configuration ---
# Replace with your storage account connection string or set as an environment variable
# Example: 'DefaultEndpointsProtocol=https;AccountName=<account>;AccountKey=<key>;EndpointSuffix=core.windows.net'
connection_string = os.environ.get('AZURE_TABLES_CONNECTION_STRING', 'YOUR_CONNECTION_STRING_HERE')

# --- Client Initialization ---
# For AAD auth, use TableServiceClient(endpoint=os.environ.get('AZURE_TABLES_ENDPOINT'), credential=DefaultAzureCredential())
# Ensure 'AZURE_TABLES_ENDPOINT' is set (e.g., 'https://<accountname>.table.core.windows.net/')

try:
    table_service_client = TableServiceClient.from_connection_string(conn_str=connection_string)
    table_name = "MyTestTable"
    table_client = table_service_client.get_table_client(table_name=table_name)

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

    # --- Add an Entity ---
    print("Adding entity...")
    entity = TableEntity(PartitionKey="pk1", RowKey="rk1", name="Alice", age=30)
    table_client.upsert_entity(entity)
    print("Entity added/updated.")

    # --- Query Entity ---
    print("Querying entity...")
    queried_entity = table_client.get_entity(partition_key="pk1", row_key="rk1")
    print(f"Queried entity: {queried_entity['name']}, {queried_entity['age']}")

    # --- List Entities (simple query) ---
    print("Listing entities...")
    entities = table_client.query_entities(filter="PartitionKey eq 'pk1'")
    for ent in entities:
        print(f" - PK: {ent['PartitionKey']}, RK: {ent['RowKey']}, Name: {ent.get('name')}")

    # --- Delete Entity ---
    print("Deleting entity...")
    table_client.delete_entity(partition_key="pk1", row_key="rk1")
    print("Entity deleted.")

    # --- Delete Table (cleanup) ---
    # print(f"Deleting table '{table_name}'...")
    # table_client.delete_table()
    # print(f"Table '{table_name}' deleted.")

except Exception as e:
    print(f"An error occurred: {e}")