TableClient Class

  • java.lang.Object
    • com.azure.data.tables.TableClient

public final class TableClient

Provides a synchronous service client for accessing a table in the Azure Tables service.

Overview

The client encapsulates the URL for the table within the Tables service endpoint, the name of the table, and the credentials for accessing the storage or CosmosDB table API account. It provides synchronous methods to create and delete the table itself, as well as methods to create, upsert, update, delete, list, and get entities within the table. These methods invoke REST API operations to make the requests and obtain the results that are returned.

Getting Started

Authenticating and building instances of this client are handled by TableClientBuilder. This sample shows how to authenticate and build a TableClient instance using the TableClientBuilder and a connection string.

TableClient tableClient = new TableClientBuilder()
     .connectionString("connectionstring")
     .tableName("myTable")
     .buildClient();

For more information on building and authenticating, see the TableClientBuilder documentation.

The following code samples provide examples of common operations preformed with this client.


Create a TableEntity

The createEntity(TableEntity entity) method can be used to create a table entity within a table in your Azure Storage or Azure Cosmos account.

The sample below creates a TableEntity with a partition key of "partitionKey" and a row key of "rowKey".

TableEntity tableEntity = new TableEntity("partitionKey", "rowKey")
     .addProperty("Property", "Value");

 tableClient.createEntity(tableEntity);

 System.out.printf("Table entity with partition key '%s' and row key: '%s' was created.", "partitionKey", "rowKey");

Note: for asynchronous sample, refer to TableAsyncClient.


Retrieve a TableEntity

The getEntity(String partitionKey, String rowKey) method can be used to retrieve a table entity within a table in your Azure Storage or Azure Cosmos account.

The sample below retrieves a TableEntity with a partition key of "partitionKey" and a row key of "rowKey".

TableEntity tableEntity = tableClient.getEntity("partitionKey", "rowKey");

 System.out.printf("Retrieved entity with partition key '%s' and row key '%s'.", tableEntity.getPartitionKey(),
     tableEntity.getRowKey());

Note: for asynchronous sample, refer to TableAsyncClient.


Update a TableEntity

The updateEntity(TableEntity entity) method can be used to update a table entity within a table in your Azure Storage or Azure Cosmos account.

The sample below updates a TableEntity with a partition key of "partitionKey" and a row key of "rowKey", adding a new property with a key of "Property" and a value of "Value".

TableEntity myTableEntity = new TableEntity("partitionKey", "rowKey")
     .addProperty("Property", "Value");

 tableClient.updateEntity(myTableEntity, TableEntityUpdateMode.REPLACE);

 System.out.printf("Table entity with partition key '%s' and row key: '%s' was updated/created.", "partitionKey",
     "rowKey");

Note: for asynchronous sample, refer to TableAsyncClient.


List TableEntity

The listEntities() method can be used to list the entities within a table in your Azure Storage or Azure Cosmos account.

The following sample lists all TableEntity within the table without filtering out any entities.

PagedIterable<TableEntity> tableEntities = tableClient.listEntities();

 tableEntities.forEach(tableEntity ->
     System.out.printf("Retrieved entity with partition key '%s' and row key '%s'.%n",
         tableEntity.getPartitionKey(), tableEntity.getRowKey()));

List TableEntity with filtering and selecting

The following sample lists TableEntity within the table, filtering out any entities that do not have a partition key of "partitionKey" and a row key of "rowKey" and only selects the "name", "lastname", and "age" properties.

List<String> propertiesToSelect = new ArrayList<>();
 propertiesToSelect.add("name");
 propertiesToSelect.add("lastname");
 propertiesToSelect.add("age");

 ListEntitiesOptions listEntitiesOptions = new ListEntitiesOptions()
     .setTop(15)
     .setFilter("PartitionKey eq 'MyPartitionKey' and RowKey eq 'MyRowKey'")
     .setSelect(propertiesToSelect);

 PagedIterable<TableEntity> myTableEntities = tableClient.listEntities(listEntitiesOptions,
     Duration.ofSeconds(5), null);

 myTableEntities.forEach(tableEntity -> {
     System.out.printf("Retrieved entity with partition key '%s', row key '%s' and properties:%n",
         tableEntity.getPartitionKey(), tableEntity.getRowKey());

     tableEntity.getProperties().forEach((key, value) ->
         System.out.printf("Name: '%s'. Value: '%s'.%n", key, value));
 });

Note: for asynchronous sample, refer to TableAsyncClient.


Delete a TableEntity

The deleteEntity(String partitionKey, String rowKey) method can be used to delete a table entity within a table in your Azure Storage or Azure Cosmos account.

The sample below deletes a TableEntity with a partition key of "partitionKey" and a row key of "rowKey".

