0
# Azure Data Tables
1

2
Microsoft Azure Data Tables Client Library for Python provides a comprehensive interface for interacting with Azure Tables, a NoSQL data storage service. It supports both Azure Storage and Azure Cosmos DB accounts, enabling scalable data storage with simple CRUD operations, batch transactions, and powerful querying capabilities.
3

4
## Package Information
5

6
- **Package Name**: azure-data-tables
7
- **Language**: Python
8
- **Installation**: `pip install azure-data-tables`
9

10
## Core Imports
11

12
```python
13
from azure.data.tables import TableServiceClient, TableClient
14
```
15

16
For entity operations:
17

18
```python
19
from azure.data.tables import TableEntity, EntityProperty, EdmType
20
```
21

22
For async operations:
23

24
```python
25
from azure.data.tables.aio import TableServiceClient, TableClient
26
```
27

28
## Basic Usage
29

30
```python
31
from azure.data.tables import TableServiceClient, TableClient, TableEntity
32

33
# Initialize service client with connection string
34
service_client = TableServiceClient.from_connection_string(
35
    conn_str="DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=mykey"
36
)
37

38
# Create a table
39
table_client = service_client.create_table(table_name="mytable")
40

41
# Create an entity
42
entity = TableEntity()
43
entity["PartitionKey"] = "pk001"
44
entity["RowKey"] = "rk001"
45
entity["Name"] = "John Doe"
46
entity["Age"] = 30
47

48
# Insert the entity
49
table_client.create_entity(entity)
50

51
# Query entities
52
entities = table_client.query_entities(
53
    query_filter="PartitionKey eq 'pk001'",
54
    select=["Name", "Age"]
55
)
56

57
for entity in entities:
58
    print(f"Name: {entity['Name']}, Age: {entity['Age']}")
59
```
60

61
## Architecture
62

63
The Azure Data Tables library follows a hierarchical client architecture:
64

65
- **TableServiceClient**: Account-level operations managing tables, service properties, and analytics
66
- **TableClient**: Table-specific operations for entity CRUD, batch transactions, and queries
67
- **TableEntity**: Dictionary-based entity representation with metadata support
68
- **Async Variants**: Complete async/await pattern support for non-blocking operations
69

70
This design enables efficient resource management, connection pooling, and both synchronous and asynchronous programming patterns for high-performance applications.
71

72
## Capabilities
73

74
### Service Management
75

76
Account-level operations including table management, service configuration, analytics, and CORS settings. Provides comprehensive service administration capabilities.
77

78
```python { .api }
79
class TableServiceClient:
80
    def __init__(self, endpoint: str, credential=None, **kwargs): ...
81
    def create_table(self, table_name: str, **kwargs) -> TableClient: ...
82
    def delete_table(self, table_name: str, **kwargs) -> None: ...
83
    def list_tables(self, **kwargs) -> ItemPaged[TableItem]: ...
84
    def get_service_properties(self, **kwargs) -> Dict[str, object]: ...
85
    def set_service_properties(self, **kwargs) -> None: ...
86
```
87

88
[Service Management](./service-management.md)
89

90
### Table Operations
91

92
Table-specific operations for entity management, CRUD operations, batch transactions, and advanced querying with filtering and pagination support.
93

94
```python { .api }
95
class TableClient:
96
    def __init__(self, endpoint: str, table_name: str, **kwargs): ...
97
    def create_entity(self, entity: Union[TableEntity, Dict], **kwargs) -> Dict[str, Any]: ...
98
    def get_entity(self, partition_key: str, row_key: str, **kwargs) -> TableEntity: ...
99
    def update_entity(self, entity: Union[TableEntity, Dict], **kwargs) -> Dict[str, Any]: ...
100
    def delete_entity(self, partition_key: str, row_key: str, **kwargs) -> None: ...
101
    def query_entities(self, query_filter: str, **kwargs) -> ItemPaged[TableEntity]: ...
102
    def submit_transaction(self, operations: List, **kwargs) -> List[Dict[str, Any]]: ...
103
```
104

105
[Table Operations](./table-operations.md)
106

107
### Entity Data Types
108

109
Data modeling capabilities including type-safe entity properties, metadata handling, and Entity Data Model (EDM) type specifications for precise data representation.
110

