Method WriteManyAsync

WriteManyAsync(WriteOperationCollection, WriteManyOptions, CancellationToken)

Atomically executes a sequence of Put and Delete operations on one or more tables that share the same shard key.
Declaration
public Task<WriteManyResult<RecordValue>> WriteManyAsync(WriteOperationCollection operations, WriteManyOptions options = null, CancellationToken cancellationToken = null)
Parameters
Type Name Description
WriteOperationCollection operations Collection of Put and Delete operations to execute in a single transaction.
WriteManyOptions options (Optional) Options for the WriteMany operation. If not specified or null, appropriate defaults will be used. See WriteManyOptions.
CancellationToken cancellationToken (Optional) Cancellation token.
Returns
Type Description
Task<WriteManyResult<RecordValue>> Task returning WriteManyResult<TRow>.
Remarks

This method executes a sequence of put and delete operations associated with one or more tables that share the same shard key portion of their primary keys. All the specified operations are executed within the scope of a single transaction, thus making the operation atomic. It is an efficient way to atomically modify multiple related rows.

You can issue operations for multiple tables as long as these tables have the same shard key. This means that these tables must be part of the same parent/child table hierarchy that has a single ancestor table specifying the shard key. Thus you may include operations for this ancestor table and/or any of its descendants (for example, parent and child tables, sibling tables, etc.). All operations must be on rows that share the same shard key value.

There are some size-based limitations on this operation:

  • The max number of individual operations (Put, Delete) in a single call to this API is 50.
  • The total request size is limited to 25 MB.

The sequence of Put and Delete operations to execute is specified as WriteOperationCollection. Each operation must be on a distinct row in the table (you may not have multiple operations on the same table that share the same primary key). When you add an operation to the collection, you may also specify its PutOptions or DeleteOptions. You may share the same options object between different operations in the collection. You may not specify Compartment, Timeout or Durability properties in the options added to the collection, these can only be specified as part of WriteManyOptions.

Using this method requires specifying table name for each operation. Thus, to add operations to WriteOperationCollection you must use methods of WriteOperationCollection that take table name as a parameter. See WriteOperationCollection for details.

AbortIfUnsuccessful parameter specifies whether the whole transaction should be aborted if a particular operation fails. You may specify this parameter for any operation added to the WriteOperationCollection. In addition, if AbortIfUnsuccessful is set to true, this will enable this option for all operations in the collection. Note that the success or failure of an operation is defined here in the same way as indicated by Success and Success, that is the failure would occur if conditional Put operation fails or conditional Delete operation fails or Delete operation fails because the given row does not exist (other failures will cause an exception to be thrown and may also abort the transaction regardless of AbortIfUnsuccessful setting).

On successful completion of this API, Results will contain a list of the execution results of all operations. If the transaction was aborted because of failure of an operation which has AbortIfUnsuccessful set to true (or if AbortIfUnsuccessful is set to true) then the index and execution result of the failed operation will be available as FailedOperationIndex and FailedOperationResult respectively.

If all operations are for single table, you may also use WriteManyAsync(String, WriteOperationCollection, WriteManyOptions, CancellationToken) method. If, in addition, the operations are all Put or all Delete and it is sufficient to specify the same options for all operations (instead of on per-operation basis), you may also opt to use simpler APIs PutManyAsync(String, IReadOnlyCollection<MapValue>, PutManyOptions, CancellationToken) and DeleteManyAsync(String, IReadOnlyCollection<MapValue>, DeleteManyOptions, CancellationToken).

Examples
Performing WriteMany operation with parent table "emp" and child table "emp.expenses". 
var row = new MapValue
{
    ["id"] = 1000,
    ["name"] = "Jane"
};

var childRow = new MapValue
{
    ["id"] = 1001,
    ["name"] = "Jane",
    ["expenseId"] = 100001,
    ["expenseTitle"] = "Books"
};
var primaryKey = new MapValue
{
    ["id"] = 2000
};

var result = await client.WriteManyAsync(
    new WriteOperationCollection()
        .AddPut("emp", row)
        .AddPutIfAbsent("emp.expenses", childRow, true)
        .AddDelete("emp", primaryKey, true));
Exceptions
Type Condition
ArgumentException If operations is null or empty or options contains invalid values.
TimeoutException Operation has timed out.
InvalidOperationException The table or the service is not in a valid state to perform this operation.
NoSQLException NoSQLException or one of its subclasses is thrown if operation cannot be performed for any other reason. See documentation for corresponding subclass of NoSQLException.
See Also

WriteManyAsync(String, WriteOperationCollection, WriteManyOptions, CancellationToken)

Atomically executes a sequence of Put and Delete operations on a table.
Declaration
public Task<WriteManyResult<RecordValue>> WriteManyAsync(string tableName, WriteOperationCollection operations, WriteManyOptions options = null, CancellationToken cancellationToken = null)
Parameters
Type Name Description
String tableName The name of the table.
WriteOperationCollection operations Collection of Put and Delete operations to execute in a single transaction.
WriteManyOptions options (Optional) Options for the WriteMany operation. If not specified or null, appropriate defaults will be used. See WriteManyOptions.
CancellationToken cancellationToken (Optional) Cancellation token.
Returns
Type Description
Task<WriteManyResult<RecordValue>> Task returning WriteManyResult<TRow>.
Remarks

This method is similar to WriteManyAsync(WriteOperationCollection, WriteManyOptions, CancellationToken), and is used to execute sequence of Put and Delete operations on a single table. All other considerations and limitations of WriteManyAsync(WriteOperationCollection, WriteManyOptions, CancellationToken) apply to this method.

This method takes tableName parameter. To use this method, when adding operations to WriteOperationCollection, use methods that do not take table name as a parameter (or pass null as table name). See WriteOperationCollection for details.

Examples
Performing WriteMany operation on a single table. 
var row1 = new MapValue
{
    ["id"] = 1000,
    ["name"] = "John"
};

var row2 = new MapValue
{
    ["id"] = 1001,
    ["name"] = "Jane"
};

var primaryKey = new MapValue
{
    ["id"] = 2000
};

var result = await client.WriteManyAsync(
    "myTable",
    new WriteOperationCollection()
        .AddPut(row1)
        .AddPutIfAbsent(row2, true)
        .AddDelete(primaryKey, true));
Exceptions
Type Condition
ArgumentException If tableName is null or invalid or operations is null or empty or options contains invalid values.
TimeoutException Operation has timed out.
InvalidOperationException The table or the service is not in a valid state to perform this operation.
NoSQLException NoSQLException or one of its subclasses is thrown if operation cannot be performed for any other reason. See documentation for corresponding subclass of NoSQLException.
See Also