Skip to content
This repository has been archived by the owner on Nov 16, 2020. It is now read-only.

API Quick Reference (Sync)

Jump to bottom
Jeff Walker Code Ranger edited this page Sep 9, 2015 · 3 revisions

This is a quick reference to the Adamantworks.Amazon.DynamoDB API. If you are already familiar with how DynamoDB works, this should give you a pretty good idea of how to use the API. Optional parameters are indicated by a trailing question mark.

Note: The async API is identical to the synchronous API except many methods end in "Asyc" following Micrsoft naming guidelines and methods return Tasks and taking extra optional arguments to control the async behavior.

Region

An instance of IDynamoDBRegion represents a single region in an account.

####Construction

DynamoDBRegion.Connect(...); // returns IDynamoDBRegion

####Properties

// determines how frequently to poll for status changes when waiting on status change of tables loaded from this region
TimeSpan WaitStatusPollingInterval { get; set; }

####Manipulate Tables

region.ListTables(); // returns table names
region.ListTablesWithPrefix(tableNamePrefix); // returns table names
region.LoadTable(tableName); // throws ResourceNotFoundException if no table
region.TryLoadTable(tableName); // returns null if no table
region.CreateTable(tableName, schema, provisionedThroughput?, indexProvisionedThroughputs?); // returns a table in creating status
region.DeleteTable(tableName);

####Batches

Batches are objects used to enroll operations in a batch and need to be completed. For more information read Batch Operations

region.BeginBatchGet();
region.BeginBatchWrite();

Table

An instance of ITable represents a table in a given region. Table objects contain information about the table schema. Consequently, to create a table requires a describe table operation. It is recommended you avoid calling LoadTable() more than necessary and cache instances of ITable. Many table methods require that a key be specified. In each of these cases, there are a number of ways to pass the hash and range key values. These parameters are indicated with <key>. For more information read Item Keys.

Construction

region.LoadTable(tableName); // throws ResourceNotFoundException if no table
region.TryLoadTable(tableName); // returns null if no table
region.CreateTable(tableName, schema, provisionedThroughput?, indexProvisionedThroughputs?); // returns a table in creating status

Properties

string Name { get; }
TableSchema Schema { get; }
IReadOnlyDictionary<string, IIndex> Indexes { get; }
DateTime CreationDateTime { get; }
long ItemCount { get; }
long SizeInBytes { get; }
CollectionStatus Status { get; }
IProvisionedThroughputInfo ProvisionedThroughput { get; }

Misc Operations

table.UpdateTable(provisionedThroughput?, indexProvisionedThroughputs?); // modify provisioned throughput
table.Reload(); // reloads table schema and status
table.WaitUntilNot(status, timeout?); // blocking wait for a table to leave a trainsient status
table.GetKey(item); // given an item of the table, get the item key

###Read Operations

####Get

table.Get(<key>);
table.BatchGet(keys);
table.BatchGetJoin(items, keySelector, resultSelector);  // joins up already loaded items by doing a batch get

####Query

Query operations are specified with a fluent syntax allowing the specification of various options. They begin with a call to Query(...) or QueryCount(...) and end with a method indicating which range key values to select for the given hash key. The option methods in between are option and can be combined. Queries come in two forms. Standard queries that return an IEnumerable<DynamoDBItem> and paged queries that return a special page object providing the last key. Paged queries do not support the LimitTo and ExclusiveStartKey options because they are specified through the paging mechanism. The paging API is recommended over the direct use of LimitTo and ExclusiveStartKey.

table.Query(hashKey, converter?, filter?).AllKeys();
table.Query(hashKey, converter?, filter?).RangeKeyEquals(rangeKey, converter?);
table.Query(hashKey, converter?, filter?).RangeKeyBeginsWith(rangeKey, converter?);
table.Query(hashKey, converter?, filter?).RangeKeyLessThan(rangeKey, converter?);
table.Query(hashKey, converter?, filter?).RangeKeyLessThanOrEqualTo(rangeKey, converter?);
table.Query(hashKey, converter?, filter?).RangeKeyGreaterThanOrEqualToAsync(rangeKey, converter?);
table.Query(hashKey, converter?, filter?).RangeKeyGreaterThanOrEqualTo(rangeKey, converter?);
table.Query(hashKey, converter?, filter?).RangeKeyBetween(startInclusive, endExclusive, converter?);
table.QueryCount(hashKey, converter?, filter?).AllKeys();
table.QueryCount(hashKey, converter?, filter?).RangeKeyEquals(rangeKey, converter?);
table.QueryCount(hashKey, converter?, filter?).RangeKeyBeginsWith(rangeKey, converter?);
table.QueryCount(hashKey, converter?, filter?).RangeKeyLessThan(rangeKey, converter?);
table.QueryCount(hashKey, converter?, filter?).RangeKeyLessThanOrEqualTo(rangeKey, converter?);
table.QueryCount(hashKey, converter?, filter?).RangeKeyGreaterThanOrEqualToAsync(rangeKey, converter?);
table.QueryCount(hashKey, converter?, filter?).RangeKeyGreaterThanOrEqualTo(rangeKey, converter?);
table.QueryCount(hashKey, converter?, filter?).RangeKeyBetween(startInclusive, endExclusive, converter?);