tableClient.deleteEntity("partitionKey", "rowKey");

 System.out.printf("Table entity with partition key '%s' and row key: '%s' was deleted.", "partitionKey", "rowKey");

Note: for asynchronous sample, refer to TableAsyncClient.


Submit a transactional batch

The submitTransaction(List<TableTransactionAction> transactionActions) method can be used to submit a transactional batch of actions to perform on the table in your Azure Storage or Azure Cosmos account.

The following sample shows how to prepare and submit a transactional batch with multiple actions.

List<TableTransactionAction> transactionActions = new ArrayList<>();

 String partitionKey = "markers";
 String firstEntityRowKey = "m001";
 String secondEntityRowKey = "m002";

 TableEntity firstEntity = new TableEntity(partitionKey, firstEntityRowKey)
     .addProperty("Type", "Dry")
     .addProperty("Color", "Red");

 transactionActions.add(new TableTransactionAction(TableTransactionActionType.CREATE, firstEntity));

 System.out.printf("Added create action for entity with partition key '%s', and row key '%s'.%n", partitionKey,
     firstEntityRowKey);

 TableEntity secondEntity = new TableEntity(partitionKey, secondEntityRowKey)
     .addProperty("Type", "Wet")
     .addProperty("Color", "Blue");

 transactionActions.add(new TableTransactionAction(TableTransactionActionType.CREATE, secondEntity));

 System.out.printf("Added create action for entity with partition key '%s', and row key '%s'.%n", partitionKey,
     secondEntityRowKey);

 TableTransactionResult tableTransactionResult = tableClient.submitTransaction(transactionActions);

 System.out.print("Submitted transaction. The ordered response status codes for the actions are:");

 tableTransactionResult.getTransactionActionResponses().forEach(tableTransactionActionResponse ->
     System.out.printf("%n%d", tableTransactionActionResponse.getStatusCode()));

Note: for asynchronous sample, refer to TableAsyncClient.

Method Summary

Modifier and Type Method and Description
void createEntity(TableEntity entity)

Inserts an TableEntity into the table.

Response<Void> createEntityWithResponse(TableEntity entity, Duration timeout, Context context)

Inserts an TableEntity into the table.

TableItem createTable()

Creates the table within the Tables service.

Response<TableItem> createTableWithResponse(Duration timeout, Context context)

Creates the table within the Tables service.

void deleteEntity(TableEntity entity)

Deletes an TableEntity from the table.

void deleteEntity(String partitionKey, String rowKey)

Deletes an TableEntity from the table.

Response<Void> deleteEntityWithResponse(TableEntity entity, boolean ifUnchanged, Duration timeout, Context context)

Deletes an TableEntity from the table.

void deleteTable()

Deletes the table within the Tables service.

Response<Void> deleteTableWithResponse(Duration timeout, Context context)

Deletes the table within the Tables service.

String generateSas(TableSasSignatureValues tableSasSignatureValues)

Generates a service SAS for the table using the specified TableSasSignatureValues.

TableAccessPolicies getAccessPolicies()

Retrieves details about any stored TableAccessPolicies specified on the table that may be used with Shared Access Signatures.

Response<TableAccessPolicies> getAccessPoliciesWithResponse(Duration timeout, Context context)

Retrieves details about any stored TableAccessPolicies specified on the table that may be used with Shared Access Signatures.

String getAccountName()

Gets the name of the account containing the table.

TableEntity getEntity(String partitionKey, String rowKey)

Gets a single TableEntity from the table.

Response<TableEntity> getEntityWithResponse(String partitionKey, String rowKey, List<String> select, Duration timeout, Context context)

Gets a single TableEntity from the table.

TableServiceVersion getServiceVersion()

Gets the REST API version used by this client.

String getTableEndpoint()

Gets the endpoint for this table.

String getTableName()

Gets the name of the table.

PagedIterable<TableEntity> listEntities()

Lists all TableEntity within the table.

PagedIterable<TableEntity> listEntities(ListEntitiesOptions options, Duration timeout, Context context)

Lists TableEntity using the parameters in the provided options.

void setAccessPolicies(List<TableSignedIdentifier> tableSignedIdentifiers)

Sets stored TableAccessPolicies for the table that may be used with Shared Access Signatures.

Response<Void> setAccessPoliciesWithResponse(List<TableSignedIdentifier> tableSignedIdentifiers, Duration timeout, Context context)

Sets stored TableAccessPolicies for the table that may be used with Shared Access Signatures.

TableTransactionResult submitTransaction(List<TableTransactionAction> transactionActions)

Executes all TableTransactionAction within the list inside a transaction.

Response<TableTransactionResult> submitTransactionWithResponse(List<TableTransactionAction> transactionActions, Duration timeout, Context context)

Executes all TableTransactionAction within the list inside a transaction.

void updateEntity(TableEntity entity)

