Method WriteManyAsync
WriteManyAsync(WriteOperationCollection, WriteManyOptions, CancellationToken)
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)
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. |