13 DynamoDB PHP Query Examples

DynamoDB is a cloud-hosted NoSQL database from Amazon. It offers dependable performance, a well-managed environment, and easy API access to interact with it.

This article will help you perform various queries in DynamoDB with PHP.

If you're looking for a similar guide but for Node.js, Rust, and Python/Boto3.

Table of Contents

• Setup
• Create Table
• Update Table
• List Tables
• Delete Table
• Add Item
• Get Item
• Update Item
• Delete Item
• Get Multiple Items
• Batch Write to Update Multiple Records
• Create a Table Using a Global Secondary Index
• Querying for Global Secondary Index

Setup

You can easily install AWS SDK for PHP using 3 methods:

• As a dependency via Composer.
• As a prepackaged phar of the SDK.
• As a ZIP file of the SDK.

Please refer to the AWS documentation to find more about these 3 methods.

After installation, you can create a new database client like the below:

use Aws\DynamoDb\DynamoDbClient;

$client = DynamoDbClient::factory(array(
   'profile' => '<profile in your aws credentials file>',
   'region'  => '<region name>'
));
use Aws\DynamoDb\DynamoDbClient;

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

Create Table

You can easily create a DynamoDB table using the createTable method from the AWS-SDK. It accepts multiple parameters as inputs, including table name, attributes definitions, billing mode, local secondary indexes, global secondary indexes, provisioned throughput, etc.

$result = $client->createTable(array(
  'TableName' => 'employeeTable',
  'AttributeDefinitions' => array(
        array(
            'AttributeName' => 'eid',
            'AttributeType' => 'N'
        ),
        array(
            'AttributeName' => 'name',
            'AttributeType' => 'S' 
        ),
        array(
            'AttributeName' => 'department',
            'AttributeType' => 'S' 
        )
  ), 
  'KeySchema' => array( 
      array( 
            'AttributeName' => 'eid', 
            'KeyType' => 'HASH'
           ), 
      array(
            'AttributeName' => 'name', 
            'KeyType' => 'RANGE' 
          )
  ), 
  'BillingMode' => 'PROVISIONED|PAY_PER_REQUEST',
  // You need to define the throughout if you select Provisioned as the billing mode
  'ProvisionedThroughput' => array(
       'ReadCapacityUnits' => 1, 
       'WriteCapacityUnits' => 1 
        )
  )
);
$result = $client->createTable(array(
  'TableName' => 'employeeTable',
  'AttributeDefinitions' => array(
        array(
            'AttributeName' => 'eid',
            'AttributeType' => 'N'
        ),
        array(
            'AttributeName' => 'name',
            'AttributeType' => 'S' 
        ),
        array(
            'AttributeName' => 'department',
            'AttributeType' => 'S' 
        )
  ), 
  'KeySchema' => array( 
      array( 
            'AttributeName' => 'eid', 
            'KeyType' => 'HASH'
           ), 
      array(
            'AttributeName' => 'name', 
            'KeyType' => 'RANGE' 
          )
  ), 
  'BillingMode' => 'PROVISIONED|PAY_PER_REQUEST',
  // You need to define the throughout if you select Provisioned as the billing mode
  'ProvisionedThroughput' => array(
       'ReadCapacityUnits' => 1, 
       'WriteCapacityUnits' => 1 
        )
  )
);

However, you need to ensure that the table name is unique within the AWS region you select. If all the parameters are in place, the createTable method will immediately return the TableStatus as CREATING. Once the table is created, the status will be updated to ACTIVE. Then you can start performing read and write requests on the table.

You can also use Dynobase to create tables.

Update Table

You can use the updateTable method to update existing DynamoDB tables. It allows updating provisioned throughput, enabling or disabling streams, and creating or removing global secondary indexes. However, you will be only allowed to perform one of the above operations at once.

The below example shows how to update the provisioned throughput using the updateTable method.

$tableName = 'employeeTable'; 
//Need to specify the table name 

$result = $client->updateTable(array( 
  'TableName' => $tableName, 
  'ProvisionedThroughput' => array( 
      'ReadCapacityUnits' => 3, 
      'WriteCapacityUnits' => 3 )
 ));
$tableName = 'employeeTable'; 
//Need to specify the table name 

$result = $client->updateTable(array( 
  'TableName' => $tableName, 
  'ProvisionedThroughput' => array( 
      'ReadCapacityUnits' => 3, 
      'WriteCapacityUnits' => 3 )
 ));

List Tables

You can use the listTables method to retrieve the details of existing DynamoDB tables. There, you need to define the start table name and the number of tables you need to retrieve. DynamoDB will return a paginated response with 100 table names per page.

$result = $client->listTables([
    'ExclusiveStartTableName' => '<string>',
    'Limit' => <integer>,
]);
$result = $client->listTables([
    'ExclusiveStartTableName' => '<string>',
    'Limit' => <integer>,
]);