Updates an existing TableEntity by merging the provided TableEntity with the existing TableEntity.

void updateEntity(TableEntity entity, TableEntityUpdateMode updateMode)

Updates an existing TableEntity using the specified TableEntityUpdateMode.

Response<Void> updateEntityWithResponse(TableEntity entity, TableEntityUpdateMode updateMode, boolean ifUnchanged, Duration timeout, Context context)

Updates an existing TableEntity using the specified TableEntityUpdateMode.

void upsertEntity(TableEntity entity)

Inserts an TableEntity into the table if it does not exist, or merges the TableEntity with the existing TableEntity otherwise.

Response<Void> upsertEntityWithResponse(TableEntity entity, TableEntityUpdateMode updateMode, Duration timeout, Context context)

Inserts an TableEntity into the table if it does not exist, or updates the existing TableEntity using the specified TableEntityUpdateMode otherwise.

Methods inherited from java.lang.Object

Method Details

createEntity

public void createEntity(TableEntity entity)

Inserts an TableEntity into the table.

Code Samples

Inserts an TableEntity into the table. Prints out the details of the created TableEntity.

TableEntity tableEntity = new TableEntity("partitionKey", "rowKey")
     .addProperty("Property", "Value");

 tableClient.createEntity(tableEntity);

 System.out.printf("Table entity with partition key '%s' and row key: '%s' was created.", "partitionKey", "rowKey");

Parameters:

entity - The TableEntity to insert.

createEntityWithResponse

public Response createEntityWithResponse(TableEntity entity, Duration timeout, Context context)

Inserts an TableEntity into the table.

Code Samples

Inserts an TableEntity into the table. Prints out the details of the Response<T> and the created TableEntity.

TableEntity myTableEntity = new TableEntity("partitionKey", "rowKey")
     .addProperty("Property", "Value");

 Response<Void> response = tableClient.createEntityWithResponse(myTableEntity, Duration.ofSeconds(5),
     new Context("key1", "value1"));

 System.out.printf("Response successful with status code: %d. Table entity with partition key '%s' and row key"
     + " '%s' was created.", response.getStatusCode(), "partitionKey", "rowKey");

Parameters:

entity - The TableEntity to insert.
timeout - An optional timeout value beyond which a RuntimeException will be raised.
context - Additional Context that is passed through the HttpPipeline during the service call.

Returns:

createTable

public TableItem createTable()

Creates the table within the Tables service.

Code Samples

Creates a table. Prints out the details of the created table.

TableItem tableItem = tableClient.createTable();

 System.out.printf("Table with name '%s' was created.", tableItem.getName());

Returns:

A TableItem that represents the table.

createTableWithResponse

public Response createTableWithResponse(Duration timeout, Context context)

Creates the table within the Tables service.

Code Samples

Creates a table. Prints out the details of the Response<T> and the created table.

Response<TableItem> response = tableClient.createTableWithResponse(Duration.ofSeconds(5),
     new Context("key1", "value1"));

 System.out.printf("Response successful with status code: %d. Table with name '%s' was created.",
     response.getStatusCode(), response.getValue().getName());

Parameters:

timeout - An optional timeout value beyond which a RuntimeException will be raised.
context - Additional Context that is passed through the HttpPipeline during the service call.

Returns:

The Response<T> containing a TableItem that represents the table.

deleteEntity

public void deleteEntity(TableEntity entity)

Deletes an TableEntity from the table.

Code Samples

Deletes a TableEntity on the table. Prints out the details of the deleted TableEntity.

TableEntity myTableEntity = new TableEntity("partitionKey", "rowKey")
     .addProperty("Property", "Value");

 tableClient.deleteEntity(myTableEntity);

 System.out.printf("Table entity with partition key '%s' and row key: '%s' was created.", "partitionKey", "rowKey");

Parameters:

entity - The TableEntity to delete.

deleteEntity

public void deleteEntity(String partitionKey, String rowKey)

Deletes an TableEntity from the table.

Code Samples

Deletes an TableEntity on the table. Prints out the entity's partitionKey and rowKey.

tableClient.deleteEntity("partitionKey", "rowKey");

 System.out.printf("Table entity with partition key '%s' and row key: '%s' was deleted.", "partitionKey", "rowKey");

Parameters:

partitionKey - The partition key of the TableEntity.
rowKey - The row key of the TableEntity.

deleteEntityWithResponse

public Response deleteEntityWithResponse(TableEntity entity, boolean ifUnchanged, Duration timeout, Context context)

Deletes an TableEntity from the table.

Code Samples

Deletes a TableEntity on the table. Prints out the details of the Response<T> and the deleted TableEntity.

