SDK for PHP 3.x

Amazon DynamoDB 2011-12-05

Client: Aws\DynamoDb\DynamoDbClient
Service ID: dynamodb
Version: 2011-12-05

This page describes the parameters and results for the operations of the Amazon DynamoDB (2011-12-05), and shows how to use the Aws\DynamoDb\DynamoDbClient object to call the described operations. This documentation is specific to the 2011-12-05 API version of the service.

Operation Summary

Each of the following operations can be created from a client using $client->getCommand('CommandName'), where "CommandName" is the name of one of the following operations. Note: a command is a value that encapsulates an operation and the parameters used to create an HTTP request.

You can also create and send a command immediately using the magic methods available on a client object: $client->commandName(/* parameters */). You can send the command asynchronously (returning a promise) by appending the word "Async" to the operation name: $client->commandNameAsync(/* parameters */).

BatchGetItem ( array $params = [] )
Retrieves the attributes for multiple items from multiple tables using their primary keys.
BatchWriteItem ( array $params = [] )
Allows to execute a batch of Put and/or Delete Requests for many tables in a single call.
CreateTable ( array $params = [] )
Adds a new table to your account.
DeleteItem ( array $params = [] )
Deletes a single item in a table by primary key.
DeleteTable ( array $params = [] )
Deletes a table and all of its items.
DescribeTable ( array $params = [] )
Retrieves information about the table, including the current status of the table, the primary key schema and when the table was created.
GetItem ( array $params = [] )
Retrieves a set of Attributes for an item that matches the primary key.
ListTables ( array $params = [] )
Retrieves a paginated list of table names created by the AWS Account of the caller in the AWS Region (e.
PutItem ( array $params = [] )
Creates a new item, or replaces an old item with a new item (including all the attributes).
Query ( array $params = [] )
Gets the values of one or more items and its attributes by primary key (composite primary key, only).
Scan ( array $params = [] )
Retrieves one or more items and its attributes by performing a full scan of a table.
UpdateItem ( array $params = [] )
Edits an existing item's attributes.
UpdateTable ( array $params = [] )
Updates the provisioned throughput for the given table.

Paginators

Paginators handle automatically iterating over paginated API results. Paginators are associated with specific API operations, and they accept the parameters that the corresponding API operation accepts. You can get a paginator from a client class using getPaginator($paginatorName, $operationParameters). This client supports the following paginators:

BatchGetItem
ListTables
Query
Scan

Waiters

Waiters allow you to poll a resource until it enters into a desired state. A waiter has a name used to describe what it does, and is associated with an API operation. When creating a waiter, you can provide the API operation parameters associated with the corresponding operation. Waiters can be accessed using the getWaiter($waiterName, $operationParameters) method of a client object. This client supports the following waiters:

Waiter name API Operation Delay Max Attempts
TableExists DescribeTable 20 25
TableNotExists DescribeTable 20 25

Operations

BatchGetItem 

$result = $client->batchGetItem([/* ... */]);
$promise = $client->batchGetItemAsync([/* ... */]);

Retrieves the attributes for multiple items from multiple tables using their primary keys.

The maximum number of item attributes that can be retrieved for a single operation is 100. Also, the number of items retrieved is constrained by a 1 MB the size limit. If the response size limit is exceeded or a partial result is returned due to an internal processing failure, Amazon DynamoDB returns an UnprocessedKeys value so you can retry the operation starting with the next item to get.

Amazon DynamoDB automatically adjusts the number of items returned per page to enforce this limit. For example, even if you ask to retrieve 100 items, but each individual item is 50k in size, the system returns 20 items and an appropriate UnprocessedKeys value so you can get the next page of results. If necessary, your application needs its own logic to assemble the pages of results into one set.

Parameter Syntax

$result = $client->batchGetItem([
    'RequestItems' => [ // REQUIRED
        '<TableName>' => [
            'AttributesToGet' => ['<string>', ...],
            'ConsistentRead' => true || false,
            'Keys' => [ // REQUIRED
                [
                    'HashKeyElement' => [ // REQUIRED
                        'B' => <string || resource || Psr\Http\Message\StreamInterface>,
                        'BS' => [<string || resource || Psr\Http\Message\StreamInterface>, ...],
                        'N' => '<string>',
                        'NS' => ['<string>', ...],
                        'S' => '<string>',
                        'SS' => ['<string>', ...],
                    ],
                    'RangeKeyElement' => [
                        'B' => <string || resource || Psr\Http\Message\StreamInterface>,
                        'BS' => [<string || resource || Psr\Http\Message\StreamInterface>, ...],
                        'N' => '<string>',
                        'NS' => ['<string>', ...],
                        'S' => '<string>',
                        'SS' => ['<string>', ...],
                    ],
                ],
                // ...
            ],
        ],
        // ...
    ],
]);

Parameter Details

Members
RequestItems
Required: Yes
Type: Associative array of custom strings keys (TableName) to KeysAndAttributes structures

A map of the table name and corresponding items to get by primary key. While requesting items, each table name can be invoked only once per operation.

Result Syntax

[
    'Responses' => [
        '<TableName>' => [
            'ConsumedCapacityUnits' => <float>,
            'Items' => [
                [
                    '<AttributeName>' => [
                        'B' => <string || resource || Psr\Http\Message\StreamInterface>,
                        'BS' => [<string || resource || Psr\Http\Message\StreamInterface>, ...],
                        'N' => '<string>',
                        'NS' => ['<string>', ...],
                        'S' => '<string>',
                        'SS' => ['<string>', ...],
                    ],
                    // ...
                ],
                // ...
            ],
        ],
        // ...
    ],
    'UnprocessedKeys' => [
        '<TableName>' => [
            'AttributesToGet' => ['<string>', ...],
            'ConsistentRead' => true || false,
            'Keys' => [
                [
                    'HashKeyElement' => [
                        'B' => <string || resource || Psr\Http\Message\StreamInterface>,
                        'BS' => [<string || resource || Psr\Http\Message\StreamInterface>, ...],
                        'N' => '<string>',
                        'NS' => ['<string>', ...],
                        'S' => '<string>',
                        'SS' => ['<string>', ...],
                    ],
                    'RangeKeyElement' => [
                        'B' => <string || resource || Psr\Http\Message\StreamInterface>,
                        'BS' => [<string || resource || Psr\Http\Message\StreamInterface>, ...],
                        'N' => '<string>',
                        'NS' => ['<string>', ...],
                        'S' => '<string>',
                        'SS' => ['<string>', ...],
                    ],
                ],
                // ...
            ],
        ],
        // ...
    ],
]

Result Details

Members
Responses
Type: Associative array of custom strings keys (TableName) to BatchResponse structures

Table names and the respective item attributes from the tables.

UnprocessedKeys
Type: Associative array of custom strings keys (TableName) to KeysAndAttributes structures

Contains a map of tables and their respective keys that were not processed with the current response, possibly due to reaching a limit on the response size. The UnprocessedKeys value is in the same form as a RequestItems parameter (so the value can be provided directly to a subsequent BatchGetItem operation). For more information, see the above RequestItems parameter.

Errors

ProvisionedThroughputExceededException:

This exception is thrown when the level of provisioned throughput defined for the table is exceeded.

ResourceNotFoundException:

This exception is thrown when the resource which is being attempted to be changed is in use.

RequestLimitExceeded:

This exception is thrown when throughput exceeds the current throughput limit for the subscriber's account.

InternalServerError:

This exception is thrown when the service has a problem when trying to process the request.

BatchWriteItem 

$result = $client->batchWriteItem([/* ... */]);
$promise = $client->batchWriteItemAsync([/* ... */]);

Allows to execute a batch of Put and/or Delete Requests for many tables in a single call. A total of 25 requests are allowed.

There are no transaction guarantees provided by this API. It does not allow conditional puts nor does it support return values.

Parameter Syntax

$result = $client->batchWriteItem([
    'RequestItems' => [ // REQUIRED
        '<TableName>' => [
            [
                'DeleteRequest' => [
                    'Key' => [ // REQUIRED
                        'HashKeyElement' => [ // REQUIRED
                            'B' => <string || resource || Psr\Http\Message\StreamInterface>,
                            'BS' => [<string || resource || Psr\Http\Message\StreamInterface>, ...],
                            'N' => '<string>',
                            'NS' => ['<string>', ...],
                            'S' => '<string>',
                            'SS' => ['<string>', ...],
                        ],
                        'RangeKeyElement' => [
                            'B' => <string || resource || Psr\Http\Message\StreamInterface>,
                            'BS' => [<string || resource || Psr\Http\Message\StreamInterface>, ...],
                            'N' => '<string>',
                            'NS' => ['<string>', ...],
                            'S' => '<string>',
                            'SS' => ['<string>', ...],
                        ],
                    ],
                ],
                'PutRequest' => [
                    'Item' => [ // REQUIRED
                        '<AttributeName>' => [
                            'B' => <string || resource || Psr\Http\Message\StreamInterface>,
                            'BS' => [<string || resource || Psr\Http\Message\StreamInterface>, ...],
                            'N' => '<string>',
                            'NS' => ['<string>', ...],
                            'S' => '<string>',
                            'SS' => ['<string>', ...],
                        ],
                        // ...
                    ],
                ],
            ],
            // ...
        ],
        // ...
    ],
]);

Parameter Details

Members
RequestItems
Required: Yes
Type: Associative array of custom strings keys (TableName) to WriteRequest structuress

A map of table name to list-of-write-requests. Used as input to the BatchWriteItem API call

Result Syntax

[
    'Responses' => [
        '<TableName>' => [
            'ConsumedCapacityUnits' => <float>,
        ],
        // ...
    ],
    'UnprocessedItems' => [
        '<TableName>' => [
            [
                'DeleteRequest' => [
                    'Key' => [
                        'HashKeyElement' => [
                            'B' => <string || resource || Psr\Http\Message\StreamInterface>,
                            'BS' => [<string || resource || Psr\Http\Message\StreamInterface>, ...],
                            'N' => '<string>',
                            'NS' => ['<string>', ...],
                            'S' => '<string>',
                            'SS' => ['<string>', ...],
                        ],
                        'RangeKeyElement' => [
                            'B' => <string || resource || Psr\Http\Message\StreamInterface>,
                            'BS' => [<string || resource || Psr\Http\Message\StreamInterface>, ...],
                            'N' => '<string>',
                            'NS' => ['<string>', ...],
                            'S' => '<string>',
                            'SS' => ['<string>', ...],
                        ],
                    ],
                ],
                'PutRequest' => [
                    'Item' => [
                        '<AttributeName>' => [
                            'B' => <string || resource || Psr\Http\Message\StreamInterface>,
                            'BS' => [<string || resource || Psr\Http\Message\StreamInterface>, ...],
                            'N' => '<string>',
                            'NS' => ['<string>', ...],
                            'S' => '<string>',
                            'SS' => ['<string>', ...],
                        ],
                        // ...
                    ],
                ],
            ],
            // ...
        ],
        // ...
    ],
]

Result Details

Members
Responses
Type: Associative array of custom strings keys (TableName) to BatchWriteResponse structures

The response object as a result of BatchWriteItem call. This is essentially a map of table name to ConsumedCapacityUnits.

UnprocessedItems
Type: Associative array of custom strings keys (TableName) to WriteRequest structuress

The Items which we could not successfully process in a BatchWriteItem call is returned as UnprocessedItems

Errors

ProvisionedThroughputExceededException:

This exception is thrown when the level of provisioned throughput defined for the table is exceeded.

ResourceNotFoundException:

This exception is thrown when the resource which is being attempted to be changed is in use.

LimitExceededException:

This exception is thrown when the subscriber exceeded the limits on the number of objects or operations.

RequestLimitExceeded:

This exception is thrown when throughput exceeds the current throughput limit for the subscriber's account.

InternalServerError:

This exception is thrown when the service has a problem when trying to process the request.

CreateTable 

$result = $client->createTable([/* ... */]);
$promise = $client->createTableAsync([/* ... */]);

Adds a new table to your account.

The table name must be unique among those associated with the AWS Account issuing the request, and the AWS Region that receives the request (e.g. us-east-1).

The CreateTable operation triggers an asynchronous workflow to begin creating the table. Amazon DynamoDB immediately returns the state of the table (CREATING) until the table is in the ACTIVE state. Once the table is in the ACTIVE state, you can perform data plane operations.

Parameter Syntax

$result = $client->createTable([
    'KeySchema' => [ // REQUIRED
        'HashKeyElement' => [ // REQUIRED
            'AttributeName' => '<string>', // REQUIRED
            'AttributeType' => 'S|N|B', // REQUIRED
        ],
        'RangeKeyElement' => [
            'AttributeName' => '<string>', // REQUIRED
            'AttributeType' => 'S|N|B', // REQUIRED
        ],
    ],
    'ProvisionedThroughput' => [ // REQUIRED
        'ReadCapacityUnits' => <integer>, // REQUIRED
        'WriteCapacityUnits' => <integer>, // REQUIRED
    ],
    'TableName' => '<string>', // REQUIRED
]);

Parameter Details

Members
KeySchema
Required: Yes
Type: KeySchema structure

The KeySchema identifies the primary key as a one attribute primary key (hash) or a composite two attribute (hash-and-range) primary key. Single attribute primary keys have one index value: a HashKeyElement. A composite hash-and-range primary key contains two attribute values: a HashKeyElement and a RangeKeyElement.

ProvisionedThroughput
Required: Yes
Type: ProvisionedThroughput structure

Provisioned throughput reserves the required read and write resources for your table in terms of ReadCapacityUnits and WriteCapacityUnits. Values for provisioned throughput depend upon your expected read/write rates, item size, and consistency. Provide the expected number of read and write operations, assuming an item size of 1k and strictly consistent reads. For 2k item size, double the value. For 3k, triple the value, etc. Eventually-consistent reads consume half the resources of strictly consistent reads.

TableName
Required: Yes
Type: string

The name of the table you want to create. Allowed characters are a-z, A-Z, 0-9, _ (underscore), - (hyphen) and . (period).

Result Syntax

[
    'TableDescription' => [
        'CreationDateTime' => <DateTime>,
        'ItemCount' => <integer>,
        'KeySchema' => [
            'HashKeyElement' => [
                'AttributeName' => '<string>',
                'AttributeType' => 'S|N|B',
            ],
            'RangeKeyElement' => [
                'AttributeName' => '<string>',
                'AttributeType' => 'S|N|B',
            ],
        ],
        'ProvisionedThroughput' => [
            'LastDecreaseDateTime' => <DateTime>,
            'LastIncreaseDateTime' => <DateTime>,
            'NumberOfDecreasesToday' => <integer>,
            'ReadCapacityUnits' => <integer>,
            'WriteCapacityUnits' => <integer>,
        ],
        'TableName' => '<string>',
        'TableSizeBytes' => <integer>,
        'TableStatus' => 'CREATING|UPDATING|DELETING|ACTIVE',
    ],
]

Result Details

Members
TableDescription
Type: TableDescription structure

Errors

ResourceInUseException:

This exception is thrown when the resource which is being attempted to be changed is in use.

LimitExceededException:

This exception is thrown when the subscriber exceeded the limits on the number of objects or operations.

InternalServerError:

This exception is thrown when the service has a problem when trying to process the request.

DeleteItem 

$result = $client->deleteItem([/* ... */]);
$promise = $client->deleteItemAsync([/* ... */]);

Deletes a single item in a table by primary key.

You can perform a conditional delete operation that deletes the item if it exists, or if it has an expected attribute value.

Parameter Syntax

$result = $client->deleteItem([
    'Expected' => [
        '<AttributeName>' => [
            'Exists' => true || false,
            'Value' => [
                'B' => <string || resource || Psr\Http\Message\StreamInterface>,
                'BS' => [<string || resource || Psr\Http\Message\StreamInterface>, ...],
                'N' => '<string>',
                'NS' => ['<string>', ...],
                'S' => '<string>',
                'SS' => ['<string>', ...],
            ],
        ],
        // ...
    ],
    'Key' => [ // REQUIRED
        'HashKeyElement' => [ // REQUIRED
            'B' => <string || resource || Psr\Http\Message\StreamInterface>,
            'BS' => [<string || resource || Psr\Http\Message\StreamInterface>, ...],
            'N' => '<string>',
            'NS' => ['<string>', ...],
            'S' => '<string>',
            'SS' => ['<string>', ...],
        ],
        'RangeKeyElement' => [
            'B' => <string || resource || Psr\Http\Message\StreamInterface>,
            'BS' => [<string || resource || Psr\Http\Message\StreamInterface>, ...],
            'N' => '<string>',
            'NS' => ['<string>', ...],
            'S' => '<string>',
            'SS' => ['<string>', ...],
        ],
    ],
    'ReturnValues' => 'NONE|ALL_OLD|UPDATED_OLD|ALL_NEW|UPDATED_NEW',
    'TableName' => '<string>', // REQUIRED
]);

Parameter Details

Members
Expected
Type: Associative array of custom strings keys (AttributeName) to ExpectedAttributeValue structures

Designates an attribute for a conditional modification. The Expected parameter allows you to provide an attribute name, and whether or not Amazon DynamoDB should check to see if the attribute has a particular value before modifying it.

Key
Required: Yes
Type: Key structure

The primary key that uniquely identifies each item in a table. A primary key can be a one attribute (hash) primary key or a two attribute (hash-and-range) primary key.

ReturnValues
Type: string

Use this parameter if you want to get the attribute name-value pairs before or after they are modified. For PUT operations, the possible parameter values are NONE (default) or ALL_OLD. For update operations, the possible parameter values are NONE (default) or ALL_OLD, UPDATED_OLD, ALL_NEW or UPDATED_NEW.

  • NONE: Nothing is returned.
  • ALL_OLD: Returns the attributes of the item as they were before the operation.
  • UPDATED_OLD: Returns the values of the updated attributes, only, as they were before the operation.
  • ALL_NEW: Returns all the attributes and their new values after the operation.
  • UPDATED_NEW: Returns the values of the updated attributes, only, as they are after the operation.
TableName
Required: Yes
Type: string

The name of the table in which you want to delete an item. Allowed characters are a-z, A-Z, 0-9, _ (underscore), - (hyphen) and . (period).

Result Syntax

[
    'Attributes' => [
        '<AttributeName>' => [
            'B' => <string || resource || Psr\Http\Message\StreamInterface>,
            'BS' => [<string || resource || Psr\Http\Message\StreamInterface>, ...],
            'N' => '<string>',
            'NS' => ['<string>', ...],
            'S' => '<string>',
            'SS' => ['<string>', ...],
        ],
        // ...
    ],
    'ConsumedCapacityUnits' => <float>,
]

Result Details

Members
Attributes
Type: Associative array of custom strings keys (AttributeName) to AttributeValue structures

If the ReturnValues parameter is provided as ALL_OLD in the request, Amazon DynamoDB returns an array of attribute name-value pairs (essentially, the deleted item). Otherwise, the response contains an empty set.

ConsumedCapacityUnits
Type: double

The number of Capacity Units of the provisioned throughput of the table consumed during the operation. GetItem, BatchGetItem, BatchWriteItem, Query, and Scan operations consume ReadCapacityUnits, while PutItem, UpdateItem, and DeleteItem operations consume WriteCapacityUnits.

Errors

ConditionalCheckFailedException:

This exception is thrown when an expected value does not match what was found in the system.

ProvisionedThroughputExceededException:

This exception is thrown when the level of provisioned throughput defined for the table is exceeded.

ResourceNotFoundException:

This exception is thrown when the resource which is being attempted to be changed is in use.

LimitExceededException:

This exception is thrown when the subscriber exceeded the limits on the number of objects or operations.

RequestLimitExceeded:

This exception is thrown when throughput exceeds the current throughput limit for the subscriber's account.

InternalServerError:

This exception is thrown when the service has a problem when trying to process the request.

DeleteTable 

$result = $client->deleteTable([/* ... */]);
$promise = $client->deleteTableAsync([/* ... */]);

Deletes a table and all of its items.

If the table is in the ACTIVE state, you can delete it. If a table is in CREATING or UPDATING states then Amazon DynamoDB returns a ResourceInUseException. If the specified table does not exist, Amazon DynamoDB returns a ResourceNotFoundException.

Parameter Syntax

$result = $client->deleteTable([
    'TableName' => '<string>', // REQUIRED
]);

Parameter Details

Members
TableName
Required: Yes
Type: string

The name of the table you want to delete. Allowed characters are a-z, A-Z, 0-9, _ (underscore), - (hyphen) and . (period).

Result Syntax

[
    'TableDescription' => [
        'CreationDateTime' => <DateTime>,
        'ItemCount' => <integer>,
        'KeySchema' => [
            'HashKeyElement' => [
                'AttributeName' => '<string>',
                'AttributeType' => 'S|N|B',
            ],
            'RangeKeyElement' => [
                'AttributeName' => '<string>',
                'AttributeType' => 'S|N|B',
            ],
        ],
        'ProvisionedThroughput' => [
            'LastDecreaseDateTime' => <DateTime>,
            'LastIncreaseDateTime' => <DateTime>,
            'NumberOfDecreasesToday' => <integer>,
            'ReadCapacityUnits' => <integer>,
            'WriteCapacityUnits' => <integer>,
        ],
        'TableName' => '<string>',
        'TableSizeBytes' => <integer>,
        'TableStatus' => 'CREATING|UPDATING|DELETING|ACTIVE',
    ],
]

Result Details

Members
TableDescription
Type: TableDescription structure

Errors

ResourceInUseException:

This exception is thrown when the resource which is being attempted to be changed is in use.

ResourceNotFoundException:

This exception is thrown when the resource which is being attempted to be changed is in use.

LimitExceededException:

This exception is thrown when the subscriber exceeded the limits on the number of objects or operations.

InternalServerError:

This exception is thrown when the service has a problem when trying to process the request.

DescribeTable 

$result = $client->describeTable([/* ... */]);
$promise = $client->describeTableAsync([/* ... */]);

Retrieves information about the table, including the current status of the table, the primary key schema and when the table was created.

If the table does not exist, Amazon DynamoDB returns a ResourceNotFoundException.

Parameter Syntax

$result = $client->describeTable([
    'TableName' => '<string>', // REQUIRED
]);

Parameter Details

Members
TableName
Required: Yes
Type: string

The name of the table you want to describe. Allowed characters are a-z, A-Z, 0-9, _ (underscore), - (hyphen) and . (period).

Result Syntax

[
    'Table' => [
        'CreationDateTime' => <DateTime>,
        'ItemCount' => <integer>,
        'KeySchema' => [
            'HashKeyElement' => [
                'AttributeName' => '<string>',
                'AttributeType' => 'S|N|B',
            ],
            'RangeKeyElement' => [
                'AttributeName' => '<string>',
                'AttributeType' => 'S|N|B',
            ],
        ],
        'ProvisionedThroughput' => [
            'LastDecreaseDateTime' => <DateTime>,
            'LastIncreaseDateTime' => <DateTime>,
            'NumberOfDecreasesToday' => <integer>,
            'ReadCapacityUnits' => <integer>,
            'WriteCapacityUnits' => <integer>,
        ],
        'TableName' => '<string>',
        'TableSizeBytes' => <integer>,
        'TableStatus' => 'CREATING|UPDATING|DELETING|ACTIVE',
    ],
]

Result Details

Members
Table
Type: TableDescription structure

Errors

ResourceNotFoundException:

This exception is thrown when the resource which is being attempted to be changed is in use.

InternalServerError:

This exception is thrown when the service has a problem when trying to process the request.

GetItem 

$result = $client->getItem([/* ... */]);
$promise = $client->getItemAsync([/* ... */]);

Retrieves a set of Attributes for an item that matches the primary key.

The GetItem operation provides an eventually-consistent read by default. If eventually-consistent reads are not acceptable for your application, use ConsistentRead. Although this operation might take longer than a standard read, it always returns the last updated value.

Parameter Syntax

$result = $client->getItem([
    'AttributesToGet' => ['<string>', ...],
    'ConsistentRead' => true || false,
    'Key' => [ // REQUIRED
        'HashKeyElement' => [ // REQUIRED
            'B' => <string || resource || Psr\Http\Message\StreamInterface>,
            'BS' => [<string || resource || Psr\Http\Message\StreamInterface>, ...],
            'N' => '<string>',
            'NS' => ['<string>', ...],
            'S' => '<string>',
            'SS' => ['<string>', ...],
        ],
        'RangeKeyElement' => [
            'B' => <string || resource || Psr\Http\Message\StreamInterface>,
            'BS' => [<string || resource || Psr\Http\Message\StreamInterface>, ...],
            'N' => '<string>',
            'NS' => ['<string>', ...],
            'S' => '<string>',
            'SS' => ['<string>', ...],
        ],
    ],
    'TableName' => '<string>', // REQUIRED
]);

Parameter Details

Members
AttributesToGet
Type: Array of strings

List of Attribute names. If attribute names are not specified then all attributes will be returned. If some attributes are not found, they will not appear in the result.

ConsistentRead
Type: boolean

If set to true, then a consistent read is issued. Otherwise eventually-consistent is used.

Key
Required: Yes
Type: Key structure

The primary key that uniquely identifies each item in a table. A primary key can be a one attribute (hash) primary key or a two attribute (hash-and-range) primary key.

TableName
Required: Yes
Type: string

The name of the table in which you want to get an item. Allowed characters are a-z, A-Z, 0-9, _ (underscore), - (hyphen) and . (period).

Result Syntax

[
    'ConsumedCapacityUnits' => <float>,
    'Item' => [
        '<AttributeName>' => [
            'B' => <string || resource || Psr\Http\Message\StreamInterface>,
            'BS' => [<string || resource || Psr\Http\Message\StreamInterface>, ...],
            'N' => '<string>',
            'NS' => ['<string>', ...],
            'S' => '<string>',
            'SS' => ['<string>', ...],
        ],
        // ...
    ],
]

Result Details

Members
ConsumedCapacityUnits
Type: double

The number of Capacity Units of the provisioned throughput of the table consumed during the operation. GetItem, BatchGetItem, BatchWriteItem, Query, and Scan operations consume ReadCapacityUnits, while PutItem, UpdateItem, and DeleteItem operations consume WriteCapacityUnits.

Item
Type: Associative array of custom strings keys (AttributeName) to AttributeValue structures

Contains the requested attributes.

Errors

ProvisionedThroughputExceededException:

This exception is thrown when the level of provisioned throughput defined for the table is exceeded.

ResourceNotFoundException:

This exception is thrown when the resource which is being attempted to be changed is in use.

RequestLimitExceeded:

This exception is thrown when throughput exceeds the current throughput limit for the subscriber's account.

InternalServerError:

This exception is thrown when the service has a problem when trying to process the request.

ListTables 

$result = $client->listTables([/* ... */]);
$promise = $client->listTablesAsync([/* ... */]);

Retrieves a paginated list of table names created by the AWS Account of the caller in the AWS Region (e.g. us-east-1).

Parameter Syntax

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

Parameter Details

Members
ExclusiveStartTableName
Type: string

The name of the table that starts the list. If you already ran a ListTables operation and received a LastEvaluatedTableName value in the response, use that value here to continue the list.

Limit
Type: int

A number of maximum table names to return.

Result Syntax

[
    'LastEvaluatedTableName' => '<string>',
    'TableNames' => ['<string>', ...],
]

Result Details

Members
LastEvaluatedTableName
Type: string

The name of the last table in the current list. Use this value as the ExclusiveStartTableName in a new request to continue the list until all the table names are returned. If this value is null, all table names have been returned.

TableNames
Type: Array of strings

Errors

InternalServerError:

This exception is thrown when the service has a problem when trying to process the request.

PutItem 

$result = $client->putItem([/* ... */]);
$promise = $client->putItemAsync([/* ... */]);

Creates a new item, or replaces an old item with a new item (including all the attributes).

If an item already exists in the specified table with the same primary key, the new item completely replaces the existing item. You can perform a conditional put (insert a new item if one with the specified primary key doesn't exist), or replace an existing item if it has certain attribute values.

Parameter Syntax

$result = $client->putItem([
    'Expected' => [
        '<AttributeName>' => [
            'Exists' => true || false,
            'Value' => [
                'B' => <string || resource || Psr\Http\Message\StreamInterface>,
                'BS' => [<string || resource || Psr\Http\Message\StreamInterface>, ...],
                'N' => '<string>',
                'NS' => ['<string>', ...],
                'S' => '<string>',
                'SS' => ['<string>', ...],
            ],
        ],
        // ...
    ],
    'Item' => [ // REQUIRED
        '<AttributeName>' => [
            'B' => <string || resource || Psr\Http\Message\StreamInterface>,
            'BS' => [<string || resource || Psr\Http\Message\StreamInterface>, ...],
            'N' => '<string>',
            'NS' => ['<string>', ...],
            'S' => '<string>',
            'SS' => ['<string>', ...],
        ],
        // ...
    ],
    'ReturnValues' => 'NONE|ALL_OLD|UPDATED_OLD|ALL_NEW|UPDATED_NEW',
    'TableName' => '<string>', // REQUIRED
]);

Parameter Details

Members
Expected
Type: Associative array of custom strings keys (AttributeName) to ExpectedAttributeValue structures

Designates an attribute for a conditional modification. The Expected parameter allows you to provide an attribute name, and whether or not Amazon DynamoDB should check to see if the attribute has a particular value before modifying it.

Item
Required: Yes
Type: Associative array of custom strings keys (AttributeName) to AttributeValue structures

A map of the attributes for the item, and must include the primary key values that define the item. Other attribute name-value pairs can be provided for the item.

ReturnValues
Type: string

Use this parameter if you want to get the attribute name-value pairs before or after they are modified. For PUT operations, the possible parameter values are NONE (default) or ALL_OLD. For update operations, the possible parameter values are NONE (default) or ALL_OLD, UPDATED_OLD, ALL_NEW or UPDATED_NEW.

  • NONE: Nothing is returned.
  • ALL_OLD: Returns the attributes of the item as they were before the operation.
  • UPDATED_OLD: Returns the values of the updated attributes, only, as they were before the operation.
  • ALL_NEW: Returns all the attributes and their new values after the operation.
  • UPDATED_NEW: Returns the values of the updated attributes, only, as they are after the operation.
TableName
Required: Yes
Type: string

The name of the table in which you want to put an item. Allowed characters are a-z, A-Z, 0-9, _ (underscore), - (hyphen) and . (period).

Result Syntax

[
    'Attributes' => [
        '<AttributeName>' => [
            'B' => <string || resource || Psr\Http\Message\StreamInterface>,
            'BS' => [<string || resource || Psr\Http\Message\StreamInterface>, ...],
            'N' => '<string>',
            'NS' => ['<string>', ...],
            'S' => '<string>',
            'SS' => ['<string>', ...],
        ],
        // ...
    ],
    'ConsumedCapacityUnits' => <float>,
]

Result Details

Members
Attributes
Type: Associative array of custom strings keys (AttributeName) to AttributeValue structures

Attribute values before the put operation, but only if the ReturnValues parameter is specified as ALL_OLD in the request.

ConsumedCapacityUnits
Type: double

The number of Capacity Units of the provisioned throughput of the table consumed during the operation. GetItem, BatchGetItem, BatchWriteItem, Query, and Scan operations consume ReadCapacityUnits, while PutItem, UpdateItem, and DeleteItem operations consume WriteCapacityUnits.

Errors

ConditionalCheckFailedException:

This exception is thrown when an expected value does not match what was found in the system.

ProvisionedThroughputExceededException:

This exception is thrown when the level of provisioned throughput defined for the table is exceeded.

ResourceNotFoundException:

This exception is thrown when the resource which is being attempted to be changed is in use.

LimitExceededException:

This exception is thrown when the subscriber exceeded the limits on the number of objects or operations.

RequestLimitExceeded:

This exception is thrown when throughput exceeds the current throughput limit for the subscriber's account.

InternalServerError:

This exception is thrown when the service has a problem when trying to process the request.

Query 

$result = $client->query([/* ... */]);
$promise = $client->queryAsync([/* ... */]);

Gets the values of one or more items and its attributes by primary key (composite primary key, only).

Narrow the scope of the query using comparison operators on the RangeKeyValue of the composite key. Use the ScanIndexForward parameter to get results in forward or reverse order by range key.

Parameter Syntax

$result = $client->query([
    'AttributesToGet' => ['<string>', ...],
    'ConsistentRead' => true || false,
    'Count' => true || false,
    'ExclusiveStartKey' => [
        'HashKeyElement' => [ // REQUIRED
            'B' => <string || resource || Psr\Http\Message\StreamInterface>,
            'BS' => [<string || resource || Psr\Http\Message\StreamInterface>, ...],
            'N' => '<string>',
            'NS' => ['<string>', ...],
            'S' => '<string>',
            'SS' => ['<string>', ...],
        ],
        'RangeKeyElement' => [
            'B' => <string || resource || Psr\Http\Message\StreamInterface>,
            'BS' => [<string || resource || Psr\Http\Message\StreamInterface>, ...],
            'N' => '<string>',
            'NS' => ['<string>', ...],
            'S' => '<string>',
            'SS' => ['<string>', ...],
        ],
    ],
    'HashKeyValue' => [ // REQUIRED
        'B' => <string || resource || Psr\Http\Message\StreamInterface>,
        'BS' => [<string || resource || Psr\Http\Message\StreamInterface>, ...],
        'N' => '<string>',
        'NS' => ['<string>', ...],
        'S' => '<string>',
        'SS' => ['<string>', ...],
    ],
    'Limit' => <integer>,
    'RangeKeyCondition' => [
        'AttributeValueList' => [
            [
                'B' => <string || resource || Psr\Http\Message\StreamInterface>,
                'BS' => [<string || resource || Psr\Http\Message\StreamInterface>, ...],
                'N' => '<string>',
                'NS' => ['<string>', ...],
                'S' => '<string>',
                'SS' => ['<string>', ...],
            ],
            // ...
        ],
        'ComparisonOperator' => 'EQ|NE|IN|LE|LT|GE|GT|BETWEEN|NOT_NULL|NULL|CONTAINS|NOT_CONTAINS|BEGINS_WITH', // REQUIRED
    ],
    'ScanIndexForward' => true || false,
    'TableName' => '<string>', // REQUIRED
]);

Parameter Details

Members
AttributesToGet
Type: Array of strings

List of Attribute names. If attribute names are not specified then all attributes will be returned. If some attributes are not found, they will not appear in the result.

ConsistentRead
Type: boolean

If set to true, then a consistent read is issued. Otherwise eventually-consistent is used.

Count
Type: boolean

If set to true, Amazon DynamoDB returns a total number of items that match the query parameters, instead of a list of the matching items and their attributes. Do not set Count to true while providing a list of AttributesToGet, otherwise Amazon DynamoDB returns a validation error.

ExclusiveStartKey
Type: Key structure

Primary key of the item from which to continue an earlier query. An earlier query might provide this value as the LastEvaluatedKey if that query operation was interrupted before completing the query; either because of the result set size or the Limit parameter. The LastEvaluatedKey can be passed back in a new query request to continue the operation from that point.

HashKeyValue
Required: Yes
Type: AttributeValue structure

Attribute value of the hash component of the composite primary key.

Limit
Type: int

The maximum number of items to return. If Amazon DynamoDB hits this limit while querying the table, it stops the query and returns the matching values up to the limit, and a LastEvaluatedKey to apply in a subsequent operation to continue the query. Also, if the result set size exceeds 1MB before Amazon DynamoDB hits this limit, it stops the query and returns the matching values, and a LastEvaluatedKey to apply in a subsequent operation to continue the query.

RangeKeyCondition
Type: Condition structure

A container for the attribute values and comparison operators to use for the query.

ScanIndexForward
Type: boolean

Specifies forward or backward traversal of the index. Amazon DynamoDB returns results reflecting the requested order, determined by the range key. The default value is true (forward).

TableName
Required: Yes
Type: string

The name of the table in which you want to query. Allowed characters are a-z, A-Z, 0-9, _ (underscore), - (hyphen) and . (period).

Result Syntax

[
    'ConsumedCapacityUnits' => <float>,
    'Count' => <integer>,
    'Items' => [
        [
            '<AttributeName>' => [
                'B' => <string || resource || Psr\Http\Message\StreamInterface>,
                'BS' => [<string || resource || Psr\Http\Message\StreamInterface>, ...],
                'N' => '<string>',
                'NS' => ['<string>', ...],
                'S' => '<string>',
                'SS' => ['<string>', ...],
            ],
            // ...
        ],
        // ...
    ],
    'LastEvaluatedKey' => [
        'HashKeyElement' => [
            'B' => <string || resource || Psr\Http\Message\StreamInterface>,
            'BS' => [<string || resource || Psr\Http\Message\StreamInterface>, ...],
            'N' => '<string>',
            'NS' => ['<string>', ...],
            'S' => '<string>',
            'SS' => ['<string>', ...],
        ],
        'RangeKeyElement' => [
            'B' => <string || resource || Psr\Http\Message\StreamInterface>,
            'BS' => [<string || resource || Psr\Http\Message\StreamInterface>, ...],
            'N' => '<string>',
            'NS' => ['<string>', ...],
            'S' => '<string>',
            'SS' => ['<string>', ...],
        ],
    ],
]

Result Details

Members
ConsumedCapacityUnits
Type: double

The number of Capacity Units of the provisioned throughput of the table consumed during the operation. GetItem, BatchGetItem, BatchWriteItem, Query, and Scan operations consume ReadCapacityUnits, while PutItem, UpdateItem, and DeleteItem operations consume WriteCapacityUnits.

Count
Type: int

Number of items in the response.

Items
Type: Array of AttributeValue structuress
LastEvaluatedKey
Type: Key structure

Primary key of the item where the query operation stopped, inclusive of the previous result set. Use this value to start a new operation excluding this value in the new request. The LastEvaluatedKey is null when the entire query result set is complete (i.e. the operation processed the "last page").

Errors

ProvisionedThroughputExceededException:

This exception is thrown when the level of provisioned throughput defined for the table is exceeded.

ResourceNotFoundException:

This exception is thrown when the resource which is being attempted to be changed is in use.

RequestLimitExceeded:

This exception is thrown when throughput exceeds the current throughput limit for the subscriber's account.

InternalServerError:

This exception is thrown when the service has a problem when trying to process the request.

Scan 

$result = $client->scan([/* ... */]);
$promise = $client->scanAsync([/* ... */]);

Retrieves one or more items and its attributes by performing a full scan of a table.

Provide a ScanFilter to get more specific results.

Parameter Syntax

$result = $client->scan([
    'AttributesToGet' => ['<string>', ...],
    'Count' => true || false,
    'ExclusiveStartKey' => [
        'HashKeyElement' => [ // REQUIRED
            'B' => <string || resource || Psr\Http\Message\StreamInterface>,
            'BS' => [<string || resource || Psr\Http\Message\StreamInterface>, ...],
            'N' => '<string>',
            'NS' => ['<string>', ...],
            'S' => '<string>',
            'SS' => ['<string>', ...],
        ],
        'RangeKeyElement' => [
            'B' => <string || resource || Psr\Http\Message\StreamInterface>,
            'BS' => [<string || resource || Psr\Http\Message\StreamInterface>, ...],
            'N' => '<string>',
            'NS' => ['<string>', ...],
            'S' => '<string>',
            'SS' => ['<string>', ...],
        ],
    ],
    'Limit' => <integer>,
    'ScanFilter' => [
        '<String>' => [
            'AttributeValueList' => [
                [
                    'B' => <string || resource || Psr\Http\Message\StreamInterface>,
                    'BS' => [<string || resource || Psr\Http\Message\StreamInterface>, ...],
                    'N' => '<string>',
                    'NS' => ['<string>', ...],
                    'S' => '<string>',
                    'SS' => ['<string>', ...],
                ],
                // ...
            ],
            'ComparisonOperator' => 'EQ|NE|IN|LE|LT|GE|GT|BETWEEN|NOT_NULL|NULL|CONTAINS|NOT_CONTAINS|BEGINS_WITH', // REQUIRED
        ],
        // ...
    ],
    'TableName' => '<string>', // REQUIRED
]);

Parameter Details

Members
AttributesToGet
Type: Array of strings

List of Attribute names. If attribute names are not specified then all attributes will be returned. If some attributes are not found, they will not appear in the result.

Count
Type: boolean

If set to true, Amazon DynamoDB returns a total number of items for the Scan operation, even if the operation has no matching items for the assigned filter. Do not set Count to true while providing a list of AttributesToGet, otherwise Amazon DynamoDB returns a validation error.

ExclusiveStartKey
Type: Key structure

Primary key of the item from which to continue an earlier scan. An earlier scan might provide this value if that scan operation was interrupted before scanning the entire table; either because of the result set size or the Limit parameter. The LastEvaluatedKey can be passed back in a new scan request to continue the operation from that point.

Limit
Type: int

The maximum number of items to return. If Amazon DynamoDB hits this limit while scanning the table, it stops the scan and returns the matching values up to the limit, and a LastEvaluatedKey to apply in a subsequent operation to continue the scan. Also, if the scanned data set size exceeds 1 MB before Amazon DynamoDB hits this limit, it stops the scan and returns the matching values up to the limit, and a LastEvaluatedKey to apply in a subsequent operation to continue the scan.

ScanFilter
Type: Associative array of custom strings keys (String) to Condition structures

Evaluates the scan results and returns only the desired values.

TableName
Required: Yes
Type: string

The name of the table in which you want to scan. Allowed characters are a-z, A-Z, 0-9, _ (underscore), - (hyphen) and . (period).

Result Syntax

[
    'ConsumedCapacityUnits' => <float>,
    'Count' => <integer>,
    'Items' => [
        [
            '<AttributeName>' => [
                'B' => <string || resource || Psr\Http\Message\StreamInterface>,
                'BS' => [<string || resource || Psr\Http\Message\StreamInterface>, ...],
                'N' => '<string>',
                'NS' => ['<string>', ...],
                'S' => '<string>',
                'SS' => ['<string>', ...],
            ],
            // ...
        ],
        // ...
    ],
    'LastEvaluatedKey' => [
        'HashKeyElement' => [
            'B' => <string || resource || Psr\Http\Message\StreamInterface>,
            'BS' => [<string || resource || Psr\Http\Message\StreamInterface>, ...],
            'N' => '<string>',
            'NS' => ['<string>', ...],
            'S' => '<string>',
            'SS' => ['<string>', ...],
        ],
        'RangeKeyElement' => [
            'B' => <string || resource || Psr\Http\Message\StreamInterface>,
            'BS' => [<string || resource || Psr\Http\Message\StreamInterface>, ...],
            'N' => '<string>',
            'NS' => ['<string>', ...],
            'S' => '<string>',
            'SS' => ['<string>', ...],
        ],
    ],
    'ScannedCount' => <integer>,
]

Result Details

Members
ConsumedCapacityUnits
Type: double

The number of Capacity Units of the provisioned throughput of the table consumed during the operation. GetItem, BatchGetItem, BatchWriteItem, Query, and Scan operations consume ReadCapacityUnits, while PutItem, UpdateItem, and DeleteItem operations consume WriteCapacityUnits.

Count
Type: int

Number of items in the response.

Items
Type: Array of AttributeValue structuress
LastEvaluatedKey
Type: Key structure

Primary key of the item where the scan operation stopped. Provide this value in a subsequent scan operation to continue the operation from that point. The LastEvaluatedKey is null when the entire scan result set is complete (i.e. the operation processed the "last page").

ScannedCount
Type: int

Number of items in the complete scan before any filters are applied. A high ScannedCount value with few, or no, Count results indicates an inefficient Scan operation.

Errors

ProvisionedThroughputExceededException:

This exception is thrown when the level of provisioned throughput defined for the table is exceeded.

ResourceNotFoundException:

This exception is thrown when the resource which is being attempted to be changed is in use.

RequestLimitExceeded:

This exception is thrown when throughput exceeds the current throughput limit for the subscriber's account.

InternalServerError:

This exception is thrown when the service has a problem when trying to process the request.

UpdateItem 

$result = $client->updateItem([/* ... */]);
$promise = $client->updateItemAsync([/* ... */]);

Edits an existing item's attributes.

You can perform a conditional update (insert a new attribute name-value pair if it doesn't exist, or replace an existing name-value pair if it has certain expected attribute values).

Parameter Syntax

$result = $client->updateItem([
    'AttributeUpdates' => [ // REQUIRED
        '<AttributeName>' => [
            'Action' => 'ADD|PUT|DELETE',
            'Value' => [
                'B' => <string || resource || Psr\Http\Message\StreamInterface>,
                'BS' => [<string || resource || Psr\Http\Message\StreamInterface>, ...],
                'N' => '<string>',
                'NS' => ['<string>', ...],
                'S' => '<string>',
                'SS' => ['<string>', ...],
            ],
        ],
        // ...
    ],
    'Expected' => [
        '<AttributeName>' => [
            'Exists' => true || false,
            'Value' => [
                'B' => <string || resource || Psr\Http\Message\StreamInterface>,
                'BS' => [<string || resource || Psr\Http\Message\StreamInterface>, ...],
                'N' => '<string>',
                'NS' => ['<string>', ...],
                'S' => '<string>',
                'SS' => ['<string>', ...],
            ],
        ],
        // ...
    ],
    'Key' => [ // REQUIRED
        'HashKeyElement' => [ // REQUIRED
            'B' => <string || resource || Psr\Http\Message\StreamInterface>,
            'BS' => [<string || resource || Psr\Http\Message\StreamInterface>, ...],
            'N' => '<string>',
            'NS' => ['<string>', ...],
            'S' => '<string>',
            'SS' => ['<string>', ...],
        ],
        'RangeKeyElement' => [
            'B' => <string || resource || Psr\Http\Message\StreamInterface>,
            'BS' => [<string || resource || Psr\Http\Message\StreamInterface>, ...],
            'N' => '<string>',
            'NS' => ['<string>', ...],
            'S' => '<string>',
            'SS' => ['<string>', ...],
        ],
    ],
    'ReturnValues' => 'NONE|ALL_OLD|UPDATED_OLD|ALL_NEW|UPDATED_NEW',
    'TableName' => '<string>', // REQUIRED
]);

Parameter Details

Members
AttributeUpdates
Required: Yes
Type: Associative array of custom strings keys (AttributeName) to AttributeValueUpdate structures

Map of attribute name to the new value and action for the update. The attribute names specify the attributes to modify, and cannot contain any primary key attributes.

Expected
Type: Associative array of custom strings keys (AttributeName) to ExpectedAttributeValue structures

Designates an attribute for a conditional modification. The Expected parameter allows you to provide an attribute name, and whether or not Amazon DynamoDB should check to see if the attribute has a particular value before modifying it.

Key
Required: Yes
Type: Key structure

The primary key that uniquely identifies each item in a table. A primary key can be a one attribute (hash) primary key or a two attribute (hash-and-range) primary key.

ReturnValues
Type: string

Use this parameter if you want to get the attribute name-value pairs before or after they are modified. For PUT operations, the possible parameter values are NONE (default) or ALL_OLD. For update operations, the possible parameter values are NONE (default) or ALL_OLD, UPDATED_OLD, ALL_NEW or UPDATED_NEW.

  • NONE: Nothing is returned.
  • ALL_OLD: Returns the attributes of the item as they were before the operation.
  • UPDATED_OLD: Returns the values of the updated attributes, only, as they were before the operation.
  • ALL_NEW: Returns all the attributes and their new values after the operation.
  • UPDATED_NEW: Returns the values of the updated attributes, only, as they are after the operation.
TableName
Required: Yes
Type: string

The name of the table in which you want to update an item. Allowed characters are a-z, A-Z, 0-9, _ (underscore), - (hyphen) and . (period).

Result Syntax

[
    'Attributes' => [
        '<AttributeName>' => [
            'B' => <string || resource || Psr\Http\Message\StreamInterface>,
            'BS' => [<string || resource || Psr\Http\Message\StreamInterface>, ...],
            'N' => '<string>',
            'NS' => ['<string>', ...],
            'S' => '<string>',
            'SS' => ['<string>', ...],
        ],
        // ...
    ],
    'ConsumedCapacityUnits' => <float>,
]

Result Details

Members
Attributes
Type: Associative array of custom strings keys (AttributeName) to AttributeValue structures

A map of attribute name-value pairs, but only if the ReturnValues parameter is specified as something other than NONE in the request.

ConsumedCapacityUnits
Type: double

The number of Capacity Units of the provisioned throughput of the table consumed during the operation. GetItem, BatchGetItem, BatchWriteItem, Query, and Scan operations consume ReadCapacityUnits, while PutItem, UpdateItem, and DeleteItem operations consume WriteCapacityUnits.

Errors

ConditionalCheckFailedException:

This exception is thrown when an expected value does not match what was found in the system.

ProvisionedThroughputExceededException:

This exception is thrown when the level of provisioned throughput defined for the table is exceeded.

ResourceNotFoundException:

This exception is thrown when the resource which is being attempted to be changed is in use.

LimitExceededException:

This exception is thrown when the subscriber exceeded the limits on the number of objects or operations.

RequestLimitExceeded:

This exception is thrown when throughput exceeds the current throughput limit for the subscriber's account.

InternalServerError:

This exception is thrown when the service has a problem when trying to process the request.

UpdateTable 

$result = $client->updateTable([/* ... */]);
$promise = $client->updateTableAsync([/* ... */]);

Updates the provisioned throughput for the given table.

Setting the throughput for a table helps you manage performance and is part of the Provisioned Throughput feature of Amazon DynamoDB.

Parameter Syntax

$result = $client->updateTable([
    'ProvisionedThroughput' => [ // REQUIRED
        'ReadCapacityUnits' => <integer>, // REQUIRED
        'WriteCapacityUnits' => <integer>, // REQUIRED
    ],
    'TableName' => '<string>', // REQUIRED
]);

Parameter Details

Members
ProvisionedThroughput
Required: Yes
Type: ProvisionedThroughput structure

Provisioned throughput reserves the required read and write resources for your table in terms of ReadCapacityUnits and WriteCapacityUnits. Values for provisioned throughput depend upon your expected read/write rates, item size, and consistency. Provide the expected number of read and write operations, assuming an item size of 1k and strictly consistent reads. For 2k item size, double the value. For 3k, triple the value, etc. Eventually-consistent reads consume half the resources of strictly consistent reads.

TableName
Required: Yes
Type: string

The name of the table you want to update. Allowed characters are a-z, A-Z, 0-9, _ (underscore), - (hyphen) and . (period).

Result Syntax

[
    'TableDescription' => [
        'CreationDateTime' => <DateTime>,
        'ItemCount' => <integer>,
        'KeySchema' => [
            'HashKeyElement' => [
                'AttributeName' => '<string>',
                'AttributeType' => 'S|N|B',
            ],
            'RangeKeyElement' => [
                'AttributeName' => '<string>',
                'AttributeType' => 'S|N|B',
            ],
        ],
        'ProvisionedThroughput' => [
            'LastDecreaseDateTime' => <DateTime>,
            'LastIncreaseDateTime' => <DateTime>,
            'NumberOfDecreasesToday' => <integer>,
            'ReadCapacityUnits' => <integer>,
            'WriteCapacityUnits' => <integer>,
        ],
        'TableName' => '<string>',
        'TableSizeBytes' => <integer>,
        'TableStatus' => 'CREATING|UPDATING|DELETING|ACTIVE',
    ],
]

Result Details

Members
TableDescription
Type: TableDescription structure

Errors

ResourceInUseException:

This exception is thrown when the resource which is being attempted to be changed is in use.

ResourceNotFoundException:

This exception is thrown when the resource which is being attempted to be changed is in use.

LimitExceededException:

This exception is thrown when the subscriber exceeded the limits on the number of objects or operations.

InternalServerError:

This exception is thrown when the service has a problem when trying to process the request.

Shapes

AttributeValue

Description

AttributeValue can be String, Number, Binary, StringSet, NumberSet, BinarySet.

Members
B
Type: blob (string|resource|Psr\Http\Message\StreamInterface)

Binary attributes are sequences of unsigned bytes.

BS
Type: Array of blob (string|resource|Psr\Http\Message\StreamInterface)s

A set of binary attributes.

N
Type: string

Numbers are positive or negative exact-value decimals and integers. A number can have up to 38 digits precision and can be between 10^-128 to 10^+126.

NS
Type: Array of strings

A set of numbers.

S
Type: string

Strings are Unicode with UTF-8 binary encoding. The maximum size is limited by the size of the primary key (1024 bytes as a range part of a key or 2048 bytes as a single part hash key) or the item size (64k).

SS
Type: Array of strings

A set of strings.

AttributeValueUpdate

Description

Specifies the attribute to update and how to perform the update. Possible values: PUT (default), ADD or DELETE.

Members
Action
Type: string

The type of action for an item update operation. Only use the add action for numbers or sets; the specified value is added to the existing value. If a set of values is specified, the values are added to the existing set. Adds the specified attribute. If the attribute exists, it is replaced by the new value. If no value is specified, this removes the attribute and its value. If a set of values is specified, then the values in the specified set are removed from the old set.

Value
Type: AttributeValue structure

AttributeValue can be String, Number, Binary, StringSet, NumberSet, BinarySet.

BatchResponse

Description

The item attributes from a response in a specific table, along with the read resources consumed on the table during the request.

Members
ConsumedCapacityUnits
Type: double

The number of Capacity Units of the provisioned throughput of the table consumed during the operation. GetItem, BatchGetItem, BatchWriteItem, Query, and Scan operations consume ReadCapacityUnits, while PutItem, UpdateItem, and DeleteItem operations consume WriteCapacityUnits.

Items
Type: Array of AttributeValue structuress

BatchWriteResponse

Members
ConsumedCapacityUnits
Type: double

The number of Capacity Units of the provisioned throughput of the table consumed during the operation. GetItem, BatchGetItem, BatchWriteItem, Query, and Scan operations consume ReadCapacityUnits, while PutItem, UpdateItem, and DeleteItem operations consume WriteCapacityUnits.

Condition

Members
AttributeValueList
Type: Array of AttributeValue structures

A list of attribute values to be used with a comparison operator for a scan or query operation. For comparisons that require more than one value, such as a BETWEEN comparison, the AttributeValueList contains two attribute values and the comparison operator.

ComparisonOperator
Required: Yes
Type: string

A comparison operator is an enumeration of several operations:

  • EQ for equal.
  • NE for not equal.
  • IN checks for exact matches.
  • LE for less than or equal to.
  • LT for less than.
  • GE for greater than or equal to.
  • GT for greater than.
  • BETWEEN for between.
  • NOT_NULL for exists.
  • NULL for not exists.
  • CONTAINS for substring or value in a set.
  • NOT_CONTAINS for absence of a substring or absence of a value in a set.
  • BEGINS_WITH for a substring prefix.

Scan operations support all available comparison operators.

Query operations support a subset of the available comparison operators: EQ, LE, LT, GE, GT, BETWEEN, and BEGINS_WITH.

ConditionalCheckFailedException

Description

This exception is thrown when an expected value does not match what was found in the system.

Members
message
Type: string

DeleteRequest

Description

A container for a Delete BatchWrite request

Members
Key
Required: Yes
Type: Key structure

The item's key to be delete

ExpectedAttributeValue

Description

Allows you to provide an attribute name, and whether or not Amazon DynamoDB should check to see if the attribute value already exists; or if the attribute value exists and has a particular value before changing it.

Members
Exists
Type: boolean

Specify whether or not a value already exists for the attribute name-value pair.

Value
Type: AttributeValue structure

Specify whether or not a value already exists and has a specific content for the attribute name-value pair.

InternalServerError

Description

This exception is thrown when the service has a problem when trying to process the request.

Members
message
Type: string

Key

Description

The primary key that uniquely identifies each item in a table. A primary key can be a one attribute (hash) primary key or a two attribute (hash-and-range) primary key.

Members
HashKeyElement
Required: Yes
Type: AttributeValue structure

A hash key element is treated as the primary key, and can be a string or a number. Single attribute primary keys have one index value. The value can be String, Number, StringSet, NumberSet.

RangeKeyElement
Type: AttributeValue structure

A range key element is treated as a secondary key (used in conjunction with the primary key), and can be a string or a number, and is only used for hash-and-range primary keys. The value can be String, Number, StringSet, NumberSet.

KeySchema

Description

The KeySchema identifies the primary key as a one attribute primary key (hash) or a composite two attribute (hash-and-range) primary key. Single attribute primary keys have one index value: a HashKeyElement. A composite hash-and-range primary key contains two attribute values: a HashKeyElement and a RangeKeyElement.

Members
HashKeyElement
Required: Yes
Type: KeySchemaElement structure

A hash key element is treated as the primary key, and can be a string or a number. Single attribute primary keys have one index value. The value can be String, Number, StringSet, NumberSet.

RangeKeyElement
Type: KeySchemaElement structure

A range key element is treated as a secondary key (used in conjunction with the primary key), and can be a string or a number, and is only used for hash-and-range primary keys. The value can be String, Number, StringSet, NumberSet.

KeySchemaElement

Description

KeySchemaElement is the primary key (hash or hash-and-range) structure for the table.

Members
AttributeName
Required: Yes
Type: string

The AttributeName of the KeySchemaElement.

AttributeType
Required: Yes
Type: string

The AttributeType of the KeySchemaElement which can be a String or a Number.

KeysAndAttributes

Members
AttributesToGet
Type: Array of strings

List of Attribute names. If attribute names are not specified then all attributes will be returned. If some attributes are not found, they will not appear in the result.

ConsistentRead
Type: boolean

If set to true, then a consistent read is issued. Otherwise eventually-consistent is used.

Keys
Required: Yes
Type: Array of Key structures

LimitExceededException

Description

This exception is thrown when the subscriber exceeded the limits on the number of objects or operations.

Members
message
Type: string

ProvisionedThroughput

Description

Provisioned throughput reserves the required read and write resources for your table in terms of ReadCapacityUnits and WriteCapacityUnits. Values for provisioned throughput depend upon your expected read/write rates, item size, and consistency. Provide the expected number of read and write operations, assuming an item size of 1k and strictly consistent reads. For 2k item size, double the value. For 3k, triple the value, etc. Eventually-consistent reads consume half the resources of strictly consistent reads.

Members
ReadCapacityUnits
Required: Yes
Type: long (int|float)

ReadCapacityUnits are in terms of strictly consistent reads, assuming items of 1k. 2k items require twice the ReadCapacityUnits. Eventually-consistent reads only require half the ReadCapacityUnits of stirctly consistent reads.

WriteCapacityUnits
Required: Yes
Type: long (int|float)

WriteCapacityUnits are in terms of strictly consistent reads, assuming items of 1k. 2k items require twice the WriteCapacityUnits.

ProvisionedThroughputDescription

Members
LastDecreaseDateTime
Type: timestamp (string|DateTime or anything parsable by strtotime)
LastIncreaseDateTime
Type: timestamp (string|DateTime or anything parsable by strtotime)
NumberOfDecreasesToday
Type: long (int|float)
ReadCapacityUnits
Type: long (int|float)
WriteCapacityUnits
Type: long (int|float)

ProvisionedThroughputExceededException

Description

This exception is thrown when the level of provisioned throughput defined for the table is exceeded.

Members
message
Type: string

PutRequest

Description

A container for a Put BatchWrite request

Members
Item
Required: Yes
Type: Associative array of custom strings keys (AttributeName) to AttributeValue structures

The item to put

RequestLimitExceeded

Description

This exception is thrown when throughput exceeds the current throughput limit for the subscriber's account.

Members
message
Type: string

ResourceInUseException

Description

This exception is thrown when the resource which is being attempted to be changed is in use.

Members
message
Type: string

ResourceNotFoundException

Description

This exception is thrown when the resource which is being attempted to be changed is in use.

Members
message
Type: string

TableDescription

Members
CreationDateTime
Type: timestamp (string|DateTime or anything parsable by strtotime)
ItemCount
Type: long (int|float)
KeySchema
Type: KeySchema structure

The KeySchema identifies the primary key as a one attribute primary key (hash) or a composite two attribute (hash-and-range) primary key. Single attribute primary keys have one index value: a HashKeyElement. A composite hash-and-range primary key contains two attribute values: a HashKeyElement and a RangeKeyElement.

ProvisionedThroughput
Type: ProvisionedThroughputDescription structure
TableName
Type: string

The name of the table being described.

TableSizeBytes
Type: long (int|float)
TableStatus
Type: string

WriteRequest

Description

This structure is a Union of PutRequest and DeleteRequest. It can contain exactly one of PutRequest or DeleteRequest. Never Both. This is enforced in the code.

Members
DeleteRequest
Type: DeleteRequest structure

A container for a Delete BatchWrite request

PutRequest
Type: PutRequest structure

A container for a Put BatchWrite request