Technical Docs

SimpleDB Basics

This is the 30-second overview of Amazon SimpleDB. If you're not familiar with SimpleDB or need a refresher, check out Amazon's very thorough documentation.

SimpleDB is a cloud database service provided by Amazon. You interact with it via HTTP requests. It's called SimpleDB because it is very simple: you can have up to 250 containers, called Domains. Each Domain can contain a very large number of Items. Each item is a set of key-value pairs, called Attributes. There are no schemas; each item can have a unique set of attributes. You can write basic SQL-like queries to retrieve items.

The Context

A SimpleDbContext represents a single session of interacting with SimpleDB. It is very lightweight to instantiate. There are two factory methods for creating SimpleDbContext instances:

Name	Description
Create(string privateKey, string publicKey)	Uses the built-in, standard implementation of ISimpleDbService to make a REST call to AWS SimpleDB using the provided credentials
Create(ISimpleDbService service)	Returns a context that will use the specified ISimpleDbService as the connection mechanism to SimpleDB. This is mostly useful for testing.

A typical example:

var myContext = SimpleDbContext.Create("publicKey", "privateKey");

Thread Safety

The SimpleDbContext is not thread-safe. It should not be used as a singleton or cached across sessions. However, keep in mind that it is trivial to create and dispose many contexts, so there is generally no performance concern with the number or frequency of contexts that are created and destroyed.

ISimpleDbDomain

Name	Description
Domains	Returns the collection of domains for this SimpleDB context. See Working with Domains for more information.
Statistics	Returns an object that has statistics about SimpleDB usage for the context. See Statistics for more information.

Working with Domains

The Context has a Domains property which is a ISimpleDbCollection. It represents the set of domains that exist in SimpleDB. It is lazy-loaded; certain actions will trigger a full fetch of the entire list of domains.

ISimpleDbDomainCollection

Name	Description
Count	Returns the number of domains. Triggers a full fetch of the domain list.
Add(string name)	Creates a domain with the specified name, and returns the ISimpleDbDomain. As with SimpleDB, calling this routine for a domain name that already exists will return that domain; it will not raise an exception or modify the existing domain.
HasDomain(string name)	Returns whether a domain with the specified name exists. Triggers a full fetch of the domain list.
[string name]	Returns an ISimpleDbDomain for the specified domain name. Note that if the domain does not exist, this will not raise an exception until an operation is attempted against the domain.

ISimpleDbDomain

Name	Description
Name	Returns the name of the domain.
Items	Returns an ISimpleDbItemsCollection that represents all the items in the domain. See Working with Items for more information.
Delete()	Deletes the domain from SimpleDB.

Working with Items

Querying

ISimpleDbService

The ISimpleDbService interface represents to the API methods of SimpleDB. SimpleDb.Net includes one main implementation: SimpleDbRestService. This handles mapping abstract .NET objects to the REST format expected by SimpleDB. There are also unit test implementations that do not make physical HTTP calls.

Statistics

The Context has a Statistics property of type ISimpleDbStatistics. It provides access to information about the current usage of the SimpleDB service, such as total box usage. (This has a direct impact on how much AWS will bill you for cloud usage. See SimpleDB Pricing for more information.)

ISimpleDbStatistics

Name	Description
LastOperationUsage	Gets the box usage for the most recently performed operation in the current context.
TotalOperationUsage	Gets the total box usage for all operations performed in the current context.
LastOperationId	Gets the ID of the most recently performed operation in the current context.
OperationCount	Gets a count of SimpleDB operations performed in the current context.