Skip to content
Orleans logoMicrosoft Orleans

DynamoDBStorage Methods

Wrapper around AWS DynamoDB SDK.

ConvertUpdate(Dictionary<string, AttributeValue>, Dictionary<string, AttributeValue>, string, Dictionary<string, AttributeValue>)

View source
public (string updateExpression, Dictionary<string, AttributeValue> expressionAttributeValues) DynamoDBStorage.ConvertUpdate(Dictionary<string, AttributeValue> fields, Dictionary<string, AttributeValue>? conditionValues = null, string extraExpression = "", Dictionary<string, AttributeValue>? extraExpressionValues = null)
Creates a DynamoDB update expression and its expression attribute values.

Parameters

fieldsDictionary<string, AttributeValue>
The attributes to assign in the update expression.
conditionValuesDictionary<string, AttributeValue>
The values referenced by the condition expression.
extraExpressionstring
An additional update expression appended after the attribute assignments.
extraExpressionValuesDictionary<string, AttributeValue>
The values referenced by extraExpression.

Returns

The update expression and all expression attribute values used by the update and condition expressions.

DeleteEntriesAsync(string, IReadOnlyCollection<Dictionary<string, AttributeValue>>, CancellationToken)

View source
public Task DeleteEntriesAsync(string tableName, IReadOnlyCollection<Dictionary<string, AttributeValue>> toDelete, CancellationToken cancellationToken)
Deletes a batch of entries using the supplied cancellation token.

Parameters

tableNamestring
The table name.
toDeleteIReadOnlyCollection<Dictionary<string, AttributeValue>>
The keys of the entries to delete.
cancellationTokenCancellationToken
The cancellation token.

DeleteEntryAsync(string, Dictionary<string, AttributeValue>, string, Dictionary<string, AttributeValue>)

View source
public Task DeleteEntryAsync(string tableName, Dictionary<string, AttributeValue> keys, string conditionExpression = "", Dictionary<string, AttributeValue>? conditionValues = null)
Delete an entry from a DynamoDB table

Parameters

tableNamestring
The name of the table to delete an entry
keysDictionary<string, AttributeValue>
The table entry keys for the entry to be deleted
conditionExpressionstring
Optional conditional expression
conditionValuesDictionary<string, AttributeValue>
Optional field/attribute values used in the conditional expression

GetEntriesTxAsync(string, IEnumerable<Dictionary<string, AttributeValue>>, Func<Dictionary<string, AttributeValue>, TResult>)

View source
public Task<IEnumerable<TResult>> GetEntriesTxAsync<TResult>(string tableName, IEnumerable<Dictionary<string, AttributeValue>> keys, Func<Dictionary<string, AttributeValue>, TResult> resolver)
Transactionally reads entries from a DynamoDB table

Parameters

tableNamestring
The name of the table to search for the entry
keysIEnumerable<Dictionary<string, AttributeValue>>
The table entry keys to search for
resolverFunc<Dictionary<string, AttributeValue>, TResult>
Function that will be called to translate the returned fields into a concrete type. This Function is only called if the result is != null

Returns

The object translated by the resolver function

GetEntriesTxAsync(string, IEnumerable<Dictionary<string, AttributeValue>>, Func<Dictionary<string, AttributeValue>, TResult>, CancellationToken)

View source
public Task<IEnumerable<TResult>> GetEntriesTxAsync<TResult>(string tableName, IEnumerable<Dictionary<string, AttributeValue>> keys, Func<Dictionary<string, AttributeValue>, TResult> resolver, CancellationToken cancellationToken)
Transactionally reads entries using the supplied cancellation token.

Parameters

tableNamestring
The table name.
keysIEnumerable<Dictionary<string, AttributeValue>>
The keys of the entries to read.
resolverFunc<Dictionary<string, AttributeValue>, TResult>
Converts each entry to the result type.
cancellationTokenCancellationToken
The cancellation token.

InitializeTable(string, List<KeySchemaElement>, List<AttributeDefinition>, List<GlobalSecondaryIndex>, string?, CancellationToken)

View source
public Task InitializeTable(string tableName, List<KeySchemaElement> keys, List<AttributeDefinition> attributes, List<GlobalSecondaryIndex>? secondaryIndexes = null, string? ttlAttributeName = null, CancellationToken cancellationToken = default(CancellationToken))
Create a DynamoDB table if it doesn't exist

Parameters

