Class DynamoDbRequests

Namespace: DynaSharp.Requests

Assembly: DynaSharp.dll

The request API of DynamoDB: one method per DynamoDB operation, as an extension method on DynamoDbClient. Each takes the request record of the operation and returns its response record, so requests and responses mirror the service and items are dictionaries of AttributeValue. The methods are in scope with using DynaSharp.Requests;.

public static class DynamoDbRequests

Inheritance: object

DynamoDbRequests

Inherited Members: object.GetType()

object.MemberwiseClone()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Remarks

What follows applies to every method of this class. How the client is created and configured is described on DynamoDbClient and DynamoDbClientOptions.

Errors returned by DynamoDB surface as DynamoDbException or one of its derived types, for example ResourceNotFoundException or ConditionalCheckFailedException. The exception names the call: OperationName and, when the call addresses one table, TableName (the message stays the one DynamoDB sent, which often says neither). A request that exceeds AttemptTimeout throws TimeoutException; a request that the caller cancels throws OperationCanceledException. Network failures surface as HttpRequestException, and so does a response body above 64 MB (DynamoDB's largest response is the 16 MB of a BatchGetItem) with HttpRequestError ConfigurationLimitExceeded; that one is not retried.

Failed requests are retried automatically, as the AWS SDKs do in their "standard" retry mode: throttling errors, server errors, network failures and attempts that time out are sent again after a growing random wait. Errors that repeating the request cannot fix surface at once. MaxAttempts, which defaults to 4 attempts in all and can be set to 1 to turn retries off, has the full list and the rules. A client shares a budget of retries between all its requests, so it stops retrying while DynamoDB keeps failing. A retried error surfaces only after the last attempt, and it is the error of that attempt. If the clock of the machine is more than four minutes away from DynamoDB's and the request is rejected for that, the client learns the difference, signs with the corrected time from then on and sends the request again without waiting.

Because a request can be sent more than once, it can also take effect more than once. When an attempt reaches DynamoDB but its response is lost (a timeout, a dropped connection), the retry repeats a write that was already applied. That is harmless for a put or a delete of the same item. An update that depends on the value it finds, such as ADD on a counter or list_append, is applied twice, and a put with a condition such as attribute_not_exists can fail against its own earlier attempt. Guard such writes with a condition (for example on a version attribute), or set MaxAttempts to 1 for them. TransactWriteItemsAsync(DynamoDbClient, TransactWriteItemsRequest, CancellationToken) is the exception: all its attempts carry one idempotency token, so DynamoDB applies the transaction once.

Each operation emits one CLIENT activity from the ActivitySource named DynaSharp and records its duration in the db.client.operation.duration histogram of the Meter named DynaSharp, following the OpenTelemetry semantic conventions. A retried operation is still one activity and one measurement. The counters dynasharp.client.operation.retries and dynasharp.client.operation.throttles count the retries and the throttling errors, tagged with the operation, the table (left out when a batch or transaction spans several tables; the activity then lists them in aws.dynamodb.table_names), the server (server.address, and server.port unless it is the default one) and the error type; the counter dynasharp.client.consumed_capacity carries the same tags, without the error type, like the duration. When a retryable error is passed on because attempts or the retry budget ran out, and when the clock is corrected, the client logs a warning. None of this contains keys, items or attribute values. Subscribe with AddSource("DynaSharp") and AddMeter("DynaSharp").

Methods

BatchGetItemAsync(DynamoDbClient, BatchGetItemRequest, CancellationToken)

Reads items from one or more tables by primary key in a single call (DynamoDB BatchGetItem).

public static Task<BatchGetItemResponse> BatchGetItemAsync(this DynamoDbClient client, BatchGetItemRequest request, CancellationToken cancellationToken = default)

Parameters

client DynamoDbClient: The client.
request BatchGetItemRequest: The keys to read per table, and the read options per table.
cancellationToken CancellationToken: Cancels the request.

Returns

Task<BatchGetItemResponse>: The items that were found, grouped by table, and the keys that were not read. A successful response can be partial: check UnprocessedKeys and send what it holds again.

Remarks

A call can name at most 100 keys in all and returns at most 16 MB; an item can be at most 400 KB. DynamoDB stops early when the response would exceed 16 MB or 1 MB for a partition, when a table is throttled and when it fails internally for some keys, and returns the keys it did not read as UnprocessedKeys. This method does not split large requests and does not read the unprocessed keys: the caller sends them again, with a growing wait between the calls (the retries of the client cover failed requests, not a partial result). The map is in the form of RequestItems.

Items come in no particular order, a key without an item contributes nothing to the response, and the same key twice is rejected. Reads are eventually consistent unless ConsistentRead is set for the table. The call fails with ProvisionedThroughputExceededException only when none of the keys could be processed. It is safe to repeat.

Exceptions

ArgumentNullException: client or request is null.
ObjectDisposedException: The client is disposed.
ResourceNotFoundException: A table does not exist or is not ACTIVE.
ValidationException: DynamoDB rejects the request, for example because it names more than 100 keys or the same key twice, a key does not match the key schema of its table, or a placeholder is unused.
ProvisionedThroughputExceededException: None of the keys could be processed because the tables are throttled, and so was every retry.
AccessDeniedException: The credentials lack permission for dynamodb:BatchGetItem on a table.
DynamoDbException: DynamoDB returns any other error, or a response that is not a DynamoDB response. A throttling or server error (for example InternalServerErrorException) surfaces only when the last attempt failed with it too.
CredentialsUnavailableException: No credentials can be found.
HttpRequestException: The request could not be sent or the response could not be read, on every attempt.
TimeoutException: The last attempt did not complete within AttemptTimeout.
OperationCanceledException: cancellationToken was cancelled.

BatchWriteItemAsync(DynamoDbClient, BatchWriteItemRequest, CancellationToken)

Puts or deletes items in one or more tables in a single call (DynamoDB BatchWriteItem).

public static Task<BatchWriteItemResponse> BatchWriteItemAsync(this DynamoDbClient client, BatchWriteItemRequest request, CancellationToken cancellationToken = default)

Parameters

client DynamoDbClient: The client.
request BatchWriteItemRequest: The writes per table, and the metrics to return.
cancellationToken CancellationToken: Cancels the request.

Returns

Task<BatchWriteItemResponse>: The writes that were not processed. A successful response does not mean that every write was applied: check UnprocessedItems and send what it holds again.

Remarks

A call can contain at most 25 writes in all and transmit at most 16 MB; an item can be at most 400 KB (the JSON form of an item in the request can be larger than the stored item). DynamoDB rejects the whole request when it exceeds a limit, when a table does not exist, when a key does not match the key schema, or when two writes address the same item. This method does not split large requests and does not write the unprocessed items: the caller sends them again, with a growing wait between the calls (the retries of the client cover failed requests, not a partial result). The map is in the form of RequestItems.

Every put and delete is atomic, the batch as a whole is not, and the writes are applied in no particular order. A put replaces an existing item entirely, and a write cannot carry a condition or return the old item; use TransactWriteItemsAsync(DynamoDbClient, TransactWriteItemsRequest, CancellationToken), PutItemAsync(DynamoDbClient, PutItemRequest, CancellationToken), UpdateItemAsync(DynamoDbClient, UpdateItemRequest, CancellationToken) or DeleteItemAsync(DynamoDbClient, DeleteItemRequest, CancellationToken) for that. Repeating the call, as the client does after a timeout or a network error, writes the same items again, which is harmless.

Exceptions

ArgumentNullException: client or request is null.
ObjectDisposedException: The client is disposed.
ResourceNotFoundException: A table does not exist or is not ACTIVE.
ValidationException: DynamoDB rejects the request, for example because it contains more than 25 writes, an item exceeds 400 KB, a key does not match the key schema of its table, or two writes address the same item.
ItemCollectionSizeLimitExceededException: The item collection of a table with a local secondary index exceeds 10 GB.
ProvisionedThroughputExceededException: None of the writes could be processed because the tables are throttled, and so was every retry.
AccessDeniedException: The credentials lack permission for dynamodb:PutItem or dynamodb:DeleteItem on a table.
DynamoDbException: DynamoDB returns any other error, or a response that is not a DynamoDB response. A throttling or server error (for example InternalServerErrorException or ReplicatedWriteConflictException) surfaces only when the last attempt failed with it too.
CredentialsUnavailableException: No credentials can be found.
HttpRequestException: The request could not be sent or the response could not be read, on every attempt.
TimeoutException: The last attempt did not complete within AttemptTimeout.
OperationCanceledException: cancellationToken was cancelled.

CreateTableAsync(DynamoDbClient, CreateTableRequest, CancellationToken)

Creates a table (DynamoDB CreateTable).

public static Task<CreateTableResponse> CreateTableAsync(this DynamoDbClient client, CreateTableRequest request, CancellationToken cancellationToken = default)

Parameters

client DynamoDbClient: The client.
request CreateTableRequest: The table name, its key, its indexes and its settings.
cancellationToken CancellationToken: Cancels the request.

Returns

Task<CreateTableResponse>: The response. TableDescription shows the new table, normally in the state Creating.

Remarks

Table creation is asynchronous. The table accepts requests only when it is Active, which takes seconds to minutes (longer with global secondary indexes): poll DescribeTableAsync(DynamoDbClient, DescribeTableRequest, CancellationToken) with a delay of a second or more until then. Reading or writing earlier fails with ResourceNotFoundException or ResourceInUseException. Creating a table is not idempotent: a request that fails with a timeout or a network error may have created the table, and the client retries such requests, so the retry can fail with ResourceInUseException although this very call created the table. Check with DescribeTableAsync(DynamoDbClient, DescribeTableRequest, CancellationToken) before treating it as an error, or set MaxAttempts to 1.

An account can create only so many tables at the same time (50 in the state Creating, and a limit on all tables per region), and DynamoDB limits how fast tables are created and deleted; exceeding it throws LimitExceededException. The primary key, the local secondary indexes and the table name cannot be changed later.

Exceptions

ArgumentNullException: client or request is null.
ObjectDisposedException: The client is disposed.
ArgumentOutOfRangeException: The request has an undefined enum value, or Unknown, Unknown or Unknown where one is required (raised as the faulted task).
ResourceInUseException: A table with that name already exists or is being created.
LimitExceededException: The account has too many tables, or creates or deletes tables too fast.
ValidationException: DynamoDB rejects the request, for example because the table name is malformed, an attribute is defined but no key uses it, capacity is set together with on-demand billing, or an index name is used twice.
AccessDeniedException: The credentials lack permission for dynamodb:CreateTable.
DynamoDbException: DynamoDB returns any other error, or a response that is not a DynamoDB response. A throttling or server error (for example InternalServerErrorException) surfaces only when the last attempt failed with it too.
CredentialsUnavailableException: No credentials can be found.
HttpRequestException: The request could not be sent or the response could not be read, on every attempt.
TimeoutException: The last attempt did not complete within AttemptTimeout.
OperationCanceledException: cancellationToken was cancelled.

DeleteItemAsync(DynamoDbClient, DeleteItemRequest, CancellationToken)

Deletes a single item by its full primary key (DynamoDB DeleteItem).

public static Task<DeleteItemResponse> DeleteItemAsync(this DynamoDbClient client, DeleteItemRequest request, CancellationToken cancellationToken = default)

Parameters

client DynamoDbClient: The client.
request DeleteItemRequest: The table, the key and the write options.
cancellationToken CancellationToken: Cancels the request.

Returns

Task<DeleteItemResponse>: The response. Attributes holds the deleted item when the request asked for AllOld and an item existed.

Remarks

Deleting an item that does not exist is not an error. Without a ConditionExpression a delete is idempotent, so repeating it after a timeout is safe. With a condition, a repeated delete can fail against its own earlier effect: attribute_exists(pk) no longer holds once the item is gone, so the repeat throws ConditionalCheckFailedException although the item was deleted.

The write capacity consumed is based on the size of the deleted item. An item that takes part in an ongoing transaction is rejected with a TransactionConflictException.

Exceptions

ArgumentNullException: client or request is null.
ObjectDisposedException: The client is disposed.
ConditionalCheckFailedException: The condition expression did not hold, so this attempt deleted nothing. If an earlier attempt of the same call was retried, it may have deleted the item.
ResourceNotFoundException: The table does not exist or is not ACTIVE.
ValidationException: DynamoDB rejects the request, for example when the key does not match the key schema of the table or ReturnValues is neither none nor all old.
ProvisionedThroughputExceededException: The table is throttled, and so was every retry.
AccessDeniedException: The credentials lack permission for dynamodb:DeleteItem on the table.
DynamoDbException: DynamoDB returns any other error, or a response that is not a DynamoDB response. A throttling or server error (for example InternalServerErrorException) surfaces only when the last attempt failed with it too.
CredentialsUnavailableException: No credentials can be found.
HttpRequestException: The request could not be sent or the response could not be read, on every attempt.
TimeoutException: The last attempt did not complete within AttemptTimeout.
OperationCanceledException: cancellationToken was cancelled.

DeleteTableAsync(DynamoDbClient, DeleteTableRequest, CancellationToken)

Deletes a table and all its items (DynamoDB DeleteTable).

public static Task<DeleteTableResponse> DeleteTableAsync(this DynamoDbClient client, DeleteTableRequest request, CancellationToken cancellationToken = default)

Parameters

client DynamoDbClient: The client.
request DeleteTableRequest: The table.
cancellationToken CancellationToken: Cancels the request.

Returns

Task<DeleteTableResponse>: The response. TableDescription shows the table, normally in the state Deleting.

Remarks

Deletion is asynchronous and cannot be undone, except by restoring a backup. The table stays visible in the state Deleting for a while: poll DescribeTableAsync(DynamoDbClient, DescribeTableRequest, CancellationToken) until it fails with ResourceNotFoundException before creating a table of the same name again. A table with deletion protection (DeletionProtectionEnabled) cannot be deleted; turn the protection off first. Its streams stay readable for 24 hours.

Deleting is safe to repeat in the sense that the end state is the same, but a repeat after a lost response can fail with ResourceNotFoundException or ResourceInUseException because the table is already going away.

Exceptions

ArgumentNullException: client or request is null.
ObjectDisposedException: The client is disposed.
ResourceNotFoundException: The table does not exist.
ResourceInUseException: The table is being created or updated, or is already being deleted.
LimitExceededException: The account creates or deletes tables too fast.
ValidationException: DynamoDB rejects the request, for example because the table has deletion protection or the name is malformed.
AccessDeniedException: The credentials lack permission for dynamodb:DeleteTable on the table.
DynamoDbException: DynamoDB returns any other error, or a response that is not a DynamoDB response. A throttling or server error (for example InternalServerErrorException) surfaces only when the last attempt failed with it too.
CredentialsUnavailableException: No credentials can be found.
HttpRequestException: The request could not be sent or the response could not be read, on every attempt.
TimeoutException: The last attempt did not complete within AttemptTimeout.
OperationCanceledException: cancellationToken was cancelled.

DescribeTableAsync(DynamoDbClient, DescribeTableRequest, CancellationToken)

Reads the definition and state of a table (DynamoDB DescribeTable).

public static Task<DescribeTableResponse> DescribeTableAsync(this DynamoDbClient client, DescribeTableRequest request, CancellationToken cancellationToken = default)

Parameters

client DynamoDbClient: The client.
request DescribeTableRequest: The table.
cancellationToken CancellationToken: Cancels the request.

Returns

Task<DescribeTableResponse>: The description of the table.

Remarks

The result is eventually consistent: right after CreateTable the table may still be reported as missing. The item count and the size are approximations that DynamoDB refreshes about every six hours. Poll until TableStatus is Active before using a new table.

Exceptions

ArgumentNullException: client or request is null.
ObjectDisposedException: The client is disposed.
ResourceNotFoundException: The table does not exist.
ValidationException: DynamoDB rejects the request, for example because the table name is malformed.
AccessDeniedException: The credentials lack permission for dynamodb:DescribeTable on the table.
DynamoDbException: DynamoDB returns any other error, or a response that is not a DynamoDB response. A throttling or server error (for example InternalServerErrorException) surfaces only when the last attempt failed with it too.
CredentialsUnavailableException: No credentials can be found.
HttpRequestException: The request could not be sent or the response could not be read, on every attempt.
TimeoutException: The last attempt did not complete within AttemptTimeout.
OperationCanceledException: cancellationToken was cancelled.

DescribeTimeToLiveAsync(DynamoDbClient, DescribeTimeToLiveRequest, CancellationToken)

Reads the Time to Live setting of a table (DynamoDB DescribeTimeToLive).

public static Task<DescribeTimeToLiveResponse> DescribeTimeToLiveAsync(this DynamoDbClient client, DescribeTimeToLiveRequest request, CancellationToken cancellationToken = default)

Parameters

client DynamoDbClient: The client.
request DescribeTimeToLiveRequest: The table.
cancellationToken CancellationToken: Cancels the request.

Returns

Task<DescribeTimeToLiveResponse>: The state of Time to Live and the name of the expiry attribute.

Remarks

A table that never had Time to Live is reported as Disabled. A change made with UpdateTimeToLiveAsync(DynamoDbClient, UpdateTimeToLiveRequest, CancellationToken) shows up as Enabling or Disabling for up to an hour. The call is safe to repeat.

Exceptions

ArgumentNullException: client or request is null.
ObjectDisposedException: The client is disposed.
ResourceNotFoundException: The table does not exist.
ValidationException: DynamoDB rejects the request, for example because the table name is malformed.
AccessDeniedException: The credentials lack permission for dynamodb:DescribeTimeToLive on the table.
DynamoDbException: DynamoDB returns any other error, or a response that is not a DynamoDB response. A throttling or server error (for example InternalServerErrorException) surfaces only when the last attempt failed with it too.
CredentialsUnavailableException: No credentials can be found.
HttpRequestException: The request could not be sent or the response could not be read, on every attempt.
TimeoutException: The last attempt did not complete within AttemptTimeout.
OperationCanceledException: cancellationToken was cancelled.

GetItemAsync(DynamoDbClient, GetItemRequest, CancellationToken)

Reads a single item by its full primary key (DynamoDB GetItem).

public static Task<GetItemResponse> GetItemAsync(this DynamoDbClient client, GetItemRequest request, CancellationToken cancellationToken = default)

Parameters

client DynamoDbClient: The client.
request GetItemRequest: The table, the key and the read options.
cancellationToken CancellationToken: Cancels the request.

Returns

Task<GetItemResponse>: The response. Item is null when no item has the key: a missing item is not an error.

Remarks

Reads are eventually consistent unless ConsistentRead is set, which costs twice the read capacity and may be slower. An item can be at most 400 KB. The key must contain exactly the key attributes of the table.

Exceptions

ArgumentNullException: client or request is null.
ObjectDisposedException: The client is disposed.
ResourceNotFoundException: The table does not exist or is not ACTIVE.
ValidationException: DynamoDB rejects the request, for example when the key does not match the key schema of the table.
ProvisionedThroughputExceededException: The table is throttled, and so was every retry.
AccessDeniedException: The credentials lack permission for dynamodb:GetItem on the table.
DynamoDbException: DynamoDB returns any other error, or a response that is not a DynamoDB response. A throttling or server error (for example InternalServerErrorException) surfaces only when the last attempt failed with it too.
CredentialsUnavailableException: No credentials can be found.
HttpRequestException: The request could not be sent or the response could not be read, on every attempt.
TimeoutException: The last attempt did not complete within AttemptTimeout.
OperationCanceledException: cancellationToken was cancelled.

ListTablesAsync(DynamoDbClient, ListTablesRequest, CancellationToken)

Lists the names of the tables of the account in the region, sorted (DynamoDB ListTables).

public static Task<ListTablesResponse> ListTablesAsync(this DynamoDbClient client, ListTablesRequest request, CancellationToken cancellationToken = default)

Parameters

client DynamoDbClient: The client.
request ListTablesRequest: The optional paging settings.
cancellationToken CancellationToken: Cancels the request.

Returns

Task<ListTablesResponse>: One page of at most 100 names. Continue with LastEvaluatedTableName until it is null.

Remarks

The call lists names only; use DescribeTableAsync(DynamoDbClient, DescribeTableRequest, CancellationToken) for a table. The list is eventually consistent: a table that was just created may be missing and one that was just deleted may still appear. This method returns a single page; the call is safe to repeat.

Exceptions

ArgumentNullException: client or request is null.
ObjectDisposedException: The client is disposed.
ValidationException: DynamoDB rejects the request, for example because Limit is not between 1 and 100.
AccessDeniedException: The credentials lack permission for dynamodb:ListTables.
DynamoDbException: DynamoDB returns any other error, or a response that is not a DynamoDB response. A throttling or server error (for example InternalServerErrorException) surfaces only when the last attempt failed with it too.
CredentialsUnavailableException: No credentials can be found.
HttpRequestException: The request could not be sent or the response could not be read, on every attempt.
TimeoutException: The last attempt did not complete within AttemptTimeout.
OperationCanceledException: cancellationToken was cancelled.

PutItemAsync(DynamoDbClient, PutItemRequest, CancellationToken)

Creates an item or replaces an existing item with the same primary key entirely (DynamoDB PutItem).

public static Task<PutItemResponse> PutItemAsync(this DynamoDbClient client, PutItemRequest request, CancellationToken cancellationToken = default)

Parameters

client DynamoDbClient: The client.
request PutItemRequest: The table, the item and the write options.
cancellationToken CancellationToken: Cancels the request.

Returns

Task<PutItemResponse>: The response. Attributes holds the replaced item when the request asked for AllOld and an item existed.

Remarks

The write is unconditional unless ConditionExpression is set, so it silently overwrites an existing item. Use attribute_not_exists(pk) (with the name of the partition key) to create an item only if it does not exist. An item can be at most 400 KB and must contain all key attributes.

A request that fails with a timeout or a network error may or may not have been applied, and the client retries such requests (see MaxAttempts), so a put can reach DynamoDB more than once: an attempt whose response was lost may already have written the item. Writing the same item again is harmless, but a put with a condition expression, for example attribute_not_exists(pk) to create an item, can then fail with ConditionalCheckFailedException against its own earlier attempt although the item was created by this very call. When that matters, put a unique value such as a request id into the item and compare it on a failed condition, or set MaxAttempts to 1.

Exceptions

ArgumentNullException: client or request is null.
ObjectDisposedException: The client is disposed.
ConditionalCheckFailedException: The condition expression did not hold, so this attempt wrote nothing. If an earlier attempt of the same call was retried, it may have written the item.
ResourceNotFoundException: The table does not exist or is not ACTIVE.
ValidationException: DynamoDB rejects the request, for example when the item exceeds 400 KB or lacks a key attribute.
ItemCollectionSizeLimitExceededException: The item collection of a table with a local secondary index exceeds 10 GB.
ProvisionedThroughputExceededException: The table is throttled, and so was every retry.
AccessDeniedException: The credentials lack permission for dynamodb:PutItem on the table.
DynamoDbException: DynamoDB returns any other error, or a response that is not a DynamoDB response. A throttling or server error (for example InternalServerErrorException) surfaces only when the last attempt failed with it too.
CredentialsUnavailableException: No credentials can be found.
HttpRequestException: The request could not be sent or the response could not be read, on every attempt.
TimeoutException: The last attempt did not complete within AttemptTimeout.
OperationCanceledException: cancellationToken was cancelled.

QueryAsync(DynamoDbClient, QueryRequest, CancellationToken)

Reads the items of one partition, optionally narrowed by a sort key condition, from a table or an index (DynamoDB Query).

public static Task<QueryResponse> QueryAsync(this DynamoDbClient client, QueryRequest request, CancellationToken cancellationToken = default)

Parameters

client DynamoDbClient: The client.
request QueryRequest: The table or index, the key condition and the read options.
cancellationToken CancellationToken: Cancels the request.

Returns

Task<QueryResponse>: One page of the result. Without matching items Items is empty: that is not an error. Continue with LastEvaluatedKey until it is null.

Remarks

A call reads at most 1 MB of data (and at most Limit items) and then applies the filter, so a page can be empty and still have a LastEvaluatedKey. A response with a key does not mean that more items exist; only a response without one is the last page. This method returns a single page; call it again with the key as ExclusiveStartKey to read on.

The read capacity consumed depends on the size of the items read, not of those returned: a filter or a projection does not reduce it. A strongly consistent read costs twice an eventually consistent one. Global secondary indexes are eventually consistent only and can lag behind the table; they reject ConsistentRead.

A query is safe to repeat. Pages are not a snapshot: items written between two calls may or may not appear.

Exceptions

ArgumentNullException: client or request is null.
ObjectDisposedException: The client is disposed.
ResourceNotFoundException: The table or index does not exist or is not ACTIVE.
ValidationException: DynamoDB rejects the request, for example because the key condition is not an equality on the partition key, Limit is below 1, a consistent read is requested on a global secondary index, or Select conflicts with the projection expression.
ProvisionedThroughputExceededException: The table or index is throttled, and so was every retry.
AccessDeniedException: The credentials lack permission for dynamodb:Query on the table or index.
DynamoDbException: DynamoDB returns any other error, or a response that is not a DynamoDB response. A throttling or server error (for example InternalServerErrorException) surfaces only when the last attempt failed with it too.
CredentialsUnavailableException: No credentials can be found.
HttpRequestException: The request could not be sent or the response could not be read, on every attempt.
TimeoutException: The last attempt did not complete within AttemptTimeout.
OperationCanceledException: cancellationToken was cancelled.

ScanAsync(DynamoDbClient, ScanRequest, CancellationToken)

Reads every item of a table or index, optionally filtered (DynamoDB Scan).

public static Task<ScanResponse> ScanAsync(this DynamoDbClient client, ScanRequest request, CancellationToken cancellationToken = default)

Parameters

client DynamoDbClient: The client.
request ScanRequest: The table or index and the read options.
cancellationToken CancellationToken: Cancels the request.

Returns

Task<ScanResponse>: One page of the result. Continue with LastEvaluatedKey until it is null.

Remarks

A scan consumes read capacity for everything it reads, whatever the filter returns, and on a large table it takes a long time. To speed it up, set TotalSegments and read the segments with parallel sequences of calls; each segment continues with its own LastEvaluatedKey. Reads are eventually consistent unless ConsistentRead is set, and a scan is not a snapshot of the table.

A scan is safe to repeat.

Exceptions

ArgumentNullException: client or request is null.
ObjectDisposedException: The client is disposed.
ResourceNotFoundException: The table or index does not exist or is not ACTIVE.
ValidationException: DynamoDB rejects the request, for example because Limit is below 1, only one of Segment and TotalSegments is set, the segment is not below the total, or a consistent read is requested on a global secondary index.
ProvisionedThroughputExceededException: The table or index is throttled, and so was every retry.
AccessDeniedException: The credentials lack permission for dynamodb:Scan on the table or index.
DynamoDbException: DynamoDB returns any other error, or a response that is not a DynamoDB response. A throttling or server error (for example InternalServerErrorException) surfaces only when the last attempt failed with it too.
CredentialsUnavailableException: No credentials can be found.
HttpRequestException: The request could not be sent or the response could not be read, on every attempt.
TimeoutException: The last attempt did not complete within AttemptTimeout.
OperationCanceledException: cancellationToken was cancelled.

TransactGetItemsAsync(DynamoDbClient, TransactGetItemsRequest, CancellationToken)

Reads up to 100 items from one or more tables as one consistent snapshot (DynamoDB TransactGetItems).

public static Task<TransactGetItemsResponse> TransactGetItemsAsync(this DynamoDbClient client, TransactGetItemsRequest request, CancellationToken cancellationToken = default)

Parameters

client DynamoDbClient: The client.
request TransactGetItemsRequest: The items to read, in order.
cancellationToken CancellationToken: Cancels the request.

Returns

Task<TransactGetItemsResponse>: One result per requested item, in the order of the request. A result without Item means that no item has the key: that is not an error.

Remarks

The reads are serializable with respect to the writes of other transactions and strongly consistent. A call can contain at most 100 actions and read at most 4 MB in all; an item can be at most 400 KB. The tables must be in one AWS account and Region, and items are read from tables only. A transactional read costs twice the read capacity of the same read outside a transaction. The call is all or nothing, with no partial result and no unprocessed items; this method does not split large requests.

DynamoDB cancels the call with a TransactionCanceledException when an item is being changed by another transaction or write, or when a table is throttled. The exception lists a reason per action. The client does not repeat a cancelled transaction; whether that is worthwhile depends on the reason. A transactional read is safe to repeat.

Exceptions

ArgumentNullException: client or request is null.
ObjectDisposedException: The client is disposed.
TransactionCanceledException: DynamoDB cancelled the transaction, for example because it conflicts with a concurrent write; see CancellationReasons.
ResourceNotFoundException: A table does not exist or is not ACTIVE.
ValidationException: DynamoDB rejects the request, for example because it contains more than 100 actions, the items exceed 4 MB, or a key does not match the key schema of its table.
ProvisionedThroughputExceededException: A table is throttled, and so was every retry.
AccessDeniedException: The credentials lack permission for dynamodb:GetItem on a table.
DynamoDbException: DynamoDB returns any other error, or a response that is not a DynamoDB response. A throttling or server error (for example InternalServerErrorException) surfaces only when the last attempt failed with it too.
CredentialsUnavailableException: No credentials can be found.
HttpRequestException: The request could not be sent or the response could not be read, on every attempt.
TimeoutException: The last attempt did not complete within AttemptTimeout.
OperationCanceledException: cancellationToken was cancelled.

TransactWriteItemsAsync(DynamoDbClient, TransactWriteItemsRequest, CancellationToken)

Applies up to 100 puts, updates, deletes and condition checks to one or more tables, all or nothing (DynamoDB TransactWriteItems).

public static Task<TransactWriteItemsResponse> TransactWriteItemsAsync(this DynamoDbClient client, TransactWriteItemsRequest request, CancellationToken cancellationToken = default)

Parameters

client DynamoDbClient: The client.
request TransactWriteItemsRequest: The actions, in order, and the idempotency token.
cancellationToken CancellationToken: Cancels the request.

Returns

Task<TransactWriteItemsResponse>: The optional metrics. A response means that every action took effect.

Remarks

A call can contain at most 100 actions and write at most 4 MB in all; an item can be at most 400 KB. The tables must be in one AWS account and Region, and no two actions can target the same item. A transactional write costs twice the write capacity of the same write outside a transaction. This method does not split large requests.

If any action fails, the call throws TransactionCanceledException and nothing was written; its CancellationReasons list one reason per action in the order of the request. The client does not repeat a cancelled transaction: the reasons ConditionalCheckFailed and ValidationError will not pass, whereas TransactionConflict and the throttling reasons may.

Idempotency. The call carries ClientRequestToken, a GUID the library generates when the request sets none. All attempts of one call, including the retries after a timeout or a network error, send the same token, so a transaction whose response was lost is not applied twice: DynamoDB recognizes the token for 10 minutes after the first request that used it was completed and answers with the outcome of the first one. A request that arrives while the first is still running is rejected with TransactionInProgressException, which the client retries; the same token with other parameters fails with IdempotentParameterMismatchException. To repeat a call yourself after an exception, within 10 minutes and with unchanged parameters, supply the token in the request, because the generated one is not returned.

Exceptions

ArgumentNullException: client or request is null.
ObjectDisposedException: The client is disposed.
TransactionCanceledException: DynamoDB cancelled the transaction, for example because a condition did not hold or an item takes part in another transaction; see CancellationReasons.
IdempotentParameterMismatchException: The token was used within the last 10 minutes for a request with other parameters.
TransactionInProgressException: A transaction with the same token is still running, and so it was on every retry.
ResourceNotFoundException: A table does not exist or is not ACTIVE.
ValidationException: DynamoDB rejects the request, for example because it contains more than 100 actions, two actions target the same item, an action has none or several members, or the token is longer than 36 characters.
ProvisionedThroughputExceededException: A table is throttled, and so was every retry.
AccessDeniedException: The credentials lack permission for the write actions of the transaction on a table.
DynamoDbException: DynamoDB returns any other error, or a response that is not a DynamoDB response. A throttling or server error (for example InternalServerErrorException or ReplicatedWriteConflictException) surfaces only when the last attempt failed with it too.
CredentialsUnavailableException: No credentials can be found.
HttpRequestException: The request could not be sent or the response could not be read, on every attempt.
TimeoutException: The last attempt did not complete within AttemptTimeout.
OperationCanceledException: cancellationToken was cancelled.

UpdateItemAsync(DynamoDbClient, UpdateItemRequest, CancellationToken)

Changes the attributes of an existing item, or creates the item if no item has the key (DynamoDB UpdateItem).

public static Task<UpdateItemResponse> UpdateItemAsync(this DynamoDbClient client, UpdateItemRequest request, CancellationToken cancellationToken = default)

Parameters

client DynamoDbClient: The client.
request UpdateItemRequest: The table, the key, the update and the write options.
cancellationToken CancellationToken: Cancels the request.

Returns

Task<UpdateItemResponse>: The response. Attributes holds the attributes that ReturnValues selected, if the request asked for any.

Remarks

The update is atomic and is applied only to the attributes the update expression names. It is an upsert: when no item has the key, the item is created, unless a ConditionExpression such as attribute_exists(pk) forbids it. The item can be at most 400 KB after the update. The write capacity consumed is that of the larger of the item before and after the update.

An update is not idempotent in general. A request that fails with a timeout or a network error may or may not have been applied, and a request that the client sends again after such a failure can be applied twice: an ADD or a SET n = n + :x then counts twice. Make updates safe to repeat by setting absolute values, or guard them with a condition on a version attribute.

An item that takes part in an ongoing transaction is rejected with a TransactionConflictException.

Exceptions

ArgumentNullException: client or request is null.
ObjectDisposedException: The client is disposed.
ConditionalCheckFailedException: The condition expression did not hold, so this attempt changed nothing. If an earlier attempt of the same call was retried, it may have changed the item.
ResourceNotFoundException: The table does not exist or is not ACTIVE.
ValidationException: DynamoDB rejects the request, for example because the update expression is malformed, an expression placeholder is unused or undefined, the key does not match the key schema, or the item would exceed 400 KB.
ItemCollectionSizeLimitExceededException: The item collection of a table with a local secondary index exceeds 10 GB.
ProvisionedThroughputExceededException: The table is throttled, and so was every retry.
AccessDeniedException: The credentials lack permission for dynamodb:UpdateItem on the table.
DynamoDbException: DynamoDB returns any other error, or a response that is not a DynamoDB response. A throttling or server error (for example InternalServerErrorException) surfaces only when the last attempt failed with it too.
CredentialsUnavailableException: No credentials can be found.
HttpRequestException: The request could not be sent or the response could not be read, on every attempt.
TimeoutException: The last attempt did not complete within AttemptTimeout.
OperationCanceledException: cancellationToken was cancelled.

UpdateTableAsync(DynamoDbClient, UpdateTableRequest, CancellationToken)

Changes the billing mode, capacity, stream, global secondary indexes, storage class or deletion protection of a table (DynamoDB UpdateTable).

public static Task<UpdateTableResponse> UpdateTableAsync(this DynamoDbClient client, UpdateTableRequest request, CancellationToken cancellationToken = default)

Parameters

client DynamoDbClient: The client.
request UpdateTableRequest: The table and the changes.
cancellationToken CancellationToken: Cancels the request.

Returns

Task<UpdateTableResponse>: The response. TableDescription shows the table, normally in the state Updating.

Remarks

Updating a table is asynchronous. While the table is Updating (and while a new index is Creating) DynamoDB rejects further structural changes with ResourceInUseException: poll DescribeTableAsync(DynamoDbClient, DescribeTableRequest, CancellationToken) with a delay of a second or more until the table is Active again. Reads and writes keep working meanwhile. A new global secondary index is provisioned and then filled from the table, which takes minutes on an empty table and hours on a large one, and the table cannot be deleted until it is done; it can be queried when its IndexStatus is Active.

A repeated request is not harmless: after a timeout or a network error the client retries, and a retry of a change that already took effect fails with ResourceInUseException or ValidationException (for example creating an index that exists, or setting the billing mode the table has). Check with DescribeTableAsync(DynamoDbClient, DescribeTableRequest, CancellationToken) before treating it as an error, or set MaxAttempts to 1. Which changes DynamoDB allows together, and how often, is described on UpdateTableRequest.

Exceptions

ArgumentNullException: client or request is null.
ObjectDisposedException: The client is disposed.
ArgumentOutOfRangeException: The request has an undefined enum value, or Unknown, Unknown or Unknown where one is required (raised as the faulted task).
ResourceNotFoundException: The table does not exist.
ResourceInUseException: The table or an index is being created, updated or deleted.
LimitExceededException: The account has too many tables or indexes, or changes tables too fast.
ValidationException: DynamoDB rejects the request, for example because it changes nothing, sets the billing mode the table already has, lowers capacity too often, combines changes that are not allowed together or has an index with an attribute that is not defined.
AccessDeniedException: The credentials lack permission for dynamodb:UpdateTable on the table.
DynamoDbException: DynamoDB returns any other error, or a response that is not a DynamoDB response. A throttling or server error (for example InternalServerErrorException) surfaces only when the last attempt failed with it too.
CredentialsUnavailableException: No credentials can be found.
HttpRequestException: The request could not be sent or the response could not be read, on every attempt.
TimeoutException: The last attempt did not complete within AttemptTimeout.
OperationCanceledException: cancellationToken was cancelled.

UpdateTimeToLiveAsync(DynamoDbClient, UpdateTimeToLiveRequest, CancellationToken)

Turns Time to Live on a table on or off (DynamoDB UpdateTimeToLive).

public static Task<UpdateTimeToLiveResponse> UpdateTimeToLiveAsync(this DynamoDbClient client, UpdateTimeToLiveRequest request, CancellationToken cancellationToken = default)

Parameters

client DynamoDbClient: The client.
request UpdateTimeToLiveRequest: The table and the new setting.
cancellationToken CancellationToken: Cancels the request.

Returns

Task<UpdateTimeToLiveResponse>: The response, which repeats the setting DynamoDB accepted.

Remarks

With Time to Live on, DynamoDB deletes items whose expiry attribute (a number holding epoch seconds) is in the past. The deletion is a background process: it lags the expiry, typically by up to a few days, so expired items are still returned by reads, queries and scans until DynamoDB gets to them. Filter on the attribute where that matters. Deleted items appear in the stream of the table as removals made by the DynamoDB service.

The change itself takes up to an hour to take effect, and DynamoDB rejects further changes to the same table during that hour with a ValidationException. Setting the value that is already in effect is rejected as well, which makes a retry after a lost response fail although the first attempt worked.

Exceptions

ArgumentNullException: client or request is null.
ObjectDisposedException: The client is disposed.
ResourceNotFoundException: The table does not exist.
ResourceInUseException: The table is being created, updated or deleted.
LimitExceededException: Too many table operations are running in the account.
ValidationException: DynamoDB rejects the request, for example because the setting is already in effect or was changed less than an hour ago.
AccessDeniedException: The credentials lack permission for dynamodb:UpdateTimeToLive on the table.
DynamoDbException: DynamoDB returns any other error, or a response that is not a DynamoDB response. A throttling or server error (for example InternalServerErrorException) surfaces only when the last attempt failed with it too.
CredentialsUnavailableException: No credentials can be found.
HttpRequestException: The request could not be sent or the response could not be read, on every attempt.
TimeoutException: The last attempt did not complete within AttemptTimeout.
OperationCanceledException: cancellationToken was cancelled.

Table of Contents

Class DynamoDbRequests

Remarks

Methods

BatchGetItemAsync(DynamoDbClient, BatchGetItemRequest, CancellationToken)

Parameters

Returns

Remarks

Exceptions

BatchWriteItemAsync(DynamoDbClient, BatchWriteItemRequest, CancellationToken)

Parameters

Returns

Remarks

Exceptions

CreateTableAsync(DynamoDbClient, CreateTableRequest, CancellationToken)

Parameters

Returns

Remarks

Exceptions

DeleteItemAsync(DynamoDbClient, DeleteItemRequest, CancellationToken)

Parameters

Returns

Remarks

Exceptions

DeleteTableAsync(DynamoDbClient, DeleteTableRequest, CancellationToken)

Parameters

Returns

Remarks

Exceptions

DescribeTableAsync(DynamoDbClient, DescribeTableRequest, CancellationToken)

Parameters

Returns

Remarks

Exceptions

DescribeTimeToLiveAsync(DynamoDbClient, DescribeTimeToLiveRequest, CancellationToken)

Parameters

Returns

Remarks

Exceptions

GetItemAsync(DynamoDbClient, GetItemRequest, CancellationToken)

Parameters

Returns

Remarks

Exceptions

ListTablesAsync(DynamoDbClient, ListTablesRequest, CancellationToken)

Parameters

Returns

Remarks

Exceptions

PutItemAsync(DynamoDbClient, PutItemRequest, CancellationToken)

Parameters

Returns

Remarks

Exceptions

QueryAsync(DynamoDbClient, QueryRequest, CancellationToken)

Parameters

Returns

Remarks

Exceptions

ScanAsync(DynamoDbClient, ScanRequest, CancellationToken)

Parameters

Returns

Remarks

Exceptions

TransactGetItemsAsync(DynamoDbClient, TransactGetItemsRequest, CancellationToken)

Parameters

Returns

Remarks

Exceptions

TransactWriteItemsAsync(DynamoDbClient, TransactWriteItemsRequest, CancellationToken)

Parameters

Returns

Remarks

Exceptions

UpdateItemAsync(DynamoDbClient, UpdateItemRequest, CancellationToken)

Parameters

Returns

Remarks

Exceptions

UpdateTableAsync(DynamoDbClient, UpdateTableRequest, CancellationToken)