TableEntity someTableEntity = new TableEntity("partitionKey", "rowKey")
     .addProperty("Property", "Value");

 Response<Void> response = tableClient.deleteEntityWithResponse(someTableEntity, true, Duration.ofSeconds(5),
     new Context("key1", "value1"));

 System.out.printf("Response successful with status code: %d. Table entity with partition key '%s' and row key"
     + " '%s' was deleted.", response.getStatusCode(), "partitionKey", "rowKey");

Parameters:

entity - The table TableEntity to delete.
ifUnchanged - When true, the ETag of the provided TableEntity must match the ETag of the TableEntity in the Table service. If the values do not match, the update will not occur and an exception will be thrown.
timeout - An optional timeout value beyond which a RuntimeException will be raised.
context - Additional Context that is passed through the HttpPipeline during the service call.

Returns:

deleteTable

public void deleteTable()

Deletes the table within the Tables service.

Code Samples

Deletes a table.

tableClient.deleteTable();

 System.out.print("Table was deleted.");

deleteTableWithResponse

public Response deleteTableWithResponse(Duration timeout, Context context)

Deletes the table within the Tables service.

Code Samples

Deletes a table. Prints out the details of the Response<T>.

Response<Void> response = tableClient.deleteTableWithResponse(Duration.ofSeconds(5),
     new Context("key1", "value1"));

 System.out.printf("Table was deleted successfully with status code: %d.", response.getStatusCode());

Parameters:

timeout - An optional timeout value beyond which a RuntimeException will be raised.
context - Additional Context that is passed through the HttpPipeline during the service call.

Returns:

generateSas

public String generateSas(TableSasSignatureValues tableSasSignatureValues)

Generates a service SAS for the table using the specified TableSasSignatureValues.

Note: The client must be authenticated via AzureNamedKeyCredential.

See TableSasSignatureValues for more information on how to construct a service SAS.

Parameters:

tableSasSignatureValues - TableSasSignatureValues.

Returns:

A String representing the SAS query parameters.

getAccessPolicies

public TableAccessPolicies getAccessPolicies()

Retrieves details about any stored TableAccessPolicies specified on the table that may be used with Shared Access Signatures.

This operation is only supported on Azure Storage endpoints.

Code Samples

Gets a table's TableAccessPolicies. Prints out the details of the retrieved TableAccessPolicies.

TableAccessPolicies accessPolicies = tableClient.getAccessPolicies();

 accessPolicies.getIdentifiers().forEach(signedIdentifier ->
     System.out.printf("Retrieved table access policy with id '%s'.", signedIdentifier.getId()));

Returns:

The table's TableAccessPolicies.

getAccessPoliciesWithResponse

public Response getAccessPoliciesWithResponse(Duration timeout, Context context)

Retrieves details about any stored TableAccessPolicies specified on the table that may be used with Shared Access Signatures.

This operation is only supported on Azure Storage endpoints.

Code Samples

Gets a table's TableAccessPolicies. Prints out the details of the Response<T> and the retrieved TableAccessPolicies.

List<String> propertiesToSelect = new ArrayList<>();
 propertiesToSelect.add("name");
 propertiesToSelect.add("lastname");
 propertiesToSelect.add("age");

 Response<TableAccessPolicies> response = tableClient.getAccessPoliciesWithResponse(Duration.ofSeconds(5),
     new Context("key1", "value1"));

 System.out.printf("Response successful with status code: %d. Retrieved table access policies with the following"
     + " IDs:", response.getStatusCode());

 response.getValue().getIdentifiers().forEach(signedIdentifier ->
     System.out.printf("%n%s", signedIdentifier.getId()));

Parameters:

timeout - An optional timeout value beyond which a RuntimeException will be raised.
context - Additional Context that is passed through the HttpPipeline during the service call.

Returns:

An Response<T> containing the table's TableAccessPolicies.

getAccountName

public String getAccountName()

Gets the name of the account containing the table.

Returns:

The name of the account containing the table.

getEntity

public TableEntity getEntity(String partitionKey, String rowKey)

Gets a single TableEntity from the table.

Code Samples

Gets an TableEntity on the table. Prints out the details of the retrieved TableEntity.

TableEntity tableEntity = tableClient.getEntity("partitionKey", "rowKey");

 System.out.printf("Retrieved entity with partition key '%s' and row key '%s'.", tableEntity.getPartitionKey(),
     tableEntity.getRowKey());

Parameters:

partitionKey - The partition key of the TableEntity.
rowKey - The partition key of the TableEntity.

Returns:

getEntityWithResponse

public Response getEntityWithResponse(String partitionKey, String rowKey, List select, Duration timeout, Context context)

Gets a single TableEntity from the table.

Code Samples

Gets an TableEntity on the table. Prints out the details of the Response<T> retrieved TableEntity.

