Menu
Amazon DynamoDB
Developer Guide (API Version 2012-08-10)

DynamoDBContext Class

The DynamoDBContext class is the entry point to the DynamoDB database. It provides a connection to DynamoDB and enables you to access your data in various tables, perform various CRUD operations, and execute queries. The DynamoDBContext class provides the following methods:

Create​MultiTable​BatchGet

Creates a MultiTableBatchGet object, composed of multiple individual BatchGet objects. Each of these BatchGet objects can be used for retrieving items from a single DynamoDB table.

To retrieve the items from the table(s), use the ExecuteBatchGet method, passing the MultiTableBatchGet object as a parameter.

Create​MultiTable​BatchWrite

Creates a MultiTableBatchWrite object, composed of multiple individual BatchWrite objects. Each of these BatchWrite objects can be used for writing or deleting items in a single DynamoDB table.

To write to the table(s), use the ExecuteBatchWrite method, passing the MultiTableBatchWrite object as a parameter.

Create​Batch​Get

Creates a BatchGet object that you can use to retrieve multiple items from a table. For more information, see Batch Get: Getting Multiple Items .

Create​Batch​Write

Creates a BatchWrite object that you can use to put multiple items into a table, or to delete multiple items from a table. For more information, see Batch Write: Putting and Deleting Multiple Items .

Delete

Deletes an item from the table. The method requires the primary key of the item you want to delete. You can provide either the primary key value or a client-side object containing a primary key value as a parameter to this method.

  • If you specify a client-side object as a parameter and you have enabled optimistic locking, the delete succeeds only if the client-side and the server-side versions of the object match.

  • If you specify only the primary key value as a parameter, the delete succeeds regardless of whether you have enabled optimistic locking or not.

Note

To perform this operation in the background, use the DeleteAsync method instead.

Dispose

Disposes of all managed and unmanaged resources.

Execute​Batch​Get

Reads data from one or more tables, processing all of the BatchGet objects in a MultiTableBatchGet.

Note

To perform this operation in the background, use the ExecuteBatchGetAsync method instead.

Execute​Batch​Write

Writes or deletes data in one or more tables, processing all of the BatchWrite objects in a MultiTableBatchWrite.

Note

To perform this operation in the background, use the ExecuteBatchWriteAsync method instead.

FromDocument

Given an instance of a Document, the FromDocument method returns an instance of a client-side class.

This is helpful if you want to use the document model classes along with the object persistence model to perform any data operations. For more information about the document model classes provided by the AWS SDK for .NET, see .NET: Document Model.

Suppose you have a Document object named doc, containing a representation of a Forum item. (To see how to construct this object, see the description for the ToDocument method below.) You can use FromDocument to retrieve the Forum item from the Document as shown in the following C# code snippet.

forum101 = context.FromDocument<Forum>(101);

Note

If your Document object implements the IEnumerable interface, you can use the FromDocuments method instead. This will allow you to iterate over all of the class instances in the Document.

FromQuery

Executes a Query operation, with the query parameters defined in a QueryOperationConfig object.

Note

To perform this operation in the background, use the FromQueryAsync method instead.

FromScan

Executes a Scan operation, with the scan parameters defined in a ScanOperationConfig object.

Note

To perform this operation in the background, use the FromScanAsync method instead.

Get​Target​Table

Retrieves the target table for the specified type. This is useful if you are writing a custom converter for mapping arbitrary data to a DynamoDB table and need to determine which table is associated with a custom data type.

Load

Retrieves an item from a table. The method requires only the primary key of the item you want to retrieve.

By default, DynamoDB returns the item with values that are eventually consistent. For information on the eventual consistency model, see Read Consistency.

Note

To perform this operation in the background, use the LoadAsync method instead.

Query

Queries a table based on query parameters you provide.

You can query a table only if it has a composite primary key (partition key and sort key). When querying, you must specify a partition key and a condition that applies to the sort key.

Suppose you have a client-side Reply class mapped to the Reply table in DynamoDB. The following C# code snippet queries the Reply table to find forum thread replies posted in the past 15 days. The Reply table has a primary key that has the Id partition key and the ReplyDateTime sort key. For more information about the Reply table, see Creating Tables and Loading Sample Data.

DynamoDBContext context = new DynamoDBContext(client);

