In this column I discuss the most important things you should know to start developing in the Amazon DynamoDB with C#. Let me briefly describe some concepts: a table is more or less the same thing you already know and it needs a name and a hash key to be created. A hash key is like a primary key. You can optionally specify a range key, so by pairing the hash and range keys you get unique items. An item is like a record but only the hash key (and the range key if defined) is required, so every item can have a different data structure. DynamoDb is a database service in the cloud, so you can’t use Sql statements in order to manipulate data, Query and Scan operations are the way to do it. The Query operation is basically a get having the ID (or hash key) of the item you want to retrieve (that’s why it’s important to choose IDs carefully). By using the Query you can optionally specify the range key. The query has better performance over the Scan. Scan is used in the same way except by the fact that you can specify any attribute as a search condition; hence the table must be full scanned, decreasing the performance. You can use the Query and Scan operations in two ways: one is by retrieving a list of attribute names and values (so you have to read/parse them later) as it’s illustrated in the following sample (note that the simple Query operation uses the hash key only).


List<Dictionary<string, AttributeValue>> foo(string hashKeyValue, string tableName)
 {
 QueryRequest queryReq = new QueryRequest().WithHashKeyValue(new AttributeValue().WithN(hashKeyValue));
 queryReq.WithTableName(tableName);

 QueryResponse response = Client.Query(queryReq);
 return response.QueryResult.Items;
 }

The second way to use the Query and Scan operations is by decorating your classes and letting the Amazon API to parse the attributes names and values for you. In this mode you have to add the following attributes to your class:

  • Table Name attribute “[DynamoDBTable(“YourTableName”)]”: this attribute must be located on top of each type being persisted in DynamoDB and it has the same effect that the tableName variable of the first sample. [Update 14/03/2013: this error also happens if you’re using a different AWS .Net SDK DLL. More info here ]
  • Hash key and/or hash range attributes “[DynamoDBHashKey]”: this attribute must be located on top of the desired variable being persisted as part of a class.

After properly decorating your class you can use the Query operation as seen in the following sample.


public IEnumerable Query(object key)
 {
 return context.Query(key);
 }

Querying and Scanning DynamoDB tables are easier by decorating. Here are some issues or restrictions that I have found and probably they can help you in the process of using DynamoDB:

  • DynamoDB does not allow null or empty string attribute values.
  • If you fail to decorate the class you’ll receive a “No DynamoDBTableAttribute on type” exception.
  • If you receive a creepy “The start tag does not match the end tag” exception maybe it’s because you’re behind of a firewall, so you can use any tool like WireShrack to make sure the requests can reach the Amazon server.
  • If you’re wondering how to work without SQL don’t worry, double check the Query sample using decorating and you’ll see that an IEnumerable collection is returned, so you can use Linq (and the Sum, Max, Avg of course).

After developing the above sample queries you can find more information on advanced topics like using search conditions here and on using complex data models here.

[Update 09/19/2012:  If you want to learn more about good distribution of request/sizes and good hash key samples (BTW: time series are good keys) you can check it out here]

[Update 06/Aug/2013: If you receive a “No DynamoDBTableAttribute on type” exception and if you’re compiling within an E2C instance it could be because VS is using the GAC assemblies, which are probably newer. Simple remove the references to the AWS dll and and add them again using the dll version you know it works. More info here]

Javier Andrés Cáceres Alvis

Microsoft Most Valuable Professional – MVP
Intel Black Belt Software Developer