Method PutAsync
PutAsync(String, MapValue, PutOptions, CancellationToken)
Declaration
public Task<PutResult<RecordValue>> PutAsync(string tableName, MapValue row, PutOptions options = null, CancellationToken cancellationToken = null)
Parameters
Type | Name | Description |
---|---|---|
String | tableName | Name of the table. |
MapValue | row | Table row as MapValue representing names and values of the fields. Using RecordValue is not required as the field order doesn't matter for this operation. |
PutOptions | options | (Optional) Options for the Put operation.
If not specified or null , appropriate defaults will be
used. See PutOptions. |
CancellationToken | cancellationToken | (Optional) Cancellation token. |
Returns
Type | Description |
---|---|
Task<PutResult<RecordValue>> | Task returning PutResult<TRow>. |
Remarks
This method creates a new row or overwrites an existing row entirely. The value used for the put must contain a complete primary key and all required fields.
It is not possible to put part of a row. Any fields that are not provided will be defaulted, overwriting any existing value. Fields that are not nullable or defaulted must be provided or the operation will fail.
By default the Put operation is unconditional, but Put operations can also be conditional based on existence, or not, of a previous value as well as conditional on the RowVersion of the existing value. You may specify conditional Put via PutOptions as follows:
- Use IfAbsent to do a put only if there is no existing row that matches the primary key.
- Use IfPresent to do a put only if there is an existing row that matches the primary key.
- Use MatchVersion to do a put only if there is an existing row that matches the primary key and its RowVersion matches that provided.
It is also possible, on failure, to return information about the
existing row. The row and it's RowVersion can be
optionally returned as part of PutResult<TRow> if a
put operation fails because of a version mismatch or if the
operation fails because the row already exists. The existing row
information will only be returned if
ReturnExisting is true
and one of
the following occurs:
-
IfAbsent is
true
and the operation fails because the row already exists. - MatchVersion is set and the operation fails because the row exists and its RowVersion does not match the one provided.
Use of ReturnExisting may result in additional consumed read capacity and may affect the operation's latency. If the operation is successful there will be no information returned about the previous row.
Note that the failures of conditional Put operations discussed above will not result in an exception and the PutResult<TRow> will still be returned.
Examples
Executing Put operation on table with schema MyTable(id LONG, name STRING, PRIMARY KEY(id)).var result = await client.PutAsync(
"MyTable",
new MapValue
{
["id"] = 1000,
["name"] = "John"
});
// Will output true because unconditional Put operation is
// always successful unless an exception is thrown.
Console.WriteLine(result.Success);
Exceptions
Type | Condition |
---|---|
ArgumentException | If
tableName is null or invalid or
row is null or invalid or
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. |