List<String> propertiesToSelect = new ArrayList<>();
 propertiesToSelect.add("name");
 propertiesToSelect.add("lastname");
 propertiesToSelect.add("age");

 Response<TableEntity> response = tableClient.getEntityWithResponse("partitionKey", "rowKey", propertiesToSelect,
     Duration.ofSeconds(5), new Context("key1", "value1"));

 TableEntity myTableEntity = response.getValue();

 System.out.printf("Response successful with status code: %d. Retrieved entity with partition key '%s', row key"
         + " '%s' and properties:", response.getStatusCode(), myTableEntity.getPartitionKey(),
     myTableEntity.getRowKey());

 myTableEntity.getProperties().forEach((key, value) ->
     System.out.printf("%nName: '%s'. Value: '%s'.", key, value));

Parameters:

partitionKey - The partition key of the TableEntity.
rowKey - The partition key of the TableEntity.
select - A list of properties to select on the TableEntity.
timeout - An optional timeout value beyond which a RuntimeException will be raised.
context - Additional Context that is passed through the HttpPipeline during the service call.

Returns:

The Response<T> containing the TableEntity.

getServiceVersion

public TableServiceVersion getServiceVersion()

Gets the REST API version used by this client.

Returns:

The REST API version used by this client.

getTableEndpoint

public String getTableEndpoint()

Gets the endpoint for this table.

Returns:

The endpoint for this table.

getTableName

public String getTableName()

Gets the name of the table.

Returns:

The name of the table.

listEntities

public PagedIterable listEntities()

Lists all TableEntity within the table.

Code Samples

Lists all TableEntity on the table. Prints out the details of the retrieved TableEntity.

PagedIterable<TableEntity> tableEntities = tableClient.listEntities();

 tableEntities.forEach(tableEntity ->
     System.out.printf("Retrieved entity with partition key '%s' and row key '%s'.%n",
         tableEntity.getPartitionKey(), tableEntity.getRowKey()));

Returns:

A PagedIterable<T> containing all TableEntity within the table.

listEntities

public PagedIterable listEntities(ListEntitiesOptions options, Duration timeout, Context context)

Lists TableEntity using the parameters in the provided options.

If the filter parameter in the options is set, only TableEntity matching the filter will be returned. If the select parameter is set, only the properties included in the select parameter will be returned for each TableEntity. If the top parameter is set, the maximum number of returned TableEntity per page will be limited to that value.

Code Samples

Lists all TableEntity on the table. Prints out the details of the Response<T> and all the retrieved TableEntity.

List<String> propertiesToSelect = new ArrayList<>();
 propertiesToSelect.add("name");
 propertiesToSelect.add("lastname");
 propertiesToSelect.add("age");

 ListEntitiesOptions listEntitiesOptions = new ListEntitiesOptions()
     .setTop(15)
     .setFilter("PartitionKey eq 'MyPartitionKey' and RowKey eq 'MyRowKey'")
     .setSelect(propertiesToSelect);

 PagedIterable<TableEntity> myTableEntities = tableClient.listEntities(listEntitiesOptions,
     Duration.ofSeconds(5), null);

 myTableEntities.forEach(tableEntity -> {
     System.out.printf("Retrieved entity with partition key '%s', row key '%s' and properties:%n",
         tableEntity.getPartitionKey(), tableEntity.getRowKey());

     tableEntity.getProperties().forEach((key, value) ->
         System.out.printf("Name: '%s'. Value: '%s'.%n", key, value));
 });

Parameters:

options - The filter, select, and top OData query options to apply to this operation.
timeout - An optional timeout value beyond which a RuntimeException will be raised.
context - Additional Context that is passed through the HttpPipeline during the service call.

Returns:

A PagedIterable<T> containing matching TableEntity within the table.

setAccessPolicies

public void setAccessPolicies(List tableSignedIdentifiers)

Sets stored TableAccessPolicies for the table that may be used with Shared Access Signatures.

This operation is only supported on Azure Storage endpoints.

Code Samples

Sets stored TableAccessPolicies on a table.

List<TableSignedIdentifier> signedIdentifiers = new ArrayList<>();

 signedIdentifiers.add(new TableSignedIdentifier("id1")
     .setAccessPolicy(new TableAccessPolicy()
         .setStartsOn(OffsetDateTime.of(2021, 1, 1, 0, 0, 0, 0, ZoneOffset.UTC))
         .setExpiresOn(OffsetDateTime.of(2022, 1, 1, 0, 0, 0, 0, ZoneOffset.UTC))
         .setPermissions("r")));
 signedIdentifiers.add(new TableSignedIdentifier("id2")
     .setAccessPolicy(new TableAccessPolicy()
         .setStartsOn(OffsetDateTime.of(2021, 1, 1, 0, 0, 0, 0, ZoneOffset.UTC))
         .setExpiresOn(OffsetDateTime.of(2021, 1, 2, 0, 0, 0, 0, ZoneOffset.UTC))
         .setPermissions("raud")));

 tableClient.setAccessPolicies(signedIdentifiers);

 System.out.print("Set table access policies.");