string replyId = "DynamoDB#DynamoDB Thread 1"; //Partition key 
DateTime twoWeeksAgoDate = DateTime.UtcNow.Subtract(new TimeSpan(14, 0, 0, 0)); // Date to compare.
IEnumerable<Reply> latestReplies = context.Query<Reply>(replyId, QueryOperator.GreaterThan, twoWeeksAgoDate);  

This returns a collection of Reply objects.

The Query method returns a "lazy-loaded" IEnumerable collection. It initially returns only one page of results, and then makes a service call for the next page if needed. To obtain all the matching items, you only need to iterate over the IEnumerable.

If your table has a simple primary key (partition key), then you cannot use the Query method. Instead, you can use the Load method and provide the partition key to retrieve the item.

Note

To perform this operation in the background, use the QueryAsync method instead.

Save

Saves the specified object to the table. If the primary key specified in the input object does not exist in the table, the method adds a new item to the table. If primary key exists, the method updates the existing item.

If you have optimistic locking configured, the update succeeds only if the client and the server side versions of the item match. For more information, see Optimistic Locking Using Version Number with DynamoDB Using the AWS SDK for .NET Object Persistence Model.

Note

To perform this operation in the background, use the SaveAsync method instead.

Scan

Performs an entire table scan.

You can filter scan result by specifying a scan condition. The condition can be evaluated on any attributes in the table. Suppose you have a client-side class Book mapped to the ProductCatalog table in DynamoDB. The following C# snippet scans the table and returns only the book items priced less than 0.

IEnumerable<Book> itemsWithWrongPrice = context.Scan<Book>(
                    new ScanCondition("Price", ScanOperator.LessThan, price),
                    new ScanCondition("ProductCategory", ScanOperator.Equal, "Book")
      );

The Scan method returns a "lazy-loaded" IEnumerable collection. It initially returns only one page of results, and then makes a service call for the next page if needed. To obtain all the matching items, you only need to iterate over the IEnumerable.

For performance reasons you should query your tables and avoid a table scan.

Note

To perform this operation in the background, use the ScanAsync method instead.

ToDocument

Returns an instance of the Document document model class from your class instance.

This is helpful if you want to use the document model classes along with the object persistence model to perform any data operations. For more information about the document model classes provided by the AWS SDK for .NET, see .NET: Document Model.

Suppose you have a client-side class mapped to the sample Forum table. You can then use a DynamoDBContext to get an item, as a Document object, from the Forum table as shown in the following C# code snippet.

DynamoDBContext context = new DynamoDBContext(client);

Forum forum101 = context.Load<Forum>(101); // Retrieve a forum by primary key.
Document doc = context.ToDocument<Forum>(forum101);

Specifying Optional Parameters for DynamoDBContext

When using the object persistence model, you can specify the following optional parameters for the DynamoDBContext.

  • ConsistentRead—When retrieving data using the Load, Query or Scan operations you can optionally add this parameter to request the latest values for the data.

  • IgnoreNullValues—This parameter informs DynamoDBContext to ignore null values on attributes during a Save operation. If this parameter is false (or if it is not set), then a null value is interpreted as directives to delete the specific attribute.

  • SkipVersionCheck— - This parameter informs DynamoDBContext to not compare versions when saving or deleting an item. For more information about versioning, see Optimistic Locking Using Version Number with DynamoDB Using the AWS SDK for .NET Object Persistence Model.

  • TableNamePrefix— - Prefixes all table names with a specific string. If this parameter is null (or if it is not set), then no prefix is used.

The following C# snippet creates a new DynamoDBContext by specifying two of the preceding optional parameters.

AmazonDynamoDBClient client = new AmazonDynamoDBClient();      
...
DynamoDBContext context = 
       new DynamoDBContext(client, new DynamoDBContextConfig { ConsistentRead = true, SkipVersionCheck = true});

DynamoDBContext includes these optional parameters with each request you send using this context.

Instead of setting these parameters at the DynamoDBContext level, you can specify them for individual operations you execute using DynamoDBContext as shown in the following C# code snippet. The example loads a specific book item. The Load method of DynamoDBContext specifies the preceding optional parameters.

AmazonDynamoDBClient client = new AmazonDynamoDBClient();      
...
DynamoDBContext context = new DynamoDBContext(client);
Book bookItem = context.Load<Book>(productId,new DynamoDBContextConfig{ ConsistentRead = true, SkipVersionCheck = true });

In this case DynamoDBContext includes these parameters only when sending the Get request.