batch_get_item ( $opt )

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.

Access

public

Parameters

Parameter

Type

Required

Description

$opt

array

Optional

An associative array of parameters that can have the following keys:

  • RequestItems - array - Required - 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.
    • [custom-key] - array - Optional - This key is variable (e.g., user-specified). [Constraints: The value must be between 3 and 255 characters, and must match the following regular expression pattern: [a-zA-Z0-9_.-]+]
      • Keys - array - Required - 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.
        • x - array - Optional - This represents a simple array index.
          • HashKeyElement - array - Required - 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.
            • S - string - Optional - 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).
            • N - string - Optional - 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.
            • B - blob - Optional - Binary attributes are sequences of unsigned bytes.
            • SS - string|array - Optional - A set of strings. Pass a string for a single value, or an indexed array for multiple values.
            • NS - string|array - Optional - A set of numbers. Pass a string for a single value, or an indexed array for multiple values.
            • BS - blob - Optional - A set of binary attributes.
          • RangeKeyElement - array - Optional - 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.
            • S - string - Optional - 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).
            • N - string - Optional - 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.
            • B - blob - Optional - Binary attributes are sequences of unsigned bytes.
            • SS - string|array - Optional - A set of strings. Pass a string for a single value, or an indexed array for multiple values.
            • NS - string|array - Optional - A set of numbers. Pass a string for a single value, or an indexed array for multiple values.
            • BS - blob - Optional - A set of binary attributes.
      • AttributesToGet - string|array - Optional - 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. Pass a string for a single value, or an indexed array for multiple values.
      • ConsistentRead - boolean - Optional - If set to true, then a consistent read is issued. Otherwise eventually-consistent is used.
  • curlopts - array - Optional - A set of values to pass directly into curl_setopt(), where the key is a pre-defined CURLOPT_* constant.
  • returnCurlHandle - boolean - Optional - A private toggle specifying that the cURL handle be returned rather than actually completing the request. This toggle is useful for manually managed batch requests.

Returns

Type

Description

CFResponse

A CFResponse object containing a parsed HTTP response.

Examples

Create a new table with a Hash Key.

// Instantiate the class
$dynamodb = new AmazonDynamoDB();

$table_name = 'my-table' . time();
$current_time = (int) time();

####################################################################
# Create a new DynamoDB table

$response = $dynamodb->create_table(array(
	'TableName' => $table_name,
	'KeySchema' => array(
		'HashKeyElement' => array(
			'AttributeName' => 'id',
			'AttributeType' => AmazonDynamoDB::TYPE_NUMBER
		),
		'RangeKeyElement' => array(
			'AttributeName' => 'date',
			'AttributeType' => AmazonDynamoDB::TYPE_NUMBER
		)
	),
	'ProvisionedThroughput' => array(
		'ReadCapacityUnits' => 50,
		'WriteCapacityUnits' => 50
	)
));

// Check for success...
if ($response->isOK())
{
	echo '# Kicked off the creation of the DynamoDB table...' . PHP_EOL;
}
else
{
	print_r($response);
}

####################################################################
# Sleep and poll until the table has been created

$count = 0;
do {
	sleep(1);
	$count++;

	$response = $dynamodb->describe_table(array(
		'TableName' => $table_name
	));
}
while ((string) $response->body->Table->TableStatus !== 'ACTIVE');

echo "The table \"${table_name}\" has been created (slept ${count} seconds)." . PHP_EOL;

####################################################################
# Adding data to the table

echo PHP_EOL . PHP_EOL;
echo "# Adding data to the table..." . PHP_EOL;

// Set up batch requests
$queue = new CFBatchRequest();
$queue->use_credentials($dynamodb->credentials);

// Add items to the batch
$dynamodb->batch($queue)->put_item(array(
	'TableName' => $table_name,
	'Item' => $dynamodb->attributes(array(
		'id'            => 1,             // Primary (Hash) Key
		'date'          => $current_time, // Range Key
		'key1'          => 'value1',
		'key2'          => 'value2',
		'îñtérnåtîønål' => 'åéîøü'
	))
));

$dynamodb->batch($queue)->put_item(array(
	'TableName' => $table_name,
	'Item' => $dynamodb->attributes(array(
		'id'            => 2,             // Primary (Hash) Key
		'date'          => $current_time, // Range Key
		'key1'          => 'value3',
		'key2'          => 'value4',
		'îñtérnåtîønål' => 'îøüåé'
	))
));

$dynamodb->batch($queue)->put_item(array(
	'TableName' => $table_name,
	'Item' => $dynamodb->attributes(array(
		'id'            => 3,             // Primary (Hash) Key
		'date'          => $current_time, // Range Key
		'key1'          => 'value5',
		'key2'          => 'value6',
		'îñtérnåtîønål' => 'üøîéå'
	))
));

// Execute the batch of requests in parallel
$responses = $dynamodb->batch($queue)->send();