// Paged (applies to any range key condition)
table.Query(null).Paged(pageSize, exclusiveStartKey?).AllKeys(); // returns a page

// Other Options (applies to any range key condition)
table.Query(hashKey, converter?, filter?).Reverse().AllKeys();
table.Query(hashKey, converter?, filter?).LimitTo(limit).ExclusiveStartKey(lastKey).AllKeys();

####Scan

Scan operations are specified with a fluent syntax allowing the specification of various options. Scan operations can be paged. A scan can also be run in segments to distribute reads across the table or index either across boxes or in parallel from a single box.

table.Scan(filter?, values?).All();
table.Scan(filter?, values?).InParallel(); // returns results out of order
table.Scan(filter?, values?).Segment(segment, totalSegments);
table.ScanCount(filter?, values?).All();
table.ScanCount(filter?, values?).InParallel();
table.ScanCount(filter?, values?).Segment(segment, totalSegments);

// Paged
table.Scan(filter?, values?).Paged(pageSize, exclusiveStartKey?).All();
table.Scan(filter?, values?).Paged(pageSize, exclusiveStartKey?).Segment(segment, totalSegments);

// Other Options (applies to any kind of scan)
table.Scan(filter?, values?).LimitTo(limit).ExclusiveStartKey(lastKey).All();

####Read Options

Any of the above read operations (get, query and scan) can be combined with the following options. A projection expression can be specified by prefixing the call with .Select(projection).From. A consistent read can be done by prefixing with .Consistent or .ConsistentIf(consistentRead) allowing the consistency to be dynamic on a boolean expression. Note that in a consistent batch get join, only the read of the joined items is consistent. The original items were read in an independent operation. To illustrate here are several of the many possibilities:

table.Consistent.BatchGet(keys);
table.Select(projection).From.ConsistentIf(consistentRead).Get(<key>);

###Write Operations

####Put

In DynamoDB, a put operation will add the item to the collection, replacing any existing item with the same key.

table.Put(item, returnOldItem?);
table.Put(batch, item); // enroll the put in the batch

Insert

An insert is not a built in DynamoDB operation. Rather it is a put with a condition that there is not an existing item with the same key. Because of this implicit condition, adding another condition with .If(...) is not supported (see Write Options below).

table.Insert(item); // throws InsertFailedException if an item with the key already exists
table.TryInsert(item); // returns false if an item with the key already exists

####Update

table.Update(update, values?, returnValue?).OnItem(<key>);

Delete

table.Delete(returnOldItem?).Item(<key>);
table.Delete(batch).Item(<key>);

Write Options

Most of the above write operations can have an added conditional expression by prefixing with .If(condition, values?). Insert operations do not support this because they are actually puts with an implicit condition that the item not already exist. Batch operations also do no support conditional write. When the the condition is not satisfied, the operation throws ConditionalCheckFailedException. Alternatively, you can use the Try* methods which return a boolean to indicate whether the condition was satisfied. However, the try methods do not allow you to return item data from the operation.

table.If(condition, values?).Put(item, returnOldItem?); // throws ConditionalCheckFailedException if the condition is false
table.If(condition, values?).TryPut(item); // returns false if the condition is false
table.If(condition, values?).Update(update, values?, returnValue?).OnItem(<key>); // throws ConditionalCheckFailedException if the condition is false
table.If(condition, values?).TryUpdate(update, values?).OnItem(<key>); // returns false if the condition is false
table.If(condition, values?).Delete(returnOldItem?).Item(<key>); // throws ConditionalCheckFailedException if the condition is false
table.If(condition, values?).TryDelete().Item(<key>); // returns false if the condition is false
Clone this wiki locally