Method PutAsync

PutAsync(String, MapValue, PutOptions, CancellationToken)

Puts a row into a table.
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.
Note that the options listed above are mutually exclusive in that specify one will unset the others. Instead of specifying these options you may also use additional APIs provided as shorthands for conditional Put operations such as PutIfAbsentAsync(String, MapValue, PutOptions, CancellationToken), PutIfPresentAsync(String, MapValue, PutOptions, CancellationToken) and PutIfVersionAsync(String, MapValue, RowVersion, PutOptions, CancellationToken).

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.
See Also
PutResult<TRow>