// Check for success...
if ($responses->areOK())
{
	echo "The data has been added to the table." . PHP_EOL;
}
else
{
	print_r($responses);
}

####################################################################
# Getting multiple items

echo PHP_EOL . PHP_EOL;
echo "# Getting multiple items from the table..." . PHP_EOL;

// Get an item
$response = $dynamodb->batch_get_item(array(
	'RequestItems' => array(
		$table_name => array(
			'Keys' => array( // Key #1
				$dynamodb->attributes(array(
					'HashKeyElement'  => 1,
					'RangeKeyElement' => $current_time,
				)),
				$dynamodb->attributes(array( // Key #2
					'HashKeyElement'  => 2,
					'RangeKeyElement' => $current_time,
				)),
			),
		)
	)
));

// Check for success...
if ($response->isOK())
{
	sleep(5);

	// Collect the values we want to show
	$result = array();
	foreach ($response->body->Responses->{$table_name}->Items as $item)
	{
		$result[] = array(
			'id'            => (string) $item->{'id'}->{AmazonDynamoDB::TYPE_NUMBER},
			'date'          => (string) $item->{'date'}->{AmazonDynamoDB::TYPE_NUMBER},
			'îñtérnåtîønål' => (string) $item->{'îñtérnåtîønål'}->{AmazonDynamoDB::TYPE_STRING},
		);
	}

	// Output
	print_r($result);
}
else
{
	print_r($response);
}

####################################################################
# Deleting the table

echo PHP_EOL . PHP_EOL;
echo "# Deleting the \"${table_name}\" table..." . PHP_EOL;

$response = $dynamodb->delete_table(array(
	'TableName' => $table_name
));

// Check for success...
if ($response->isOK())
{
	echo 'The table is in the process of deleting...' . PHP_EOL;
}
else
{
	print_r($response);
}

####################################################################
# Sleep and poll until the table has been deleted.

$count = 0;
do {
	sleep(1);
	$count++;

	$response = $dynamodb->describe_table(array(
		'TableName' => $table_name
	));
}
while ((integer) $response->status !== 400);

echo "The table \"${table_name}\" has been deleted (slept ${count} seconds)." . PHP_EOL;

Handle retrieved NULL bytes.

// Instantiate the class
$dynamodb = new AmazonDynamoDB();

$table_name = 'my-table' . time();

####################################################################
# Create a new DynamoDB table

$response = $dynamodb->create_table(array(
	'TableName' => $table_name,
	'KeySchema' => array(
		'HashKeyElement' => array(
			'AttributeName' => 'id',
			'AttributeType' => AmazonDynamoDB::TYPE_NUMBER,
		),
	),
	'ProvisionedThroughput' => array(
		'ReadCapacityUnits' => 10,
		'WriteCapacityUnits' => 5,
	),
));

var_dump($response->isOK());

if (!$response->isOK())
{
	die('Table creation failed.');
}

// Sleep and poll during table creation
do
{
	sleep(1);

	$response = $dynamodb->describe_table(array(
		'TableName' => $table_name
	));
}
while ((string) $response->body->Table->TableStatus !== 'ACTIVE');

####################################################################
# Add data containing a NULL byte to the table

// Create a class with a private/protected member
class Dummy
{
	private   $private_prop   = 'private';
	protected $protected_prop = 'private';
	public    $public_prop    = 'public';
}

// Store the serialized PHP class in DynamoDB
$response = $dynamodb->put_item(array(
	'TableName' => $table_name,
	'Item' => $dynamodb->attributes(array(
		'id' => 1,
		'data' => serialize(new Dummy)
	))
));

var_dump($response->isOK());

sleep(1);

####################################################################
# Getting an item

$response = $dynamodb->get_item(array(
	'TableName' => $table_name,
	'Key' => array(
		'HashKeyElement' => array(
			AmazonDynamoDB::TYPE_NUMBER => '1'
		),
	),
));

var_dump($response->isOK());

// Read back the serialized data. Decode it during stringification, or force it with to_string().
$dummy = unserialize($response->body->Item->data->{AmazonDynamoDB::TYPE_STRING}->to_string());

// Output the public value
var_dump($dummy->public_prop);

####################################################################
# Deleting the table

$response = $dynamodb->delete_table(array(
	'TableName' => $table_name
));

var_dump($response->isOK());

// Sleep and poll until table is deleted
do
{
	sleep(1);

	$response = $dynamodb->describe_table(array(
		'TableName' => $table_name
	));
}
while ((integer) $response->status !== 400);
Result:
bool(true)
bool(true)
bool(true)
string(6) "public"
bool(true)

Source

Method defined in services/dynamodb.class.php | Toggle source view (6 lines) | View on GitHub

public function batch_get_item($opt = null)
{
    if (!$opt) $opt = array();
    
    return $this->authenticate('BatchGetItem', $opt);
}

Copyright © 2010–2013 Amazon Web Services, LLC


Feedback