tableNamestring
The name of the table
keysList<KeySchemaElement>
The keys definitions
attributesList<AttributeDefinition>
The attributes used on the key definition
secondaryIndexesList<GlobalSecondaryIndex>
(optional) The secondary index definitions
ttlAttributeNamestring?
(optional) The name of the item attribute that indicates the item TTL (if null, ttl won't be enabled)
cancellationTokenCancellationToken
The cancellation token.

PutEntriesAsync(string, IReadOnlyCollection<Dictionary<string, AttributeValue>>)

View source
public Task PutEntriesAsync(string tableName, IReadOnlyCollection<Dictionary<string, AttributeValue>> toCreate)
Crete or replace multiple entries in a DynamoDB table (Batch put)

Parameters

tableNamestring
The name of the table to search for the entry
toCreateIReadOnlyCollection<Dictionary<string, AttributeValue>>
List of key values for each entry that must be created or replaced in the batch

PutEntryAsync(string, Dictionary<string, AttributeValue>, CancellationToken, string, Dictionary<string, AttributeValue>)

View source
public Task PutEntryAsync(string tableName, Dictionary<string, AttributeValue> fields, CancellationToken cancellationToken, string conditionExpression = "", Dictionary<string, AttributeValue>? conditionValues = null)
Creates or replaces an entry using the supplied cancellation token.

Parameters

tableNamestring
The table name.
fieldsDictionary<string, AttributeValue>
The fields to write.
cancellationTokenCancellationToken
The cancellation token.
conditionExpressionstring
The optional conditional expression.
conditionValuesDictionary<string, AttributeValue>
The conditional expression values.

PutEntryAsync(string, Dictionary<string, AttributeValue>, string, Dictionary<string, AttributeValue>)

View source
public Task PutEntryAsync(string tableName, Dictionary<string, AttributeValue> fields, string conditionExpression = "", Dictionary<string, AttributeValue>? conditionValues = null)
Create or Replace an entry in a DynamoDB Table

Parameters

tableNamestring
The name of the table to put an entry
fieldsDictionary<string, AttributeValue>
The fields/attributes to add or replace in the table
conditionExpressionstring
Optional conditional expression
conditionValuesDictionary<string, AttributeValue>
Optional field/attribute values used in the conditional expression

QueryAllAsync(string, Dictionary<string, AttributeValue>, string, Func<Dictionary<string, AttributeValue>, TResult>, CancellationToken, string, bool, bool)

View source
public Task<List<TResult>> QueryAllAsync<TResult>(string tableName, Dictionary<string, AttributeValue> keys, string keyConditionExpression, Func<Dictionary<string, AttributeValue>, TResult> resolver, CancellationToken cancellationToken, string indexName = "", bool scanIndexForward = true, bool consistentRead = true)
Queries all matching entries using the supplied cancellation token.

Parameters

tableNamestring
The table name.
keysDictionary<string, AttributeValue>
The key condition values.
keyConditionExpressionstring
The expression filtering the keys.
resolverFunc<Dictionary<string, AttributeValue>, TResult>
Converts each entry to the result type.
cancellationTokenCancellationToken
The cancellation token.
indexNamestring
The optional secondary index name.
scanIndexForwardbool
Whether the index is read in ascending order.
consistentReadbool
Whether reads must be strongly consistent.

QueryAllAsync(string, Dictionary<string, AttributeValue>, string, Func<Dictionary<string, AttributeValue>, TResult>, string, bool, bool)

View source
public Task<List<TResult>> QueryAllAsync<TResult>(string tableName, Dictionary<string, AttributeValue> keys, string keyConditionExpression, Func<Dictionary<string, AttributeValue>, TResult> resolver, string indexName = "", bool scanIndexForward = true, bool consistentRead = true)
Query for multiple entries in a DynamoDB table by filtering its keys

Parameters

tableNamestring
The name of the table to search for the entries
keysDictionary<string, AttributeValue>
The table entry keys to search for
keyConditionExpressionstring
the expression that will filter the keys
resolverFunc<Dictionary<string, AttributeValue>, TResult>
Function that will be called to translate the returned fields into a concrete type. This Function is only called if the result is != null and will be called for each entry that match the query and added to the results list
indexNamestring
In case a secondary index is used in the keyConditionExpression
scanIndexForwardbool
In case an index is used, show if the seek order is ascending (true) or descending (false)
consistentReadbool
Determines the read consistency model. Note that if a GSI is used, this must be false.

Returns

The collection containing a list of objects translated by the resolver function

QueryAsync(string, Dictionary<string, AttributeValue>, string, Func<Dictionary<string, AttributeValue>, TResult>, CancellationToken, string, bool, Dictionary<string, AttributeValue>, bool)

View source
public Task<(List<TResult> results, Dictionary<string, AttributeValue>? lastEvaluatedKey)> DynamoDBStorage.QueryAsync<TResult>(string tableName, Dictionary<string, AttributeValue> keys, string keyConditionExpression, Func<Dictionary<string, AttributeValue>, TResult> resolver, CancellationToken cancellationToken, string indexName = "", bool scanIndexForward = true, Dictionary<string, AttributeValue>? lastEvaluatedKey = null, bool consistentRead = true)
Queries a page of entries using the supplied cancellation token.

Parameters

tableNamestring
The table name.
keysDictionary<string, AttributeValue>
The key condition values.
keyConditionExpressionstring
The expression filtering the keys.
resolverFunc<Dictionary<string, AttributeValue>, TResult>
Converts each entry to the result type.
cancellationTokenCancellationToken
The cancellation token.
indexNamestring
The optional secondary index name.
scanIndexForwardbool
Whether the index is read in ascending order.
lastEvaluatedKeyDictionary<string, AttributeValue>
The previous page's continuation key.
consistentReadbool
Whether reads must be strongly consistent.

QueryAsync(string, Dictionary<string, AttributeValue>, string, Func<Dictionary<string, AttributeValue>, TResult>, string, bool, Dictionary<string, AttributeValue>, bool)

View source
public Task<(List<TResult> results, Dictionary<string, AttributeValue>? lastEvaluatedKey)> DynamoDBStorage.QueryAsync<TResult>(string tableName, Dictionary<string, AttributeValue> keys, string keyConditionExpression, Func<Dictionary<string, AttributeValue>, TResult> resolver, string indexName = "", bool scanIndexForward = true, Dictionary<string, AttributeValue>? lastEvaluatedKey = null, bool consistentRead = true)
Query for multiple entries in a DynamoDB table by filtering its keys

Parameters

tableNamestring
The name of the table to search for the entries
keysDictionary<string, AttributeValue>
The table entry keys to search for
keyConditionExpressionstring
the expression that will filter the keys
resolverFunc<Dictionary<string, AttributeValue>, TResult>
Function that will be called to translate the returned fields into a concrete type. This Function is only called if the result is != null and will be called for each entry that match the query and added to the results list
indexNamestring
In case a secondary index is used in the keyConditionExpression
scanIndexForwardbool
In case an index is used, show if the seek order is ascending (true) or descending (false)
lastEvaluatedKeyDictionary<string, AttributeValue>
The primary key of the first item that this operation will evaluate. Use the value that was returned for LastEvaluatedKey in the previous operation
consistentReadbool
Determines the read consistency model. Note that if a GSI is used, this must be false.

Returns

The collection containing a list of objects translated by the resolver function and the LastEvaluatedKey for paged results

ReadSingleEntryAsync(string, Dictionary<string, AttributeValue>, Func<Dictionary<string, AttributeValue>, TResult>)

View source
public Task<TResult?> ReadSingleEntryAsync<TResult>(string tableName, Dictionary<string, AttributeValue> keys, Func<Dictionary<string, AttributeValue>, TResult> resolver)
Read an entry from a DynamoDB table

Parameters

tableNamestring
The name of the table to search for the entry
keysDictionary<string, AttributeValue>
The table entry keys to search for
resolverFunc<Dictionary<string, AttributeValue>, TResult>
Function that will be called to translate the returned fields into a concrete type. This Function is only called if the result is != null

Returns

The object translated by the resolver function

ReadSingleEntryAsync(string, Dictionary<string, AttributeValue>, Func<Dictionary<string, AttributeValue>, TResult>, CancellationToken)

View source
public Task<TResult?> ReadSingleEntryAsync<TResult>(string tableName, Dictionary<string, AttributeValue> keys, Func<Dictionary<string, AttributeValue>, TResult> resolver, CancellationToken cancellationToken)
Reads an entry using the supplied cancellation token.

Parameters

tableNamestring
The table name.
keysDictionary<string, AttributeValue>
The entry keys.
resolverFunc<Dictionary<string, AttributeValue>, TResult>
Converts the returned fields to the result.
cancellationTokenCancellationToken
The cancellation token.

ScanAsync(string, Dictionary<string, AttributeValue>, string, Func<Dictionary<string, AttributeValue>, TResult>)

View source
public Task<List<TResult>> ScanAsync<TResult>(string tableName, Dictionary<string, AttributeValue> attributes, string expression, Func<Dictionary<string, AttributeValue>, TResult> resolver)
Scan a DynamoDB table by querying the entry fields.

Parameters

tableNamestring
The name of the table to search for the entries
attributesDictionary<string, AttributeValue>
The attributes used on the expression
expressionstring
The filter expression
resolverFunc<Dictionary<string, AttributeValue>, TResult>
Function that will be called to translate the returned fields into a concrete type. This Function is only called if the result is != null and will be called for each entry that match the query and added to the results list

Returns

The collection containing a list of objects translated by the resolver function

UpsertEntryAsync(string, Dictionary<string, AttributeValue>, Dictionary<string, AttributeValue>, CancellationToken, string, Dictionary<string, AttributeValue>, string, Dictionary<string, AttributeValue>)

View source
public Task UpsertEntryAsync(string tableName, Dictionary<string, AttributeValue> keys, Dictionary<string, AttributeValue> fields, CancellationToken cancellationToken, string conditionExpression = "", Dictionary<string, AttributeValue>? conditionValues = null, string extraExpression = "", Dictionary<string, AttributeValue>? extraExpressionValues = null)
Creates or updates an entry using the supplied cancellation token.

Parameters

tableNamestring
The table name.
keysDictionary<string, AttributeValue>
The entry keys.
fieldsDictionary<string, AttributeValue>
The fields to write, updated with values returned by DynamoDB.
cancellationTokenCancellationToken
The cancellation token.
conditionExpressionstring
The optional conditional expression.
conditionValuesDictionary<string, AttributeValue>
The conditional expression values.
extraExpressionstring
The additional update expression.
extraExpressionValuesDictionary<string, AttributeValue>
The additional expression values.

UpsertEntryAsync(string, Dictionary<string, AttributeValue>, Dictionary<string, AttributeValue>, string, Dictionary<string, AttributeValue>, string, Dictionary<string, AttributeValue>)

View source
public Task UpsertEntryAsync(string tableName, Dictionary<string, AttributeValue> keys, Dictionary<string, AttributeValue> fields, string conditionExpression = "", Dictionary<string, AttributeValue>? conditionValues = null, string extraExpression = "", Dictionary<string, AttributeValue>? extraExpressionValues = null)
Create or update an entry in a DynamoDB Table

Parameters

tableNamestring
The name of the table to upsert an entry
keysDictionary<string, AttributeValue>
The table entry keys for the entry
fieldsDictionary<string, AttributeValue>
The fields/attributes to add or updated in the table
conditionExpressionstring
Optional conditional expression
conditionValuesDictionary<string, AttributeValue>
Optional field/attribute values used in the conditional expression
extraExpressionstring
Additional expression that will be added in the end of the upsert expression
extraExpressionValuesDictionary<string, AttributeValue>
Additional field/attribute that will be used in the extraExpression

WriteTxAsync(CancellationToken, IEnumerable<Put>, IEnumerable<Update>, IEnumerable<Delete>, IEnumerable<ConditionCheck>)

View source
public Task WriteTxAsync(CancellationToken cancellationToken, IEnumerable<Put>? puts = null, IEnumerable<Update>? updates = null, IEnumerable<Delete>? deletes = null, IEnumerable<ConditionCheck>? conditionChecks = null)
Transactionally writes entries using the supplied cancellation token.

Parameters

cancellationTokenCancellationToken
The cancellation token.
putsIEnumerable<Put>
The entries to put.
updatesIEnumerable<Update>
The updates to perform.
deletesIEnumerable<Delete>
The deletes to perform.
conditionChecksIEnumerable<ConditionCheck>
The conditions to check.

WriteTxAsync(IEnumerable<Put>, IEnumerable<Update>, IEnumerable<Delete>, IEnumerable<ConditionCheck>)

View source
public Task WriteTxAsync(IEnumerable<Put>? puts = null, IEnumerable<Update>? updates = null, IEnumerable<Delete>? deletes = null, IEnumerable<ConditionCheck>? conditionChecks = null)
Transactionally performs write requests

Parameters

putsIEnumerable<Put>
Any puts to be performed
updatesIEnumerable<Update>
Any updated to be performed
deletesIEnumerable<Delete>
Any deletes to be performed
conditionChecksIEnumerable<ConditionCheck>
Any condition checks to be performed