111
```python { .api }
112
class TableEntity(dict):
113
    metadata: EntityMetadata
114

115
class EntityProperty:
116
    value: Any
117
    edm_type: Union[str, EdmType]
118

119
class EdmType(Enum):
120
    STRING = "Edm.String"
121
    INT32 = "Edm.Int32"
122
    INT64 = "Edm.Int64"
123
    BOOLEAN = "Edm.Boolean"
124
    DATETIME = "Edm.DateTime"
125
    GUID = "Edm.Guid"
126
    BINARY = "Edm.Binary"
127
    DOUBLE = "Edm.Double"
128
```
129

130
[Entity Data Types](./entity-data-types.md)
131

132
### Security and Access Control
133

134
Shared Access Signature (SAS) generation, access policies, and permission management for secure, time-limited access to tables and entities.
135

136
```python { .api }
137
def generate_account_sas(
138
    credential: AzureNamedKeyCredential,
139
    resource_types: ResourceTypes,
140
    permission: Union[str, AccountSasPermissions],
141
    expiry: Union[datetime, str],
142
    **kwargs
143
) -> str: ...
144

145
def generate_table_sas(
146
    credential: AzureNamedKeyCredential,
147
    table_name: str,
148
    permission: Union[str, TableSasPermissions] = None,
149
    expiry: Union[datetime, str] = None,
150
    **kwargs
151
) -> str: ...
152
```
153

154
[Security and Access Control](./security-access-control.md)
155

156
### Error Handling
157

158
Comprehensive exception handling with specific error codes, transaction failure management, and detailed error information for robust application development.
159

160
```python { .api }
161
class TableTransactionError(Exception):
162
    index: int
163
    error_code: TableErrorCode
164
    message: str
165
    additional_info: Dict[str, Any]
166

167
class RequestTooLargeError(TableTransactionError): ...
168

169
class TableErrorCode(Enum):
170
    AUTHENTICATION_FAILED = "AuthenticationFailed"
171
    RESOURCE_NOT_FOUND = "ResourceNotFound"
172
    ENTITY_ALREADY_EXISTS = "EntityAlreadyExists"
173
    # ... additional error codes
174
```
175

176
[Error Handling](./error-handling.md)
177

178
### Batch Operations
179

180
High-performance batch transaction processing supporting multiple entity operations in single atomic transactions with comprehensive operation types.
181

182
```python { .api }
183
class TransactionOperation(Enum):
184
    CREATE = "create"
185
    UPDATE = "update"
186
    UPSERT = "upsert"
187
    DELETE = "delete"
188

189
class UpdateMode(Enum):
190
    REPLACE = "replace"
191
    MERGE = "merge"
192
```
193

194
[Batch Operations](./batch-operations.md)
195

196
### Async Operations
197

198
Complete asynchronous operation support using async/await patterns for non-blocking I/O, providing identical functionality to synchronous clients with improved performance for concurrent scenarios.
199

200
```python { .api }
201
from azure.data.tables.aio import TableServiceClient, TableClient
202

203
class TableServiceClient:
204
    async def create_table(self, table_name: str, **kwargs) -> TableClient: ...
205
    async def list_tables(self, **kwargs) -> AsyncItemPaged[TableItem]: ...
206

207
class TableClient:
208
    async def create_entity(self, entity: Union[TableEntity, Dict], **kwargs) -> Dict[str, Any]: ...
209
    async def query_entities(self, query_filter: str, **kwargs) -> AsyncItemPaged[TableEntity]: ...
210
```
211

212
[Async Operations](./async-operations.md)
213

214
## Common Types
215

216
```python { .api }
217
# Type aliases for entity operations
218
EntityType = Union[TableEntity, Mapping[str, Any]]
219
TransactionOperationType = Union[
220
    Tuple[TransactionOperation, EntityType],
221
    Tuple[TransactionOperation, EntityType, Mapping[str, Any]]
222
]
223

224
# Metadata structure
225
class EntityMetadata(TypedDict):
226
    etag: Optional[str]
227
    timestamp: Optional[datetime]
228
    id: str  # optional
229
    type: str  # optional
230
    editLink: str  # optional
231
```