The first table name this operation will evaluate is the value returned for LastEvaluatedTableName in a previous operation.

Delete Table

You can easily delete a DynamoDB table using the deleteTable method. You only need to provide the table name:

$tableName = 'employeeTable'; 

$result = $client->deleteTable(array(
    'TableName' => $tableName

));
$tableName = 'employeeTable'; 

$result = $client->deleteTable(array(
    'TableName' => $tableName

));

Add Item

DynamoDB uses putItem method to add items to a DynamoDB table.

$response = $client->putItem(array(
    'TableName' => 'employeeTable', 
    'Item' => array(
        'eid'         => array('N'       =>  01      ), 
        'name'        => array('S'       => 'emp 01' ),
        'department'  => array('S'       => 'dep 1' ),
        'age'         => array('N'       =>  44 ),
        'gender'      => array('S'       => 'male' ),
        'address'     => array('S'       => 'Address 1 ' ),
        'salary'      => array('N'       =>  100000  )
    )
));
$response = $client->putItem(array(
    'TableName' => 'employeeTable', 
    'Item' => array(
        'eid'         => array('N'       =>  01      ), 
        'name'        => array('S'       => 'emp 01' ),
        'department'  => array('S'       => 'dep 1' ),
        'age'         => array('N'       =>  44 ),
        'gender'      => array('S'       => 'male' ),
        'address'     => array('S'       => 'Address 1 ' ),
        'salary'      => array('N'       =>  100000  )
    )
));

DynamoDB putItemthe method will create a new item or replace an item with the same primary key. You can also use conditions in putItem method.

The use of empty string and binary attribute values is permitted. However, if the attribute is used as a key attribute for a table or index, attribute values for data types must have a length larger than zero. In addition, there can't be any empty set type attributes. Validation exception will be thrown for invalid requests with empty values.

Get Item

When you need to access the data item in the table, you can quickly call getItem method to access any item from the table. The primary key should be specified to get the relevant item.

$response = $client->getItem(array(
    'TableName' => 'employeeTable',
    'Key' => array(
        'eid' => array( 'N' => 1 ),'name' => array( 'S' => 'emp 01' )
    )
));

print_r ($response['Item']);
$response = $client->getItem(array(
    'TableName' => 'employeeTable',
    'Key' => array(
        'eid' => array( 'N' => 1 ),'name' => array( 'S' => 'emp 01' )
    )
));

print_r ($response['Item']);

Update Item

You can use the updateItem method to update an item in a DynamoDB table.

$response = $client->updateItem(array(
    'TableName' => 'employeeTable ',
        'Key' => array(
            'eid' => array('N' => 1), 'name' => array( 'S' => 'emp  01' )
        ),
    'ExpressionAttributeValues' =>  array (
        ':val1' => array('N' => '001'),
        ':val2' => array('N' => '2000')
    ) ,

    'UpdateExpression' => 'SET jobId = :val1, salary = salary - :val2 REMOVE address'

));
$response = $client->updateItem(array(
    'TableName' => 'employeeTable ',
        'Key' => array(
            'eid' => array('N' => 1), 'name' => array( 'S' => 'emp  01' )
        ),
    'ExpressionAttributeValues' =>  array (
        ':val1' => array('N' => '001'),
        ':val2' => array('N' => '2000')
    ) ,

    'UpdateExpression' => 'SET jobId = :val1, salary = salary - :val2 REMOVE address'

));

In the above example, I add a new attribute called jobId and set the value to 001, reduce the salary by 2000 and remove the address attribute from the table. Finally, the updated change will be applied to the record where the eId is 1, and the name is emp 01.

Also, you can use a conditional expression to update an item with a condition. For that, you need to invoke the ConditionalExpression method.

$response = $client->updateItem(array(
    'TableName' => 'employeeTable',
        'Key' => array(
            'eid' => array('N' => 1), 'name' => array( 'S' => 'emp 01' )
        ),
    'ExpressionAttributeValues' =>  array (
        ':val1' => array('N' => '60000'),
        ':val2' => array('N' => '50000')
    ) ,

    'UpdateExpression'       => 'SET salary = :val1 ', 
    'ConditionalExpression'  => 'salary > :val2 ',
    'ReturnValues '          => 'ALL_NEW'
));
$response = $client->updateItem(array(
    'TableName' => 'employeeTable',
        'Key' => array(
            'eid' => array('N' => 1), 'name' => array( 'S' => 'emp 01' )
        ),
    'ExpressionAttributeValues' =>  array (
        ':val1' => array('N' => '60000'),
        ':val2' => array('N' => '50000')
    ) ,

    'UpdateExpression'       => 'SET salary = :val1 ', 
    'ConditionalExpression'  => 'salary > :val2 ',
    'ReturnValues '          => 'ALL_NEW'
));