Parameters:

tableSignedIdentifiers - The TableSignedIdentifier for the table.

setAccessPoliciesWithResponse

public Response setAccessPoliciesWithResponse(List tableSignedIdentifiers, Duration timeout, Context context)

Sets stored TableAccessPolicies for the table that may be used with Shared Access Signatures.

This operation is only supported on Azure Storage endpoints.

Code Samples

Sets stored TableAccessPolicies on a table. Prints out details of the Response<T>.

List<TableSignedIdentifier> mySignedIdentifiers = new ArrayList<>();

 mySignedIdentifiers.add(new TableSignedIdentifier("id1")
     .setAccessPolicy(new TableAccessPolicy()
         .setStartsOn(OffsetDateTime.of(2021, 1, 1, 0, 0, 0, 0, ZoneOffset.UTC))
         .setExpiresOn(OffsetDateTime.of(2022, 1, 1, 0, 0, 0, 0, ZoneOffset.UTC))
         .setPermissions("r")));
 mySignedIdentifiers.add(new TableSignedIdentifier("id2")
     .setAccessPolicy(new TableAccessPolicy()
         .setStartsOn(OffsetDateTime.of(2021, 1, 1, 0, 0, 0, 0, ZoneOffset.UTC))
         .setExpiresOn(OffsetDateTime.of(2021, 1, 2, 0, 0, 0, 0, ZoneOffset.UTC))
         .setPermissions("raud")));

 Response<Void> response = tableClient.setAccessPoliciesWithResponse(mySignedIdentifiers, Duration.ofSeconds(5),
     new Context("key1", "value1"));

 System.out.printf("Set table access policies successfully with status code: %d.", response.getStatusCode());

Parameters:

tableSignedIdentifiers - The TableSignedIdentifier for the table.
timeout - An optional timeout value beyond which a RuntimeException will be raised.
context - Additional Context that is passed through the HttpPipeline during the service call.

Returns:

submitTransaction

public TableTransactionResult submitTransaction(List transactionActions)

Executes all TableTransactionAction within the list inside a transaction. When the call completes, either all TableTransactionAction in the transaction will succeed, or if a failure occurs, all TableTransactionAction in the transaction will be rolled back. TableTransactionAction are executed sequentially. Each TableTransactionAction must operate on a distinct row key. Attempting to pass multiple TableTransactionAction that share the same row key will cause an error.

Code Samples

Submits a transaction that contains multiple TableTransactionAction to be applied to TableEntity on a table. Prints out details of each TableTransactionAction's Response<T>.

List<TableTransactionAction> transactionActions = new ArrayList<>();

 String partitionKey = "markers";
 String firstEntityRowKey = "m001";
 String secondEntityRowKey = "m002";

 TableEntity firstEntity = new TableEntity(partitionKey, firstEntityRowKey)
     .addProperty("Type", "Dry")
     .addProperty("Color", "Red");

 transactionActions.add(new TableTransactionAction(TableTransactionActionType.CREATE, firstEntity));

 System.out.printf("Added create action for entity with partition key '%s', and row key '%s'.%n", partitionKey,
     firstEntityRowKey);

 TableEntity secondEntity = new TableEntity(partitionKey, secondEntityRowKey)
     .addProperty("Type", "Wet")
     .addProperty("Color", "Blue");

 transactionActions.add(new TableTransactionAction(TableTransactionActionType.CREATE, secondEntity));

 System.out.printf("Added create action for entity with partition key '%s', and row key '%s'.%n", partitionKey,
     secondEntityRowKey);

 TableTransactionResult tableTransactionResult = tableClient.submitTransaction(transactionActions);

 System.out.print("Submitted transaction. The ordered response status codes for the actions are:");

 tableTransactionResult.getTransactionActionResponses().forEach(tableTransactionActionResponse ->
     System.out.printf("%n%d", tableTransactionActionResponse.getStatusCode()));

Shows how to handle a transaction with a failing TableTransactionAction via the provided TableTransactionFailedException, which contains the index of the first failing action in the transaction.

tableAsyncClient.submitTransaction(transactionActions)
     .contextWrite(Context.of("key1", "value1", "key2", "value2"))
     .doOnError(TableTransactionFailedException.class, e -> {
         // If the transaction fails, the resulting exception contains the index of the first action that failed.
         int failedActionIndex = e.getFailedTransactionActionIndex();
         // You can use this index to modify the offending action or remove it from the list of actions to send
         // in the transaction, for example.
         transactionActions.remove(failedActionIndex);
         // And then retry submitting the transaction.
     })
     .subscribe(tableTransactionResult -> {
         System.out.print("Submitted transaction. The ordered response status codes for the actions are:");

         tableTransactionResult.getTransactionActionResponses().forEach(tableTransactionActionResponse ->
             System.out.printf("%n%d", tableTransactionActionResponse.getStatusCode()));
     });

