Azure Data Tables Py

1---
2name: azure-data-tables-py
3description: |
4  Azure Tables SDK for Python (Storage and Cosmos DB). Use for NoSQL key-value storage, entity CRUD, and batch operations.
5  Triggers: "table storage", "TableServiceClient", "TableClient", "entities", "PartitionKey", "RowKey".
6package: azure-data-tables
7---
8 
9# Azure Tables SDK for Python
10 
11NoSQL key-value store for structured data (Azure Storage Tables or Cosmos DB Table API).
12 
13## Installation
14 
15```bash
16pip install azure-data-tables azure-identity
17```
18 
19## Environment Variables
20 
21```bash
22# Azure Storage Tables
23AZURE_STORAGE_ACCOUNT_URL=https://<account>.table.core.windows.net
24 
25# Cosmos DB Table API
26COSMOS_TABLE_ENDPOINT=https://<account>.table.cosmos.azure.com
27```
28 
29## Authentication
30 
31```python
32from azure.identity import DefaultAzureCredential
33from azure.data.tables import TableServiceClient, TableClient
34 
35credential = DefaultAzureCredential()
36endpoint = "https://<account>.table.core.windows.net"
37 
38# Service client (manage tables)
39service_client = TableServiceClient(endpoint=endpoint, credential=credential)
40 
41# Table client (work with entities)
42table_client = TableClient(endpoint=endpoint, table_name="mytable", credential=credential)
43```
44 
45## Client Types
46 
47| Client | Purpose |
48|--------|---------|
49| `TableServiceClient` | Create/delete tables, list tables |
50| `TableClient` | Entity CRUD, queries |
51 
52## Table Operations
53 
54```python
55# Create table
56service_client.create_table("mytable")
57 
58# Create if not exists
59service_client.create_table_if_not_exists("mytable")
60 
61# Delete table
62service_client.delete_table("mytable")
63 
64# List tables
65for table in service_client.list_tables():
66    print(table.name)
67 
68# Get table client
69table_client = service_client.get_table_client("mytable")
70```
71 
72## Entity Operations
73 
74**Important**: Every entity requires `PartitionKey` and `RowKey` (together form unique ID).
75 
76### Create Entity
77 
78```python
79entity = {
80    "PartitionKey": "sales",
81    "RowKey": "order-001",
82    "product": "Widget",
83    "quantity": 5,
84    "price": 9.99,
85    "shipped": False
86}
87 
88# Create (fails if exists)
89table_client.create_entity(entity=entity)
90 
91# Upsert (create or replace)
92table_client.upsert_entity(entity=entity)
93```
94 
95### Get Entity
96 
97```python
98# Get by key (fastest)
99entity = table_client.get_entity(
100    partition_key="sales",
101    row_key="order-001"
102)
103print(f"Product: {entity['product']}")
104```
105 
106### Update Entity
107 
108```python
109# Replace entire entity
110entity["quantity"] = 10
111table_client.update_entity(entity=entity, mode="replace")
112 
113# Merge (update specific fields only)
114update = {
115    "PartitionKey": "sales",
116    "RowKey": "order-001",
117    "shipped": True
118}
119table_client.update_entity(entity=update, mode="merge")
120```
121 
122### Delete Entity
123 
124```python
125table_client.delete_entity(
126    partition_key="sales",
127    row_key="order-001"
128)
129```
130 
131## Query Entities
132 
133### Query Within Partition
134 
135```python
136# Query by partition (efficient)
137entities = table_client.query_entities(
138    query_filter="PartitionKey eq 'sales'"
139)
140for entity in entities:
141    print(entity)
142```
143 
144### Query with Filters
145 
146```python
147# Filter by properties
148entities = table_client.query_entities(
149    query_filter="PartitionKey eq 'sales' and quantity gt 3"
150)
151 
152# With parameters (safer)
153entities = table_client.query_entities(
154    query_filter="PartitionKey eq @pk and price lt @max_price",
155    parameters={"pk": "sales", "max_price": 50.0}
156)
157```
158 
159### Select Specific Properties
160 
161```python
162entities = table_client.query_entities(
163    query_filter="PartitionKey eq 'sales'",
164    select=["RowKey", "product", "price"]
165)
166```
167 
168### List All Entities
169 
170```python
171# List all (cross-partition - use sparingly)
172for entity in table_client.list_entities():
173    print(entity)
174```
175 
176## Batch Operations
177 
178```python
179from azure.data.tables import TableTransactionError
180 
181# Batch operations (same partition only!)
182operations = [
183    ("create", {"PartitionKey": "batch", "RowKey": "1", "data": "first"}),
184    ("create", {"PartitionKey": "batch", "RowKey": "2", "data": "second"}),
185    ("upsert", {"PartitionKey": "batch", "RowKey": "3", "data": "third"}),
186]
187 
188try:
189    table_client.submit_transaction(operations)
190except TableTransactionError as e:
191    print(f"Transaction failed: {e}")
192```
193 
194## Async Client
195 
196```python
197from azure.data.tables.aio import TableServiceClient, TableClient
198from azure.identity.aio import DefaultAzureCredential
199 
200async def table_operations():
201    credential = DefaultAzureCredential()
202    
203    async with TableClient(
204        endpoint="https://<account>.table.core.windows.net",
205        table_name="mytable",
206        credential=credential
207    ) as client:
208        # Create
209        await client.create_entity(entity={
210            "PartitionKey": "async",
211            "RowKey": "1",
212            "data": "test"
213        })
214        
215        # Query
216        async for entity in client.query_entities("PartitionKey eq 'async'"):
217            print(entity)
218 
219import asyncio
220asyncio.run(table_operations())
221```
222 
223## Data Types
224 
225| Python Type | Table Storage Type |
226|-------------|-------------------|
227| `str` | String |
228| `int` | Int64 |
229| `float` | Double |
230| `bool` | Boolean |
231| `datetime` | DateTime |
232| `bytes` | Binary |
233| `UUID` | Guid |
234 
235## Best Practices
236 
2371. **Design partition keys** for query patterns and even distribution
2382. **Query within partitions** whenever possible (cross-partition is expensive)
2393. **Use batch operations** for multiple entities in same partition
2404. **Use `upsert_entity`** for idempotent writes
2415. **Use parameterized queries** to prevent injection
2426. **Keep entities small** — max 1MB per entity
2437. **Use async client** for high-throughput scenarios
244