Class TransactionalBatch

Namespace

Microsoft.Azure.Cosmos

Assembly

Microsoft.Azure.Cosmos.Client.dll

Represents a batch of operations against items with the same PartitionKey in a container that will be performed in a transactional manner at the Azure Cosmos DB service. Use CreateTransactionalBatch(PartitionKey) to create an instance of TransactionalBatch.

public abstract class TransactionalBatch

Inheritance

object

TransactionalBatch

Inherited Members

object.GetType()

object.MemberwiseClone()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Extension Methods

CosmosLinqExtensions.DocumentId(object)

CosmosLinqExtensions.IsArray(object)

CosmosLinqExtensions.IsBool(object)

CosmosLinqExtensions.IsDefined(object)

CosmosLinqExtensions.IsNull(object)

CosmosLinqExtensions.IsNumber(object)

CosmosLinqExtensions.IsObject(object)

CosmosLinqExtensions.IsPrimitive(object)

CosmosLinqExtensions.IsString(object)

CosmosLinqExtensions.RegexMatch(object, string, string)

CosmosLinqExtensions.RegexMatch(object, string)

Examples

This example atomically modifies a set of documents as a batch.

public class ToDoActivity
{
    public string type { get; set; }
    public string id { get; set; }
    public string status { get; set; }
}

string activityType = "personal";
ToDoActivity test1 = new ToDoActivity()
{
    type = activityType,
    id = "learning",
    status = "ToBeDone"
};

ToDoActivity test2 = new ToDoActivity()
{
    type = activityType,
    id = "shopping",
    status = "Done"
};

ToDoActivity test3 = new ToDoActivity()
{
    type = activityType,
    id = "swimming",
    status = "ToBeDone"
};

ToDoActivity test4 = new ToDoActivity()
{
    type = activityType,
    id = "running",
    status = "ToBeDone"
};