Parameters:

transactionActions - A List of TableTransactionAction to perform on TableEntity in a table.

Returns:

A List of TableTransactionActionResponse that correspond to each TableTransactionResult in the transaction.

submitTransactionWithResponse

public Response submitTransactionWithResponse(List transactionActions, Duration timeout, Context context)

Executes all TableTransactionAction within the list inside a transaction. When the call completes, either all TableTransactionAction in the transaction will succeed, or if a failure occurs, all TableTransactionAction in the transaction will be rolled back. TableTransactionAction are executed sequentially. Each TableTransactionAction must operate on a distinct row key. Attempting to pass multiple TableTransactionAction that share the same row key will cause an error.

Code Samples

Submits a transaction that contains multiple TableTransactionAction to be applied to TableEntity on a table. Prints out details of the Response<T> for the operation, as well as each TableTransactionAction's corresponding HTTP response.

List<TableTransactionAction> myTransactionActions = new ArrayList<>();

 String myPartitionKey = "markers";
 String myFirstEntityRowKey = "m001";
 String mySecondEntityRowKey = "m002";

 TableEntity myFirstEntity = new TableEntity(myPartitionKey, myFirstEntityRowKey)
     .addProperty("Type", "Dry")
     .addProperty("Color", "Red");

 myTransactionActions.add(new TableTransactionAction(TableTransactionActionType.CREATE, myFirstEntity));

 System.out.printf("Added create action for entity with partition key '%s', and row key '%s'.%n", myPartitionKey,
     myFirstEntityRowKey);

 TableEntity mySecondEntity = new TableEntity(myPartitionKey, mySecondEntityRowKey)
     .addProperty("Type", "Wet")
     .addProperty("Color", "Blue");

 myTransactionActions.add(new TableTransactionAction(TableTransactionActionType.CREATE, mySecondEntity));

 System.out.printf("Added create action for entity with partition key '%s', and row key '%s'.%n", myPartitionKey,
     mySecondEntityRowKey);

 Response<TableTransactionResult> response = tableClient.submitTransactionWithResponse(myTransactionActions,
     Duration.ofSeconds(5), new Context("key1", "value1"));

 System.out.printf("Response successful with status code: %d. The ordered response status codes of the submitted"
     + " actions are:", response.getStatusCode());

 response.getValue().getTransactionActionResponses().forEach(tableTransactionActionResponse ->
     System.out.printf("%n%d", tableTransactionActionResponse.getStatusCode()));

Shows how to handle a transaction with a failing TableTransactionAction via the provided TableTransactionFailedException, which contains the index of the first failing action in the transaction.

try {
     Response<TableTransactionResult> transactionResultResponse =
         tableClient.submitTransactionWithResponse(myTransactionActions, Duration.ofSeconds(5),
             new Context("key1", "value1"));

     System.out.printf("Response successful with status code: %d. The ordered response status codes of the"
         + " submitted actions are:", transactionResultResponse.getStatusCode());

     transactionResultResponse.getValue().getTransactionActionResponses()
         .forEach(tableTransactionActionResponse ->
             System.out.printf("%n%d", tableTransactionActionResponse.getStatusCode()));
 } catch (TableTransactionFailedException e) {
     // If the transaction fails, the resulting exception contains the index of the first action that failed.
     int failedActionIndex = e.getFailedTransactionActionIndex();
     // You can use this index to modify the offending action or remove it from the list of actions to send in
     // the transaction, for example.
     myTransactionActions.remove(failedActionIndex);
     // And then retry submitting the transaction.
 }

Parameters:

transactionActions - A List of TableTransactionAction to perform on TableEntity in a table.
timeout - An optional timeout value beyond which a RuntimeException will be raised.
context - Additional Context that is passed through the HttpPipeline during the service call.

Returns:

An Response<T> produced for the transaction itself. The response's value will contain a List of TableTransactionActionResponse that correspond to each TableTransactionAction in the transaction.

updateEntity

public void updateEntity(TableEntity entity)

Updates an existing TableEntity by merging the provided TableEntity with the existing TableEntity.

Code Samples

Updates a TableEntity on the table. Prints out the details of the updated TableEntity.

TableEntity tableEntity = new TableEntity("partitionKey", "rowKey")
     .addProperty("Property", "Value");

 tableClient.updateEntity(tableEntity);

 System.out.printf("Table entity with partition key '%s' and row key: '%s' was updated/created.", "partitionKey",
     "rowKey");