In the above code snippet, the salary will update to 60000 where the salary is greater than 50000 in the given record. This conditional expression will ensure that you do the exact change to the exact attribute.

Delete Item

You can delete an item from a DynamoDB table using deleteItem method.

$response = $client->deleteItem(array(
    'TableName' => 'employeeTable',
    'Key' => array(
        'eid' => array(
            'N' => 2
        ),
    'name' => array(
            'S' => 'emp 2'
        )
    )
));
$response = $client->deleteItem(array(
    'TableName' => 'employeeTable',
    'Key' => array(
        'eid' => array(
            'N' => 2
        ),
    'name' => array(
            'S' => 'emp 2'
        )
    )
));

Once you delete an item, you can not retrieve that value again. As I mentioned in updating items, you can also use conditionalExpression to delete a specific attribute after executing a particular condition. For example, if you want to delete employee details that are allocated in another company, you can use the below code :

$tableName = "employeeTable";
$response = $client->deleteItem ( array (

 'TableName' => $tableName,
        'Key' => array(
            'eid' => array('N' => 1), 'name' => array( 'S' => 'emp 01' )
        ),

       'ExpressionAttributeValues' => array( 
             ':val1' => array('BOOL' => true) 
       ),
    'ConditionalExpression'  => 'isInAnotherCompany > :val1 ',
    'ReturnValues '          => 'ALL_OLD'

));
$tableName = "employeeTable";
$response = $client->deleteItem ( array (

 'TableName' => $tableName,
        'Key' => array(
            'eid' => array('N' => 1), 'name' => array( 'S' => 'emp 01' )
        ),

       'ExpressionAttributeValues' => array( 
             ':val1' => array('BOOL' => true) 
       ),
    'ConditionalExpression'  => 'isInAnotherCompany > :val1 ',
    'ReturnValues '          => 'ALL_OLD'

));

Get Multiple Items

You can use batchGetItem to get multiple items from a table. However, batchGetItem method execution is parallel. Therefore you can not guarantee the order of the retrieved item.

$response = $client->batchGetItem(array(
    "RequestItems" => array(
        "Reply" => array(
            "Keys" => array(
                array( 
                    "eid"  => array( 'N' => "1"),
                    "name" => array( 'S' => "emp 01"),
                ),
                array( 
                    "eid"  => array( 'N' => "2"),
                    "name" => array( 'S' => "emp 2"),
                ),
            )
        )
    )
));
$response = $client->batchGetItem(array(
    "RequestItems" => array(
        "Reply" => array(
            "Keys" => array(
                array( 
                    "eid"  => array( 'N' => "1"),
                    "name" => array( 'S' => "emp 01"),
                ),
                array( 
                    "eid"  => array( 'N' => "2"),
                    "name" => array( 'S' => "emp 2"),
                ),
            )
        )
    )
));

Batch Write to Update Multiple Records

To update multiple records in one instance, you need to invoke batchWrite method by defining the keys of records you need to put or delete in your DynamoDB table.

$response = $client->batchWriteItem(array(
    "RequestItems" => array(
        $tableName => array(
            array(
                "PutRequest" => array(
                    "Item" => array(
                        "eid"   => array('N' => 1),
                        "name" => array('S' => "emp  1"),
                        "middleName"=> array('S' => "emp mid name")
                    ))
            ),
            array(
                "DeleteRequest" => array(
                    "Key" => array(
                        "eid"   => array('N' => 2),
                        "name" => array('S' => "emp 2"),
                    ))
            )
        )
    )
));
$response = $client->batchWriteItem(array(
    "RequestItems" => array(
        $tableName => array(
            array(
                "PutRequest" => array(
                    "Item" => array(
                        "eid"   => array('N' => 1),
                        "name" => array('S' => "emp  1"),
                        "middleName"=> array('S' => "emp mid name")
                    ))
            ),
            array(
                "DeleteRequest" => array(
                    "Key" => array(
                        "eid"   => array('N' => 2),
                        "name" => array('S' => "emp 2"),
                    ))
            )
        )
    )
));

The BatchWriteItem operation can write or remove up to 16 MB of data in a single operation. If one or more tables do not exist, if the request contains more than 25 items, if any of the things are more than 400 KB, or if the overall data size exceeds 16 MB, the BatchWriteItem operation will be refused.

There is no method to recover data that has been destroyed.

Create a Table Using a Global Secondary Index

A global secondary index is an index with a partition key and sort key different from the keys on the base table. Lets' see how to create a table using a secondary index.

For that, you need to specify AttributeDefinitions, keySchema, and GlobalSecondaryIndex. In the employeeTable, we will use eid and name as primary indexes, while department and address as the hash and range keys for GlobalSecondaryIndex.

$tableName ="employeeTable";

