Azure Data Tables Java

1---
2name: azure-data-tables-java
3description: Build table storage applications with Azure Tables SDK for Java. Use when working with Azure Table Storage or Cosmos DB Table API for NoSQL key-value data, schemaless storage, or structured data at scale.
4package: com.azure:azure-data-tables
5---
6 
7# Azure Tables SDK for Java
8 
9Build table storage applications using the Azure Tables SDK for Java. Works with both Azure Table Storage and Cosmos DB Table API.
10 
11## Installation
12 
13```xml
14<dependency>
15  <groupId>com.azure</groupId>
16  <artifactId>azure-data-tables</artifactId>
17  <version>12.6.0-beta.1</version>
18</dependency>
19```
20 
21## Client Creation
22 
23### With Connection String
24 
25```java
26import com.azure.data.tables.TableServiceClient;
27import com.azure.data.tables.TableServiceClientBuilder;
28import com.azure.data.tables.TableClient;
29 
30TableServiceClient serviceClient = new TableServiceClientBuilder()
31    .connectionString("<your-connection-string>")
32    .buildClient();
33```
34 
35### With Shared Key
36 
37```java
38import com.azure.core.credential.AzureNamedKeyCredential;
39 
40AzureNamedKeyCredential credential = new AzureNamedKeyCredential(
41    "<account-name>",
42    "<account-key>");
43 
44TableServiceClient serviceClient = new TableServiceClientBuilder()
45    .endpoint("<your-table-account-url>")
46    .credential(credential)
47    .buildClient();
48```
49 
50### With SAS Token
51 
52```java
53TableServiceClient serviceClient = new TableServiceClientBuilder()
54    .endpoint("<your-table-account-url>")
55    .sasToken("<sas-token>")
56    .buildClient();
57```
58 
59### With DefaultAzureCredential (Storage only)
60 
61```java
62import com.azure.identity.DefaultAzureCredentialBuilder;
63 
64TableServiceClient serviceClient = new TableServiceClientBuilder()
65    .endpoint("<your-table-account-url>")
66    .credential(new DefaultAzureCredentialBuilder().build())
67    .buildClient();
68```
69 
70## Key Concepts
71 
72- **TableServiceClient**: Manage tables (create, list, delete)
73- **TableClient**: Manage entities within a table (CRUD)
74- **Partition Key**: Groups entities for efficient queries
75- **Row Key**: Unique identifier within a partition
76- **Entity**: A row with up to 252 properties (1MB Storage, 2MB Cosmos)
77 
78## Core Patterns
79 
80### Create Table
81 
82```java
83// Create table (throws if exists)
84TableClient tableClient = serviceClient.createTable("mytable");
85 
86// Create if not exists (no exception)
87TableClient tableClient = serviceClient.createTableIfNotExists("mytable");
88```
89 
90### Get Table Client
91 
92```java
93// From service client
94TableClient tableClient = serviceClient.getTableClient("mytable");
95 
96// Direct construction
97TableClient tableClient = new TableClientBuilder()
98    .connectionString("<connection-string>")
99    .tableName("mytable")
100    .buildClient();
101```
102 
103### Create Entity
104 
105```java
106import com.azure.data.tables.models.TableEntity;
107 
108TableEntity entity = new TableEntity("partitionKey", "rowKey")
109    .addProperty("Name", "Product A")
110    .addProperty("Price", 29.99)
111    .addProperty("Quantity", 100)
112    .addProperty("IsAvailable", true);
113 
114tableClient.createEntity(entity);
115```
116 
117### Get Entity
118 
119```java
120TableEntity entity = tableClient.getEntity("partitionKey", "rowKey");
121 
122String name = (String) entity.getProperty("Name");
123Double price = (Double) entity.getProperty("Price");
124System.out.printf("Product: %s, Price: %.2f%n", name, price);
125```
126 
127### Update Entity
128 
129```java
130import com.azure.data.tables.models.TableEntityUpdateMode;
131 
132// Merge (update only specified properties)
133TableEntity updateEntity = new TableEntity("partitionKey", "rowKey")
134    .addProperty("Price", 24.99);
135tableClient.updateEntity(updateEntity, TableEntityUpdateMode.MERGE);
136 
137// Replace (replace entire entity)
138TableEntity replaceEntity = new TableEntity("partitionKey", "rowKey")
139    .addProperty("Name", "Product A Updated")
140    .addProperty("Price", 24.99)
141    .addProperty("Quantity", 150);
142tableClient.updateEntity(replaceEntity, TableEntityUpdateMode.REPLACE);
143```
144 
145### Upsert Entity
146 
147```java
148// Insert or update (merge mode)
149tableClient.upsertEntity(entity, TableEntityUpdateMode.MERGE);
150 
151// Insert or replace
152tableClient.upsertEntity(entity, TableEntityUpdateMode.REPLACE);
153```
154 
155### Delete Entity
156 
157```java
158tableClient.deleteEntity("partitionKey", "rowKey");
159```
160 
161### List Entities
162 
163```java
164import com.azure.data.tables.models.ListEntitiesOptions;
165 
166// List all entities
167for (TableEntity entity : tableClient.listEntities()) {
168    System.out.printf("%s - %s%n",
169        entity.getPartitionKey(),
170        entity.getRowKey());
171}
172 
173// With filtering and selection
174ListEntitiesOptions options = new ListEntitiesOptions()
175    .setFilter("PartitionKey eq 'sales'")
176    .setSelect("Name", "Price");
177 
178for (TableEntity entity : tableClient.listEntities(options, null, null)) {
179    System.out.printf("%s: %.2f%n",
180        entity.getProperty("Name"),
181        entity.getProperty("Price"));
182}
183```
184 
185### Query with OData Filter
186 
187```java
188// Filter by partition key
189ListEntitiesOptions options = new ListEntitiesOptions()
190    .setFilter("PartitionKey eq 'electronics'");
191 
192// Filter with multiple conditions
193options.setFilter("PartitionKey eq 'electronics' and Price gt 100");
194 
195// Filter with comparison operators
196options.setFilter("Quantity ge 10 and Quantity le 100");
197 
198// Top N results
199options.setTop(10);
200 
201for (TableEntity entity : tableClient.listEntities(options, null, null)) {
202    System.out.println(entity.getRowKey());
203}
204```
205 
206### Batch Operations (Transactions)
207 
208```java
209import com.azure.data.tables.models.TableTransactionAction;
210import com.azure.data.tables.models.TableTransactionActionType;
211import java.util.Arrays;
212 
213// All entities must have same partition key
214List<TableTransactionAction> actions = Arrays.asList(
215    new TableTransactionAction(
216        TableTransactionActionType.CREATE,
217        new TableEntity("batch", "row1").addProperty("Name", "Item 1")),
218    new TableTransactionAction(
219        TableTransactionActionType.CREATE,
220        new TableEntity("batch", "row2").addProperty("Name", "Item 2")),
221    new TableTransactionAction(
222        TableTransactionActionType.UPSERT_MERGE,
223        new TableEntity("batch", "row3").addProperty("Name", "Item 3"))
224);
225 
226tableClient.submitTransaction(actions);
227```
228 
229### List Tables
230 
231```java
232import com.azure.data.tables.models.TableItem;
233import com.azure.data.tables.models.ListTablesOptions;
234 
235// List all tables
236for (TableItem table : serviceClient.listTables()) {
237    System.out.println(table.getName());
238}
239 
240// Filter tables
241ListTablesOptions options = new ListTablesOptions()
242    .setFilter("TableName eq 'mytable'");
243 
244for (TableItem table : serviceClient.listTables(options, null, null)) {
245    System.out.println(table.getName());
246}
247```
248 
249### Delete Table
250 
251```java
252serviceClient.deleteTable("mytable");
253```
254 
255## Typed Entities
256 
257```java
258public class Product implements TableEntity {
259    private String partitionKey;
260    private String rowKey;
261    private OffsetDateTime timestamp;
262    private String eTag;
263    private String name;
264    private double price;
265    
266    // Getters and setters for all fields
267    @Override
268    public String getPartitionKey() { return partitionKey; }
269    @Override
270    public void setPartitionKey(String partitionKey) { this.partitionKey = partitionKey; }
271    @Override
272    public String getRowKey() { return rowKey; }
273    @Override
274    public void setRowKey(String rowKey) { this.rowKey = rowKey; }
275    // ... other getters/setters
276    
277    public String getName() { return name; }
278    public void setName(String name) { this.name = name; }
279    public double getPrice() { return price; }
280    public void setPrice(double price) { this.price = price; }
281}
282 
283// Usage
284Product product = new Product();
285product.setPartitionKey("electronics");
286product.setRowKey("laptop-001");
287product.setName("Laptop");
288product.setPrice(999.99);
289 
290tableClient.createEntity(product);
291```
292 
293## Error Handling
294 
295```java
296import com.azure.data.tables.models.TableServiceException;
297 
298try {
299    tableClient.createEntity(entity);
300} catch (TableServiceException e) {
301    System.out.println("Status: " + e.getResponse().getStatusCode());
302    System.out.println("Error: " + e.getMessage());
303    // 409 = Conflict (entity exists)
304    // 404 = Not Found
305}
306```
307 
308## Environment Variables
309 
310```bash
311# Storage Account
312AZURE_TABLES_CONNECTION_STRING=DefaultEndpointsProtocol=https;AccountName=...
313AZURE_TABLES_ENDPOINT=https://<account>.table.core.windows.net
314 
315# Cosmos DB Table API
316COSMOS_TABLE_ENDPOINT=https://<account>.table.cosmosdb.azure.com
317```
318 
319## Best Practices
320 
3211. **Partition Key Design**: Choose keys that distribute load evenly
3222. **Batch Operations**: Use transactions for atomic multi-entity updates
3233. **Query Optimization**: Always filter by PartitionKey when possible
3244. **Select Projection**: Only select needed properties for performance
3255. **Entity Size**: Keep entities under 1MB (Storage) or 2MB (Cosmos)
326 
327## Trigger Phrases
328 
329- "Azure Tables Java"
330- "table storage SDK"
331- "Cosmos DB Table API"
332- "NoSQL key-value storage"
333- "partition key row key"
334- "table entity CRUD"
335