List<PatchOperation> patchOperations = new List<PatchOperation>();
patchOperations.Add(PatchOperation.Replace("/status", "InProgress");
patchOperations.Add(PatchOperation.Add("/progress", 50);

using (TransactionalBatchResponse batchResponse = await container.CreateTransactionalBatch(new Cosmos.PartitionKey(activityType))
    .CreateItem<ToDoActivity>(test1)
    .ReplaceItem<ToDoActivity>(test2.id, test2)
    .UpsertItem<ToDoActivity>(test3)
    .PatchItem(test4.id, patchOperations)
    .DeleteItem("reading")
    .CreateItemStream(streamPayload1)
    .ReplaceItemStream("eating", streamPayload2)
    .UpsertItemStream(streamPayload3)
    .ExecuteAsync())
{
   if (!batchResponse.IsSuccessStatusCode)
   {
       // Handle and log exception
       return;
   }

   // Look up interested results - eg. via typed access on operation results
   TransactionalBatchOperationResult<ToDoActivity> replaceResult = batchResponse.GetOperationResultAtIndex<ToDoActivity>(0);
   ToDoActivity readActivity = replaceResult.Resource;
}

This example atomically reads a set of documents as a batch.

string activityType = "personal";
using (TransactionalBatchResponse batchResponse = await container.CreateTransactionalBatch(new Cosmos.PartitionKey(activityType))
   .ReadItem("playing")
   .ReadItem("walking")
   .ReadItem("jogging")
   .ReadItem("running")
   .ExecuteAsync())
{
    // Look up interested results - eg. via direct access to operation result stream
    List<string> resultItems = new List<string>();
    foreach (TransactionalBatchOperationResult operationResult in batchResponse)
    {
        using (StreamReader streamReader = new StreamReader(operationResult.ResourceStream))
        {
            resultItems.Add(await streamReader.ReadToEndAsync());
        }
    }
}

Remarks

Limits on TransactionalBatch requests

Constructors

TransactionalBatch()

protected TransactionalBatch()

Methods

CreateItemStream(Stream, TransactionalBatchItemRequestOptions)

Adds an operation to create an item into the batch.

public abstract TransactionalBatch CreateItemStream(Stream streamPayload, TransactionalBatchItemRequestOptions requestOptions = null)

Parameters

streamPayload Stream

A Stream containing the payload of the item. The stream must have a UTF-8 encoded JSON object which contains an id property.

requestOptions TransactionalBatchItemRequestOptions

(Optional) The options for the item request.

Returns

TransactionalBatch

The transactional batch instance with the operation added.

CreateItem<T>(T, TransactionalBatchItemRequestOptions)

Adds an operation to create an item into the batch.

public abstract TransactionalBatch CreateItem<T>(T item, TransactionalBatchItemRequestOptions requestOptions = null)

Parameters

item T

A JSON serializable object that must contain an id property. See CosmosSerializer to implement a custom serializer.

requestOptions TransactionalBatchItemRequestOptions

(Optional) The options for the item request.

Returns

TransactionalBatch

The transactional batch instance with the operation added.

Type Parameters

T

The type of item to be created.

DeleteItem(string, TransactionalBatchItemRequestOptions)

Adds an operation to delete an item into the batch.

public abstract TransactionalBatch DeleteItem(string id, TransactionalBatchItemRequestOptions requestOptions = null)

Parameters

id string

The unique id of the item.

requestOptions TransactionalBatchItemRequestOptions

(Optional) The options for the item request.

Returns

TransactionalBatch

The transactional batch instance with the operation added.

ExecuteAsync(TransactionalBatchRequestOptions, CancellationToken)

Executes the transactional batch at the Azure Cosmos service as an asynchronous operation.

public abstract Task<TransactionalBatchResponse> ExecuteAsync(TransactionalBatchRequestOptions requestOptions, CancellationToken cancellationToken = default)

Parameters

requestOptions TransactionalBatchRequestOptions

Options that apply specifically to batch request.

cancellationToken CancellationToken

(Optional) Cancellation token representing request cancellation.

Returns

Task<TransactionalBatchResponse>

An awaitable response which contains details of execution of the transactional batch.

If the transactional batch executes successfully, the StatusCode on the response returned will be set to OK.

If an operation within the transactional batch fails during execution, no changes from the batch will be committed and the status of the failing operation is made available in the StatusCode. To get more details about the operation that failed, the response can be enumerated - this returns TransactionalBatchOperationResult instances corresponding to each operation in the transactional batch in the order they were added into the transactional batch. For a result corresponding to an operation within the transactional batch, the StatusCode indicates the status of the operation - if the operation was not executed or it was aborted due to the failure of another operation within the transactional batch, the value of this field will be HTTP 424 (Failed Dependency); for the operation that caused the batch to abort, the value of this field will indicate the cause of failure as a HTTP status code.

The StatusCode on the response returned may also have values such as HTTP 5xx in case of server errors and HTTP 429 (Too Many Requests).

Remarks

This API only throws on client side exceptions. This is to increase performance and prevent the overhead of throwing exceptions. Use IsSuccessStatusCode on the response returned to ensure that the transactional batch succeeded. Limits on TransactionalBatch requests

ExecuteAsync(CancellationToken)

Executes the transactional batch at the Azure Cosmos service as an asynchronous operation.

public abstract Task<TransactionalBatchResponse> ExecuteAsync(CancellationToken cancellationToken = default)

Parameters

cancellationToken CancellationToken

(Optional) Cancellation token representing request cancellation.

Returns

Task<TransactionalBatchResponse>

An awaitable response which contains details of execution of the transactional batch.

If the transactional batch executes successfully, the StatusCode on the response returned will be set to OK.

If an operation within the transactional batch fails during execution, no changes from the batch will be committed and the status of the failing operation is made available in the StatusCode. To get more details about the operation that failed, the response can be enumerated - this returns TransactionalBatchOperationResult instances corresponding to each operation in the transactional batch in the order they were added into the transactional batch. For a result corresponding to an operation within the transactional batch, the StatusCode indicates the status of the operation - if the operation was not executed or it was aborted due to the failure of another operation within the transactional batch, the value of this field will be HTTP 424 (Failed Dependency); for the operation that caused the batch to abort, the value of this field will indicate the cause of failure as a HTTP status code.

The StatusCode on the response returned may also have values such as HTTP 5xx in case of server errors and HTTP 429 (Too Many Requests).

Remarks

This API only throws on client side exceptions. This is to increase performance and prevent the overhead of throwing exceptions. Use IsSuccessStatusCode on the response returned to ensure that the transactional batch succeeded. Limits on TransactionalBatch requests

PatchItem(string, IReadOnlyList<PatchOperation>, TransactionalBatchPatchItemRequestOptions)

Adds an operation to patch an item into the batch.

public abstract TransactionalBatch PatchItem(string id, IReadOnlyList<PatchOperation> patchOperations, TransactionalBatchPatchItemRequestOptions requestOptions = null)

Parameters

id string

The unique id of the item.

patchOperations IReadOnlyList<PatchOperation>

Represents a list of operations to be sequentially applied to the referred Cosmos item.

requestOptions TransactionalBatchPatchItemRequestOptions

(Optional) The options for the item request.

Returns

TransactionalBatch

The transactional batch instance with the operation added.

ReadItem(string, TransactionalBatchItemRequestOptions)

Adds an operation to read an item into the batch.

public abstract TransactionalBatch ReadItem(string id, TransactionalBatchItemRequestOptions requestOptions = null)

Parameters

id string

The unique id of the item.

requestOptions TransactionalBatchItemRequestOptions

(Optional) The options for the item request.

Returns

TransactionalBatch

The transactional batch instance with the operation added.

ReplaceItemStream(string, Stream, TransactionalBatchItemRequestOptions)

Adds an operation to replace an item into the batch.

public abstract TransactionalBatch ReplaceItemStream(string id, Stream streamPayload, TransactionalBatchItemRequestOptions requestOptions = null)

Parameters

id string

The unique id of the item.

streamPayload Stream

A Stream containing the payload of the item. The stream must have a UTF-8 encoded JSON object which contains an id property.

requestOptions TransactionalBatchItemRequestOptions

(Optional) The options for the item request.

Returns

TransactionalBatch

The transactional batch instance with the operation added.

ReplaceItem<T>(string, T, TransactionalBatchItemRequestOptions)

Adds an operation to replace an item into the batch.

public abstract TransactionalBatch ReplaceItem<T>(string id, T item, TransactionalBatchItemRequestOptions requestOptions = null)

Parameters

id string

The unique id of the item.

item T

A JSON serializable object that must contain an id property. See CosmosSerializer to implement a custom serializer.

requestOptions TransactionalBatchItemRequestOptions

(Optional) The options for the item request.

Returns

TransactionalBatch

The transactional batch instance with the operation added.

Type Parameters

T

The type of item to be created.

UpsertItemStream(Stream, TransactionalBatchItemRequestOptions)

Adds an operation to upsert an item into the batch.

public abstract TransactionalBatch UpsertItemStream(Stream streamPayload, TransactionalBatchItemRequestOptions requestOptions = null)

Parameters

streamPayload Stream

A Stream containing the payload of the item. The stream must have a UTF-8 encoded JSON object which contains an id property.

requestOptions TransactionalBatchItemRequestOptions

(Optional) The options for the item request.

Returns

TransactionalBatch

The transactional batch instance with the operation added.

UpsertItem<T>(T, TransactionalBatchItemRequestOptions)

Adds an operation to upsert an item into the batch.

public abstract TransactionalBatch UpsertItem<T>(T item, TransactionalBatchItemRequestOptions requestOptions = null)

Parameters

item T

A JSON serializable object that must contain an id property. See CosmosSerializer to implement a custom serializer.

requestOptions TransactionalBatchItemRequestOptions

(Optional) The options for the item request.

Returns

TransactionalBatch

The transactional batch instance with the operation added.

Type Parameters

T

The type of item to be created.