13 DynamoDB PHP Query Examples

DynamoDB is a cloud-hosted NoSQL database from Amazon Web Services (AWS). It offers dependable performance, a fully managed environment, and easy API access to interact with it. DynamoDB is designed to handle high-scale applications with low latency and high availability.

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, we have those as well.

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>',
   'version' => 'latest'
));
use Aws\DynamoDb\DynamoDbClient;

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

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, attribute 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' => 'PAY_PER_REQUEST',
  // You need to define the throughput 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' => 'PAY_PER_REQUEST',
  // You need to define the throughput 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 the putItem method to add items to a DynamoDB table.

$response = $client->putItem(array(
    'TableName' => 'employeeTable', 
    'Item' => array(
        'eid'         => array('N'       =>  1      ), 
        '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'       =>  1      ), 
        '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's putItem method will create a new item or replace an item with the same primary key. You can also use conditions in the 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. A 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 the 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, a new attribute called jobId is added and set to 001, the salary is reduced by 2000, and the address attribute is removed from the table. Finally, the updated change will be applied to the record where the eid is 1, and the name is emp 01.

You can also use a conditional expression to update an item with a condition. For that, you need to invoke the ConditionExpression 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 ', 
    'ConditionExpression'  => '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 ', 
    'ConditionExpression'  => '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 the 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 cannot retrieve that value again. As mentioned in updating items, you can also use ConditionExpression 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) 
       ),
    'ConditionExpression'  => '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) 
       ),
    'ConditionExpression'  => '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 cannot guarantee the order of the retrieved items.

$response = $client->batchGetItem(array(
    "RequestItems" => array(
        "employeeTable" => 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(
        "employeeTable" => 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 the batchWriteItem method by defining the keys of records you need to put or delete in your DynamoDB table.

$response = $client->batchWriteItem(array(
    "RequestItems" => array(
        "employeeTable" => 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(
        "employeeTable" => 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 items 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. Let's 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' => 'DepartmentAddressIndex',
            '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' => 'DepartmentAddressIndex',
            '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' => 'DepartmentAddressIndex',
    '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' => 'DepartmentAddressIndex',
    '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.

Conclusion

DynamoDB is a powerful NoSQL database service provided by AWS, designed to handle large-scale applications with ease. By leveraging the AWS SDK for PHP, you can perform a wide range of operations on your DynamoDB tables, from creating and updating tables to querying and managing items. Understanding these operations and how to implement them in PHP can significantly enhance your ability to build robust and scalable applications. For more advanced use cases, consider exploring features like DynamoDB Streams, Transactions, and the integration with other AWS services such as Lambda and API Gateway.