Amazon SimpleDB

This guide focuses on the AWS SDK for PHP client for Amazon SimpleDB. This guide assumes that you have already downloaded and installed the AWS SDK for PHP. See Installation for more information on getting started.

Creating a client

First you need to create a client object using one of the following techniques.

Factory method

The easiest way to get up and running quickly is to use the Aws\SimpleDb\SimpleDbClient::factory() method and provide your credential profile (via the profile option), which identifies the set of credentials you want to use from your ~/.aws/credentials file (see Using the AWS credentials file and credential profiles).

A region parameter is required. You can find a list of available regions using the Regions and Endpoints reference.

use Aws\SimpleDb\SimpleDbClient;

$client = SimpleDbClient::factory(array(
    'profile' => '<profile in your aws credentials file>',
    'region'  => '<region name>'
));

You can provide your credential profile like in the preceding example, specify your access keys directly (via key and secret), or you can choose to omit any credential information if you are using AWS Identity and Access Management (IAM) roles for EC2 instances or credentials sourced from the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables.

Note

The profile option and AWS credential file support is only available for version 2.6.1 of the SDK and higher. We recommend that all users update their copies of the SDK to take advantage of this feature, which is a safer way to specify credentials than explicitly providing key and secret.

Service builder

A more robust way to connect to Amazon SimpleDB is through the service builder. This allows you to specify credentials and other configuration settings in a configuration file. These settings can then be shared across all clients so that you only have to specify your settings once.

use Aws\Common\Aws;

// Create a service builder using a configuration file
$aws = Aws::factory('/path/to/my_config.json');

// Get the client from the builder by namespace
$client = $aws->get('SimpleDb');

For more information about configuration files, see Configuring the SDK.

Creating domains

The first step in storing data within Amazon SimpleDB is to create one or more domains.

Domains are similar to database tables, except that you cannot perform functions across multiple domains, such as querying multiple domains or using foreign keys. As a consequence, you should plan an Amazon SimpleDB data architecture that will meet the needs of your project.

Let's use the CreateDomain operation of the Amazon SimpleDB client to create a domain.

$client->createDomain(array('DomainName' => 'mydomain'));

List all domains

Now that the domain is created, we can list the domains in our account to verify that it exists. This is done using the ListDomains operation and the ListDomains iterator.

$domains = $client->getIterator('ListDomains')->toArray();
var_export($domains);
// Lists an array of domain names, including "mydomain"

Retrieving a domain

You can get more information about a domain using the DomainMetadata operation. This operation returns information about a domain, including when the domain was created, the number of items and attributes, and the size of attribute names and values.

$result = $client->domainMetadata(array('DomainName' => 'mydomain'));
echo $result['ItemCount'] . "\n";
echo $result['ItemNamesSizeBytes'] . "\n";
echo $result['AttributeNameCount'] . "\n";
echo $result['AttributeNamesSizeBytes'] . "\n";
echo $result['AttributeValueCount'] . "\n";
echo $result['AttributeValuesSizeBytes'] . "\n";
echo $result['Timestamp'] . "\n";

Adding items

After creating a domain, you are ready to start putting data into it. Domains consist of items, which are described by attribute name-value pairs. Items are added to a domain using the PutAttributes operation.

$client->putAttributes(array(
    'DomainName' => 'mydomain',
    'ItemName'   => 'test',
    'Attributes' => array(
        array('Name' => 'a', 'Value' => 1, 'Replace' => true),
        array('Name' => 'b', 'Value' => 2),
    )
));

Note

When you put attributes, notice that the Replace parameter is optional, and set to false by default. If you do not explicitly set Replace to true, a new attribute name-value pair is created each time; even if the Name value already exists in your Amazon SimpleDB domain.

Retrieving items

GetAttributes

We can check to see if the item was added correctly by retrieving the specific item by name using the GetAttribute operation.

$result = $client->getAttributes(array(
    'DomainName' => 'mydomain',
    'ItemName'   => 'test',
    'Attributes' => array(
        'a', 'b'
    ),
    'ConsistentRead' => true
));

Notice that we set the ConsistentRead option to true. Amazon SimpleDB keeps multiple copies of each domain. A successful write (using PutAttributes, BatchPutAttributes, DeleteAttributes, BatchDeleteAttributes, CreateDomain, or DeleteDomain) guarantees that all copies of the domain will durably persist. Amazon SimpleDB supports two read consistency options: eventually consistent read and consistent read. A consistent read (using Select or GetAttributes with ConsistentRead=true) returns a result that reflects all writes that received a successful response prior to the read.

You can find out more about consistency and Amazon SimpleDB in the service's developer guide on consistency.

Select

You can retrieve attributes for items by name, but Amazon SimpleDB also supports the Select operation. The Select operation returns a set of Attributes for ItemNames that match the select expression. Select is similar to the standard SQL SELECT statement.

Let's write a select query that will return all items withe the a attribute set to 1.

$result = $client->select(array(
    'SelectExpression' => "select * from mydomain where a = '1'"
));
foreach ($result['Items'] as $item) {
    echo $item['Name'] . "\n";
    var_export($item['Attributes']);
}

Because some responses will be truncated and require subsequent requests, it is recommended to always use the Select iterator to easily retrieve an entire result set.

$iterator = $client->getIterator('Select', array(
    'SelectExpression' => "select * from mydomain where a = '1'"
));
foreach ($iterator as $item) {
    echo $item['Name'] . "\n";
    var_export($item['Attributes']);
}

You can find much more information about the Select operation in the service's developer guide on select.

Deleting items

You can delete specific attributes of an item or an entire item using the DeleteAttributes operation. If all attributes of an item are deleted, the item is deleted.

Let's go ahead and delete the item we created in mydomain.

$client->deleteAttributes(array(
    'DomainName' => 'mydomain',
    'ItemName'   => 'test'
));

Because we did not specify an Attributes parameter, the entire item is deleted.

Deleting domains

Now that we've explored some of the features of Amazon SimpleDB, we should delete our testing data. The DeleteDomain operation deletes a domain. Any items (and their attributes) in the domain are deleted as well. The DeleteDomain operation might take 10 or more seconds to complete.

$client->deleteDomain(array('DomainName' => 'mydomain'));

API Reference

Please see the Amazon SimpleDB Client API reference for a details about all of the available methods, including descriptions of the inputs and outputs.

BatchDeleteAttributes BatchPutAttributes
CreateDomain DeleteAttributes
DeleteDomain DomainMetadata
GetAttributes ListDomains
PutAttributes Select