DynamoDBContext class from the .NET object persistence model

The DynamoDBContext class is the entry point to the Amazon DynamoDB database. It provides a connection to DynamoDB and enables you to access your data in various tables, perform various CRUD operations, and run 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 tables, 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 tables, use the ExecuteBatchWrite method, passing the MultiTableBatchWrite object as a parameter.

CreateBatchGet

Creates a BatchGet object that you can use to retrieve multiple items from a table.

CreateBatchWrite

Creates a BatchWrite object that you can use to put multiple items into a table, or to delete multiple items from a table.

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.

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.

Execute​Batch​Write

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

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 Working with the .NET document model in DynamoDB.

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

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

FromQuery

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

FromScan

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

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 you 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 about the eventual consistency model, see DynamoDB read consistency.

Load or LoadAsync method calls the GetItem operation, which requires you to specify the primary key for the table. Because GetItem ignores the IndexName parameter, you can’t load an item using an index’s partition or sort key. Therefore, you must use the table's primary key to load an item.

    /// <summary>
    /// Shows how to perform high-level CRUD operations on an Amazon DynamoDB
    /// table.
    /// </summary>
    public class HighLevelItemCrud
    {
        public static async Task Main()
        {
            var client = new AmazonDynamoDBClient();
            DynamoDBContext context = new DynamoDBContext(client);
            await PerformCRUDOperations(context);
        }

        public static async Task PerformCRUDOperations(IDynamoDBContext context)
        {
            int bookId = 1001; // Some unique value.
            Book myBook = new Book
            {
                Id = bookId,
                Title = "object persistence-AWS SDK for.NET SDK-Book 1001",
                Isbn = "111-1111111001",
                BookAuthors = new List<string> { "Author 1", "Author 2" },
            };

            // Save the book to the ProductCatalog table.
            await context.SaveAsync(myBook);

            // Retrieve the book from the ProductCatalog table.
            Book bookRetrieved = await context.LoadAsync<Book>(bookId);

            // Update some properties.
            bookRetrieved.Isbn = "222-2222221001";

            // Update existing authors list with the following values.
            bookRetrieved.BookAuthors = new List<string> { " Author 1", "Author x" };
            await context.SaveAsync(bookRetrieved);

            // Retrieve the updated book. This time, add the optional
            // ConsistentRead parameter using DynamoDBContextConfig object.
            await context.LoadAsync<Book>(bookId, new DynamoDBContextConfig
            {
                ConsistentRead = true,
            });

            // Delete the book.
            await context.DeleteAsync<Book>(bookId);

            // Try to retrieve deleted book. It should return null.
            Book deletedBook = await context.LoadAsync<Book>(bookId, new DynamoDBContextConfig
            {
                ConsistentRead = true,
            });

            if (deletedBook == null)
            {
                Console.WriteLine("Book is deleted");
            }
        }
    }

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 that you have a client-side Reply class mapped to the Reply table in DynamoDB. The following C# code example 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.

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 need to iterate only over the IEnumerable.

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

Save

Saves the specified object to the table. If the primary key specified in the input object doesn't exist in the table, the method adds a new item to the table. If the 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 DynamoDB and the AWS SDK for .NET object persistence model.

Scan

Performs an entire table scan.

You can filter scan results by specifying a scan condition. The condition can be evaluated on any attributes in the table. Suppose that you have a client-side class Book mapped to the ProductCatalog table in DynamoDB. The following C# example 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.

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 Working with the .NET document model in DynamoDB.

Suppose that 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 example.

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.

The following C# example creates a new DynamoDBContext by specifying two of the preceding optional parameters, ConsistentRead and SkipVersionCheck.

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

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

Instead of setting these parameters at the DynamoDBContext level, you can specify them for individual operations you run using DynamoDBContext, as shown in the following C# code example. The example loads a specific book item. The Load method of DynamoDBContext specifies the ConsistentRead and SkipVersionCheck 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.