$result = $client->createTable(array(
    'TableName' => $tableName,
    'AttributeDefinitions' => array(
        array(
            'AttributeName' => 'eid',
            'AttributeType' => 'N'
        ),
        array(
            'AttributeName' => 'name',
            'AttributeType' => 'S' 
        ),
        array(
            'AttributeName' => 'department',
            'AttributeType' => 'S' 
        ),
        array(
            'AttributeName' => 'age',
            'AttributeType' => 'N' 
       ),
        array(
            'AttributeName' => 'gender',
            'AttributeType' => 'S' 
       ),
        array(
            'AttributeName' => 'address',
            'AttributeType' => 'S' 
     
   ),
        array(
            'AttributeName' => 'salary',
            'AttributeType' => 'N' 
      ) 
), 
'KeySchema' => array( 
      array( 
            'AttributeName' => 'eid', 
            'KeyType' => 'HASH'
           ), 
      array(
            'AttributeName' => 'name', 
            'KeyType' => 'RANGE' 
          )
 ), 
  'GlobalSecondaryIndexes' => array(
        array(
            'IndexName' => 'NameManufacturerIndex',
            'ProvisionedThroughput' => array (
                'ReadCapacityUnits' => 4,
                'WriteCapacityUnits' => 4
            ),
            'KeySchema' => array(
                array(
                    'AttributeName' => 'department',
                    'KeyType' => 'HASH'
                ),
                array(
                    'AttributeName' => 'address',
                    'KeyType' => 'RANGE'
                )
            ),
            'Projection' => array(
                'ProjectionType' => 'ALL'
            )
        )
    ),
  'ProvisionedThroughput' => array(
       'ReadCapacityUnits' => 1, 
       'WriteCapacityUnits' => 1 
        )
 ));
$tableName ="employeeTable";

$result = $client->createTable(array(
    'TableName' => $tableName,
    'AttributeDefinitions' => array(
        array(
            'AttributeName' => 'eid',
            'AttributeType' => 'N'
        ),
        array(
            'AttributeName' => 'name',
            'AttributeType' => 'S' 
        ),
        array(
            'AttributeName' => 'department',
            'AttributeType' => 'S' 
        ),
        array(
            'AttributeName' => 'age',
            'AttributeType' => 'N' 
       ),
        array(
            'AttributeName' => 'gender',
            'AttributeType' => 'S' 
       ),
        array(
            'AttributeName' => 'address',
            'AttributeType' => 'S' 
     
   ),
        array(
            'AttributeName' => 'salary',
            'AttributeType' => 'N' 
      ) 
), 
'KeySchema' => array( 
      array( 
            'AttributeName' => 'eid', 
            'KeyType' => 'HASH'
           ), 
      array(
            'AttributeName' => 'name', 
            'KeyType' => 'RANGE' 
          )
 ), 
  'GlobalSecondaryIndexes' => array(
        array(
            'IndexName' => 'NameManufacturerIndex',
            'ProvisionedThroughput' => array (
                'ReadCapacityUnits' => 4,
                'WriteCapacityUnits' => 4
            ),
            'KeySchema' => array(
                array(
                    'AttributeName' => 'department',
                    'KeyType' => 'HASH'
                ),
                array(
                    'AttributeName' => 'address',
                    'KeyType' => 'RANGE'
                )
            ),
            'Projection' => array(
                'ProjectionType' => 'ALL'
            )
        )
    ),
  'ProvisionedThroughput' => array(
       'ReadCapacityUnits' => 1, 
       'WriteCapacityUnits' => 1 
        )
 ));

Querying for Global Secondary Index

Here, you have to invoke the query method on the DynamoDB client by specifying secondary index keys which you used to perform the query. In the below example, we fetch all the data where the department is Dep 1.

$tableName = 'employeeTable';

$response = $client->query(array(
    'TableName' => $tableName,
    'IndexName' => 'NameManufacturerIndex',
    'KeyConditionExpression' => '#dep = :v_dep',
    'ExpressionAttributeNames' => array (
        '#dep' => 'department'),
    'ExpressionAttributeValues' =>  array (
        ':v_dep' => array('S' => 'Dep 1')
    ),
    'Select' => 'ALL_ATTRIBUTES'
));
$tableName = 'employeeTable';

$response = $client->query(array(
    'TableName' => $tableName,
    'IndexName' => 'NameManufacturerIndex',
    'KeyConditionExpression' => '#dep = :v_dep',
    'ExpressionAttributeNames' => array (
        '#dep' => 'department'),
    'ExpressionAttributeValues' =>  array (
        ':v_dep' => array('S' => 'Dep 1')
    ),
    'Select' => 'ALL_ATTRIBUTES'
));

DynamoDB replicates the data to secondary indexes and creates a hash and range indexing on the duplicated data. All requests for this index are forwarded to the secondary index itself when we query for it.