Parameters:

entity - The TableEntity to update.

updateEntity

public void updateEntity(TableEntity entity, TableEntityUpdateMode updateMode)

Updates an existing TableEntity using the specified TableEntityUpdateMode. The default TableEntityUpdateMode is MERGE.

When the TableEntityUpdateMode is MERGE, the provided TableEntity's properties will be merged into the existing TableEntity. When the TableEntityUpdateMode is REPLACE, the provided TableEntity's properties will completely replace those in the existing TableEntity.

Code Samples

Updates a TableEntity on the table with the specified TableEntityUpdateMode. Prints out the details of the updated TableEntity.

TableEntity myTableEntity = new TableEntity("partitionKey", "rowKey")
     .addProperty("Property", "Value");

 tableClient.updateEntity(myTableEntity, TableEntityUpdateMode.REPLACE);

 System.out.printf("Table entity with partition key '%s' and row key: '%s' was updated/created.", "partitionKey",
     "rowKey");

Parameters:

entity - The TableEntity to update.
updateMode - The type of update to perform.

updateEntityWithResponse

public Response updateEntityWithResponse(TableEntity entity, TableEntityUpdateMode updateMode, boolean ifUnchanged, Duration timeout, Context context)

Updates an existing TableEntity using the specified TableEntityUpdateMode. The default TableEntityUpdateMode is MERGE.

When the TableEntityUpdateMode is MERGE, the provided TableEntity's properties will be merged into the existing TableEntity. When the TableEntityUpdateMode is REPLACE, the provided TableEntity's properties will completely replace those in the existing TableEntity.

Code Samples

Updates a TableEntity on the table with the specified update mode if the ETags on both TableEntity match. Prints out the details of the Response<T> updated TableEntity.

TableEntity someTableEntity = new TableEntity("partitionKey", "rowKey")
     .addProperty("Property", "Value");

 Response<Void> response = tableClient.updateEntityWithResponse(someTableEntity, TableEntityUpdateMode.REPLACE,
     true, Duration.ofSeconds(5), new Context("key1", "value1"));

 System.out.printf("Response successful with status code: %d. Table entity with partition key '%s' and row key"
     + " '%s' was updated.", response.getStatusCode(), "partitionKey", "rowKey");

Parameters:

entity - The TableEntity to update.
updateMode - The type of update to perform.
ifUnchanged - When true, the ETag of the provided TableEntity must match the ETag of the TableEntity in the Table service. If the values do not match, the update will not occur and an exception will be thrown.
timeout - An optional timeout value beyond which a RuntimeException will be raised.
context - Additional Context that is passed through the HttpPipeline during the service call.

Returns:

upsertEntity

public void upsertEntity(TableEntity entity)

Inserts an TableEntity into the table if it does not exist, or merges the TableEntity with the existing TableEntity otherwise.

Code Samples

Upserts an TableEntity into the table. Prints out the details of the upserted TableEntity.

TableEntity tableEntity = new TableEntity("partitionKey", "rowKey")
     .addProperty("Property", "Value");

 tableClient.upsertEntity(tableEntity);

 System.out.printf("Table entity with partition key '%s' and row key: '%s' was updated/created.", "partitionKey",
     "rowKey");

Parameters:

entity - The TableEntity to upsert.

upsertEntityWithResponse

public Response upsertEntityWithResponse(TableEntity entity, TableEntityUpdateMode updateMode, Duration timeout, Context context)

Inserts an TableEntity into the table if it does not exist, or updates the existing TableEntity using the specified TableEntityUpdateMode otherwise. The default TableEntityUpdateMode is MERGE.

When the TableEntityUpdateMode is MERGE, the provided TableEntity's properties will be merged into the existing TableEntity. When the TableEntityUpdateMode is REPLACE, the provided TableEntity's properties will completely replace those in the existing TableEntity.

Code Samples

Upserts an TableEntity into the table with the specified TableEntityUpdateMode if said TableEntity already exists. Prints out the details of the Response<T> and the upserted TableEntity.

TableEntity myTableEntity = new TableEntity("partitionKey", "rowKey")
     .addProperty("Property", "Value");

 Response<Void> response = tableClient.upsertEntityWithResponse(myTableEntity, TableEntityUpdateMode.REPLACE,
     Duration.ofSeconds(5), new Context("key1", "value1"));

 System.out.printf("Response successful with status code: %d. Table entity with partition key '%s' and row key"
     + " '%s' was updated/created.", response.getStatusCode(), "partitionKey", "rowKey");

Parameters:

entity - The TableEntity to upsert.
updateMode - The type of update to perform if the TableEntity already exits.
timeout - An optional timeout value beyond which a RuntimeException will be raised.
context - Additional Context that is passed through the HttpPipeline during the service call.

Returns:

Applies to