put_item ( $opt )

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.

Access

public

Parameters

Parameter

Type

Required

Description

$opt

array

Optional

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

  • TableName - string - Required - 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). [Constraints: The value must be between 3 and 255 characters, and must match the following regular expression pattern: [a-zA-Z0-9_.-]+]
  • Item - array - Required - 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.
    • [custom-key] - array - Optional - AttributeValue can be String, Number, Binary, StringSet, NumberSet, BinarySet.
      • 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.
  • Expected - array - Optional - 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.
    • [custom-key] - array - Optional - 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.
      • Value - array - Optional - Specify whether or not a value already exists and has a specific content for the attribute name-value pair.
        • 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.
      • Exists - boolean - Optional - Specify whether or not a value already exists for the attribute name-value pair.
  • ReturnValues - string - Optional - 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.
    [Allowed values: NONE, ALL_OLD, UPDATED_OLD, ALL_NEW, UPDATED_NEW]
  • 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;

// Add items to the batch
$response = $dynamodb->batch_write_item(array(
	'RequestItems' => array(
		$table_name => array(
			array(
				'PutRequest' => array(
					'Item' => $dynamodb->attributes(array(
						'id'   => 1,             // Primary (Hash) Key
						'date' => $current_time, // Range Key
						'key1' => 'value1',
						'key2' => 'value2',
						'key3' => array('sub-value1', 'sub-value2'),
					))
				)
			),
			array(
				'PutRequest' => array(
					'Item' => $dynamodb->attributes(array(
						'id'   => 2,             // Primary (Hash) Key
						'date' => $current_time, // Range Key
						'key1' => 'value3',
						'key2' => 'value4',
						'key3' => array('sub-value1', 'sub-value2'),
					))
				)
			),
			array(
				'PutRequest' => array(
					'Item' => $dynamodb->attributes(array(
						'id'   => 3,             // Primary (Hash) Key
						'date' => $current_time, // Range Key
						'key1' => 'value5',
						'key2' => 'value6',
						'key3' => array('sub-value1', 'sub-value2'),
					))
				)
			),
		)
	)
));

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

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

echo PHP_EOL . PHP_EOL;
echo "# Getting an item from the table..." . PHP_EOL;

// Get an item
$response = $dynamodb->get_item(array(
	'TableName' => $table_name,
	'Key' => $dynamodb->attributes(array(
		'HashKeyElement'  => 3,             // "id" column
		'RangeKeyElement' => $current_time, // "date" column
	)),
	'AttributesToGet' => array('id', 'date', 'key1', 'key2', 'key3'),
	'ConsistentRead' => 'true'
));

// Check for success...
if ($response->isOK())
{
	var_dump((string) $response->body->Item->key1->{AmazonDynamoDB::TYPE_STRING});
}
else
{
	print_r($response);
}

####################################################################
# Updating an item

echo PHP_EOL . PHP_EOL;
echo "# Updating an item from the table..." . PHP_EOL;

// Updating an item
$response = $dynamodb->update_item(array(
	'TableName' => $table_name,
	'Key' => $dynamodb->attributes(array(
		'HashKeyElement'  => 3, // "id" column
		'RangeKeyElement' => $current_time, // "date" column
	)),
	'AttributeUpdates' => array(
		'key1' => array(
			'Action' => AmazonDynamoDB::ACTION_PUT,
			'Value'  => array(AmazonDynamoDB::TYPE_STRING => 'updated-value1')
		),
		'key2' => array(
			'Action' => AmazonDynamoDB::ACTION_DELETE
		),
		'key3' => array(
			'Action' => AmazonDynamoDB::ACTION_ADD,
			'Value'  => array(AmazonDynamoDB::TYPE_STRING_SET => array('sub-value3'))
		),
		'key4' => array(
			'Action' => AmazonDynamoDB::ACTION_PUT,
			'Value'  => $dynamodb->binary('binary-value')
		),
	),
	'Expected' => array(
		'key1' => array(
			'Value' => array( AmazonDynamoDB::TYPE_STRING => 'value5' )
		)
	)
));

// Check for success...
if ($response->isOK())
{
	echo 'Updating the item...' . PHP_EOL;
}
else
{
	print_r($response);
}

####################################################################
# Checking the binary result

echo PHP_EOL . PHP_EOL;
echo "# Getting an item from the table..." . PHP_EOL;

// Get an item
$response = $dynamodb->get_item(array(
	'TableName' => $table_name,
	'Key' => $dynamodb->attributes(array(
		'HashKeyElement'  => 3,             // "id" column
		'RangeKeyElement' => $current_time, // "date" column
	)),
	'AttributesToGet' => array('key4'),
	'ConsistentRead' => 'true'
));

// Check for success...
if ($response->isOK())
{
	var_dump((string) $response->body->Item->key4->{AmazonDynamoDB::TYPE_BINARY});
}
else
{
	print_r($response);
}

####################################################################
# Deleting an item

echo PHP_EOL . PHP_EOL;
echo "# Deleting an item from the table..." . PHP_EOL;

// Deleting an item
$response = $dynamodb->delete_item(array(
	'TableName' => $table_name,
	'Key' => $dynamodb->attributes(array(
		'HashKeyElement'  => 1, // "id" column
		'RangeKeyElement' => $current_time, // "date" column
	)),

));

// Check for success...
if ($response->isOK())
{
	echo 'Deleting the item...' . PHP_EOL;
}
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 {
	echo '.';
	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;

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;

Source

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

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

Copyright © 2010–2013 Amazon Web Services, LLC


Feedback