()
{
new KeySchemaElement
{
AttributeName = "year",
KeyType = KeyType.HASH,
},
new KeySchemaElement
{
AttributeName = "title",
KeyType = KeyType.RANGE,
},
},
BillingMode = BillingMode.PAY_PER_REQUEST,
});
// Wait until the table is ACTIVE and then report success.
Console.Write("Waiting for table to become active...");
var request = new DescribeTableRequest
{
TableName = response.TableDescription.TableName,
};
TableStatus status;
int sleepDuration = 2000;
do
{
Thread.Sleep(sleepDuration);
var describeTableResponse = await _amazonDynamoDB.DescribeTableAsync(request);
status = describeTableResponse.Table.TableStatus;
Console.Write(".");
}
while (status != "ACTIVE");
return status == TableStatus.ACTIVE;
}
catch (ResourceInUseException ex)
{
Console.WriteLine($"Table {tableName} already exists. {ex.Message}");
throw;
}
catch (AmazonDynamoDBException ex)
{
Console.WriteLine($"An Amazon DynamoDB error occurred while creating table {tableName}. {ex.Message}");
throw;
}
catch (Exception ex)
{
Console.WriteLine($"An error occurred while creating table {tableName}. {ex.Message}");
throw;
}
}
```
+ For API details, see [CreateTable](https://docs.amazonaws.cn/goto/DotNetSDKV4/dynamodb-2012-08-10/CreateTable) in *Amazon SDK for .NET API Reference*.
------
#### [ Bash ]
**Amazon CLI with Bash script**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/aws-cli/bash-linux/dynamodb#code-examples).
```
###############################################################################
# function dynamodb_create_table
#
# This function creates an Amazon DynamoDB table.
#
# Parameters:
# -n table_name -- The name of the table to create.
# -a attribute_definitions -- JSON file path of a list of attributes and their types.
# -k key_schema -- JSON file path of a list of attributes and their key types.
#
# Returns:
# 0 - If successful.
# 1 - If it fails.
###############################################################################
function dynamodb_create_table() {
local table_name attribute_definitions key_schema response
local option OPTARG # Required to use getopts command in a function.
#######################################
# Function usage explanation
#######################################
function usage() {
echo "function dynamodb_create_table"
echo "Creates an Amazon DynamoDB table with on-demand billing."
echo " -n table_name -- The name of the table to create."
echo " -a attribute_definitions -- JSON file path of a list of attributes and their types."
echo " -k key_schema -- JSON file path of a list of attributes and their key types."
echo ""
}
# Retrieve the calling parameters.
while getopts "n:a:k:h" option; do
case "${option}" in
n) table_name="${OPTARG}" ;;
a) attribute_definitions="${OPTARG}" ;;
k) key_schema="${OPTARG}" ;;
h)
usage
return 0
;;
\?)
echo "Invalid parameter"
usage
return 1
;;
esac
done
export OPTIND=1
if [[ -z "$table_name" ]]; then
errecho "ERROR: You must provide a table name with the -n parameter."
usage
return 1
fi
if [[ -z "$attribute_definitions" ]]; then
errecho "ERROR: You must provide an attribute definitions json file path the -a parameter."
usage
return 1
fi
if [[ -z "$key_schema" ]]; then
errecho "ERROR: You must provide a key schema json file path the -k parameter."
usage
return 1
fi
iecho "Parameters:\n"
iecho " table_name: $table_name"
iecho " attribute_definitions: $attribute_definitions"
iecho " key_schema: $key_schema"
iecho ""
response=$(aws dynamodb create-table \
--table-name "$table_name" \
--attribute-definitions file://"$attribute_definitions" \
--billing-mode PAY_PER_REQUEST \
--key-schema file://"$key_schema" )
local error_code=${?}
if [[ $error_code -ne 0 ]]; then
aws_cli_error_log $error_code
errecho "ERROR: AWS reports create-table operation failed.$response"
return 1
fi
return 0
}
```
The utility functions used in this example.
```
###############################################################################
# function iecho
#
# This function enables the script to display the specified text only if
# the global variable $VERBOSE is set to true.
###############################################################################
function iecho() {
if [[ $VERBOSE == true ]]; then
echo "$@"
fi
}
###############################################################################
# function errecho
#
# This function outputs everything sent to it to STDERR (standard error output).
###############################################################################
function errecho() {
printf "%s\n" "$*" 1>&2
}
##############################################################################
# function aws_cli_error_log()
#
# This function is used to log the error messages from the AWS CLI.
#
# See https://docs.aws.amazon.com/cli/latest/topic/return-codes.html#cli-aws-help-return-codes.
#
# The function expects the following argument:
# $1 - The error code returned by the AWS CLI.
#
# Returns:
# 0: - Success.
#
##############################################################################
function aws_cli_error_log() {
local err_code=$1
errecho "Error code : $err_code"
if [ "$err_code" == 1 ]; then
errecho " One or more S3 transfers failed."
elif [ "$err_code" == 2 ]; then
errecho " Command line failed to parse."
elif [ "$err_code" == 130 ]; then
errecho " Process received SIGINT."
elif [ "$err_code" == 252 ]; then
errecho " Command syntax invalid."
elif [ "$err_code" == 253 ]; then
errecho " The system environment or configuration was invalid."
elif [ "$err_code" == 254 ]; then
errecho " The service returned an error."
elif [ "$err_code" == 255 ]; then
errecho " 255 is a catch-all error."
fi
return 0
}
```
+ For API details, see [CreateTable](https://docs.amazonaws.cn/goto/aws-cli/dynamodb-2012-08-10/CreateTable) in *Amazon CLI Command Reference*.
------
#### [ C\$1\$1 ]
**SDK for C\$1\$1**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/cpp/example_code/dynamodb#code-examples).
```
//! Create an Amazon DynamoDB table.
/*!
\sa createTable()
\param tableName: Name for the DynamoDB table.
\param primaryKey: Primary key for the DynamoDB table.
\param clientConfiguration: AWS client configuration.
\return bool: Function succeeded.
*/
bool AwsDoc::DynamoDB::createTable(const Aws::String &tableName,
const Aws::String &primaryKey,
const Aws::Client::ClientConfiguration &clientConfiguration) {
Aws::DynamoDB::DynamoDBClient dynamoClient(clientConfiguration);
std::cout << "Creating table " << tableName <<
" with a simple primary key: \"" << primaryKey << "\"." << std::endl;
Aws::DynamoDB::Model::CreateTableRequest request;
Aws::DynamoDB::Model::AttributeDefinition hashKey;
hashKey.SetAttributeName(primaryKey);
hashKey.SetAttributeType(Aws::DynamoDB::Model::ScalarAttributeType::S);
request.AddAttributeDefinitions(hashKey);
Aws::DynamoDB::Model::KeySchemaElement keySchemaElement;
keySchemaElement.WithAttributeName(primaryKey).WithKeyType(
Aws::DynamoDB::Model::KeyType::HASH);
request.AddKeySchema(keySchemaElement);
Aws::DynamoDB::Model::ProvisionedThroughput throughput;
throughput.WithReadCapacityUnits(5).WithWriteCapacityUnits(5);
request.SetProvisionedThroughput(throughput);
request.SetTableName(tableName);
const Aws::DynamoDB::Model::CreateTableOutcome &outcome = dynamoClient.CreateTable(
request);
if (outcome.IsSuccess()) {
std::cout << "Table \""
<< outcome.GetResult().GetTableDescription().GetTableName() <<
" created!" << std::endl;
}
else {
std::cerr << "Failed to create table: " << outcome.GetError().GetMessage()
<< std::endl;
return false;
}
return waitTableActive(tableName, dynamoClient);
}
```
Code that waits for the table to become active.
```
//! Query a newly created DynamoDB table until it is active.
/*!
\sa waitTableActive()
\param waitTableActive: The DynamoDB table's name.
\param dynamoClient: A DynamoDB client.
\return bool: Function succeeded.
*/
bool AwsDoc::DynamoDB::waitTableActive(const Aws::String &tableName,
const Aws::DynamoDB::DynamoDBClient &dynamoClient) {
// Repeatedly call DescribeTable until table is ACTIVE.
const int MAX_QUERIES = 20;
Aws::DynamoDB::Model::DescribeTableRequest request;
request.SetTableName(tableName);
int count = 0;
while (count < MAX_QUERIES) {
const Aws::DynamoDB::Model::DescribeTableOutcome &result = dynamoClient.DescribeTable(
request);
if (result.IsSuccess()) {
Aws::DynamoDB::Model::TableStatus status = result.GetResult().GetTable().GetTableStatus();
if (Aws::DynamoDB::Model::TableStatus::ACTIVE != status) {
std::this_thread::sleep_for(std::chrono::seconds(1));
}
else {
return true;
}
}
else {
std::cerr << "Error DynamoDB::waitTableActive "
<< result.GetError().GetMessage() << std::endl;
return false;
}
count++;
}
return false;
}
```
+ For API details, see [CreateTable](https://docs.amazonaws.cn/goto/SdkForCpp/dynamodb-2012-08-10/CreateTable) in *Amazon SDK for C\$1\$1 API Reference*.
------
#### [ CLI ]
**Amazon CLI**
**Example 1: To create a table with tags**
The following `create-table` example uses the specified attributes and key schema to create a table named `MusicCollection`. This table uses provisioned throughput and is encrypted at rest using the default Amazon owned CMK. The command also applies a tag to the table, with a key of `Owner` and a value of `blueTeam`.
```
aws dynamodb create-table \
--table-name MusicCollection \
--attribute-definitions AttributeName=Artist,AttributeType=S AttributeName=SongTitle,AttributeType=S \
--key-schema AttributeName=Artist,KeyType=HASH AttributeName=SongTitle,KeyType=RANGE \
--provisioned-throughput ReadCapacityUnits=5,WriteCapacityUnits=5 \
--tags Key=Owner,Value=blueTeam
```
Output:
```
{
"TableDescription": {
"AttributeDefinitions": [
{
"AttributeName": "Artist",
"AttributeType": "S"
},
{
"AttributeName": "SongTitle",
"AttributeType": "S"
}
],
"ProvisionedThroughput": {
"NumberOfDecreasesToday": 0,
"WriteCapacityUnits": 5,
"ReadCapacityUnits": 5
},
"TableSizeBytes": 0,
"TableName": "MusicCollection",
"TableStatus": "CREATING",
"KeySchema": [
{
"KeyType": "HASH",
"AttributeName": "Artist"
},
{
"KeyType": "RANGE",
"AttributeName": "SongTitle"
}
],
"ItemCount": 0,
"CreationDateTime": "2020-05-26T16:04:41.627000-07:00",
"TableArn": "arn:aws:dynamodb:us-west-2:123456789012:table/MusicCollection",
"TableId": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111"
}
}
```
For more information, see [Basic Operations for Tables](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/WorkingWithTables.Basics.html) in the *Amazon DynamoDB Developer Guide*.
**Example 2: To create a table in On-Demand Mode**
The following example creates a table called `MusicCollection` using on-demand mode, rather than provisioned throughput mode. This is useful for tables with unpredictable workloads.
```
aws dynamodb create-table \
--table-name MusicCollection \
--attribute-definitions AttributeName=Artist,AttributeType=S AttributeName=SongTitle,AttributeType=S \
--key-schema AttributeName=Artist,KeyType=HASH AttributeName=SongTitle,KeyType=RANGE \
--billing-mode PAY_PER_REQUEST
```
Output:
```
{
"TableDescription": {
"AttributeDefinitions": [
{
"AttributeName": "Artist",
"AttributeType": "S"
},
{
"AttributeName": "SongTitle",
"AttributeType": "S"
}
],
"TableName": "MusicCollection",
"KeySchema": [
{
"AttributeName": "Artist",
"KeyType": "HASH"
},
{
"AttributeName": "SongTitle",
"KeyType": "RANGE"
}
],
"TableStatus": "CREATING",
"CreationDateTime": "2020-05-27T11:44:10.807000-07:00",
"ProvisionedThroughput": {
"NumberOfDecreasesToday": 0,
"ReadCapacityUnits": 0,
"WriteCapacityUnits": 0
},
"TableSizeBytes": 0,
"ItemCount": 0,
"TableArn": "arn:aws:dynamodb:us-west-2:123456789012:table/MusicCollection",
"TableId": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
"BillingModeSummary": {
"BillingMode": "PAY_PER_REQUEST"
}
}
}
```
For more information, see [Basic Operations for Tables](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/WorkingWithTables.Basics.html) in the *Amazon DynamoDB Developer Guide*.
**Example 3: To create a table and encrypt it with a Customer Managed CMK**
The following example creates a table named `MusicCollection` and encrypts it using a customer managed CMK.
```
aws dynamodb create-table \
--table-name MusicCollection \
--attribute-definitions AttributeName=Artist,AttributeType=S AttributeName=SongTitle,AttributeType=S \
--key-schema AttributeName=Artist,KeyType=HASH AttributeName=SongTitle,KeyType=RANGE \
--provisioned-throughput ReadCapacityUnits=5,WriteCapacityUnits=5 \
--sse-specification Enabled=true,SSEType=KMS,KMSMasterKeyId=abcd1234-abcd-1234-a123-ab1234a1b234
```
Output:
```
{
"TableDescription": {
"AttributeDefinitions": [
{
"AttributeName": "Artist",
"AttributeType": "S"
},
{
"AttributeName": "SongTitle",
"AttributeType": "S"
}
],
"TableName": "MusicCollection",
"KeySchema": [
{
"AttributeName": "Artist",
"KeyType": "HASH"
},
{
"AttributeName": "SongTitle",
"KeyType": "RANGE"
}
],
"TableStatus": "CREATING",
"CreationDateTime": "2020-05-27T11:12:16.431000-07:00",
"ProvisionedThroughput": {
"NumberOfDecreasesToday": 0,
"ReadCapacityUnits": 5,
"WriteCapacityUnits": 5
},
"TableSizeBytes": 0,
"ItemCount": 0,
"TableArn": "arn:aws:dynamodb:us-west-2:123456789012:table/MusicCollection",
"TableId": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
"SSEDescription": {
"Status": "ENABLED",
"SSEType": "KMS",
"KMSMasterKeyArn": "arn:aws:kms:us-west-2:123456789012:key/abcd1234-abcd-1234-a123-ab1234a1b234"
}
}
}
```
For more information, see [Basic Operations for Tables](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/WorkingWithTables.Basics.html) in the *Amazon DynamoDB Developer Guide*.
**Example 4: To create a table with a Local Secondary Index**
The following example uses the specified attributes and key schema to create a table named `MusicCollection` with a Local Secondary Index named `AlbumTitleIndex`.
```
aws dynamodb create-table \
--table-name MusicCollection \
--attribute-definitions AttributeName=Artist,AttributeType=S AttributeName=SongTitle,AttributeType=S AttributeName=AlbumTitle,AttributeType=S \
--key-schema AttributeName=Artist,KeyType=HASH AttributeName=SongTitle,KeyType=RANGE \
--provisioned-throughput ReadCapacityUnits=10,WriteCapacityUnits=5 \
--local-secondary-indexes \
"[
{
\"IndexName\": \"AlbumTitleIndex\",
\"KeySchema\": [
{\"AttributeName\": \"Artist\",\"KeyType\":\"HASH\"},
{\"AttributeName\": \"AlbumTitle\",\"KeyType\":\"RANGE\"}
],
\"Projection\": {
\"ProjectionType\": \"INCLUDE\",
\"NonKeyAttributes\": [\"Genre\", \"Year\"]
}
}
]"
```
Output:
```
{
"TableDescription": {
"AttributeDefinitions": [
{
"AttributeName": "AlbumTitle",
"AttributeType": "S"
},
{
"AttributeName": "Artist",
"AttributeType": "S"
},
{
"AttributeName": "SongTitle",
"AttributeType": "S"
}
],
"TableName": "MusicCollection",
"KeySchema": [
{
"AttributeName": "Artist",
"KeyType": "HASH"
},
{
"AttributeName": "SongTitle",
"KeyType": "RANGE"
}
],
"TableStatus": "CREATING",
"CreationDateTime": "2020-05-26T15:59:49.473000-07:00",
"ProvisionedThroughput": {
"NumberOfDecreasesToday": 0,
"ReadCapacityUnits": 10,
"WriteCapacityUnits": 5
},
"TableSizeBytes": 0,
"ItemCount": 0,
"TableArn": "arn:aws:dynamodb:us-west-2:123456789012:table/MusicCollection",
"TableId": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
"LocalSecondaryIndexes": [
{
"IndexName": "AlbumTitleIndex",
"KeySchema": [
{
"AttributeName": "Artist",
"KeyType": "HASH"
},
{
"AttributeName": "AlbumTitle",
"KeyType": "RANGE"
}
],
"Projection": {
"ProjectionType": "INCLUDE",
"NonKeyAttributes": [
"Genre",
"Year"
]
},
"IndexSizeBytes": 0,
"ItemCount": 0,
"IndexArn": "arn:aws:dynamodb:us-west-2:123456789012:table/MusicCollection/index/AlbumTitleIndex"
}
]
}
}
```
For more information, see [Basic Operations for Tables](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/WorkingWithTables.Basics.html) in the *Amazon DynamoDB Developer Guide*.
**Example 5: To create a table with a Global Secondary Index**
The following example creates a table named `GameScores` with a Global Secondary Index called `GameTitleIndex`. The base table has a partition key of `UserId` and a sort key of `GameTitle`, allowing you to find an individual user's best score for a specific game efficiently, whereas the GSI has a partition key of `GameTitle` and a sort key of `TopScore`, allowing you to quickly find the overall highest score for a particular game.
```
aws dynamodb create-table \
--table-name GameScores \
--attribute-definitions AttributeName=UserId,AttributeType=S AttributeName=GameTitle,AttributeType=S AttributeName=TopScore,AttributeType=N \
--key-schema AttributeName=UserId,KeyType=HASH \
AttributeName=GameTitle,KeyType=RANGE \
--provisioned-throughput ReadCapacityUnits=10,WriteCapacityUnits=5 \
--global-secondary-indexes \
"[
{
\"IndexName\": \"GameTitleIndex\",
\"KeySchema\": [
{\"AttributeName\":\"GameTitle\",\"KeyType\":\"HASH\"},
{\"AttributeName\":\"TopScore\",\"KeyType\":\"RANGE\"}
],
\"Projection\": {
\"ProjectionType\":\"INCLUDE\",
\"NonKeyAttributes\":[\"UserId\"]
},
\"ProvisionedThroughput\": {
\"ReadCapacityUnits\": 10,
\"WriteCapacityUnits\": 5
}
}
]"
```
Output:
```
{
"TableDescription": {
"AttributeDefinitions": [
{
"AttributeName": "GameTitle",
"AttributeType": "S"
},
{
"AttributeName": "TopScore",
"AttributeType": "N"
},
{
"AttributeName": "UserId",
"AttributeType": "S"
}
],
"TableName": "GameScores",
"KeySchema": [
{
"AttributeName": "UserId",
"KeyType": "HASH"
},
{
"AttributeName": "GameTitle",
"KeyType": "RANGE"
}
],
"TableStatus": "CREATING",
"CreationDateTime": "2020-05-26T17:28:15.602000-07:00",
"ProvisionedThroughput": {
"NumberOfDecreasesToday": 0,
"ReadCapacityUnits": 10,
"WriteCapacityUnits": 5
},
"TableSizeBytes": 0,
"ItemCount": 0,
"TableArn": "arn:aws:dynamodb:us-west-2:123456789012:table/GameScores",
"TableId": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
"GlobalSecondaryIndexes": [
{
"IndexName": "GameTitleIndex",
"KeySchema": [
{
"AttributeName": "GameTitle",
"KeyType": "HASH"
},
{
"AttributeName": "TopScore",
"KeyType": "RANGE"
}
],
"Projection": {
"ProjectionType": "INCLUDE",
"NonKeyAttributes": [
"UserId"
]
},
"IndexStatus": "CREATING",
"ProvisionedThroughput": {
"NumberOfDecreasesToday": 0,
"ReadCapacityUnits": 10,
"WriteCapacityUnits": 5
},
"IndexSizeBytes": 0,
"ItemCount": 0,
"IndexArn": "arn:aws:dynamodb:us-west-2:123456789012:table/GameScores/index/GameTitleIndex"
}
]
}
}
```
For more information, see [Basic Operations for Tables](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/WorkingWithTables.Basics.html) in the *Amazon DynamoDB Developer Guide*.
**Example 6: To create a table with multiple Global Secondary Indexes at once**
The following example creates a table named `GameScores` with two Global Secondary Indexes. The GSI schemas are passed via a file, rather than on the command line.
```
aws dynamodb create-table \
--table-name GameScores \
--attribute-definitions AttributeName=UserId,AttributeType=S AttributeName=GameTitle,AttributeType=S AttributeName=TopScore,AttributeType=N AttributeName=Date,AttributeType=S \
--key-schema AttributeName=UserId,KeyType=HASH AttributeName=GameTitle,KeyType=RANGE \
--provisioned-throughput ReadCapacityUnits=10,WriteCapacityUnits=5 \
--global-secondary-indexes file://gsi.json
```
Contents of `gsi.json`:
```
[
{
"IndexName": "GameTitleIndex",
"KeySchema": [
{
"AttributeName": "GameTitle",
"KeyType": "HASH"
},
{
"AttributeName": "TopScore",
"KeyType": "RANGE"
}
],
"Projection": {
"ProjectionType": "ALL"
},
"ProvisionedThroughput": {
"ReadCapacityUnits": 10,
"WriteCapacityUnits": 5
}
},
{
"IndexName": "GameDateIndex",
"KeySchema": [
{
"AttributeName": "GameTitle",
"KeyType": "HASH"
},
{
"AttributeName": "Date",
"KeyType": "RANGE"
}
],
"Projection": {
"ProjectionType": "ALL"
},
"ProvisionedThroughput": {
"ReadCapacityUnits": 5,
"WriteCapacityUnits": 5
}
}
]
```
Output:
```
{
"TableDescription": {
"AttributeDefinitions": [
{
"AttributeName": "Date",
"AttributeType": "S"
},
{
"AttributeName": "GameTitle",
"AttributeType": "S"
},
{
"AttributeName": "TopScore",
"AttributeType": "N"
},
{
"AttributeName": "UserId",
"AttributeType": "S"
}
],
"TableName": "GameScores",
"KeySchema": [
{
"AttributeName": "UserId",
"KeyType": "HASH"
},
{
"AttributeName": "GameTitle",
"KeyType": "RANGE"
}
],
"TableStatus": "CREATING",
"CreationDateTime": "2020-08-04T16:40:55.524000-07:00",
"ProvisionedThroughput": {
"NumberOfDecreasesToday": 0,
"ReadCapacityUnits": 10,
"WriteCapacityUnits": 5
},
"TableSizeBytes": 0,
"ItemCount": 0,
"TableArn": "arn:aws:dynamodb:us-west-2:123456789012:table/GameScores",
"TableId": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
"GlobalSecondaryIndexes": [
{
"IndexName": "GameTitleIndex",
"KeySchema": [
{
"AttributeName": "GameTitle",
"KeyType": "HASH"
},
{
"AttributeName": "TopScore",
"KeyType": "RANGE"
}
],
"Projection": {
"ProjectionType": "ALL"
},
"IndexStatus": "CREATING",
"ProvisionedThroughput": {
"NumberOfDecreasesToday": 0,
"ReadCapacityUnits": 10,
"WriteCapacityUnits": 5
},
"IndexSizeBytes": 0,
"ItemCount": 0,
"IndexArn": "arn:aws:dynamodb:us-west-2:123456789012:table/GameScores/index/GameTitleIndex"
},
{
"IndexName": "GameDateIndex",
"KeySchema": [
{
"AttributeName": "GameTitle",
"KeyType": "HASH"
},
{
"AttributeName": "Date",
"KeyType": "RANGE"
}
],
"Projection": {
"ProjectionType": "ALL"
},
"IndexStatus": "CREATING",
"ProvisionedThroughput": {
"NumberOfDecreasesToday": 0,
"ReadCapacityUnits": 5,
"WriteCapacityUnits": 5
},
"IndexSizeBytes": 0,
"ItemCount": 0,
"IndexArn": "arn:aws:dynamodb:us-west-2:123456789012:table/GameScores/index/GameDateIndex"
}
]
}
}
```
For more information, see [Basic Operations for Tables](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/WorkingWithTables.Basics.html) in the *Amazon DynamoDB Developer Guide*.
**Example 7: To create a table with Streams enabled**
The following example creates a table called `GameScores` with DynamoDB Streams enabled. Both new and old images of each item will be written to the stream.
```
aws dynamodb create-table \
--table-name GameScores \
--attribute-definitions AttributeName=UserId,AttributeType=S AttributeName=GameTitle,AttributeType=S \
--key-schema AttributeName=UserId,KeyType=HASH AttributeName=GameTitle,KeyType=RANGE \
--provisioned-throughput ReadCapacityUnits=10,WriteCapacityUnits=5 \
--stream-specification StreamEnabled=TRUE,StreamViewType=NEW_AND_OLD_IMAGES
```
Output:
```
{
"TableDescription": {
"AttributeDefinitions": [
{
"AttributeName": "GameTitle",
"AttributeType": "S"
},
{
"AttributeName": "UserId",
"AttributeType": "S"
}
],
"TableName": "GameScores",
"KeySchema": [
{
"AttributeName": "UserId",
"KeyType": "HASH"
},
{
"AttributeName": "GameTitle",
"KeyType": "RANGE"
}
],
"TableStatus": "CREATING",
"CreationDateTime": "2020-05-27T10:49:34.056000-07:00",
"ProvisionedThroughput": {
"NumberOfDecreasesToday": 0,
"ReadCapacityUnits": 10,
"WriteCapacityUnits": 5
},
"TableSizeBytes": 0,
"ItemCount": 0,
"TableArn": "arn:aws:dynamodb:us-west-2:123456789012:table/GameScores",
"TableId": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
"StreamSpecification": {
"StreamEnabled": true,
"StreamViewType": "NEW_AND_OLD_IMAGES"
},
"LatestStreamLabel": "2020-05-27T17:49:34.056",
"LatestStreamArn": "arn:aws:dynamodb:us-west-2:123456789012:table/GameScores/stream/2020-05-27T17:49:34.056"
}
}
```
For more information, see [Basic Operations for Tables](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/WorkingWithTables.Basics.html) in the *Amazon DynamoDB Developer Guide*.
**Example 8: To create a table with Keys-Only Stream enabled**
The following example creates a table called `GameScores` with DynamoDB Streams enabled. Only the key attributes of modified items are written to the stream.
```
aws dynamodb create-table \
--table-name GameScores \
--attribute-definitions AttributeName=UserId,AttributeType=S AttributeName=GameTitle,AttributeType=S \
--key-schema AttributeName=UserId,KeyType=HASH AttributeName=GameTitle,KeyType=RANGE \
--provisioned-throughput ReadCapacityUnits=10,WriteCapacityUnits=5 \
--stream-specification StreamEnabled=TRUE,StreamViewType=KEYS_ONLY
```
Output:
```
{
"TableDescription": {
"AttributeDefinitions": [
{
"AttributeName": "GameTitle",
"AttributeType": "S"
},
{
"AttributeName": "UserId",
"AttributeType": "S"
}
],
"TableName": "GameScores",
"KeySchema": [
{
"AttributeName": "UserId",
"KeyType": "HASH"
},
{
"AttributeName": "GameTitle",
"KeyType": "RANGE"
}
],
"TableStatus": "CREATING",
"CreationDateTime": "2023-05-25T18:45:34.140000+00:00",
"ProvisionedThroughput": {
"NumberOfDecreasesToday": 0,
"ReadCapacityUnits": 10,
"WriteCapacityUnits": 5
},
"TableSizeBytes": 0,
"ItemCount": 0,
"TableArn": "arn:aws:dynamodb:us-west-2:123456789012:table/GameScores",
"TableId": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
"StreamSpecification": {
"StreamEnabled": true,
"StreamViewType": "KEYS_ONLY"
},
"LatestStreamLabel": "2023-05-25T18:45:34.140",
"LatestStreamArn": "arn:aws:dynamodb:us-west-2:123456789012:table/GameScores/stream/2023-05-25T18:45:34.140",
"DeletionProtectionEnabled": false
}
}
```
For more information, see [Change data capture for DynamoDB Streams](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Streams.html) in the *Amazon DynamoDB Developer Guide*.
**Example 9: To create a table with the Standard Infrequent Access class**
The following example creates a table called `GameScores` and assigns the Standard-Infrequent Access (DynamoDB Standard-IA) table class. This table class is optimized for storage being the dominant cost.
```
aws dynamodb create-table \
--table-name GameScores \
--attribute-definitions AttributeName=UserId,AttributeType=S AttributeName=GameTitle,AttributeType=S \
--key-schema AttributeName=UserId,KeyType=HASH AttributeName=GameTitle,KeyType=RANGE \
--provisioned-throughput ReadCapacityUnits=10,WriteCapacityUnits=5 \
--table-class STANDARD_INFREQUENT_ACCESS
```
Output:
```
{
"TableDescription": {
"AttributeDefinitions": [
{
"AttributeName": "GameTitle",
"AttributeType": "S"
},
{
"AttributeName": "UserId",
"AttributeType": "S"
}
],
"TableName": "GameScores",
"KeySchema": [
{
"AttributeName": "UserId",
"KeyType": "HASH"
},
{
"AttributeName": "GameTitle",
"KeyType": "RANGE"
}
],
"TableStatus": "CREATING",
"CreationDateTime": "2023-05-25T18:33:07.581000+00:00",
"ProvisionedThroughput": {
"NumberOfDecreasesToday": 0,
"ReadCapacityUnits": 10,
"WriteCapacityUnits": 5
},
"TableSizeBytes": 0,
"ItemCount": 0,
"TableArn": "arn:aws:dynamodb:us-west-2:123456789012:table/GameScores",
"TableId": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
"TableClassSummary": {
"TableClass": "STANDARD_INFREQUENT_ACCESS"
},
"DeletionProtectionEnabled": false
}
}
```
For more information, see [Table classes](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.TableClasses.html) in the *Amazon DynamoDB Developer Guide*.
**Example 10: To Create a table with Delete Protection enabled**
The following example creates a table called `GameScores` and enables deletion protection.
```
aws dynamodb create-table \
--table-name GameScores \
--attribute-definitions AttributeName=UserId,AttributeType=S AttributeName=GameTitle,AttributeType=S \
--key-schema AttributeName=UserId,KeyType=HASH AttributeName=GameTitle,KeyType=RANGE \
--provisioned-throughput ReadCapacityUnits=10,WriteCapacityUnits=5 \
--deletion-protection-enabled
```
Output:
```
{
"TableDescription": {
"AttributeDefinitions": [
{
"AttributeName": "GameTitle",
"AttributeType": "S"
},
{
"AttributeName": "UserId",
"AttributeType": "S"
}
],
"TableName": "GameScores",
"KeySchema": [
{
"AttributeName": "UserId",
"KeyType": "HASH"
},
{
"AttributeName": "GameTitle",
"KeyType": "RANGE"
}
],
"TableStatus": "CREATING",
"CreationDateTime": "2023-05-25T23:02:17.093000+00:00",
"ProvisionedThroughput": {
"NumberOfDecreasesToday": 0,
"ReadCapacityUnits": 10,
"WriteCapacityUnits": 5
},
"TableSizeBytes": 0,
"ItemCount": 0,
"TableArn": "arn:aws:dynamodb:us-west-2:123456789012:table/GameScores",
"TableId": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
"DeletionProtectionEnabled": true
}
}
```
For more information, see [Using deletion protection](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/WorkingWithTables.Basics.html#WorkingWithTables.Basics.DeletionProtection) in the *Amazon DynamoDB Developer Guide*.
+ For API details, see [CreateTable](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/dynamodb/create-table.html) in *Amazon CLI Command Reference*.
------
#### [ Go ]
**SDK for Go V2**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/gov2/dynamodb#code-examples).
```
import (
"context"
"errors"
"log"
"time"
"github.com/aws/aws-sdk-go-v2/aws"
"github.com/aws/aws-sdk-go-v2/feature/dynamodb/attributevalue"
"github.com/aws/aws-sdk-go-v2/feature/dynamodb/expression"
"github.com/aws/aws-sdk-go-v2/service/dynamodb"
"github.com/aws/aws-sdk-go-v2/service/dynamodb/types"
)
// TableBasics encapsulates the Amazon DynamoDB service actions used in the examples.
// It contains a DynamoDB service client that is used to act on the specified table.
type TableBasics struct {
DynamoDbClient *dynamodb.Client
TableName string
}
// CreateMovieTable creates a DynamoDB table with a composite primary key defined as
// a string sort key named `title`, and a numeric partition key named `year`.
// This function uses NewTableExistsWaiter to wait for the table to be created by
// DynamoDB before it returns.
func (basics TableBasics) CreateMovieTable(ctx context.Context) (*types.TableDescription, error) {
var tableDesc *types.TableDescription
table, err := basics.DynamoDbClient.CreateTable(ctx, &dynamodb.CreateTableInput{
AttributeDefinitions: []types.AttributeDefinition{{
AttributeName: aws.String("year"),
AttributeType: types.ScalarAttributeTypeN,
}, {
AttributeName: aws.String("title"),
AttributeType: types.ScalarAttributeTypeS,
}},
KeySchema: []types.KeySchemaElement{{
AttributeName: aws.String("year"),
KeyType: types.KeyTypeHash,
}, {
AttributeName: aws.String("title"),
KeyType: types.KeyTypeRange,
}},
TableName: aws.String(basics.TableName),
BillingMode: types.BillingModePayPerRequest,
})
if err != nil {
log.Printf("Couldn't create table %v. Here's why: %v\n", basics.TableName, err)
} else {
waiter := dynamodb.NewTableExistsWaiter(basics.DynamoDbClient)
err = waiter.Wait(ctx, &dynamodb.DescribeTableInput{
TableName: aws.String(basics.TableName)}, 5*time.Minute)
if err != nil {
log.Printf("Wait for table exists failed. Here's why: %v\n", err)
}
tableDesc = table.TableDescription
log.Printf("Ccreating table test")
}
return tableDesc, err
}
```
+ For API details, see [CreateTable](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/service/dynamodb#Client.CreateTable) in *Amazon SDK for Go API Reference*.
------
#### [ Java ]
**SDK for Java 2.x**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2/example_code/dynamodb#code-examples).
```
import software.amazon.awssdk.core.waiters.WaiterResponse;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
import software.amazon.awssdk.services.dynamodb.model.AttributeDefinition;
import software.amazon.awssdk.services.dynamodb.model.BillingMode;
import software.amazon.awssdk.services.dynamodb.model.CreateTableRequest;
import software.amazon.awssdk.services.dynamodb.model.CreateTableResponse;
import software.amazon.awssdk.services.dynamodb.model.DescribeTableRequest;
import software.amazon.awssdk.services.dynamodb.model.DescribeTableResponse;
import software.amazon.awssdk.services.dynamodb.model.DynamoDbException;
import software.amazon.awssdk.services.dynamodb.model.KeySchemaElement;
import software.amazon.awssdk.services.dynamodb.model.KeyType;
import software.amazon.awssdk.services.dynamodb.model.OnDemandThroughput;
import software.amazon.awssdk.services.dynamodb.model.ProvisionedThroughput;
import software.amazon.awssdk.services.dynamodb.model.ScalarAttributeType;
import software.amazon.awssdk.services.dynamodb.waiters.DynamoDbWaiter;
/**
* Before running this Java V2 code example, set up your development
* environment, including your credentials.
*
* For more information, see the following documentation topic:
*
* https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/get-started.html
*/
public class CreateTable {
public static void main(String[] args) {
final String usage = """
Usage:
Where:
tableName - The Amazon DynamoDB table to create (for example, Music3).
key - The key for the Amazon DynamoDB table (for example, Artist).
""";
if (args.length != 2) {
System.out.println(usage);
System.exit(1);
}
String tableName = args[0];
String key = args[1];
System.out.println("Creating an Amazon DynamoDB table " + tableName + " with a simple primary key: " + key);
Region region = Region.US_EAST_1;
DynamoDbClient ddb = DynamoDbClient.builder()
.region(region)
.build();
String result = createTable(ddb, tableName, key);
System.out.println("New table is " + result);
ddb.close();
}
public static String createTable(DynamoDbClient ddb, String tableName, String key) {
DynamoDbWaiter dbWaiter = ddb.waiter();
CreateTableRequest request = CreateTableRequest.builder()
.attributeDefinitions(AttributeDefinition.builder()
.attributeName(key)
.attributeType(ScalarAttributeType.S)
.build())
.keySchema(KeySchemaElement.builder()
.attributeName(key)
.keyType(KeyType.HASH)
.build())
.billingMode(BillingMode.PAY_PER_REQUEST) // DynamoDB automatically scales based on traffic.
.tableName(tableName)
.build();
String newTable;
try {
CreateTableResponse response = ddb.createTable(request);
DescribeTableRequest tableRequest = DescribeTableRequest.builder()
.tableName(tableName)
.build();
// Wait until the Amazon DynamoDB table is created.
WaiterResponse waiterResponse = dbWaiter.waitUntilTableExists(tableRequest);
waiterResponse.matched().response().ifPresent(System.out::println);
newTable = response.tableDescription().tableName();
return newTable;
} catch (DynamoDbException e) {
System.err.println(e.getMessage());
System.exit(1);
}
return "";
}
}
```
+ For API details, see [CreateTable](https://docs.amazonaws.cn/goto/SdkForJavaV2/dynamodb-2012-08-10/CreateTable) in *Amazon SDK for Java 2.x API Reference*.
------
#### [ JavaScript ]
**SDK for JavaScript (v3)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javascriptv3/example_code/dynamodb#code-examples).
```
import { CreateTableCommand, DynamoDBClient } from "@aws-sdk/client-dynamodb";
const client = new DynamoDBClient({});
export const main = async () => {
const command = new CreateTableCommand({
TableName: "EspressoDrinks",
// For more information about data types,
// see https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html#HowItWorks.DataTypes and
// https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Programming.LowLevelAPI.html#Programming.LowLevelAPI.DataTypeDescriptors
AttributeDefinitions: [
{
AttributeName: "DrinkName",
AttributeType: "S",
},
],
KeySchema: [
{
AttributeName: "DrinkName",
KeyType: "HASH",
},
],
BillingMode: "PAY_PER_REQUEST",
});
const response = await client.send(command);
console.log(response);
return response;
};
```
+ For more information, see [Amazon SDK for JavaScript Developer Guide](https://docs.amazonaws.cn/sdk-for-javascript/v3/developer-guide/dynamodb-examples-using-tables.html#dynamodb-examples-using-tables-creating-a-table).
+ For API details, see [CreateTable](https://docs.amazonaws.cn/AWSJavaScriptSDK/v3/latest/client/dynamodb/command/CreateTableCommand) in *Amazon SDK for JavaScript API Reference*.
**SDK for JavaScript (v2)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javascript/example_code/dynamodb#code-examples).
```
// Load the AWS SDK for Node.js
var AWS = require("aws-sdk");
// Set the region
AWS.config.update({ region: "REGION" });
// Create the DynamoDB service object
var ddb = new AWS.DynamoDB({ apiVersion: "2012-08-10" });
var params = {
AttributeDefinitions: [
{
AttributeName: "CUSTOMER_ID",
AttributeType: "N",
},
{
AttributeName: "CUSTOMER_NAME",
AttributeType: "S",
},
],
KeySchema: [
{
AttributeName: "CUSTOMER_ID",
KeyType: "HASH",
},
{
AttributeName: "CUSTOMER_NAME",
KeyType: "RANGE",
},
],
ProvisionedThroughput: {
ReadCapacityUnits: 1,
WriteCapacityUnits: 1,
},
TableName: "CUSTOMER_LIST",
StreamSpecification: {
StreamEnabled: false,
},
};
// Call DynamoDB to create the table
ddb.createTable(params, function (err, data) {
if (err) {
console.log("Error", err);
} else {
console.log("Table Created", data);
}
});
```
+ For more information, see [Amazon SDK for JavaScript Developer Guide](https://docs.amazonaws.cn/sdk-for-javascript/v2/developer-guide/dynamodb-examples-using-tables.html#dynamodb-examples-using-tables-creating-a-table).
+ For API details, see [CreateTable](https://docs.amazonaws.cn/goto/AWSJavaScriptSDK/dynamodb-2012-08-10/CreateTable) in *Amazon SDK for JavaScript API Reference*.
------
#### [ Kotlin ]
**SDK for Kotlin**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/kotlin/services/dynamodb#code-examples).
```
suspend fun createNewTable(
tableNameVal: String,
key: String,
): String? {
val attDef =
AttributeDefinition {
attributeName = key
attributeType = ScalarAttributeType.S
}
val keySchemaVal =
KeySchemaElement {
attributeName = key
keyType = KeyType.Hash
}
val request =
CreateTableRequest {
attributeDefinitions = listOf(attDef)
keySchema = listOf(keySchemaVal)
billingMode = BillingMode.PayPerRequest
tableName = tableNameVal
}
DynamoDbClient.fromEnvironment { region = "us-east-1" }.use { ddb ->
var tableArn: String
val response = ddb.createTable(request)
ddb.waitUntilTableExists {
// suspend call
tableName = tableNameVal
}
tableArn = response.tableDescription!!.tableArn.toString()
println("Table $tableArn is ready")
return tableArn
}
}
```
+ For API details, see [CreateTable](https://sdk.amazonaws.com/kotlin/api/latest/index.html) in *Amazon SDK for Kotlin API reference*.
------
#### [ PHP ]
**SDK for PHP**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code/dynamodb#code-examples).
Create a table.
```
$tableName = "ddb_demo_table_$uuid";
$service->createTable(
$tableName,
[
new DynamoDBAttribute('year', 'N', 'HASH'),
new DynamoDBAttribute('title', 'S', 'RANGE')
]
);
public function createTable(string $tableName, array $attributes)
{
$keySchema = [];
$attributeDefinitions = [];
foreach ($attributes as $attribute) {
if (is_a($attribute, DynamoDBAttribute::class)) {
$keySchema[] = ['AttributeName' => $attribute->AttributeName, 'KeyType' => $attribute->KeyType];
$attributeDefinitions[] =
['AttributeName' => $attribute->AttributeName, 'AttributeType' => $attribute->AttributeType];
}
}
$this->dynamoDbClient->createTable([
'TableName' => $tableName,
'KeySchema' => $keySchema,
'AttributeDefinitions' => $attributeDefinitions,
'ProvisionedThroughput' => ['ReadCapacityUnits' => 10, 'WriteCapacityUnits' => 10],
]);
}
```
+ For API details, see [CreateTable](https://docs.amazonaws.cn/goto/SdkForPHPV3/dynamodb-2012-08-10/CreateTable) in *Amazon SDK for PHP API Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: This example creates a table named Thread that has a primary key consisting of 'ForumName' (key type hash) and 'Subject' (key type range). The schema used to construct the table can be piped into each cmdlet as shown or specified using the -Schema parameter.**
```
$schema = New-DDBTableSchema
$schema | Add-DDBKeySchema -KeyName "ForumName" -KeyDataType "S"
$schema | Add-DDBKeySchema -KeyName "Subject" -KeyType RANGE -KeyDataType "S"
$schema | New-DDBTable -TableName "Thread" -ReadCapacity 10 -WriteCapacity 5
```
**Output:**
```
AttributeDefinitions : {ForumName, Subject}
TableName : Thread
KeySchema : {ForumName, Subject}
TableStatus : CREATING
CreationDateTime : 10/28/2013 4:39:49 PM
ProvisionedThroughput : Amazon.DynamoDBv2.Model.ProvisionedThroughputDescription
TableSizeBytes : 0
ItemCount : 0
LocalSecondaryIndexes : {}
```
**Example 2: This example creates a table named Thread that has a primary key consisting of 'ForumName' (key type hash) and 'Subject' (key type range). A local secondary index is also defined. The key of the local secondary index will be set automatically from the primary hash key on the table (ForumName). The schema used to construct the table can be piped into each cmdlet as shown or specified using the -Schema parameter.**
```
$schema = New-DDBTableSchema
$schema | Add-DDBKeySchema -KeyName "ForumName" -KeyDataType "S"
$schema | Add-DDBKeySchema -KeyName "Subject" -KeyDataType "S"
$schema | Add-DDBIndexSchema -IndexName "LastPostIndex" -RangeKeyName "LastPostDateTime" -RangeKeyDataType "S" -ProjectionType "keys_only"
$schema | New-DDBTable -TableName "Thread" -ReadCapacity 10 -WriteCapacity 5
```
**Output:**
```
AttributeDefinitions : {ForumName, LastPostDateTime, Subject}
TableName : Thread
KeySchema : {ForumName, Subject}
TableStatus : CREATING
CreationDateTime : 10/28/2013 4:39:49 PM
ProvisionedThroughput : Amazon.DynamoDBv2.Model.ProvisionedThroughputDescription
TableSizeBytes : 0
ItemCount : 0
LocalSecondaryIndexes : {LastPostIndex}
```
**Example 3: This example shows how to use a single pipeline to create a table named Thread that has a primary key consisting of 'ForumName' (key type hash) and 'Subject' (key type range) and a local secondary index. The Add-DDBKeySchema and Add-DDBIndexSchema create a new TableSchema object for you if one is not supplied from the pipeline or the -Schema parameter.**
```
New-DDBTableSchema |
Add-DDBKeySchema -KeyName "ForumName" -KeyDataType "S" |
Add-DDBKeySchema -KeyName "Subject" -KeyDataType "S" |
Add-DDBIndexSchema -IndexName "LastPostIndex" `
-RangeKeyName "LastPostDateTime" `
-RangeKeyDataType "S" `
-ProjectionType "keys_only" |
New-DDBTable -TableName "Thread" -ReadCapacity 10 -WriteCapacity 5
```
**Output:**
```
AttributeDefinitions : {ForumName, LastPostDateTime, Subject}
TableName : Thread
KeySchema : {ForumName, Subject}
TableStatus : CREATING
CreationDateTime : 10/28/2013 4:39:49 PM
ProvisionedThroughput : Amazon.DynamoDBv2.Model.ProvisionedThroughputDescription
TableSizeBytes : 0
ItemCount : 0
LocalSecondaryIndexes : {LastPostIndex}
```
+ For API details, see [CreateTable](https://docs.aws.amazon.com/powershell/v4/reference) in *Amazon Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: This example creates a table named Thread that has a primary key consisting of 'ForumName' (key type hash) and 'Subject' (key type range). The schema used to construct the table can be piped into each cmdlet as shown or specified using the -Schema parameter.**
```
$schema = New-DDBTableSchema
$schema | Add-DDBKeySchema -KeyName "ForumName" -KeyDataType "S"
$schema | Add-DDBKeySchema -KeyName "Subject" -KeyType RANGE -KeyDataType "S"
$schema | New-DDBTable -TableName "Thread" -ReadCapacity 10 -WriteCapacity 5
```
**Output:**
```
AttributeDefinitions : {ForumName, Subject}
TableName : Thread
KeySchema : {ForumName, Subject}
TableStatus : CREATING
CreationDateTime : 10/28/2013 4:39:49 PM
ProvisionedThroughput : Amazon.DynamoDBv2.Model.ProvisionedThroughputDescription
TableSizeBytes : 0
ItemCount : 0
LocalSecondaryIndexes : {}
```
**Example 2: This example creates a table named Thread that has a primary key consisting of 'ForumName' (key type hash) and 'Subject' (key type range). A local secondary index is also defined. The key of the local secondary index will be set automatically from the primary hash key on the table (ForumName). The schema used to construct the table can be piped into each cmdlet as shown or specified using the -Schema parameter.**
```
$schema = New-DDBTableSchema
$schema | Add-DDBKeySchema -KeyName "ForumName" -KeyDataType "S"
$schema | Add-DDBKeySchema -KeyName "Subject" -KeyDataType "S"
$schema | Add-DDBIndexSchema -IndexName "LastPostIndex" -RangeKeyName "LastPostDateTime" -RangeKeyDataType "S" -ProjectionType "keys_only"
$schema | New-DDBTable -TableName "Thread" -ReadCapacity 10 -WriteCapacity 5
```
**Output:**
```
AttributeDefinitions : {ForumName, LastPostDateTime, Subject}
TableName : Thread
KeySchema : {ForumName, Subject}
TableStatus : CREATING
CreationDateTime : 10/28/2013 4:39:49 PM
ProvisionedThroughput : Amazon.DynamoDBv2.Model.ProvisionedThroughputDescription
TableSizeBytes : 0
ItemCount : 0
LocalSecondaryIndexes : {LastPostIndex}
```
**Example 3: This example shows how to use a single pipeline to create a table named Thread that has a primary key consisting of 'ForumName' (key type hash) and 'Subject' (key type range) and a local secondary index. The Add-DDBKeySchema and Add-DDBIndexSchema create a new TableSchema object for you if one is not supplied from the pipeline or the -Schema parameter.**
```
New-DDBTableSchema |
Add-DDBKeySchema -KeyName "ForumName" -KeyDataType "S" |
Add-DDBKeySchema -KeyName "Subject" -KeyDataType "S" |
Add-DDBIndexSchema -IndexName "LastPostIndex" `
-RangeKeyName "LastPostDateTime" `
-RangeKeyDataType "S" `
-ProjectionType "keys_only" |
New-DDBTable -TableName "Thread" -ReadCapacity 10 -WriteCapacity 5
```
**Output:**
```
AttributeDefinitions : {ForumName, LastPostDateTime, Subject}
TableName : Thread
KeySchema : {ForumName, Subject}
TableStatus : CREATING
CreationDateTime : 10/28/2013 4:39:49 PM
ProvisionedThroughput : Amazon.DynamoDBv2.Model.ProvisionedThroughputDescription
TableSizeBytes : 0
ItemCount : 0
LocalSecondaryIndexes : {LastPostIndex}
```
+ For API details, see [CreateTable](https://docs.aws.amazon.com/powershell/v5/reference) in *Amazon Tools for PowerShell Cmdlet Reference (V5)*.
------
#### [ Python ]
**SDK for Python (Boto3)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/dynamodb#code-examples).
Create a table for storing movie data.
```
class Movies:
"""Encapsulates an Amazon DynamoDB table of movie data.
Example data structure for a movie record in this table:
{
"year": 1999,
"title": "For Love of the Game",
"info": {
"directors": ["Sam Raimi"],
"release_date": "1999-09-15T00:00:00Z",
"rating": 6.3,
"plot": "A washed up pitcher flashes through his career.",
"rank": 4987,
"running_time_secs": 8220,
"actors": [
"Kevin Costner",
"Kelly Preston",
"John C. Reilly"
]
}
}
"""
def __init__(self, dyn_resource):
"""
:param dyn_resource: A Boto3 DynamoDB resource.
"""
self.dyn_resource = dyn_resource
# The table variable is set during the scenario in the call to
# 'exists' if the table exists. Otherwise, it is set by 'create_table'.
self.table = None
def create_table(self, table_name):
"""
Creates an Amazon DynamoDB table that can be used to store movie data.
The table uses the release year of the movie as the partition key and the
title as the sort key.
:param table_name: The name of the table to create.
:return: The newly created table.
"""
try:
self.table = self.dyn_resource.create_table(
TableName=table_name,
KeySchema=[
{"AttributeName": "year", "KeyType": "HASH"}, # Partition key
{"AttributeName": "title", "KeyType": "RANGE"}, # Sort key
],
AttributeDefinitions=[
{"AttributeName": "year", "AttributeType": "N"},
{"AttributeName": "title", "AttributeType": "S"},
],
BillingMode='PAY_PER_REQUEST',
)
self.table.wait_until_exists()
except ClientError as err:
logger.error(
"Couldn't create table %s. Here's why: %s: %s",
table_name,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
else:
return self.table
```
+ For API details, see [CreateTable](https://docs.amazonaws.cn/goto/boto3/dynamodb-2012-08-10/CreateTable) in *Amazon SDK for Python (Boto3) API Reference*.
------
#### [ Ruby ]
**SDK for Ruby**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/ruby/example_code/dynamodb#code-examples).
```
# Encapsulates an Amazon DynamoDB table of movie data.
class Scaffold
attr_reader :dynamo_resource, :table_name, :table
def initialize(table_name)
client = Aws::DynamoDB::Client.new(region: 'us-east-1')
@dynamo_resource = Aws::DynamoDB::Resource.new(client: client)
@table_name = table_name
@table = nil
@logger = Logger.new($stdout)
@logger.level = Logger::DEBUG
end
# Creates an Amazon DynamoDB table that can be used to store movie data.
# The table uses the release year of the movie as the partition key and the
# title as the sort key.
#
# @param table_name [String] The name of the table to create.
# @return [Aws::DynamoDB::Table] The newly created table.
def create_table(table_name)
@table = @dynamo_resource.create_table(
table_name: table_name,
key_schema: [
{ attribute_name: 'year', key_type: 'HASH' }, # Partition key
{ attribute_name: 'title', key_type: 'RANGE' } # Sort key
],
attribute_definitions: [
{ attribute_name: 'year', attribute_type: 'N' },
{ attribute_name: 'title', attribute_type: 'S' }
],
billing_mode: 'PAY_PER_REQUEST'
)
@dynamo_resource.client.wait_until(:table_exists, table_name: table_name)
@table
rescue Aws::DynamoDB::Errors::ServiceError => e
@logger.error("Failed create table #{table_name}:\n#{e.code}: #{e.message}")
raise
end
```
+ For API details, see [CreateTable](https://docs.amazonaws.cn/goto/SdkForRubyV3/dynamodb-2012-08-10/CreateTable) in *Amazon SDK for Ruby API Reference*.
------
#### [ Rust ]
**SDK for Rust**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/rustv1/examples/dynamodb#code-examples).
```
pub async fn create_table(
client: &Client,
table: &str,
key: &str,
) -> Result {
let a_name: String = key.into();
let table_name: String = table.into();
let ad = AttributeDefinition::builder()
.attribute_name(&a_name)
.attribute_type(ScalarAttributeType::S)
.build()
.map_err(Error::BuildError)?;
let ks = KeySchemaElement::builder()
.attribute_name(&a_name)
.key_type(KeyType::Hash)
.build()
.map_err(Error::BuildError)?;
let create_table_response = client
.create_table()
.table_name(table_name)
.key_schema(ks)
.attribute_definitions(ad)
.billing_mode(BillingMode::PayPerRequest)
.send()
.await;
match create_table_response {
Ok(out) => {
println!("Added table {} with key {}", table, key);
Ok(out)
}
Err(e) => {
eprintln!("Got an error creating table:");
eprintln!("{}", e);
Err(Error::unhandled(e))
}
}
}
```
+ For API details, see [CreateTable](https://docs.rs/aws-sdk-dynamodb/latest/aws_sdk_dynamodb/client/struct.Client.html#method.create_table) in *Amazon SDK for Rust API reference*.
------
#### [ SAP ABAP ]
**SDK for SAP ABAP**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/sap-abap/services/dyn#code-examples).
```
TRY.
DATA(lt_keyschema) = VALUE /aws1/cl_dynkeyschemaelement=>tt_keyschema(
( NEW /aws1/cl_dynkeyschemaelement( iv_attributename = 'year'
iv_keytype = 'HASH' ) )
( NEW /aws1/cl_dynkeyschemaelement( iv_attributename = 'title'
iv_keytype = 'RANGE' ) ) ).
DATA(lt_attributedefinitions) = VALUE /aws1/cl_dynattributedefn=>tt_attributedefinitions(
( NEW /aws1/cl_dynattributedefn( iv_attributename = 'year'
iv_attributetype = 'N' ) )
( NEW /aws1/cl_dynattributedefn( iv_attributename = 'title'
iv_attributetype = 'S' ) ) ).
" Adjust read/write capacities as desired.
DATA(lo_dynprovthroughput) = NEW /aws1/cl_dynprovthroughput(
iv_readcapacityunits = 5
iv_writecapacityunits = 5 ).
oo_result = lo_dyn->createtable(
it_keyschema = lt_keyschema
iv_tablename = iv_table_name
it_attributedefinitions = lt_attributedefinitions
io_provisionedthroughput = lo_dynprovthroughput ).
" Table creation can take some time. Wait till table exists before returning.
lo_dyn->get_waiter( )->tableexists(
iv_max_wait_time = 200
iv_tablename = iv_table_name ).
MESSAGE 'DynamoDB Table' && iv_table_name && 'created.' TYPE 'I'.
" This exception can happen if the table already exists.
CATCH /aws1/cx_dynresourceinuseex INTO DATA(lo_resourceinuseex).
DATA(lv_error) = |"{ lo_resourceinuseex->av_err_code }" - { lo_resourceinuseex->av_err_msg }|.
MESSAGE lv_error TYPE 'E'.
ENDTRY.
```
+ For API details, see [CreateTable](https://docs.amazonaws.cn/sdk-for-sap-abap/v1/api/latest/index.html) in *Amazon SDK for SAP ABAP API reference*.
------
#### [ Swift ]
**SDK for Swift**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/swift/example_code/dynamodb#code-examples).
```
import AWSDynamoDB
///
/// Create a movie table in the Amazon DynamoDB data store.
///
private func createTable() async throws {
do {
guard let client = self.ddbClient else {
throw MoviesError.UninitializedClient
}
let input = CreateTableInput(
attributeDefinitions: [
DynamoDBClientTypes.AttributeDefinition(attributeName: "year", attributeType: .n),
DynamoDBClientTypes.AttributeDefinition(attributeName: "title", attributeType: .s)
],
billingMode: DynamoDBClientTypes.BillingMode.payPerRequest,
keySchema: [
DynamoDBClientTypes.KeySchemaElement(attributeName: "year", keyType: .hash),
DynamoDBClientTypes.KeySchemaElement(attributeName: "title", keyType: .range)
],
tableName: self.tableName
)
let output = try await client.createTable(input: input)
if output.tableDescription == nil {
throw MoviesError.TableNotFound
}
} catch {
print("ERROR: createTable:", dump(error))
throw error
}
}
```
+ For API details, see [CreateTable](https://sdk.amazonaws.com/swift/api/awsdynamodb/latest/documentation/awsdynamodb/dynamodbclient/createtable(input:)) in *Amazon SDK for Swift API reference*.
------
For more DynamoDB examples, see [Code examples for DynamoDB using Amazon SDKs](service_code_examples.md).
After creating the new table, proceed to [Step 2: Write data to a DynamoDB table](getting-started-step-2.md).
# Step 2: Write data to a DynamoDB table
In this step, you insert several items into the `Music` table that you created in [Step 1: Create a table in DynamoDB](getting-started-step-1.md).
For more information about write operations, see [Writing an item](WorkingWithItems.md#WorkingWithItems.WritingData).
## Amazon Web Services Management Console
Follow these steps to write data to the `Music` table using the DynamoDB console.
1. Open the DynamoDB console at [https://console.amazonaws.cn/dynamodb/](https://console.amazonaws.cn/dynamodb/).
1. In the left navigation pane, choose **Tables**.
1. On the **Tables** page, choose the **Music** table.
1. Choose **Explore table items**.
1. In the **Items returned** section, choose **Create item**.
1. On the **Create item** page, do the following to add items to your table:
1. Choose **Add new attribute**, and then choose **Number**.
1. For Attribute name, enter **Awards**.
1. Repeat this process to create an **AlbumTitle** of type **String**.
1. Enter the following values for your item:
1. For **Artist**, enter **No One You Know**.
1. For **SongTitle**, enter **Call Me Today**.
1. For **AlbumTitle**, enter **Somewhat Famous**.
1. For **Awards**, enter **1**.
1. Choose **Create item**.
1. Repeat this process and create another item with the following values:
1. For **Artist**, enter **Acme Band**.
1. For **SongTitle** enter **Happy Day**.
1. For **AlbumTitle**, enter **Songs About Life**.
1. For **Awards**, enter **10**.
1. Do this one more time to create another item with the same **Artist** as the previous step, but different values for the other attributes:
1. For **Artist**, enter **Acme Band**.
1. For **SongTitle** enter **PartiQL Rocks**.
1. For **AlbumTitle**, enter **Another Album Title**.
1. For **Awards**, enter **8**.
## Amazon CLI
The following Amazon CLI example creates several new items in the `Music` table. You can do this either through the DynamoDB API or [PartiQL](https://docs.amazonaws.cn/amazondynamodb/latest/developerguide/ql-reference.html), a SQL-compatible query language for DynamoDB.
------
#### [ DynamoDB API ]
**Linux**
```
aws dynamodb put-item \
--table-name Music \
--item \
'{"Artist": {"S": "No One You Know"}, "SongTitle": {"S": "Call Me Today"}, "AlbumTitle": {"S": "Somewhat Famous"}, "Awards": {"N": "1"}}'
aws dynamodb put-item \
--table-name Music \
--item \
'{"Artist": {"S": "No One You Know"}, "SongTitle": {"S": "Howdy"}, "AlbumTitle": {"S": "Somewhat Famous"}, "Awards": {"N": "2"}}'
aws dynamodb put-item \
--table-name Music \
--item \
'{"Artist": {"S": "Acme Band"}, "SongTitle": {"S": "Happy Day"}, "AlbumTitle": {"S": "Songs About Life"}, "Awards": {"N": "10"}}'
aws dynamodb put-item \
--table-name Music \
--item \
'{"Artist": {"S": "Acme Band"}, "SongTitle": {"S": "PartiQL Rocks"}, "AlbumTitle": {"S": "Another Album Title"}, "Awards": {"N": "8"}}'
```
**Windows CMD**
```
aws dynamodb put-item ^
--table-name Music ^
--item ^
"{\"Artist\": {\"S\": \"No One You Know\"}, \"SongTitle\": {\"S\": \"Call Me Today\"}, \"AlbumTitle\": {\"S\": \"Somewhat Famous\"}, \"Awards\": {\"N\": \"1\"}}"
aws dynamodb put-item ^
--table-name Music ^
--item ^
"{\"Artist\": {\"S\": \"No One You Know\"}, \"SongTitle\": {\"S\": \"Howdy\"}, \"AlbumTitle\": {\"S\": \"Somewhat Famous\"}, \"Awards\": {\"N\": \"2\"}}"
aws dynamodb put-item ^
--table-name Music ^
--item ^
"{\"Artist\": {\"S\": \"Acme Band\"}, \"SongTitle\": {\"S\": \"Happy Day\"}, \"AlbumTitle\": {\"S\": \"Songs About Life\"}, \"Awards\": {\"N\": \"10\"}}"
aws dynamodb put-item ^
--table-name Music ^
--item ^
"{\"Artist\": {\"S\": \"Acme Band\"}, \"SongTitle\": {\"S\": \"PartiQL Rocks\"}, \"AlbumTitle\": {\"S\": \"Another Album Title\"}, \"Awards\": {\"N\": \"8\"}}"
```
------
#### [ PartiQL for DynamoDB ]
**Linux**
```
aws dynamodb execute-statement --statement "INSERT INTO Music \
VALUE \
{'Artist':'No One You Know','SongTitle':'Call Me Today', 'AlbumTitle':'Somewhat Famous', 'Awards':'1'}"
aws dynamodb execute-statement --statement "INSERT INTO Music \
VALUE \
{'Artist':'No One You Know','SongTitle':'Howdy', 'AlbumTitle':'Somewhat Famous', 'Awards':'2'}"
aws dynamodb execute-statement --statement "INSERT INTO Music \
VALUE \
{'Artist':'Acme Band','SongTitle':'Happy Day', 'AlbumTitle':'Songs About Life', 'Awards':'10'}"
aws dynamodb execute-statement --statement "INSERT INTO Music \
VALUE \
{'Artist':'Acme Band','SongTitle':'PartiQL Rocks', 'AlbumTitle':'Another Album Title', 'Awards':'8'}"
```
**Windows CMD**
```
aws dynamodb execute-statement --statement "INSERT INTO Music VALUE {'Artist':'No One You Know','SongTitle':'Call Me Today', 'AlbumTitle':'Somewhat Famous', 'Awards':'1'}"
aws dynamodb execute-statement --statement "INSERT INTO Music VALUE {'Artist':'No One You Know','SongTitle':'Howdy', 'AlbumTitle':'Somewhat Famous', 'Awards':'2'}"
aws dynamodb execute-statement --statement "INSERT INTO Music VALUE {'Artist':'Acme Band','SongTitle':'Happy Day', 'AlbumTitle':'Songs About Life', 'Awards':'10'}"
aws dynamodb execute-statement --statement "INSERT INTO Music VALUE {'Artist':'Acme Band','SongTitle':'PartiQL Rocks', 'AlbumTitle':'Another Album Title', 'Awards':'8'}"
```
For more information about writing data with PartiQL, see [PartiQL insert statements](https://docs.amazonaws.cn/amazondynamodb/latest/developerguide/ql-reference.insert.html).
------
For more information about supported data types in DynamoDB, see [Data types](https://docs.amazonaws.cn/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html#HowItWorks.DataTypes).
For more information about how to represent DynamoDB data types in JSON, see [Attribute values](https://docs.amazonaws.cn/amazondynamodb/latest/APIReference/API_AttributeValue.html).
## Amazon SDK
The following code examples show how to write an item to a DynamoDB table using an Amazon SDK.
------
#### [ .NET ]
**Amazon SDK for .NET (v4)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/dotnetv4/DynamoDB#code-examples).
```
///
/// Adds a new item to the table.
///
/// A Movie object containing informtation for
/// the movie to add to the table.
/// The name of the table where the item will be added.
/// A Boolean value that indicates the results of adding the item.
public async Task PutItemAsync(Movie newMovie, string tableName)
{
try
{
var item = new Dictionary
{
["title"] = new AttributeValue { S = newMovie.Title },
["year"] = new AttributeValue { N = newMovie.Year.ToString() },
};
var request = new PutItemRequest
{
TableName = tableName,
Item = item,
};
await _amazonDynamoDB.PutItemAsync(request);
return true;
}
catch (ResourceNotFoundException ex)
{
Console.WriteLine($"Table {tableName} was not found. {ex.Message}");
return false;
}
catch (AmazonDynamoDBException ex)
{
Console.WriteLine($"An Amazon DynamoDB error occurred while putting item. {ex.Message}");
throw;
}
catch (Exception ex)
{
Console.WriteLine($"An error occurred while putting item. {ex.Message}");
throw;
}
}
```
+ For API details, see [PutItem](https://docs.amazonaws.cn/goto/DotNetSDKV4/dynamodb-2012-08-10/PutItem) in *Amazon SDK for .NET API Reference*.
------
#### [ Bash ]
**Amazon CLI with Bash script**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/aws-cli/bash-linux/dynamodb#code-examples).
```
##############################################################################
# function dynamodb_put_item
#
# This function puts an item into a DynamoDB table.
#
# Parameters:
# -n table_name -- The name of the table.
# -i item -- Path to json file containing the item values.
#
# Returns:
# 0 - If successful.
# 1 - If it fails.
##############################################################################
function dynamodb_put_item() {
local table_name item response
local option OPTARG # Required to use getopts command in a function.
#######################################
# Function usage explanation
#######################################
function usage() {
echo "function dynamodb_put_item"
echo "Put an item into a DynamoDB table."
echo " -n table_name -- The name of the table."
echo " -i item -- Path to json file containing the item values."
echo ""
}
while getopts "n:i:h" option; do
case "${option}" in
n) table_name="${OPTARG}" ;;
i) item="${OPTARG}" ;;
h)
usage
return 0
;;
\?)
echo "Invalid parameter"
usage
return 1
;;
esac
done
export OPTIND=1
if [[ -z "$table_name" ]]; then
errecho "ERROR: You must provide a table name with the -n parameter."
usage
return 1
fi
if [[ -z "$item" ]]; then
errecho "ERROR: You must provide an item with the -i parameter."
usage
return 1
fi
iecho "Parameters:\n"
iecho " table_name: $table_name"
iecho " item: $item"
iecho ""
iecho ""
response=$(aws dynamodb put-item \
--table-name "$table_name" \
--item file://"$item")
local error_code=${?}
if [[ $error_code -ne 0 ]]; then
aws_cli_error_log $error_code
errecho "ERROR: AWS reports put-item operation failed.$response"
return 1
fi
return 0
}
```
The utility functions used in this example.
```
###############################################################################
# function iecho
#
# This function enables the script to display the specified text only if
# the global variable $VERBOSE is set to true.
###############################################################################
function iecho() {
if [[ $VERBOSE == true ]]; then
echo "$@"
fi
}
###############################################################################
# function errecho
#
# This function outputs everything sent to it to STDERR (standard error output).
###############################################################################
function errecho() {
printf "%s\n" "$*" 1>&2
}
##############################################################################
# function aws_cli_error_log()
#
# This function is used to log the error messages from the AWS CLI.
#
# See https://docs.aws.amazon.com/cli/latest/topic/return-codes.html#cli-aws-help-return-codes.
#
# The function expects the following argument:
# $1 - The error code returned by the AWS CLI.
#
# Returns:
# 0: - Success.
#
##############################################################################
function aws_cli_error_log() {
local err_code=$1
errecho "Error code : $err_code"
if [ "$err_code" == 1 ]; then
errecho " One or more S3 transfers failed."
elif [ "$err_code" == 2 ]; then
errecho " Command line failed to parse."
elif [ "$err_code" == 130 ]; then
errecho " Process received SIGINT."
elif [ "$err_code" == 252 ]; then
errecho " Command syntax invalid."
elif [ "$err_code" == 253 ]; then
errecho " The system environment or configuration was invalid."
elif [ "$err_code" == 254 ]; then
errecho " The service returned an error."
elif [ "$err_code" == 255 ]; then
errecho " 255 is a catch-all error."
fi
return 0
}
```
+ For API details, see [PutItem](https://docs.amazonaws.cn/goto/aws-cli/dynamodb-2012-08-10/PutItem) in *Amazon CLI Command Reference*.
------
#### [ C\$1\$1 ]
**SDK for C\$1\$1**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/cpp/example_code/dynamodb#code-examples).
```
//! Put an item in an Amazon DynamoDB table.
/*!
\sa putItem()
\param tableName: The table name.
\param artistKey: The artist key. This is the partition key for the table.
\param artistValue: The artist value.
\param albumTitleKey: The album title key.
\param albumTitleValue: The album title value.
\param awardsKey: The awards key.
\param awardsValue: The awards value.
\param songTitleKey: The song title key.
\param songTitleValue: The song title value.
\param clientConfiguration: AWS client configuration.
\return bool: Function succeeded.
*/
bool AwsDoc::DynamoDB::putItem(const Aws::String &tableName,
const Aws::String &artistKey,
const Aws::String &artistValue,
const Aws::String &albumTitleKey,
const Aws::String &albumTitleValue,
const Aws::String &awardsKey,
const Aws::String &awardsValue,
const Aws::String &songTitleKey,
const Aws::String &songTitleValue,
const Aws::Client::ClientConfiguration &clientConfiguration) {
Aws::DynamoDB::DynamoDBClient dynamoClient(clientConfiguration);
Aws::DynamoDB::Model::PutItemRequest putItemRequest;
putItemRequest.SetTableName(tableName);
putItemRequest.AddItem(artistKey, Aws::DynamoDB::Model::AttributeValue().SetS(
artistValue)); // This is the hash key.
putItemRequest.AddItem(albumTitleKey, Aws::DynamoDB::Model::AttributeValue().SetS(
albumTitleValue));
putItemRequest.AddItem(awardsKey,
Aws::DynamoDB::Model::AttributeValue().SetS(awardsValue));
putItemRequest.AddItem(songTitleKey,
Aws::DynamoDB::Model::AttributeValue().SetS(songTitleValue));
const Aws::DynamoDB::Model::PutItemOutcome outcome = dynamoClient.PutItem(
putItemRequest);
if (outcome.IsSuccess()) {
std::cout << "Successfully added Item!" << std::endl;
}
else {
std::cerr << outcome.GetError().GetMessage() << std::endl;
return false;
}
return waitTableActive(tableName, dynamoClient);
}
```
Code that waits for the table to become active.
```
//! Query a newly created DynamoDB table until it is active.
/*!
\sa waitTableActive()
\param waitTableActive: The DynamoDB table's name.
\param dynamoClient: A DynamoDB client.
\return bool: Function succeeded.
*/
bool AwsDoc::DynamoDB::waitTableActive(const Aws::String &tableName,
const Aws::DynamoDB::DynamoDBClient &dynamoClient) {
// Repeatedly call DescribeTable until table is ACTIVE.
const int MAX_QUERIES = 20;
Aws::DynamoDB::Model::DescribeTableRequest request;
request.SetTableName(tableName);
int count = 0;
while (count < MAX_QUERIES) {
const Aws::DynamoDB::Model::DescribeTableOutcome &result = dynamoClient.DescribeTable(
request);
if (result.IsSuccess()) {
Aws::DynamoDB::Model::TableStatus status = result.GetResult().GetTable().GetTableStatus();
if (Aws::DynamoDB::Model::TableStatus::ACTIVE != status) {
std::this_thread::sleep_for(std::chrono::seconds(1));
}
else {
return true;
}
}
else {
std::cerr << "Error DynamoDB::waitTableActive "
<< result.GetError().GetMessage() << std::endl;
return false;
}
count++;
}
return false;
}
```
+ For API details, see [PutItem](https://docs.amazonaws.cn/goto/SdkForCpp/dynamodb-2012-08-10/PutItem) in *Amazon SDK for C\$1\$1 API Reference*.
------
#### [ CLI ]
**Amazon CLI**
**Example 1: To add an item to a table**
The following `put-item` example adds a new item to the *MusicCollection* table.
```
aws dynamodb put-item \
--table-name MusicCollection \
--item file://item.json \
--return-consumed-capacity TOTAL \
--return-item-collection-metrics SIZE
```
Contents of `item.json`:
```
{
"Artist": {"S": "No One You Know"},
"SongTitle": {"S": "Call Me Today"},
"AlbumTitle": {"S": "Greatest Hits"}
}
```
Output:
```
{
"ConsumedCapacity": {
"TableName": "MusicCollection",
"CapacityUnits": 1.0
},
"ItemCollectionMetrics": {
"ItemCollectionKey": {
"Artist": {
"S": "No One You Know"
}
},
"SizeEstimateRangeGB": [
0.0,
1.0
]
}
}
```
For more information, see [Writing an Item](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/WorkingWithItems.html#WorkingWithItems.WritingData) in the *Amazon DynamoDB Developer Guide*.
**Example 2: To conditionally overwrite an item in a table**
The following `put-item` example overwrites an existing item in the `MusicCollection` table only if that existing item has an `AlbumTitle` attribute with a value of `Greatest Hits`. The command returns the previous value of the item.
```
aws dynamodb put-item \
--table-name MusicCollection \
--item file://item.json \
--condition-expression "#A = :A" \
--expression-attribute-names file://names.json \
--expression-attribute-values file://values.json \
--return-values ALL_OLD
```
Contents of `item.json`:
```
{
"Artist": {"S": "No One You Know"},
"SongTitle": {"S": "Call Me Today"},
"AlbumTitle": {"S": "Somewhat Famous"}
}
```
Contents of `names.json`:
```
{
"#A": "AlbumTitle"
}
```
Contents of `values.json`:
```
{
":A": {"S": "Greatest Hits"}
}
```
Output:
```
{
"Attributes": {
"AlbumTitle": {
"S": "Greatest Hits"
},
"Artist": {
"S": "No One You Know"
},
"SongTitle": {
"S": "Call Me Today"
}
}
}
```
If the key already exists, you should see the following output:
```
A client error (ConditionalCheckFailedException) occurred when calling the PutItem operation: The conditional request failed.
```
For more information, see [Writing an Item](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/WorkingWithItems.html#WorkingWithItems.WritingData) in the *Amazon DynamoDB Developer Guide*.
+ For API details, see [PutItem](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/dynamodb/put-item.html) in *Amazon CLI Command Reference*.
------
#### [ Go ]
**SDK for Go V2**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/gov2/dynamodb#code-examples).
```
import (
"context"
"errors"
"log"
"time"
"github.com/aws/aws-sdk-go-v2/aws"
"github.com/aws/aws-sdk-go-v2/feature/dynamodb/attributevalue"
"github.com/aws/aws-sdk-go-v2/feature/dynamodb/expression"
"github.com/aws/aws-sdk-go-v2/service/dynamodb"
"github.com/aws/aws-sdk-go-v2/service/dynamodb/types"
)
// TableBasics encapsulates the Amazon DynamoDB service actions used in the examples.
// It contains a DynamoDB service client that is used to act on the specified table.
type TableBasics struct {
DynamoDbClient *dynamodb.Client
TableName string
}
// AddMovie adds a movie the DynamoDB table.
func (basics TableBasics) AddMovie(ctx context.Context, movie Movie) error {
item, err := attributevalue.MarshalMap(movie)
if err != nil {
panic(err)
}
_, err = basics.DynamoDbClient.PutItem(ctx, &dynamodb.PutItemInput{
TableName: aws.String(basics.TableName), Item: item,
})
if err != nil {
log.Printf("Couldn't add item to table. Here's why: %v\n", err)
}
return err
}
```
Define a Movie struct that is used in this example.
```
import (
"archive/zip"
"bytes"
"encoding/json"
"fmt"
"io"
"log"
"net/http"
"github.com/aws/aws-sdk-go-v2/feature/dynamodb/attributevalue"
"github.com/aws/aws-sdk-go-v2/service/dynamodb/types"
)
// Movie encapsulates data about a movie. Title and Year are the composite primary key
// of the movie in Amazon DynamoDB. Title is the sort key, Year is the partition key,
// and Info is additional data.
type Movie struct {
Title string `dynamodbav:"title"`
Year int `dynamodbav:"year"`
Info map[string]interface{} `dynamodbav:"info"`
}
// GetKey returns the composite primary key of the movie in a format that can be
// sent to DynamoDB.
func (movie Movie) GetKey() map[string]types.AttributeValue {
title, err := attributevalue.Marshal(movie.Title)
if err != nil {
panic(err)
}
year, err := attributevalue.Marshal(movie.Year)
if err != nil {
panic(err)
}
return map[string]types.AttributeValue{"title": title, "year": year}
}
// String returns the title, year, rating, and plot of a movie, formatted for the example.
func (movie Movie) String() string {
return fmt.Sprintf("%v\n\tReleased: %v\n\tRating: %v\n\tPlot: %v\n",
movie.Title, movie.Year, movie.Info["rating"], movie.Info["plot"])
}
```
+ For API details, see [PutItem](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/service/dynamodb#Client.PutItem) in *Amazon SDK for Go API Reference*.
------
#### [ Java ]
**SDK for Java 2.x**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2/example_code/dynamodb#code-examples).
Puts an item into a table using [DynamoDbClient](http://docs.aws.amazon.com/sdk-for-java/latest/reference/software/amazon/awssdk/services/dynamodb/DynamoDbClient.html).
```
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
import software.amazon.awssdk.services.dynamodb.model.AttributeValue;
import software.amazon.awssdk.services.dynamodb.model.DynamoDbException;
import software.amazon.awssdk.services.dynamodb.model.PutItemRequest;
import software.amazon.awssdk.services.dynamodb.model.PutItemResponse;
import software.amazon.awssdk.services.dynamodb.model.ResourceNotFoundException;
import java.util.HashMap;
/**
* Before running this Java V2 code example, set up your development
* environment, including your credentials.
*
* For more information, see the following documentation topic:
*
* https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/get-started.html
*
* To place items into an Amazon DynamoDB table using the AWS SDK for Java V2,
* its better practice to use the
* Enhanced Client. See the EnhancedPutItem example.
*/
public class PutItem {
public static void main(String[] args) {
final String usage = """
Usage:
Where:
tableName - The Amazon DynamoDB table in which an item is placed (for example, Music3).
key - The key used in the Amazon DynamoDB table (for example, Artist).
keyval - The key value that represents the item to get (for example, Famous Band).
albumTitle - The Album title (for example, AlbumTitle).
AlbumTitleValue - The name of the album (for example, Songs About Life ).
Awards - The awards column (for example, Awards).
AwardVal - The value of the awards (for example, 10).
SongTitle - The song title (for example, SongTitle).
SongTitleVal - The value of the song title (for example, Happy Day).
**Warning** This program will place an item that you specify into a table!
""";
if (args.length != 9) {
System.out.println(usage);
System.exit(1);
}
String tableName = args[0];
String key = args[1];
String keyVal = args[2];
String albumTitle = args[3];
String albumTitleValue = args[4];
String awards = args[5];
String awardVal = args[6];
String songTitle = args[7];
String songTitleVal = args[8];
Region region = Region.US_EAST_1;
DynamoDbClient ddb = DynamoDbClient.builder()
.region(region)
.build();
putItemInTable(ddb, tableName, key, keyVal, albumTitle, albumTitleValue, awards, awardVal, songTitle,
songTitleVal);
System.out.println("Done!");
ddb.close();
}
public static void putItemInTable(DynamoDbClient ddb,
String tableName,
String key,
String keyVal,
String albumTitle,
String albumTitleValue,
String awards,
String awardVal,
String songTitle,
String songTitleVal) {
HashMap itemValues = new HashMap<>();
itemValues.put(key, AttributeValue.builder().s(keyVal).build());
itemValues.put(songTitle, AttributeValue.builder().s(songTitleVal).build());
itemValues.put(albumTitle, AttributeValue.builder().s(albumTitleValue).build());
itemValues.put(awards, AttributeValue.builder().s(awardVal).build());
PutItemRequest request = PutItemRequest.builder()
.tableName(tableName)
.item(itemValues)
.build();
try {
PutItemResponse response = ddb.putItem(request);
System.out.println(tableName + " was successfully updated. The request id is "
+ response.responseMetadata().requestId());
} catch (ResourceNotFoundException e) {
System.err.format("Error: The Amazon DynamoDB table \"%s\" can't be found.\n", tableName);
System.err.println("Be sure that it exists and that you've typed its name correctly!");
System.exit(1);
} catch (DynamoDbException e) {
System.err.println(e.getMessage());
System.exit(1);
}
}
}
```
+ For API details, see [PutItem](https://docs.amazonaws.cn/goto/SdkForJavaV2/dynamodb-2012-08-10/PutItem) in *Amazon SDK for Java 2.x API Reference*.
------
#### [ JavaScript ]
**SDK for JavaScript (v3)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javascriptv3/example_code/dynamodb#code-examples).
This example uses the document client to simplify working with items in DynamoDB. For API details see [PutCommand](https://docs.amazonaws.cn/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-lib-dynamodb/Class/PutCommand/).
```
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { PutCommand, DynamoDBDocumentClient } from "@aws-sdk/lib-dynamodb";
const client = new DynamoDBClient({});
const docClient = DynamoDBDocumentClient.from(client);
export const main = async () => {
const command = new PutCommand({
TableName: "HappyAnimals",
Item: {
CommonName: "Shiba Inu",
},
});
const response = await docClient.send(command);
console.log(response);
return response;
};
```
+ For API details, see [PutItem](https://docs.amazonaws.cn/AWSJavaScriptSDK/v3/latest/client/dynamodb/command/PutItemCommand) in *Amazon SDK for JavaScript API Reference*.
**SDK for JavaScript (v2)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javascript/example_code/dynamodb#code-examples).
Put an item in a table.
```
// Load the AWS SDK for Node.js
var AWS = require("aws-sdk");
// Set the region
AWS.config.update({ region: "REGION" });
// Create the DynamoDB service object
var ddb = new AWS.DynamoDB({ apiVersion: "2012-08-10" });
var params = {
TableName: "CUSTOMER_LIST",
Item: {
CUSTOMER_ID: { N: "001" },
CUSTOMER_NAME: { S: "Richard Roe" },
},
};
// Call DynamoDB to add the item to the table
ddb.putItem(params, function (err, data) {
if (err) {
console.log("Error", err);
} else {
console.log("Success", data);
}
});
```
Put an item in a table using the DynamoDB document client.
```
// Load the AWS SDK for Node.js
var AWS = require("aws-sdk");
// Set the region
AWS.config.update({ region: "REGION" });
// Create DynamoDB document client
var docClient = new AWS.DynamoDB.DocumentClient({ apiVersion: "2012-08-10" });
var params = {
TableName: "TABLE",
Item: {
HASHKEY: VALUE,
ATTRIBUTE_1: "STRING_VALUE",
ATTRIBUTE_2: VALUE_2,
},
};
docClient.put(params, function (err, data) {
if (err) {
console.log("Error", err);
} else {
console.log("Success", data);
}
});
```
+ For more information, see [Amazon SDK for JavaScript Developer Guide](https://docs.amazonaws.cn/sdk-for-javascript/v2/developer-guide/dynamodb-example-table-read-write.html#dynamodb-example-table-read-write-writing-an-item).
+ For API details, see [PutItem](https://docs.amazonaws.cn/goto/AWSJavaScriptSDK/dynamodb-2012-08-10/PutItem) in *Amazon SDK for JavaScript API Reference*.
------
#### [ Kotlin ]
**SDK for Kotlin**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/kotlin/services/dynamodb#code-examples).
```
suspend fun putItemInTable(
tableNameVal: String,
key: String,
keyVal: String,
albumTitle: String,
albumTitleValue: String,
awards: String,
awardVal: String,
songTitle: String,
songTitleVal: String,
) {
val itemValues = mutableMapOf()
// Add all content to the table.
itemValues[key] = AttributeValue.S(keyVal)
itemValues[songTitle] = AttributeValue.S(songTitleVal)
itemValues[albumTitle] = AttributeValue.S(albumTitleValue)
itemValues[awards] = AttributeValue.S(awardVal)
val request =
PutItemRequest {
tableName = tableNameVal
item = itemValues
}
DynamoDbClient.fromEnvironment { region = "us-east-1" }.use { ddb ->
ddb.putItem(request)
println(" A new item was placed into $tableNameVal.")
}
}
```
+ For API details, see [PutItem](https://sdk.amazonaws.com/kotlin/api/latest/index.html) in *Amazon SDK for Kotlin API reference*.
------
#### [ PHP ]
**SDK for PHP**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code/dynamodb#code-examples).
```
echo "What's the name of the last movie you watched?\n";
while (empty($movieName)) {
$movieName = testable_readline("Movie name: ");
}
echo "And what year was it released?\n";
$movieYear = "year";
while (!is_numeric($movieYear) || intval($movieYear) != $movieYear) {
$movieYear = testable_readline("Year released: ");
}
$service->putItem([
'Item' => [
'year' => [
'N' => "$movieYear",
],
'title' => [
'S' => $movieName,
],
],
'TableName' => $tableName,
]);
public function putItem(array $array)
{
$this->dynamoDbClient->putItem($array);
}
```
+ For API details, see [PutItem](https://docs.amazonaws.cn/goto/SdkForPHPV3/dynamodb-2012-08-10/PutItem) in *Amazon SDK for PHP API Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: Creates a new item, or replaces an existing item with a new item.**
```
$item = @{
SongTitle = 'Somewhere Down The Road'
Artist = 'No One You Know'
AlbumTitle = 'Somewhat Famous'
Price = 1.94
Genre = 'Country'
CriticRating = 9.0
} | ConvertTo-DDBItem
Set-DDBItem -TableName 'Music' -Item $item
```
+ For API details, see [PutItem](https://docs.aws.amazon.com/powershell/v4/reference) in *Amazon Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: Creates a new item, or replaces an existing item with a new item.**
```
$item = @{
SongTitle = 'Somewhere Down The Road'
Artist = 'No One You Know'
AlbumTitle = 'Somewhat Famous'
Price = 1.94
Genre = 'Country'
CriticRating = 9.0
} | ConvertTo-DDBItem
Set-DDBItem -TableName 'Music' -Item $item
```
+ For API details, see [PutItem](https://docs.aws.amazon.com/powershell/v5/reference) in *Amazon Tools for PowerShell Cmdlet Reference (V5)*.
------
#### [ Python ]
**SDK for Python (Boto3)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/dynamodb#code-examples).
```
class Movies:
"""Encapsulates an Amazon DynamoDB table of movie data.
Example data structure for a movie record in this table:
{
"year": 1999,
"title": "For Love of the Game",
"info": {
"directors": ["Sam Raimi"],
"release_date": "1999-09-15T00:00:00Z",
"rating": 6.3,
"plot": "A washed up pitcher flashes through his career.",
"rank": 4987,
"running_time_secs": 8220,
"actors": [
"Kevin Costner",
"Kelly Preston",
"John C. Reilly"
]
}
}
"""
def __init__(self, dyn_resource):
"""
:param dyn_resource: A Boto3 DynamoDB resource.
"""
self.dyn_resource = dyn_resource
# The table variable is set during the scenario in the call to
# 'exists' if the table exists. Otherwise, it is set by 'create_table'.
self.table = None
def add_movie(self, title, year, plot, rating):
"""
Adds a movie to the table.
:param title: The title of the movie.
:param year: The release year of the movie.
:param plot: The plot summary of the movie.
:param rating: The quality rating of the movie.
"""
try:
self.table.put_item(
Item={
"year": year,
"title": title,
"info": {"plot": plot, "rating": Decimal(str(rating))},
}
)
except ClientError as err:
logger.error(
"Couldn't add movie %s to table %s. Here's why: %s: %s",
title,
self.table.name,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
```
+ For API details, see [PutItem](https://docs.amazonaws.cn/goto/boto3/dynamodb-2012-08-10/PutItem) in *Amazon SDK for Python (Boto3) API Reference*.
------
#### [ Ruby ]
**SDK for Ruby**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/ruby/example_code/dynamodb#code-examples).
```
class DynamoDBBasics
attr_reader :dynamo_resource, :table
def initialize(table_name)
client = Aws::DynamoDB::Client.new(region: 'us-east-1')
@dynamo_resource = Aws::DynamoDB::Resource.new(client: client)
@table = @dynamo_resource.table(table_name)
end
# Adds a movie to the table.
#
# @param movie [Hash] The title, year, plot, and rating of the movie.
def add_item(movie)
@table.put_item(
item: {
'year' => movie[:year],
'title' => movie[:title],
'info' => { 'plot' => movie[:plot], 'rating' => movie[:rating] }
}
)
rescue Aws::DynamoDB::Errors::ServiceError => e
puts("Couldn't add movie #{title} to table #{@table.name}. Here's why:")
puts("\t#{e.code}: #{e.message}")
raise
end
```
+ For API details, see [PutItem](https://docs.amazonaws.cn/goto/SdkForRubyV3/dynamodb-2012-08-10/PutItem) in *Amazon SDK for Ruby API Reference*.
------
#### [ Rust ]
**SDK for Rust**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/rustv1/examples/dynamodb#code-examples).
```
pub async fn add_item(client: &Client, item: Item, table: &String) -> Result {
let user_av = AttributeValue::S(item.username);
let type_av = AttributeValue::S(item.p_type);
let age_av = AttributeValue::S(item.age);
let first_av = AttributeValue::S(item.first);
let last_av = AttributeValue::S(item.last);
let request = client
.put_item()
.table_name(table)
.item("username", user_av)
.item("account_type", type_av)
.item("age", age_av)
.item("first_name", first_av)
.item("last_name", last_av);
println!("Executing request [{request:?}] to add item...");
let resp = request.send().await?;
let attributes = resp.attributes().unwrap();
let username = attributes.get("username").cloned();
let first_name = attributes.get("first_name").cloned();
let last_name = attributes.get("last_name").cloned();
let age = attributes.get("age").cloned();
let p_type = attributes.get("p_type").cloned();
println!(
"Added user {:?}, {:?} {:?}, age {:?} as {:?} user",
username, first_name, last_name, age, p_type
);
Ok(ItemOut {
p_type,
age,
username,
first_name,
last_name,
})
}
```
+ For API details, see [PutItem](https://docs.rs/aws-sdk-dynamodb/latest/aws_sdk_dynamodb/client/struct.Client.html#method.put_item) in *Amazon SDK for Rust API reference*.
------
#### [ SAP ABAP ]
**SDK for SAP ABAP**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/sap-abap/services/dyn#code-examples).
```
TRY.
DATA(lo_resp) = lo_dyn->putitem(
iv_tablename = iv_table_name
it_item = it_item ).
MESSAGE '1 row inserted into DynamoDB Table' && iv_table_name TYPE 'I'.
CATCH /aws1/cx_dyncondalcheckfaile00.
MESSAGE 'A condition specified in the operation could not be evaluated.' TYPE 'E'.
CATCH /aws1/cx_dynresourcenotfoundex.
MESSAGE 'The table or index does not exist' TYPE 'E'.
CATCH /aws1/cx_dyntransactconflictex.
MESSAGE 'Another transaction is using the item' TYPE 'E'.
ENDTRY.
```
+ For API details, see [PutItem](https://docs.amazonaws.cn/sdk-for-sap-abap/v1/api/latest/index.html) in *Amazon SDK for SAP ABAP API reference*.
------
#### [ Swift ]
**SDK for Swift**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/swift/example_code/dynamodb#code-examples).
```
import AWSDynamoDB
/// Add a movie specified as a `Movie` structure to the Amazon DynamoDB
/// table.
///
/// - Parameter movie: The `Movie` to add to the table.
///
func add(movie: Movie) async throws {
do {
guard let client = self.ddbClient else {
throw MoviesError.UninitializedClient
}
// Get a DynamoDB item containing the movie data.
let item = try await movie.getAsItem()
// Send the `PutItem` request to Amazon DynamoDB.
let input = PutItemInput(
item: item,
tableName: self.tableName
)
_ = try await client.putItem(input: input)
} catch {
print("ERROR: add movie:", dump(error))
throw error
}
}
///
/// Return an array mapping attribute names to Amazon DynamoDB attribute
/// values, representing the contents of the `Movie` record as a DynamoDB
/// item.
///
/// - Returns: The movie item as an array of type
/// `[Swift.String:DynamoDBClientTypes.AttributeValue]`.
///
func getAsItem() async throws -> [Swift.String:DynamoDBClientTypes.AttributeValue] {
// Build the item record, starting with the year and title, which are
// always present.
var item: [Swift.String:DynamoDBClientTypes.AttributeValue] = [
"year": .n(String(self.year)),
"title": .s(self.title)
]
// Add the `info` field with the rating and/or plot if they're
// available.
var details: [Swift.String:DynamoDBClientTypes.AttributeValue] = [:]
if (self.info.rating != nil || self.info.plot != nil) {
if self.info.rating != nil {
details["rating"] = .n(String(self.info.rating!))
}
if self.info.plot != nil {
details["plot"] = .s(self.info.plot!)
}
}
item["info"] = .m(details)
return item
}
```
+ For API details, see [PutItem](https://sdk.amazonaws.com/swift/api/awsdynamodb/latest/documentation/awsdynamodb/dynamodbclient/putitem(input:)) in *Amazon SDK for Swift API reference*.
------
For more DynamoDB examples, see [Code examples for DynamoDB using Amazon SDKs](service_code_examples.md).
After writing data to your table, proceed to [Step 3: Read data from a DynamoDB table](getting-started-step-3.md).
# Step 3: Read data from a DynamoDB table
In this step, you'll read back one of the items that you created in [Step 2: Write data to a DynamoDB table](getting-started-step-2.md). You can use the DynamoDB console or the Amazon CLI to read an item from the `Music` table by specifying `Artist` and `SongTitle`.
For more information about read operations in DynamoDB, see [Reading an item](WorkingWithItems.md#WorkingWithItems.ReadingData).
## Amazon Web Services Management Console
Follow these steps to read data from the `Music` table using the DynamoDB console.
1. Open the DynamoDB console at [https://console.amazonaws.cn/dynamodb/](https://console.amazonaws.cn/dynamodb/).
1. In the left navigation pane, choose **Tables**.
1. On the **Tables** page, choose the **Music** table.
1. Choose **Explore table items**.
1. On the **Items returned** section, view the list of items stored in the table, sorted by `Artist` and `SongTitle`. The first item in the list is the one with the **Artist** named **Acme Band** and the **SongTitle** **PartiQL Rocks**.
## Amazon CLI
The following Amazon CLI example reads an item from the `Music`. You can do this either through the DynamoDB API or [PartiQL](https://docs.amazonaws.cn/amazondynamodb/latest/developerguide/ql-reference.html), a SQL-compatible query language for DynamoDB.
------
#### [ DynamoDB API ]
**Note**
The default behavior for DynamoDB is eventually consistent reads. The `consistent-read` parameter is used below to demonstrate strongly consistent reads.
**Linux**
```
aws dynamodb get-item --consistent-read \
--table-name Music \
--key '{ "Artist": {"S": "Acme Band"}, "SongTitle": {"S": "Happy Day"}}'
```
**Windows CMD**
```
aws dynamodb get-item --consistent-read ^
--table-name Music ^
--key "{\"Artist\": {\"S\": \"Acme Band\"}, \"SongTitle\": {\"S\": \"Happy Day\"}}"
```
Using `get-item` returns the following sample result.
```
{
"Item": {
"AlbumTitle": {
"S": "Songs About Life"
},
"Awards": {
"S": "10"
},
"Artist": {
"S": "Acme Band"
},
"SongTitle": {
"S": "Happy Day"
}
}
}
```
------
#### [ PartiQL for DynamoDB ]
**Linux**
```
aws dynamodb execute-statement --statement "SELECT * FROM Music \
WHERE Artist='Acme Band' AND SongTitle='Happy Day'"
```
**Windows CMD**
```
aws dynamodb execute-statement --statement "SELECT * FROM Music WHERE Artist='Acme Band' AND SongTitle='Happy Day'"
```
Using the PartiQL `Select` statement returns the following sample result.
```
{
"Items": [
{
"AlbumTitle": {
"S": "Songs About Life"
},
"Awards": {
"S": "10"
},
"Artist": {
"S": "Acme Band"
},
"SongTitle": {
"S": "Happy Day"
}
}
]
}
```
For more information about reading data with PartiQL, see [PartiQL select statements](https://docs.amazonaws.cn/amazondynamodb/latest/developerguide/ql-reference.SELECT.html).
------
## Amazon SDK
The following code examples show how to read an item from a DynamoDB table using an Amazon SDK.
------
#### [ .NET ]
**Amazon SDK for .NET (v4)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/dotnetv4/DynamoDB#code-examples).
```
///
/// Gets information about an existing movie from the table.
///
/// A Movie object containing information about
/// the movie to retrieve.
/// The name of the table containing the movie.
/// A Dictionary object containing information about the item
/// retrieved.
public async Task> GetItemAsync(Movie newMovie, string tableName)
{
try
{
var key = new Dictionary
{
["title"] = new AttributeValue { S = newMovie.Title },
["year"] = new AttributeValue { N = newMovie.Year.ToString() },
};
var request = new GetItemRequest
{
Key = key,
TableName = tableName,
};
var response = await _amazonDynamoDB.GetItemAsync(request);
return response.Item;
}
catch (ResourceNotFoundException ex)
{
Console.WriteLine($"Table {tableName} was not found. {ex.Message}");
return new Dictionary();
}
catch (AmazonDynamoDBException ex)
{
Console.WriteLine($"An Amazon DynamoDB error occurred while getting item. {ex.Message}");
throw;
}
catch (Exception ex)
{
Console.WriteLine($"An error occurred while getting item. {ex.Message}");
throw;
}
}
```
+ For API details, see [GetItem](https://docs.amazonaws.cn/goto/DotNetSDKV4/dynamodb-2012-08-10/GetItem) in *Amazon SDK for .NET API Reference*.
------
#### [ Bash ]
**Amazon CLI with Bash script**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/aws-cli/bash-linux/dynamodb#code-examples).
```
#############################################################################
# function dynamodb_get_item
#
# This function gets an item from a DynamoDB table.
#
# Parameters:
# -n table_name -- The name of the table.
# -k keys -- Path to json file containing the keys that identify the item to get.
# [-q query] -- Optional JMESPath query expression.
#
# Returns:
# The item as text output.
# And:
# 0 - If successful.
# 1 - If it fails.
############################################################################
function dynamodb_get_item() {
local table_name keys query response
local option OPTARG # Required to use getopts command in a function.
# ######################################
# Function usage explanation
#######################################
function usage() {
echo "function dynamodb_get_item"
echo "Get an item from a DynamoDB table."
echo " -n table_name -- The name of the table."
echo " -k keys -- Path to json file containing the keys that identify the item to get."
echo " [-q query] -- Optional JMESPath query expression."
echo ""
}
query=""
while getopts "n:k:q:h" option; do
case "${option}" in
n) table_name="${OPTARG}" ;;
k) keys="${OPTARG}" ;;
q) query="${OPTARG}" ;;
h)
usage
return 0
;;
\?)
echo "Invalid parameter"
usage
return 1
;;
esac
done
export OPTIND=1
if [[ -z "$table_name" ]]; then
errecho "ERROR: You must provide a table name with the -n parameter."
usage
return 1
fi
if [[ -z "$keys" ]]; then
errecho "ERROR: You must provide a keys json file path the -k parameter."
usage
return 1
fi
if [[ -n "$query" ]]; then
response=$(aws dynamodb get-item \
--table-name "$table_name" \
--key file://"$keys" \
--output text \
--query "$query")
else
response=$(
aws dynamodb get-item \
--table-name "$table_name" \
--key file://"$keys" \
--output text
)
fi
local error_code=${?}
if [[ $error_code -ne 0 ]]; then
aws_cli_error_log $error_code
errecho "ERROR: AWS reports get-item operation failed.$response"
return 1
fi
if [[ -n "$query" ]]; then
echo "$response" | sed "/^\t/s/\t//1" # Remove initial tab that the JMSEPath query inserts on some strings.
else
echo "$response"
fi
return 0
}
```
The utility functions used in this example.
```
###############################################################################
# function errecho
#
# This function outputs everything sent to it to STDERR (standard error output).
###############################################################################
function errecho() {
printf "%s\n" "$*" 1>&2
}
##############################################################################
# function aws_cli_error_log()
#
# This function is used to log the error messages from the AWS CLI.
#
# See https://docs.aws.amazon.com/cli/latest/topic/return-codes.html#cli-aws-help-return-codes.
#
# The function expects the following argument:
# $1 - The error code returned by the AWS CLI.
#
# Returns:
# 0: - Success.
#
##############################################################################
function aws_cli_error_log() {
local err_code=$1
errecho "Error code : $err_code"
if [ "$err_code" == 1 ]; then
errecho " One or more S3 transfers failed."
elif [ "$err_code" == 2 ]; then
errecho " Command line failed to parse."
elif [ "$err_code" == 130 ]; then
errecho " Process received SIGINT."
elif [ "$err_code" == 252 ]; then
errecho " Command syntax invalid."
elif [ "$err_code" == 253 ]; then
errecho " The system environment or configuration was invalid."
elif [ "$err_code" == 254 ]; then
errecho " The service returned an error."
elif [ "$err_code" == 255 ]; then
errecho " 255 is a catch-all error."
fi
return 0
}
```
+ For API details, see [GetItem](https://docs.amazonaws.cn/goto/aws-cli/dynamodb-2012-08-10/GetItem) in *Amazon CLI Command Reference*.
------
#### [ C\$1\$1 ]
**SDK for C\$1\$1**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/cpp/example_code/dynamodb#code-examples).
```
//! Get an item from an Amazon DynamoDB table.
/*!
\sa getItem()
\param tableName: The table name.
\param partitionKey: The partition key.
\param partitionValue: The value for the partition key.
\param clientConfiguration: AWS client configuration.
\return bool: Function succeeded.
*/
bool AwsDoc::DynamoDB::getItem(const Aws::String &tableName,
const Aws::String &partitionKey,
const Aws::String &partitionValue,
const Aws::Client::ClientConfiguration &clientConfiguration) {
Aws::DynamoDB::DynamoDBClient dynamoClient(clientConfiguration);
Aws::DynamoDB::Model::GetItemRequest request;
// Set up the request.
request.SetTableName(tableName);
request.AddKey(partitionKey,
Aws::DynamoDB::Model::AttributeValue().SetS(partitionValue));
// Retrieve the item's fields and values.
const Aws::DynamoDB::Model::GetItemOutcome &outcome = dynamoClient.GetItem(request);
if (outcome.IsSuccess()) {
// Reference the retrieved fields/values.
const Aws::Map &item = outcome.GetResult().GetItem();
if (!item.empty()) {
// Output each retrieved field and its value.
for (const auto &i: item)
std::cout << "Values: " << i.first << ": " << i.second.GetS()
<< std::endl;
}
else {
std::cout << "No item found with the key " << partitionKey << std::endl;
}
}
else {
std::cerr << "Failed to get item: " << outcome.GetError().GetMessage();
}
return outcome.IsSuccess();
}
```
+ For API details, see [GetItem](https://docs.amazonaws.cn/goto/SdkForCpp/dynamodb-2012-08-10/GetItem) in *Amazon SDK for C\$1\$1 API Reference*.
------
#### [ CLI ]
**Amazon CLI**
**Example 1: To read an item in a table**
The following `get-item` example retrieves an item from the `MusicCollection` table. The table has a hash-and-range primary key (`Artist` and `SongTitle`), so you must specify both of these attributes. The command also requests information about the read capacity consumed by the operation.
```
aws dynamodb get-item \
--table-name MusicCollection \
--key file://key.json \
--return-consumed-capacity TOTAL
```
Contents of `key.json`:
```
{
"Artist": {"S": "Acme Band"},
"SongTitle": {"S": "Happy Day"}
}
```
Output:
```
{
"Item": {
"AlbumTitle": {
"S": "Songs About Life"
},
"SongTitle": {
"S": "Happy Day"
},
"Artist": {
"S": "Acme Band"
}
},
"ConsumedCapacity": {
"TableName": "MusicCollection",
"CapacityUnits": 0.5
}
}
```
For more information, see [Reading an Item](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/WorkingWithItems.html#WorkingWithItems.ReadingData) in the *Amazon DynamoDB Developer Guide*.
**Example 2: To read an item using a consistent read**
The following example retrieves an item from the `MusicCollection` table using strongly consistent reads.
```
aws dynamodb get-item \
--table-name MusicCollection \
--key file://key.json \
--consistent-read \
--return-consumed-capacity TOTAL
```
Contents of `key.json`:
```
{
"Artist": {"S": "Acme Band"},
"SongTitle": {"S": "Happy Day"}
}
```
Output:
```
{
"Item": {
"AlbumTitle": {
"S": "Songs About Life"
},
"SongTitle": {
"S": "Happy Day"
},
"Artist": {
"S": "Acme Band"
}
},
"ConsumedCapacity": {
"TableName": "MusicCollection",
"CapacityUnits": 1.0
}
}
```
For more information, see [Reading an Item](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/WorkingWithItems.html#WorkingWithItems.ReadingData) in the *Amazon DynamoDB Developer Guide*.
**Example 3: To retrieve specific attributes of an item**
The following example uses a projection expression to retrieve only three attributes of the desired item.
```
aws dynamodb get-item \
--table-name ProductCatalog \
--key '{"Id": {"N": "102"}}' \
--projection-expression "#T, #C, #P" \
--expression-attribute-names file://names.json
```
Contents of `names.json`:
```
{
"#T": "Title",
"#C": "ProductCategory",
"#P": "Price"
}
```
Output:
```
{
"Item": {
"Price": {
"N": "20"
},
"Title": {
"S": "Book 102 Title"
},
"ProductCategory": {
"S": "Book"
}
}
}
```
For more information, see [Reading an Item](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/WorkingWithItems.html#WorkingWithItems.ReadingData) in the *Amazon DynamoDB Developer Guide*.
+ For API details, see [GetItem](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/dynamodb/get-item.html) in *Amazon CLI Command Reference*.
------
#### [ Go ]
**SDK for Go V2**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/gov2/dynamodb#code-examples).
```
import (
"context"
"errors"
"log"
"time"
"github.com/aws/aws-sdk-go-v2/aws"
"github.com/aws/aws-sdk-go-v2/feature/dynamodb/attributevalue"
"github.com/aws/aws-sdk-go-v2/feature/dynamodb/expression"
"github.com/aws/aws-sdk-go-v2/service/dynamodb"
"github.com/aws/aws-sdk-go-v2/service/dynamodb/types"
)
// TableBasics encapsulates the Amazon DynamoDB service actions used in the examples.
// It contains a DynamoDB service client that is used to act on the specified table.
type TableBasics struct {
DynamoDbClient *dynamodb.Client
TableName string
}
// GetMovie gets movie data from the DynamoDB table by using the primary composite key
// made of title and year.
func (basics TableBasics) GetMovie(ctx context.Context, title string, year int) (Movie, error) {
movie := Movie{Title: title, Year: year}
response, err := basics.DynamoDbClient.GetItem(ctx, &dynamodb.GetItemInput{
Key: movie.GetKey(), TableName: aws.String(basics.TableName),
})
if err != nil {
log.Printf("Couldn't get info about %v. Here's why: %v\n", title, err)
} else {
err = attributevalue.UnmarshalMap(response.Item, &movie)
if err != nil {
log.Printf("Couldn't unmarshal response. Here's why: %v\n", err)
}
}
return movie, err
}
```
Define a Movie struct that is used in this example.
```
import (
"archive/zip"
"bytes"
"encoding/json"
"fmt"
"io"
"log"
"net/http"
"github.com/aws/aws-sdk-go-v2/feature/dynamodb/attributevalue"
"github.com/aws/aws-sdk-go-v2/service/dynamodb/types"
)
// Movie encapsulates data about a movie. Title and Year are the composite primary key
// of the movie in Amazon DynamoDB. Title is the sort key, Year is the partition key,
// and Info is additional data.
type Movie struct {
Title string `dynamodbav:"title"`
Year int `dynamodbav:"year"`
Info map[string]interface{} `dynamodbav:"info"`
}
// GetKey returns the composite primary key of the movie in a format that can be
// sent to DynamoDB.
func (movie Movie) GetKey() map[string]types.AttributeValue {
title, err := attributevalue.Marshal(movie.Title)
if err != nil {
panic(err)
}
year, err := attributevalue.Marshal(movie.Year)
if err != nil {
panic(err)
}
return map[string]types.AttributeValue{"title": title, "year": year}
}
// String returns the title, year, rating, and plot of a movie, formatted for the example.
func (movie Movie) String() string {
return fmt.Sprintf("%v\n\tReleased: %v\n\tRating: %v\n\tPlot: %v\n",
movie.Title, movie.Year, movie.Info["rating"], movie.Info["plot"])
}
```
+ For API details, see [GetItem](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/service/dynamodb#Client.GetItem) in *Amazon SDK for Go API Reference*.
------
#### [ Java ]
**SDK for Java 2.x**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2/example_code/dynamodb#code-examples).
Gets an item from a table by using the DynamoDbClient.
```
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.dynamodb.model.DynamoDbException;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
import software.amazon.awssdk.services.dynamodb.model.AttributeValue;
import software.amazon.awssdk.services.dynamodb.model.GetItemRequest;
import java.util.HashMap;
import java.util.Map;
import java.util.Set;
/**
* Before running this Java V2 code example, set up your development
* environment, including your credentials.
*
* For more information, see the following documentation topic:
*
* https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/get-started.html
*
* To get an item from an Amazon DynamoDB table using the AWS SDK for Java V2,
* its better practice to use the
* Enhanced Client, see the EnhancedGetItem example.
*/
public class GetItem {
public static void main(String[] args) {
final String usage = """
Usage:
Where:
tableName - The Amazon DynamoDB table from which an item is retrieved (for example, Music3).\s
key - The key used in the Amazon DynamoDB table (for example, Artist).\s
keyval - The key value that represents the item to get (for example, Famous Band).
""";
if (args.length != 3) {
System.out.println(usage);
System.exit(1);
}
String tableName = args[0];
String key = args[1];
String keyVal = args[2];
System.out.format("Retrieving item \"%s\" from \"%s\"\n", keyVal, tableName);
Region region = Region.US_EAST_1;
DynamoDbClient ddb = DynamoDbClient.builder()
.region(region)
.build();
getDynamoDBItem(ddb, tableName, key, keyVal);
ddb.close();
}
public static void getDynamoDBItem(DynamoDbClient ddb, String tableName, String key, String keyVal) {
HashMap keyToGet = new HashMap<>();
keyToGet.put(key, AttributeValue.builder()
.s(keyVal)
.build());
GetItemRequest request = GetItemRequest.builder()
.key(keyToGet)
.tableName(tableName)
.build();
try {
// If there is no matching item, GetItem does not return any data.
Map returnedItem = ddb.getItem(request).item();
if (returnedItem.isEmpty())
System.out.format("No item found with the key %s!\n", key);
else {
Set keys = returnedItem.keySet();
System.out.println("Amazon DynamoDB table attributes: \n");
for (String key1 : keys) {
System.out.format("%s: %s\n", key1, returnedItem.get(key1).toString());
}
}
} catch (DynamoDbException e) {
System.err.println(e.getMessage());
System.exit(1);
}
}
}
```
+ For API details, see [GetItem](https://docs.amazonaws.cn/goto/SdkForJavaV2/dynamodb-2012-08-10/GetItem) in *Amazon SDK for Java 2.x API Reference*.
------
#### [ JavaScript ]
**SDK for JavaScript (v3)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javascriptv3/example_code/dynamodb#code-examples).
This example uses the document client to simplify working with items in DynamoDB. For API details see [GetCommand](https://docs.amazonaws.cn/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-lib-dynamodb/Class/GetCommand/).
```
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, GetCommand } from "@aws-sdk/lib-dynamodb";
const client = new DynamoDBClient({});
const docClient = DynamoDBDocumentClient.from(client);
export const main = async () => {
const command = new GetCommand({
TableName: "AngryAnimals",
Key: {
CommonName: "Shoebill",
},
});
const response = await docClient.send(command);
console.log(response);
return response;
};
```
+ For API details, see [GetItem](https://docs.amazonaws.cn/AWSJavaScriptSDK/v3/latest/client/dynamodb/command/GetItemCommand) in *Amazon SDK for JavaScript API Reference*.
**SDK for JavaScript (v2)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javascript/example_code/dynamodb#code-examples).
Get an item from a table.
```
// Load the AWS SDK for Node.js
var AWS = require("aws-sdk");
// Set the region
AWS.config.update({ region: "REGION" });
// Create the DynamoDB service object
var ddb = new AWS.DynamoDB({ apiVersion: "2012-08-10" });
var params = {
TableName: "TABLE",
Key: {
KEY_NAME: { N: "001" },
},
ProjectionExpression: "ATTRIBUTE_NAME",
};
// Call DynamoDB to read the item from the table
ddb.getItem(params, function (err, data) {
if (err) {
console.log("Error", err);
} else {
console.log("Success", data.Item);
}
});
```
Get an item from a table using the DynamoDB document client.
```
// Load the AWS SDK for Node.js
var AWS = require("aws-sdk");
// Set the region
AWS.config.update({ region: "REGION" });
// Create DynamoDB document client
var docClient = new AWS.DynamoDB.DocumentClient({ apiVersion: "2012-08-10" });
var params = {
TableName: "EPISODES_TABLE",
Key: { KEY_NAME: VALUE },
};
docClient.get(params, function (err, data) {
if (err) {
console.log("Error", err);
} else {
console.log("Success", data.Item);
}
});
```
+ For more information, see [Amazon SDK for JavaScript Developer Guide](https://docs.amazonaws.cn/sdk-for-javascript/v2/developer-guide/dynamodb-example-dynamodb-utilities.html#dynamodb-example-document-client-get).
+ For API details, see [GetItem](https://docs.amazonaws.cn/goto/AWSJavaScriptSDK/dynamodb-2012-08-10/GetItem) in *Amazon SDK for JavaScript API Reference*.
------
#### [ Kotlin ]
**SDK for Kotlin**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/kotlin/services/dynamodb#code-examples).
```
suspend fun getSpecificItem(
tableNameVal: String,
keyName: String,
keyVal: String,
) {
val keyToGet = mutableMapOf()
keyToGet[keyName] = AttributeValue.S(keyVal)
val request =
GetItemRequest {
key = keyToGet
tableName = tableNameVal
}
DynamoDbClient.fromEnvironment { region = "us-east-1" }.use { ddb ->
val returnedItem = ddb.getItem(request)
val numbersMap = returnedItem.item
numbersMap?.forEach { key1 ->
println(key1.key)
println(key1.value)
}
}
}
```
+ For API details, see [GetItem](https://sdk.amazonaws.com/kotlin/api/latest/index.html) in *Amazon SDK for Kotlin API reference*.
------
#### [ PHP ]
**SDK for PHP**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code/dynamodb#code-examples).
```
$movie = $service->getItemByKey($tableName, $key);
echo "\nThe movie {$movie['Item']['title']['S']} was released in {$movie['Item']['year']['N']}.\n";
public function getItemByKey(string $tableName, array $key)
{
return $this->dynamoDbClient->getItem([
'Key' => $key['Item'],
'TableName' => $tableName,
]);
}
```
+ For API details, see [GetItem](https://docs.amazonaws.cn/goto/SdkForPHPV3/dynamodb-2012-08-10/GetItem) in *Amazon SDK for PHP API Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: Returns the DynamoDB item with the partition key SongTitle and the sort key Artist.**
```
$key = @{
SongTitle = 'Somewhere Down The Road'
Artist = 'No One You Know'
} | ConvertTo-DDBItem
Get-DDBItem -TableName 'Music' -Key $key | ConvertFrom-DDBItem
```
**Output:**
```
Name Value
---- -----
Genre Country
SongTitle Somewhere Down The Road
Price 1.94
Artist No One You Know
CriticRating 9
AlbumTitle Somewhat Famous
```
+ For API details, see [GetItem](https://docs.aws.amazon.com/powershell/v4/reference) in *Amazon Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: Returns the DynamoDB item with the partition key SongTitle and the sort key Artist.**
```
$key = @{
SongTitle = 'Somewhere Down The Road'
Artist = 'No One You Know'
} | ConvertTo-DDBItem
Get-DDBItem -TableName 'Music' -Key $key | ConvertFrom-DDBItem
```
**Output:**
```
Name Value
---- -----
Genre Country
SongTitle Somewhere Down The Road
Price 1.94
Artist No One You Know
CriticRating 9
AlbumTitle Somewhat Famous
```
+ For API details, see [GetItem](https://docs.aws.amazon.com/powershell/v5/reference) in *Amazon Tools for PowerShell Cmdlet Reference (V5)*.
------
#### [ Python ]
**SDK for Python (Boto3)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/dynamodb#code-examples).
```
class Movies:
"""Encapsulates an Amazon DynamoDB table of movie data.
Example data structure for a movie record in this table:
{
"year": 1999,
"title": "For Love of the Game",
"info": {
"directors": ["Sam Raimi"],
"release_date": "1999-09-15T00:00:00Z",
"rating": 6.3,
"plot": "A washed up pitcher flashes through his career.",
"rank": 4987,
"running_time_secs": 8220,
"actors": [
"Kevin Costner",
"Kelly Preston",
"John C. Reilly"
]
}
}
"""
def __init__(self, dyn_resource):
"""
:param dyn_resource: A Boto3 DynamoDB resource.
"""
self.dyn_resource = dyn_resource
# The table variable is set during the scenario in the call to
# 'exists' if the table exists. Otherwise, it is set by 'create_table'.
self.table = None
def get_movie(self, title, year):
"""
Gets movie data from the table for a specific movie.
:param title: The title of the movie.
:param year: The release year of the movie.
:return: The data about the requested movie.
"""
try:
response = self.table.get_item(Key={"year": year, "title": title})
except ClientError as err:
logger.error(
"Couldn't get movie %s from table %s. Here's why: %s: %s",
title,
self.table.name,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
else:
return response["Item"]
```
+ For API details, see [GetItem](https://docs.amazonaws.cn/goto/boto3/dynamodb-2012-08-10/GetItem) in *Amazon SDK for Python (Boto3) API Reference*.
------
#### [ Ruby ]
**SDK for Ruby**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/ruby/example_code/dynamodb#code-examples).
```
class DynamoDBBasics
attr_reader :dynamo_resource, :table
def initialize(table_name)
client = Aws::DynamoDB::Client.new(region: 'us-east-1')
@dynamo_resource = Aws::DynamoDB::Resource.new(client: client)
@table = @dynamo_resource.table(table_name)
end
# Gets movie data from the table for a specific movie.
#
# @param title [String] The title of the movie.
# @param year [Integer] The release year of the movie.
# @return [Hash] The data about the requested movie.
def get_item(title, year)
@table.get_item(key: { 'year' => year, 'title' => title })
rescue Aws::DynamoDB::Errors::ServiceError => e
puts("Couldn't get movie #{title} (#{year}) from table #{@table.name}:\n")
puts("\t#{e.code}: #{e.message}")
raise
end
```
+ For API details, see [GetItem](https://docs.amazonaws.cn/goto/SdkForRubyV3/dynamodb-2012-08-10/GetItem) in *Amazon SDK for Ruby API Reference*.
------
#### [ SAP ABAP ]
**SDK for SAP ABAP**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/sap-abap/services/dyn#code-examples).
```
TRY.
oo_item = lo_dyn->getitem(
iv_tablename = iv_table_name
it_key = it_key ).
DATA(lt_attr) = oo_item->get_item( ).
DATA(lo_title) = lt_attr[ key = 'title' ]-value.
DATA(lo_year) = lt_attr[ key = 'year' ]-value.
DATA(lo_rating) = lt_attr[ key = 'rating' ]-value.
MESSAGE 'Movie name is: ' && lo_title->get_s( )
&& 'Movie year is: ' && lo_year->get_n( )
&& 'Moving rating is: ' && lo_rating->get_n( ) TYPE 'I'.
CATCH /aws1/cx_dynresourcenotfoundex.
MESSAGE 'The table or index does not exist' TYPE 'E'.
ENDTRY.
```
+ For API details, see [GetItem](https://docs.amazonaws.cn/sdk-for-sap-abap/v1/api/latest/index.html) in *Amazon SDK for SAP ABAP API reference*.
------
#### [ Swift ]
**SDK for Swift**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/swift/example_code/dynamodb#code-examples).
```
import AWSDynamoDB
/// Return a `Movie` record describing the specified movie from the Amazon
/// DynamoDB table.
///
/// - Parameters:
/// - title: The movie's title (`String`).
/// - year: The movie's release year (`Int`).
///
/// - Throws: `MoviesError.ItemNotFound` if the movie isn't in the table.
///
/// - Returns: A `Movie` record with the movie's details.
func get(title: String, year: Int) async throws -> Movie {
do {
guard let client = self.ddbClient else {
throw MoviesError.UninitializedClient
}
let input = GetItemInput(
key: [
"year": .n(String(year)),
"title": .s(title)
],
tableName: self.tableName
)
let output = try await client.getItem(input: input)
guard let item = output.item else {
throw MoviesError.ItemNotFound
}
let movie = try Movie(withItem: item)
return movie
} catch {
print("ERROR: get:", dump(error))
throw error
}
}
```
+ For API details, see [GetItem](https://sdk.amazonaws.com/swift/api/awsdynamodb/latest/documentation/awsdynamodb/dynamodbclient/getitem(input:)) in *Amazon SDK for Swift API reference*.
------
For more DynamoDB examples, see [Code examples for DynamoDB using Amazon SDKs](service_code_examples.md).
To update the data in your table, proceed to [Step 4: Update data in a DynamoDB table](getting-started-step-4.md).
# Step 4: Update data in a DynamoDB table
In this step, you update an item that you created in [Step 2: Write data to a DynamoDB table](getting-started-step-2.md). You can use the DynamoDB console or the Amazon CLI to update the `AlbumTitle` of an item in the `Music` table by specifying `Artist`, `SongTitle`, and the updated `AlbumTitle`.
For more information about write operations, see [Writing an item](WorkingWithItems.md#WorkingWithItems.WritingData).
## Amazon Web Services Management Console
You can use the DynamoDB console to update data in the `Music` table.
1. Open the DynamoDB console at [https://console.amazonaws.cn/dynamodb/](https://console.amazonaws.cn/dynamodb/).
1. In the left navigation pane, choose **Tables**.
1. Choose the **Music** table from the table list.
1. Choose **Explore table items**.
1. In **Items returned**, for the item row with **Acme Band** **Artist** and **Happy Day** **SongTitle**, do the following:
1. Place your cursor on the **AlbumTitle** named **Songs About Life**.
1. Choose the Edit icon.
1. In the **Edit String** popup window, enter **Songs of Twilight**.
1. Choose **Save**.
**Tip**
Alternatively, to update an item, do the following in the **Items returned** section:
Choose the item row with **Artist** named **Acme Band** and **SongTitle** named **Happy Day**.
From the **Actions** dropdown list, choose **Edit item**.
For enter **AlbumTitle**, enter **Songs of Twilight**.
Choose **Save and close**.
## Amazon CLI
The following Amazon CLI example updates an item in the `Music` table. You can do this either through the DynamoDB API or [PartiQL](https://docs.amazonaws.cn/amazondynamodb/latest/developerguide/ql-reference.html), a SQL-compatible query language for DynamoDB.
------
#### [ DynamoDB API ]
**Linux**
```
aws dynamodb update-item \
--table-name Music \
--key '{ "Artist": {"S": "Acme Band"}, "SongTitle": {"S": "Happy Day"}}' \
--update-expression "SET AlbumTitle = :newval" \
--expression-attribute-values '{":newval":{"S":"Updated Album Title"}}' \
--return-values ALL_NEW
```
**Windows CMD**
```
aws dynamodb update-item ^
--table-name Music ^
--key "{\"Artist\": {\"S\": \"Acme Band\"}, \"SongTitle\": {\"S\": \"Happy Day\"}}" ^
--update-expression "SET AlbumTitle = :newval" ^
--expression-attribute-values "{\":newval\":{\"S\":\"Updated Album Title\"}}" ^
--return-values ALL_NEW
```
Using `update-item` returns the following sample result because `return-values ALL_NEW` was specified.
```
{
"Attributes": {
"AlbumTitle": {
"S": "Updated Album Title"
},
"Awards": {
"S": "10"
},
"Artist": {
"S": "Acme Band"
},
"SongTitle": {
"S": "Happy Day"
}
}
}
```
------
#### [ PartiQL for DynamoDB ]
**Linux**
```
aws dynamodb execute-statement --statement "UPDATE Music \
SET AlbumTitle='Updated Album Title' \
WHERE Artist='Acme Band' AND SongTitle='Happy Day' \
RETURNING ALL NEW *"
```
**Windows CMD**
```
aws dynamodb execute-statement --statement "UPDATE Music SET AlbumTitle='Updated Album Title' WHERE Artist='Acme Band' AND SongTitle='Happy Day' RETURNING ALL NEW *"
```
Using the `Update` statement returns the following sample result because `RETURNING ALL NEW *` was specified.
```
{
"Items": [
{
"AlbumTitle": {
"S": "Updated Album Title"
},
"Awards": {
"S": "10"
},
"Artist": {
"S": "Acme Band"
},
"SongTitle": {
"S": "Happy Day"
}
}
]
}
```
For more information about updating data with PartiQL, see [PartiQL update statements](https://docs.amazonaws.cn/amazondynamodb/latest/developerguide/ql-reference.update.html).
------
## Amazon SDK
The following code examples show how to update an item in a DynamoDB table using an Amazon SDK.
------
#### [ .NET ]
**Amazon SDK for .NET (v4)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/dotnetv4/DynamoDB#code-examples).
```
///
/// Updates an existing item in the movies table.
///
/// A Movie object containing information for
/// the movie to update.
/// A MovieInfo object that contains the
/// information that will be changed.
/// The name of the table that contains the movie.
/// A Boolean value that indicates the success of the operation.
public async Task UpdateItemAsync(
Movie newMovie,
MovieInfo newInfo,
string tableName)
{
try
{
var key = new Dictionary
{
["title"] = new AttributeValue { S = newMovie.Title },
["year"] = new AttributeValue { N = newMovie.Year.ToString() },
};
var updates = new Dictionary
{
["info.plot"] = new AttributeValueUpdate
{
Action = AttributeAction.PUT,
Value = new AttributeValue { S = newInfo.Plot },
},
["info.rating"] = new AttributeValueUpdate
{
Action = AttributeAction.PUT,
Value = new AttributeValue { N = newInfo.Rank.ToString() },
},
};
var request = new UpdateItemRequest
{
AttributeUpdates = updates,
Key = key,
TableName = tableName,
};
await _amazonDynamoDB.UpdateItemAsync(request);
return true;
}
catch (ResourceNotFoundException ex)
{
Console.WriteLine($"Table {tableName} or item was not found. {ex.Message}");
return false;
}
catch (AmazonDynamoDBException ex)
{
Console.WriteLine($"An Amazon DynamoDB error occurred while updating item. {ex.Message}");
throw;
}
catch (Exception ex)
{
Console.WriteLine($"An error occurred while updating item. {ex.Message}");
throw;
}
}
```
+ For API details, see [UpdateItem](https://docs.amazonaws.cn/goto/DotNetSDKV4/dynamodb-2012-08-10/UpdateItem) in *Amazon SDK for .NET API Reference*.
------
#### [ Bash ]
**Amazon CLI with Bash script**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/aws-cli/bash-linux/dynamodb#code-examples).
```
##############################################################################
# function dynamodb_update_item
#
# This function updates an item in a DynamoDB table.
#
#
# Parameters:
# -n table_name -- The name of the table.
# -k keys -- Path to json file containing the keys that identify the item to update.
# -e update expression -- An expression that defines one or more attributes to be updated.
# -v values -- Path to json file containing the update values.
#
# Returns:
# 0 - If successful.
# 1 - If it fails.
#############################################################################
function dynamodb_update_item() {
local table_name keys update_expression values response
local option OPTARG # Required to use getopts command in a function.
#######################################
# Function usage explanation
#######################################
function usage() {
echo "function dynamodb_update_item"
echo "Update an item in a DynamoDB table."
echo " -n table_name -- The name of the table."
echo " -k keys -- Path to json file containing the keys that identify the item to update."
echo " -e update expression -- An expression that defines one or more attributes to be updated."
echo " -v values -- Path to json file containing the update values."
echo ""
}
while getopts "n:k:e:v:h" option; do
case "${option}" in
n) table_name="${OPTARG}" ;;
k) keys="${OPTARG}" ;;
e) update_expression="${OPTARG}" ;;
v) values="${OPTARG}" ;;
h)
usage
return 0
;;
\?)
echo "Invalid parameter"
usage
return 1
;;
esac
done
export OPTIND=1
if [[ -z "$table_name" ]]; then
errecho "ERROR: You must provide a table name with the -n parameter."
usage
return 1
fi
if [[ -z "$keys" ]]; then
errecho "ERROR: You must provide a keys json file path the -k parameter."
usage
return 1
fi
if [[ -z "$update_expression" ]]; then
errecho "ERROR: You must provide an update expression with the -e parameter."
usage
return 1
fi
if [[ -z "$values" ]]; then
errecho "ERROR: You must provide a values json file path the -v parameter."
usage
return 1
fi
iecho "Parameters:\n"
iecho " table_name: $table_name"
iecho " keys: $keys"
iecho " update_expression: $update_expression"
iecho " values: $values"
response=$(aws dynamodb update-item \
--table-name "$table_name" \
--key file://"$keys" \
--update-expression "$update_expression" \
--expression-attribute-values file://"$values")
local error_code=${?}
if [[ $error_code -ne 0 ]]; then
aws_cli_error_log $error_code
errecho "ERROR: AWS reports update-item operation failed.$response"
return 1
fi
return 0
}
```
The utility functions used in this example.
```
###############################################################################
# function iecho
#
# This function enables the script to display the specified text only if
# the global variable $VERBOSE is set to true.
###############################################################################
function iecho() {
if [[ $VERBOSE == true ]]; then
echo "$@"
fi
}
###############################################################################
# function errecho
#
# This function outputs everything sent to it to STDERR (standard error output).
###############################################################################
function errecho() {
printf "%s\n" "$*" 1>&2
}
##############################################################################
# function aws_cli_error_log()
#
# This function is used to log the error messages from the AWS CLI.
#
# See https://docs.aws.amazon.com/cli/latest/topic/return-codes.html#cli-aws-help-return-codes.
#
# The function expects the following argument:
# $1 - The error code returned by the AWS CLI.
#
# Returns:
# 0: - Success.
#
##############################################################################
function aws_cli_error_log() {
local err_code=$1
errecho "Error code : $err_code"
if [ "$err_code" == 1 ]; then
errecho " One or more S3 transfers failed."
elif [ "$err_code" == 2 ]; then
errecho " Command line failed to parse."
elif [ "$err_code" == 130 ]; then
errecho " Process received SIGINT."
elif [ "$err_code" == 252 ]; then
errecho " Command syntax invalid."
elif [ "$err_code" == 253 ]; then
errecho " The system environment or configuration was invalid."
elif [ "$err_code" == 254 ]; then
errecho " The service returned an error."
elif [ "$err_code" == 255 ]; then
errecho " 255 is a catch-all error."
fi
return 0
}
```
+ For API details, see [UpdateItem](https://docs.amazonaws.cn/goto/aws-cli/dynamodb-2012-08-10/UpdateItem) in *Amazon CLI Command Reference*.
------
#### [ C\$1\$1 ]
**SDK for C\$1\$1**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/cpp/example_code/dynamodb#code-examples).
```
//! Update an Amazon DynamoDB table item.
/*!
\sa updateItem()
\param tableName: The table name.
\param partitionKey: The partition key.
\param partitionValue: The value for the partition key.
\param attributeKey: The key for the attribute to be updated.
\param attributeValue: The value for the attribute to be updated.
\param clientConfiguration: AWS client configuration.
\return bool: Function succeeded.
*/
/*
* The example code only sets/updates an attribute value. It processes
* the attribute value as a string, even if the value could be interpreted
* as a number. Also, the example code does not remove an existing attribute
* from the key value.
*/
bool AwsDoc::DynamoDB::updateItem(const Aws::String &tableName,
const Aws::String &partitionKey,
const Aws::String &partitionValue,
const Aws::String &attributeKey,
const Aws::String &attributeValue,
const Aws::Client::ClientConfiguration &clientConfiguration) {
Aws::DynamoDB::DynamoDBClient dynamoClient(clientConfiguration);
// *** Define UpdateItem request arguments.
// Define TableName argument.
Aws::DynamoDB::Model::UpdateItemRequest request;
request.SetTableName(tableName);
// Define KeyName argument.
Aws::DynamoDB::Model::AttributeValue attribValue;
attribValue.SetS(partitionValue);
request.AddKey(partitionKey, attribValue);
// Construct the SET update expression argument.
Aws::String update_expression("SET #a = :valueA");
request.SetUpdateExpression(update_expression);
// Construct attribute name argument.
Aws::Map expressionAttributeNames;
expressionAttributeNames["#a"] = attributeKey;
request.SetExpressionAttributeNames(expressionAttributeNames);
// Construct attribute value argument.
Aws::DynamoDB::Model::AttributeValue attributeUpdatedValue;
attributeUpdatedValue.SetS(attributeValue);
Aws::Map expressionAttributeValues;
expressionAttributeValues[":valueA"] = attributeUpdatedValue;
request.SetExpressionAttributeValues(expressionAttributeValues);
// Update the item.
const Aws::DynamoDB::Model::UpdateItemOutcome &outcome = dynamoClient.UpdateItem(
request);
if (outcome.IsSuccess()) {
std::cout << "Item was updated" << std::endl;
} else {
std::cerr << outcome.GetError().GetMessage() << std::endl;
return false;
}
return waitTableActive(tableName, dynamoClient);
}
```
Code that waits for the table to become active.
```
//! Query a newly created DynamoDB table until it is active.
/*!
\sa waitTableActive()
\param waitTableActive: The DynamoDB table's name.
\param dynamoClient: A DynamoDB client.
\return bool: Function succeeded.
*/
bool AwsDoc::DynamoDB::waitTableActive(const Aws::String &tableName,
const Aws::DynamoDB::DynamoDBClient &dynamoClient) {
// Repeatedly call DescribeTable until table is ACTIVE.
const int MAX_QUERIES = 20;
Aws::DynamoDB::Model::DescribeTableRequest request;
request.SetTableName(tableName);
int count = 0;
while (count < MAX_QUERIES) {
const Aws::DynamoDB::Model::DescribeTableOutcome &result = dynamoClient.DescribeTable(
request);
if (result.IsSuccess()) {
Aws::DynamoDB::Model::TableStatus status = result.GetResult().GetTable().GetTableStatus();
if (Aws::DynamoDB::Model::TableStatus::ACTIVE != status) {
std::this_thread::sleep_for(std::chrono::seconds(1));
}
else {
return true;
}
}
else {
std::cerr << "Error DynamoDB::waitTableActive "
<< result.GetError().GetMessage() << std::endl;
return false;
}
count++;
}
return false;
}
```
+ For API details, see [UpdateItem](https://docs.amazonaws.cn/goto/SdkForCpp/dynamodb-2012-08-10/UpdateItem) in *Amazon SDK for C\$1\$1 API Reference*.
------
#### [ CLI ]
**Amazon CLI**
**Example 1: To update an item in a table**
The following `update-item` example updates an item in the `MusicCollection` table. It adds a new attribute (`Year`) and modifies the `AlbumTitle` attribute. All of the attributes in the item, as they appear after the update, are returned in the response.
```
aws dynamodb update-item \
--table-name MusicCollection \
--key file://key.json \
--update-expression "SET #Y = :y, #AT = :t" \
--expression-attribute-names file://expression-attribute-names.json \
--expression-attribute-values file://expression-attribute-values.json \
--return-values ALL_NEW \
--return-consumed-capacity TOTAL \
--return-item-collection-metrics SIZE
```
Contents of `key.json`:
```
{
"Artist": {"S": "Acme Band"},
"SongTitle": {"S": "Happy Day"}
}
```
Contents of `expression-attribute-names.json`:
```
{
"#Y":"Year", "#AT":"AlbumTitle"
}
```
Contents of `expression-attribute-values.json`:
```
{
":y":{"N": "2015"},
":t":{"S": "Louder Than Ever"}
}
```
Output:
```
{
"Attributes": {
"AlbumTitle": {
"S": "Louder Than Ever"
},
"Awards": {
"N": "10"
},
"Artist": {
"S": "Acme Band"
},
"Year": {
"N": "2015"
},
"SongTitle": {
"S": "Happy Day"
}
},
"ConsumedCapacity": {
"TableName": "MusicCollection",
"CapacityUnits": 3.0
},
"ItemCollectionMetrics": {
"ItemCollectionKey": {
"Artist": {
"S": "Acme Band"
}
},
"SizeEstimateRangeGB": [
0.0,
1.0
]
}
}
```
For more information, see [Writing an Item](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/WorkingWithItems.html#WorkingWithItems.WritingData) in the *Amazon DynamoDB Developer Guide*.
**Example 2: To update an item conditionally**
The following example updates an item in the `MusicCollection` table, but only if the existing item does not already have a `Year` attribute.
```
aws dynamodb update-item \
--table-name MusicCollection \
--key file://key.json \
--update-expression "SET #Y = :y, #AT = :t" \
--expression-attribute-names file://expression-attribute-names.json \
--expression-attribute-values file://expression-attribute-values.json \
--condition-expression "attribute_not_exists(#Y)"
```
Contents of `key.json`:
```
{
"Artist": {"S": "Acme Band"},
"SongTitle": {"S": "Happy Day"}
}
```
Contents of `expression-attribute-names.json`:
```
{
"#Y":"Year",
"#AT":"AlbumTitle"
}
```
Contents of `expression-attribute-values.json`:
```
{
":y":{"N": "2015"},
":t":{"S": "Louder Than Ever"}
}
```
If the item already has a `Year` attribute, DynamoDB returns the following output.
```
An error occurred (ConditionalCheckFailedException) when calling the UpdateItem operation: The conditional request failed
```
For more information, see [Writing an Item](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/WorkingWithItems.html#WorkingWithItems.WritingData) in the *Amazon DynamoDB Developer Guide*.
+ For API details, see [UpdateItem](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/dynamodb/update-item.html) in *Amazon CLI Command Reference*.
------
#### [ Go ]
**SDK for Go V2**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/gov2/dynamodb#code-examples).
```
import (
"context"
"errors"
"log"
"time"
"github.com/aws/aws-sdk-go-v2/aws"
"github.com/aws/aws-sdk-go-v2/feature/dynamodb/attributevalue"
"github.com/aws/aws-sdk-go-v2/feature/dynamodb/expression"
"github.com/aws/aws-sdk-go-v2/service/dynamodb"
"github.com/aws/aws-sdk-go-v2/service/dynamodb/types"
)
// TableBasics encapsulates the Amazon DynamoDB service actions used in the examples.
// It contains a DynamoDB service client that is used to act on the specified table.
type TableBasics struct {
DynamoDbClient *dynamodb.Client
TableName string
}
// UpdateMovie updates the rating and plot of a movie that already exists in the
// DynamoDB table. This function uses the `expression` package to build the update
// expression.
func (basics TableBasics) UpdateMovie(ctx context.Context, movie Movie) (map[string]map[string]interface{}, error) {
var err error
var response *dynamodb.UpdateItemOutput
var attributeMap map[string]map[string]interface{}
update := expression.Set(expression.Name("info.rating"), expression.Value(movie.Info["rating"]))
update.Set(expression.Name("info.plot"), expression.Value(movie.Info["plot"]))
expr, err := expression.NewBuilder().WithUpdate(update).Build()
if err != nil {
log.Printf("Couldn't build expression for update. Here's why: %v\n", err)
} else {
response, err = basics.DynamoDbClient.UpdateItem(ctx, &dynamodb.UpdateItemInput{
TableName: aws.String(basics.TableName),
Key: movie.GetKey(),
ExpressionAttributeNames: expr.Names(),
ExpressionAttributeValues: expr.Values(),
UpdateExpression: expr.Update(),
ReturnValues: types.ReturnValueUpdatedNew,
})
if err != nil {
log.Printf("Couldn't update movie %v. Here's why: %v\n", movie.Title, err)
} else {
err = attributevalue.UnmarshalMap(response.Attributes, &attributeMap)
if err != nil {
log.Printf("Couldn't unmarshall update response. Here's why: %v\n", err)
}
}
}
return attributeMap, err
}
```
Define a Movie struct that is used in this example.
```
import (
"archive/zip"
"bytes"
"encoding/json"
"fmt"
"io"
"log"
"net/http"
"github.com/aws/aws-sdk-go-v2/feature/dynamodb/attributevalue"
"github.com/aws/aws-sdk-go-v2/service/dynamodb/types"
)
// Movie encapsulates data about a movie. Title and Year are the composite primary key
// of the movie in Amazon DynamoDB. Title is the sort key, Year is the partition key,
// and Info is additional data.
type Movie struct {
Title string `dynamodbav:"title"`
Year int `dynamodbav:"year"`
Info map[string]interface{} `dynamodbav:"info"`
}
// GetKey returns the composite primary key of the movie in a format that can be
// sent to DynamoDB.
func (movie Movie) GetKey() map[string]types.AttributeValue {
title, err := attributevalue.Marshal(movie.Title)
if err != nil {
panic(err)
}
year, err := attributevalue.Marshal(movie.Year)
if err != nil {
panic(err)
}
return map[string]types.AttributeValue{"title": title, "year": year}
}
// String returns the title, year, rating, and plot of a movie, formatted for the example.
func (movie Movie) String() string {
return fmt.Sprintf("%v\n\tReleased: %v\n\tRating: %v\n\tPlot: %v\n",
movie.Title, movie.Year, movie.Info["rating"], movie.Info["plot"])
}
```
+ For API details, see [UpdateItem](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/service/dynamodb#Client.UpdateItem) in *Amazon SDK for Go API Reference*.
------
#### [ Java ]
**SDK for Java 2.x**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2/example_code/dynamodb#code-examples).
Updates an item in a table using [DynamoDbClient](http://docs.aws.amazon.com/sdk-for-java/latest/reference/software/amazon/awssdk/services/dynamodb/DynamoDbClient.html).
```
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.dynamodb.model.DynamoDbException;
import software.amazon.awssdk.services.dynamodb.model.AttributeAction;
import software.amazon.awssdk.services.dynamodb.model.AttributeValue;
import software.amazon.awssdk.services.dynamodb.model.AttributeValueUpdate;
import software.amazon.awssdk.services.dynamodb.model.UpdateItemRequest;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
import java.util.HashMap;
/**
* Before running this Java V2 code example, set up your development
* environment, including your credentials.
*
* For more information, see the following documentation topic:
*
* https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/get-started.html
*
* To update an Amazon DynamoDB table using the AWS SDK for Java V2, its better
* practice to use the
* Enhanced Client, See the EnhancedModifyItem example.
*/
public class UpdateItem {
public static void main(String[] args) {
final String usage = """
Usage:
Where:
tableName - The Amazon DynamoDB table (for example, Music3).
key - The name of the key in the table (for example, Artist).
keyVal - The value of the key (for example, Famous Band).
name - The name of the column where the value is updated (for example, Awards).
updateVal - The value used to update an item (for example, 14).
Example:
UpdateItem Music3 Artist Famous Band Awards 14
""";
if (args.length != 5) {
System.out.println(usage);
System.exit(1);
}
String tableName = args[0];
String key = args[1];
String keyVal = args[2];
String name = args[3];
String updateVal = args[4];
Region region = Region.US_EAST_1;
DynamoDbClient ddb = DynamoDbClient.builder()
.region(region)
.build();
updateTableItem(ddb, tableName, key, keyVal, name, updateVal);
ddb.close();
}
public static void updateTableItem(DynamoDbClient ddb,
String tableName,
String key,
String keyVal,
String name,
String updateVal) {
HashMap itemKey = new HashMap<>();
itemKey.put(key, AttributeValue.builder()
.s(keyVal)
.build());
HashMap updatedValues = new HashMap<>();
updatedValues.put(name, AttributeValueUpdate.builder()
.value(AttributeValue.builder().s(updateVal).build())
.action(AttributeAction.PUT)
.build());
UpdateItemRequest request = UpdateItemRequest.builder()
.tableName(tableName)
.key(itemKey)
.attributeUpdates(updatedValues)
.build();
try {
ddb.updateItem(request);
} catch (DynamoDbException e) {
System.err.println(e.getMessage());
System.exit(1);
}
System.out.println("The Amazon DynamoDB table was updated!");
}
}
```
+ For API details, see [UpdateItem](https://docs.amazonaws.cn/goto/SdkForJavaV2/dynamodb-2012-08-10/UpdateItem) in *Amazon SDK for Java 2.x API Reference*.
------
#### [ JavaScript ]
**SDK for JavaScript (v3)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javascriptv3/example_code/dynamodb#code-examples).
This example uses the document client to simplify working with items in DynamoDB. For API details see [UpdateCommand](https://docs.amazonaws.cn/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-lib-dynamodb/Class/UpdateCommand/).
```
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, UpdateCommand } from "@aws-sdk/lib-dynamodb";
const client = new DynamoDBClient({});
const docClient = DynamoDBDocumentClient.from(client);
export const main = async () => {
const command = new UpdateCommand({
TableName: "Dogs",
Key: {
Breed: "Labrador",
},
UpdateExpression: "set Color = :color",
ExpressionAttributeValues: {
":color": "black",
},
ReturnValues: "ALL_NEW",
});
const response = await docClient.send(command);
console.log(response);
return response;
};
```
+ For API details, see [UpdateItem](https://docs.amazonaws.cn/AWSJavaScriptSDK/v3/latest/client/dynamodb/command/UpdateItemCommand) in *Amazon SDK for JavaScript API Reference*.
------
#### [ Kotlin ]
**SDK for Kotlin**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/kotlin/services/dynamodb#code-examples).
```
suspend fun updateTableItem(
tableNameVal: String,
keyName: String,
keyVal: String,
name: String,
updateVal: String,
) {
val itemKey = mutableMapOf()
itemKey[keyName] = AttributeValue.S(keyVal)
val updatedValues = mutableMapOf()
updatedValues[name] =
AttributeValueUpdate {
value = AttributeValue.S(updateVal)
action = AttributeAction.Put
}
val request =
UpdateItemRequest {
tableName = tableNameVal
key = itemKey
attributeUpdates = updatedValues
}
DynamoDbClient.fromEnvironment { region = "us-east-1" }.use { ddb ->
ddb.updateItem(request)
println("Item in $tableNameVal was updated")
}
}
```
+ For API details, see [UpdateItem](https://sdk.amazonaws.com/kotlin/api/latest/index.html) in *Amazon SDK for Kotlin API reference*.
------
#### [ PHP ]
**SDK for PHP**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code/dynamodb#code-examples).
```
echo "What rating would you like to give {$movie['Item']['title']['S']}?\n";
$rating = 0;
while (!is_numeric($rating) || intval($rating) != $rating || $rating < 1 || $rating > 10) {
$rating = testable_readline("Rating (1-10): ");
}
$service->updateItemAttributeByKey($tableName, $key, 'rating', 'N', $rating);
public function updateItemAttributeByKey(
string $tableName,
array $key,
string $attributeName,
string $attributeType,
string $newValue
) {
$this->dynamoDbClient->updateItem([
'Key' => $key['Item'],
'TableName' => $tableName,
'UpdateExpression' => "set #NV=:NV",
'ExpressionAttributeNames' => [
'#NV' => $attributeName,
],
'ExpressionAttributeValues' => [
':NV' => [
$attributeType => $newValue
]
],
]);
}
```
+ For API details, see [UpdateItem](https://docs.amazonaws.cn/goto/SdkForPHPV3/dynamodb-2012-08-10/UpdateItem) in *Amazon SDK for PHP API Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: Sets the genre attribute to 'Rap' on the DynamoDB item with the partition key SongTitle and the sort key Artist.**
```
$key = @{
SongTitle = 'Somewhere Down The Road'
Artist = 'No One You Know'
} | ConvertTo-DDBItem
$updateDdbItem = @{
TableName = 'Music'
Key = $key
UpdateExpression = 'set Genre = :val1'
ExpressionAttributeValue = (@{
':val1' = ([Amazon.DynamoDBv2.Model.AttributeValue]'Rap')
})
}
Update-DDBItem @updateDdbItem
```
**Output:**
```
Name Value
---- -----
Genre Rap
```
+ For API details, see [UpdateItem](https://docs.aws.amazon.com/powershell/v4/reference) in *Amazon Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: Sets the genre attribute to 'Rap' on the DynamoDB item with the partition key SongTitle and the sort key Artist.**
```
$key = @{
SongTitle = 'Somewhere Down The Road'
Artist = 'No One You Know'
} | ConvertTo-DDBItem
$updateDdbItem = @{
TableName = 'Music'
Key = $key
UpdateExpression = 'set Genre = :val1'
ExpressionAttributeValue = (@{
':val1' = ([Amazon.DynamoDBv2.Model.AttributeValue]'Rap')
})
}
Update-DDBItem @updateDdbItem
```
**Output:**
```
Name Value
---- -----
Genre Rap
```
+ For API details, see [UpdateItem](https://docs.aws.amazon.com/powershell/v5/reference) in *Amazon Tools for PowerShell Cmdlet Reference (V5)*.
------
#### [ Python ]
**SDK for Python (Boto3)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/dynamodb#code-examples).
Update an item by using an update expression.
```
class Movies:
"""Encapsulates an Amazon DynamoDB table of movie data.
Example data structure for a movie record in this table:
{
"year": 1999,
"title": "For Love of the Game",
"info": {
"directors": ["Sam Raimi"],
"release_date": "1999-09-15T00:00:00Z",
"rating": 6.3,
"plot": "A washed up pitcher flashes through his career.",
"rank": 4987,
"running_time_secs": 8220,
"actors": [
"Kevin Costner",
"Kelly Preston",
"John C. Reilly"
]
}
}
"""
def __init__(self, dyn_resource):
"""
:param dyn_resource: A Boto3 DynamoDB resource.
"""
self.dyn_resource = dyn_resource
# The table variable is set during the scenario in the call to
# 'exists' if the table exists. Otherwise, it is set by 'create_table'.
self.table = None
def update_movie(self, title, year, rating, plot):
"""
Updates rating and plot data for a movie in the table.
:param title: The title of the movie to update.
:param year: The release year of the movie to update.
:param rating: The updated rating to the give the movie.
:param plot: The updated plot summary to give the movie.
:return: The fields that were updated, with their new values.
"""
try:
response = self.table.update_item(
Key={"year": year, "title": title},
UpdateExpression="set info.rating=:r, info.plot=:p",
ExpressionAttributeValues={":r": Decimal(str(rating)), ":p": plot},
ReturnValues="UPDATED_NEW",
)
except ClientError as err:
logger.error(
"Couldn't update movie %s in table %s. Here's why: %s: %s",
title,
self.table.name,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
else:
return response["Attributes"]
```
Update an item by using an update expression that includes an arithmetic operation.
```
class UpdateQueryWrapper:
def __init__(self, table):
self.table = table
def update_rating(self, title, year, rating_change):
"""
Updates the quality rating of a movie in the table by using an arithmetic
operation in the update expression. By specifying an arithmetic operation,
you can adjust a value in a single request, rather than first getting its
value and then setting its new value.
:param title: The title of the movie to update.
:param year: The release year of the movie to update.
:param rating_change: The amount to add to the current rating for the movie.
:return: The updated rating.
"""
try:
response = self.table.update_item(
Key={"year": year, "title": title},
UpdateExpression="set info.rating = info.rating + :val",
ExpressionAttributeValues={":val": Decimal(str(rating_change))},
ReturnValues="UPDATED_NEW",
)
except ClientError as err:
logger.error(
"Couldn't update movie %s in table %s. Here's why: %s: %s",
title,
self.table.name,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
else:
return response["Attributes"]
```
Update an item only when it meets certain conditions.
```
class UpdateQueryWrapper:
def __init__(self, table):
self.table = table
def remove_actors(self, title, year, actor_threshold):
"""
Removes an actor from a movie, but only when the number of actors is greater
than a specified threshold. If the movie does not list more than the threshold,
no actors are removed.
:param title: The title of the movie to update.
:param year: The release year of the movie to update.
:param actor_threshold: The threshold of actors to check.
:return: The movie data after the update.
"""
try:
response = self.table.update_item(
Key={"year": year, "title": title},
UpdateExpression="remove info.actors[0]",
ConditionExpression="size(info.actors) > :num",
ExpressionAttributeValues={":num": actor_threshold},
ReturnValues="ALL_NEW",
)
except ClientError as err:
if err.response["Error"]["Code"] == "ConditionalCheckFailedException":
logger.warning(
"Didn't update %s because it has fewer than %s actors.",
title,
actor_threshold + 1,
)
else:
logger.error(
"Couldn't update movie %s. Here's why: %s: %s",
title,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
else:
return response["Attributes"]
```
+ For API details, see [UpdateItem](https://docs.amazonaws.cn/goto/boto3/dynamodb-2012-08-10/UpdateItem) in *Amazon SDK for Python (Boto3) API Reference*.
------
#### [ Ruby ]
**SDK for Ruby**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/ruby/example_code/dynamodb#code-examples).
```
class DynamoDBBasics
attr_reader :dynamo_resource, :table
def initialize(table_name)
client = Aws::DynamoDB::Client.new(region: 'us-east-1')
@dynamo_resource = Aws::DynamoDB::Resource.new(client: client)
@table = @dynamo_resource.table(table_name)
end
# Updates rating and plot data for a movie in the table.
#
# @param movie [Hash] The title, year, plot, rating of the movie.
def update_item(movie)
response = @table.update_item(
key: { 'year' => movie[:year], 'title' => movie[:title] },
update_expression: 'set info.rating=:r',
expression_attribute_values: { ':r' => movie[:rating] },
return_values: 'UPDATED_NEW'
)
rescue Aws::DynamoDB::Errors::ServiceError => e
puts("Couldn't update movie #{movie[:title]} (#{movie[:year]}) in table #{@table.name}\n")
puts("\t#{e.code}: #{e.message}")
raise
else
response.attributes
end
```
+ For API details, see [UpdateItem](https://docs.amazonaws.cn/goto/SdkForRubyV3/dynamodb-2012-08-10/UpdateItem) in *Amazon SDK for Ruby API Reference*.
------
#### [ SAP ABAP ]
**SDK for SAP ABAP**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/sap-abap/services/dyn#code-examples).
```
TRY.
oo_output = lo_dyn->updateitem(
iv_tablename = iv_table_name
it_key = it_item_key
it_attributeupdates = it_attribute_updates ).
MESSAGE '1 item updated in DynamoDB Table' && iv_table_name TYPE 'I'.
CATCH /aws1/cx_dyncondalcheckfaile00.
MESSAGE 'A condition specified in the operation could not be evaluated.' TYPE 'E'.
CATCH /aws1/cx_dynresourcenotfoundex.
MESSAGE 'The table or index does not exist' TYPE 'E'.
CATCH /aws1/cx_dyntransactconflictex.
MESSAGE 'Another transaction is using the item' TYPE 'E'.
ENDTRY.
```
+ For API details, see [UpdateItem](https://docs.amazonaws.cn/sdk-for-sap-abap/v1/api/latest/index.html) in *Amazon SDK for SAP ABAP API reference*.
------
#### [ Swift ]
**SDK for Swift**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/swift/example_code/dynamodb#code-examples).
```
import AWSDynamoDB
/// Update the specified movie with new `rating` and `plot` information.
///
/// - Parameters:
/// - title: The title of the movie to update.
/// - year: The release year of the movie to update.
/// - rating: The new rating for the movie.
/// - plot: The new plot summary string for the movie.
///
/// - Returns: An array of mappings of attribute names to their new
/// listing each item actually changed. Items that didn't need to change
/// aren't included in this list. `nil` if no changes were made.
///
func update(title: String, year: Int, rating: Double? = nil, plot: String? = nil) async throws
-> [Swift.String: DynamoDBClientTypes.AttributeValue]?
{
do {
guard let client = self.ddbClient else {
throw MoviesError.UninitializedClient
}
// Build the update expression and the list of expression attribute
// values. Include only the information that's changed.
var expressionParts: [String] = []
var attrValues: [Swift.String: DynamoDBClientTypes.AttributeValue] = [:]
if rating != nil {
expressionParts.append("info.rating=:r")
attrValues[":r"] = .n(String(rating!))
}
if plot != nil {
expressionParts.append("info.plot=:p")
attrValues[":p"] = .s(plot!)
}
let expression = "set \(expressionParts.joined(separator: ", "))"
let input = UpdateItemInput(
// Create substitution tokens for the attribute values, to ensure
// no conflicts in expression syntax.
expressionAttributeValues: attrValues,
// The key identifying the movie to update consists of the release
// year and title.
key: [
"year": .n(String(year)),
"title": .s(title)
],
returnValues: .updatedNew,
tableName: self.tableName,
updateExpression: expression
)
let output = try await client.updateItem(input: input)
guard let attributes: [Swift.String: DynamoDBClientTypes.AttributeValue] = output.attributes else {
throw MoviesError.InvalidAttributes
}
return attributes
} catch {
print("ERROR: update:", dump(error))
throw error
}
}
```
+ For API details, see [UpdateItem](https://sdk.amazonaws.com/swift/api/awsdynamodb/latest/documentation/awsdynamodb/dynamodbclient/updateitem(input:)) in *Amazon SDK for Swift API reference*.
------
For more DynamoDB examples, see [Code examples for DynamoDB using Amazon SDKs](service_code_examples.md).
To query the data in the `Music` table, proceed to [Step 5: Query data in a DynamoDB table](getting-started-step-5.md).
# Step 5: Query data in a DynamoDB table
In this step, you query the data that you wrote to the `Music` table in [Step 2: Write data to a DynamoDB table](getting-started-step-2.md) by specifying `Artist`. This will display all songs that are associated with the partition key: `Artist`.
For more information about query operations, see [Querying tables in DynamoDB](Query.md).
## Amazon Web Services Management Console
Follow these steps to use the DynamoDB console to query data in the `Music` table.
1. Open the DynamoDB console at [https://console.amazonaws.cn/dynamodb/](https://console.amazonaws.cn/dynamodb/).
1. In the left navigation pane, choose **Tables**.
1. Choose the **Music** table from the table list.
1. Choose **Explore table items**.
1. In **Scan or query items**, make sure that **Query** is selected.
1. For **Partition key**, enter **Acme Band**, and then choose **Run**.
## Amazon CLI
The following Amazon CLI example queries an item in the `Music` table. You can do this either through the DynamoDB API or [PartiQL](https://docs.amazonaws.cn/amazondynamodb/latest/developerguide/ql-reference.html), a SQL-compatible query language for DynamoDB.
------
#### [ DynamoDB API ]
You query an item through the DynamoDB API by using `query` and providing the partition key.
**Linux**
```
aws dynamodb query \
--table-name Music \
--key-condition-expression "Artist = :name" \
--expression-attribute-values '{":name":{"S":"Acme Band"}}'
```
**Windows CMD**
```
aws dynamodb query ^
--table-name Music ^
--key-condition-expression "Artist = :name" ^
--expression-attribute-values "{\":name\":{\"S\":\"Acme Band\"}}"
```
Using `query` returns all the songs associated with this particular `Artist`.
```
{
"Items": [
{
"AlbumTitle": {
"S": "Updated Album Title"
},
"Awards": {
"N": "10"
},
"Artist": {
"S": "Acme Band"
},
"SongTitle": {
"S": "Happy Day"
}
},
{
"AlbumTitle": {
"S": "Another Album Title"
},
"Awards": {
"N": "8"
},
"Artist": {
"S": "Acme Band"
},
"SongTitle": {
"S": "PartiQL Rocks"
}
}
],
"Count": 2,
"ScannedCount": 2,
"ConsumedCapacity": null
}
```
------
#### [ PartiQL for DynamoDB ]
You query an item through PartiQL by using the `Select` statement and providing the partition key.
**Linux**
```
aws dynamodb execute-statement --statement "SELECT * FROM Music \
WHERE Artist='Acme Band'"
```
**Windows CMD**
```
aws dynamodb execute-statement --statement "SELECT * FROM Music WHERE Artist='Acme Band'"
```
Using the `Select` statement in this way returns all the songs associated with this particular `Artist`.
```
{
"Items": [
{
"AlbumTitle": {
"S": "Updated Album Title"
},
"Awards": {
"S": "10"
},
"Artist": {
"S": "Acme Band"
},
"SongTitle": {
"S": "Happy Day"
}
},
{
"AlbumTitle": {
"S": "Another Album Title"
},
"Awards": {
"S": "8"
},
"Artist": {
"S": "Acme Band"
},
"SongTitle": {
"S": "PartiQL Rocks"
}
}
]
}
```
For more information about querying data with PartiQL, see [PartiQL select statements](https://docs.amazonaws.cn/amazondynamodb/latest/developerguide/ql-reference.select.html).
------
## Amazon SDK
The following code examples show how to query a DynamoDB table using an Amazon SDK.
------
#### [ .NET ]
**Amazon SDK for .NET (v4)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/dotnetv4/DynamoDB#code-examples).
```
///
/// Queries the table for movies released in a particular year and
/// then displays the information for the movies returned.
///
/// The name of the table to query.
/// The release year for which we want to
/// view movies.
/// The number of movies that match the query.
public async Task QueryMoviesAsync(string tableName, int year)
{
try
{
var movieTable = new TableBuilder(_amazonDynamoDB, tableName)
.AddHashKey("year", DynamoDBEntryType.Numeric)
.AddRangeKey("title", DynamoDBEntryType.String)
.Build();
var filter = new QueryFilter("year", QueryOperator.Equal, year);
Console.WriteLine("\nFind movies released in: {year}:");
var config = new QueryOperationConfig()
{
Limit = 10, // 10 items per page.
Select = SelectValues.SpecificAttributes,
AttributesToGet = new List
{
"title",
"year",
},
ConsistentRead = true,
Filter = filter,
};
// Value used to track how many movies match the
// supplied criteria.
var moviesFound = 0;
var search = movieTable.Query(config);
do
{
var movieList = await search.GetNextSetAsync();
moviesFound += movieList.Count;
foreach (var movie in movieList)
{
DisplayDocument(movie);
}
}
while (!search.IsDone);
return moviesFound;
}
catch (ResourceNotFoundException ex)
{
Console.WriteLine($"Table {tableName} was not found. {ex.Message}");
return 0;
}
catch (AmazonDynamoDBException ex)
{
Console.WriteLine($"An Amazon DynamoDB error occurred while querying movies. {ex.Message}");
throw;
}
catch (Exception ex)
{
Console.WriteLine($"An error occurred while querying movies. {ex.Message}");
throw;
}
}
```
+ For API details, see [Query](https://docs.amazonaws.cn/goto/DotNetSDKV4/dynamodb-2012-08-10/Query) in *Amazon SDK for .NET API Reference*.
------
#### [ Bash ]
**Amazon CLI with Bash script**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/aws-cli/bash-linux/dynamodb#code-examples).
```
#############################################################################
# function dynamodb_query
#
# This function queries a DynamoDB table.
#
# Parameters:
# -n table_name -- The name of the table.
# -k key_condition_expression -- The key condition expression.
# -a attribute_names -- Path to JSON file containing the attribute names.
# -v attribute_values -- Path to JSON file containing the attribute values.
# [-p projection_expression] -- Optional projection expression.
#
# Returns:
# The items as json output.
# And:
# 0 - If successful.
# 1 - If it fails.
###########################################################################
function dynamodb_query() {
local table_name key_condition_expression attribute_names attribute_values projection_expression response
local option OPTARG # Required to use getopts command in a function.
# ######################################
# Function usage explanation
#######################################
function usage() {
echo "function dynamodb_query"
echo "Query a DynamoDB table."
echo " -n table_name -- The name of the table."
echo " -k key_condition_expression -- The key condition expression."
echo " -a attribute_names -- Path to JSON file containing the attribute names."
echo " -v attribute_values -- Path to JSON file containing the attribute values."
echo " [-p projection_expression] -- Optional projection expression."
echo ""
}
while getopts "n:k:a:v:p:h" option; do
case "${option}" in
n) table_name="${OPTARG}" ;;
k) key_condition_expression="${OPTARG}" ;;
a) attribute_names="${OPTARG}" ;;
v) attribute_values="${OPTARG}" ;;
p) projection_expression="${OPTARG}" ;;
h)
usage
return 0
;;
\?)
echo "Invalid parameter"
usage
return 1
;;
esac
done
export OPTIND=1
if [[ -z "$table_name" ]]; then
errecho "ERROR: You must provide a table name with the -n parameter."
usage
return 1
fi
if [[ -z "$key_condition_expression" ]]; then
errecho "ERROR: You must provide a key condition expression with the -k parameter."
usage
return 1
fi
if [[ -z "$attribute_names" ]]; then
errecho "ERROR: You must provide a attribute names with the -a parameter."
usage
return 1
fi
if [[ -z "$attribute_values" ]]; then
errecho "ERROR: You must provide a attribute values with the -v parameter."
usage
return 1
fi
if [[ -z "$projection_expression" ]]; then
response=$(aws dynamodb query \
--table-name "$table_name" \
--key-condition-expression "$key_condition_expression" \
--expression-attribute-names file://"$attribute_names" \
--expression-attribute-values file://"$attribute_values")
else
response=$(aws dynamodb query \
--table-name "$table_name" \
--key-condition-expression "$key_condition_expression" \
--expression-attribute-names file://"$attribute_names" \
--expression-attribute-values file://"$attribute_values" \
--projection-expression "$projection_expression")
fi
local error_code=${?}
if [[ $error_code -ne 0 ]]; then
aws_cli_error_log $error_code
errecho "ERROR: AWS reports query operation failed.$response"
return 1
fi
echo "$response"
return 0
}
```
The utility functions used in this example.
```
###############################################################################
# function errecho
#
# This function outputs everything sent to it to STDERR (standard error output).
###############################################################################
function errecho() {
printf "%s\n" "$*" 1>&2
}
##############################################################################
# function aws_cli_error_log()
#
# This function is used to log the error messages from the AWS CLI.
#
# See https://docs.aws.amazon.com/cli/latest/topic/return-codes.html#cli-aws-help-return-codes.
#
# The function expects the following argument:
# $1 - The error code returned by the AWS CLI.
#
# Returns:
# 0: - Success.
#
##############################################################################
function aws_cli_error_log() {
local err_code=$1
errecho "Error code : $err_code"
if [ "$err_code" == 1 ]; then
errecho " One or more S3 transfers failed."
elif [ "$err_code" == 2 ]; then
errecho " Command line failed to parse."
elif [ "$err_code" == 130 ]; then
errecho " Process received SIGINT."
elif [ "$err_code" == 252 ]; then
errecho " Command syntax invalid."
elif [ "$err_code" == 253 ]; then
errecho " The system environment or configuration was invalid."
elif [ "$err_code" == 254 ]; then
errecho " The service returned an error."
elif [ "$err_code" == 255 ]; then
errecho " 255 is a catch-all error."
fi
return 0
}
```
+ For API details, see [Query](https://docs.amazonaws.cn/goto/aws-cli/dynamodb-2012-08-10/Query) in *Amazon CLI Command Reference*.
------
#### [ C\$1\$1 ]
**SDK for C\$1\$1**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/cpp/example_code/dynamodb#code-examples).
```
//! Perform a query on an Amazon DynamoDB Table and retrieve items.
/*!
\sa queryItem()
\param tableName: The table name.
\param partitionKey: The partition key.
\param partitionValue: The value for the partition key.
\param projectionExpression: The projections expression, which is ignored if empty.
\param clientConfiguration: AWS client configuration.
\return bool: Function succeeded.
*/
/*
* The partition key attribute is searched with the specified value. By default, all fields and values
* contained in the item are returned. If an optional projection expression is
* specified on the command line, only the specified fields and values are
* returned.
*/
bool AwsDoc::DynamoDB::queryItems(const Aws::String &tableName,
const Aws::String &partitionKey,
const Aws::String &partitionValue,
const Aws::String &projectionExpression,
const Aws::Client::ClientConfiguration &clientConfiguration) {
Aws::DynamoDB::DynamoDBClient dynamoClient(clientConfiguration);
Aws::DynamoDB::Model::QueryRequest request;
request.SetTableName(tableName);
if (!projectionExpression.empty()) {
request.SetProjectionExpression(projectionExpression);
}
// Set query key condition expression.
request.SetKeyConditionExpression(partitionKey + "= :valueToMatch");
// Set Expression AttributeValues.
Aws::Map attributeValues;
attributeValues.emplace(":valueToMatch", partitionValue);
request.SetExpressionAttributeValues(attributeValues);
bool result = true;
// "exclusiveStartKey" is used for pagination.
Aws::Map exclusiveStartKey;
do {
if (!exclusiveStartKey.empty()) {
request.SetExclusiveStartKey(exclusiveStartKey);
exclusiveStartKey.clear();
}
// Perform Query operation.
const Aws::DynamoDB::Model::QueryOutcome &outcome = dynamoClient.Query(request);
if (outcome.IsSuccess()) {
// Reference the retrieved items.
const Aws::Vector> &items = outcome.GetResult().GetItems();
if (!items.empty()) {
std::cout << "Number of items retrieved from Query: " << items.size()
<< std::endl;
// Iterate each item and print.
for (const auto &item: items) {
std::cout
<< "******************************************************"
<< std::endl;
// Output each retrieved field and its value.
for (const auto &i: item)
std::cout << i.first << ": " << i.second.GetS() << std::endl;
}
}
else {
std::cout << "No item found in table: " << tableName << std::endl;
}
exclusiveStartKey = outcome.GetResult().GetLastEvaluatedKey();
}
else {
std::cerr << "Failed to Query items: " << outcome.GetError().GetMessage();
result = false;
break;
}
} while (!exclusiveStartKey.empty());
return result;
}
```
+ For API details, see [Query](https://docs.amazonaws.cn/goto/SdkForCpp/dynamodb-2012-08-10/Query) in *Amazon SDK for C\$1\$1 API Reference*.
------
#### [ CLI ]
**Amazon CLI**
**Example 1: To query a table**
The following `query` example queries items in the `MusicCollection` table. The table has a hash-and-range primary key (`Artist` and `SongTitle`), but this query only specifies the hash key value. It returns song titles by the artist named "No One You Know".
```
aws dynamodb query \
--table-name MusicCollection \
--projection-expression "SongTitle" \
--key-condition-expression "Artist = :v1" \
--expression-attribute-values file://expression-attributes.json \
--return-consumed-capacity TOTAL
```
Contents of `expression-attributes.json`:
```
{
":v1": {"S": "No One You Know"}
}
```
Output:
```
{
"Items": [
{
"SongTitle": {
"S": "Call Me Today"
},
"SongTitle": {
"S": "Scared of My Shadow"
}
}
],
"Count": 2,
"ScannedCount": 2,
"ConsumedCapacity": {
"TableName": "MusicCollection",
"CapacityUnits": 0.5
}
}
```
For more information, see [Working with Queries in DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Query.html) in the *Amazon DynamoDB Developer Guide*.
**Example 2: To query a table using strongly consistent reads and traverse the index in descending order**
The following example performs the same query as the first example, but returns results in reverse order and uses strongly consistent reads.
```
aws dynamodb query \
--table-name MusicCollection \
--projection-expression "SongTitle" \
--key-condition-expression "Artist = :v1" \
--expression-attribute-values file://expression-attributes.json \
--consistent-read \
--no-scan-index-forward \
--return-consumed-capacity TOTAL
```
Contents of `expression-attributes.json`:
```
{
":v1": {"S": "No One You Know"}
}
```
Output:
```
{
"Items": [
{
"SongTitle": {
"S": "Scared of My Shadow"
}
},
{
"SongTitle": {
"S": "Call Me Today"
}
}
],
"Count": 2,
"ScannedCount": 2,
"ConsumedCapacity": {
"TableName": "MusicCollection",
"CapacityUnits": 1.0
}
}
```
For more information, see [Working with Queries in DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Query.html) in the *Amazon DynamoDB Developer Guide*.
**Example 3: To filter out specific results**
The following example queries the `MusicCollection` but excludes results with specific values in the `AlbumTitle` attribute. Note that this does not affect the `ScannedCount` or `ConsumedCapacity`, because the filter is applied after the items have been read.
```
aws dynamodb query \
--table-name MusicCollection \
--key-condition-expression "#n1 = :v1" \
--filter-expression "NOT (#n2 IN (:v2, :v3))" \
--expression-attribute-names file://names.json \
--expression-attribute-values file://values.json \
--return-consumed-capacity TOTAL
```
Contents of `values.json`:
```
{
":v1": {"S": "No One You Know"},
":v2": {"S": "Blue Sky Blues"},
":v3": {"S": "Greatest Hits"}
}
```
Contents of `names.json`:
```
{
"#n1": "Artist",
"#n2": "AlbumTitle"
}
```
Output:
```
{
"Items": [
{
"AlbumTitle": {
"S": "Somewhat Famous"
},
"Artist": {
"S": "No One You Know"
},
"SongTitle": {
"S": "Call Me Today"
}
}
],
"Count": 1,
"ScannedCount": 2,
"ConsumedCapacity": {
"TableName": "MusicCollection",
"CapacityUnits": 0.5
}
}
```
For more information, see [Working with Queries in DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Query.html) in the *Amazon DynamoDB Developer Guide*.
**Example 4: To retrieve only an item count**
The following example retrieves a count of items matching the query, but does not retrieve any of the items themselves.
```
aws dynamodb query \
--table-name MusicCollection \
--select COUNT \
--key-condition-expression "Artist = :v1" \
--expression-attribute-values file://expression-attributes.json
```
Contents of `expression-attributes.json`:
```
{
":v1": {"S": "No One You Know"}
}
```
Output:
```
{
"Count": 2,
"ScannedCount": 2,
"ConsumedCapacity": null
}
```
For more information, see [Working with Queries in DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Query.html) in the *Amazon DynamoDB Developer Guide*.
**Example 5: To query an index**
The following example queries the local secondary index `AlbumTitleIndex`. The query returns all attributes from the base table that have been projected into the local secondary index. Note that when querying a local secondary index or global secondary index, you must also provide the name of the base table using the `table-name` parameter.
```
aws dynamodb query \
--table-name MusicCollection \
--index-name AlbumTitleIndex \
--key-condition-expression "Artist = :v1" \
--expression-attribute-values file://expression-attributes.json \
--select ALL_PROJECTED_ATTRIBUTES \
--return-consumed-capacity INDEXES
```
Contents of `expression-attributes.json`:
```
{
":v1": {"S": "No One You Know"}
}
```
Output:
```
{
"Items": [
{
"AlbumTitle": {
"S": "Blue Sky Blues"
},
"Artist": {
"S": "No One You Know"
},
"SongTitle": {
"S": "Scared of My Shadow"
}
},
{
"AlbumTitle": {
"S": "Somewhat Famous"
},
"Artist": {
"S": "No One You Know"
},
"SongTitle": {
"S": "Call Me Today"
}
}
],
"Count": 2,
"ScannedCount": 2,
"ConsumedCapacity": {
"TableName": "MusicCollection",
"CapacityUnits": 0.5,
"Table": {
"CapacityUnits": 0.0
},
"LocalSecondaryIndexes": {
"AlbumTitleIndex": {
"CapacityUnits": 0.5
}
}
}
}
```
For more information, see [Working with Queries in DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Query.html) in the *Amazon DynamoDB Developer Guide*.
+ For API details, see [Query](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/dynamodb/query.html) in *Amazon CLI Command Reference*.
------
#### [ Go ]
**SDK for Go V2**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/gov2/dynamodb#code-examples).
```
import (
"context"
"errors"
"log"
"time"
"github.com/aws/aws-sdk-go-v2/aws"
"github.com/aws/aws-sdk-go-v2/feature/dynamodb/attributevalue"
"github.com/aws/aws-sdk-go-v2/feature/dynamodb/expression"
"github.com/aws/aws-sdk-go-v2/service/dynamodb"
"github.com/aws/aws-sdk-go-v2/service/dynamodb/types"
)
// TableBasics encapsulates the Amazon DynamoDB service actions used in the examples.
// It contains a DynamoDB service client that is used to act on the specified table.
type TableBasics struct {
DynamoDbClient *dynamodb.Client
TableName string
}
// Query gets all movies in the DynamoDB table that were released in the specified year.
// The function uses the `expression` package to build the key condition expression
// that is used in the query.
func (basics TableBasics) Query(ctx context.Context, releaseYear int) ([]Movie, error) {
var err error
var response *dynamodb.QueryOutput
var movies []Movie
keyEx := expression.Key("year").Equal(expression.Value(releaseYear))
expr, err := expression.NewBuilder().WithKeyCondition(keyEx).Build()
if err != nil {
log.Printf("Couldn't build expression for query. Here's why: %v\n", err)
} else {
queryPaginator := dynamodb.NewQueryPaginator(basics.DynamoDbClient, &dynamodb.QueryInput{
TableName: aws.String(basics.TableName),
ExpressionAttributeNames: expr.Names(),
ExpressionAttributeValues: expr.Values(),
KeyConditionExpression: expr.KeyCondition(),
})
for queryPaginator.HasMorePages() {
response, err = queryPaginator.NextPage(ctx)
if err != nil {
log.Printf("Couldn't query for movies released in %v. Here's why: %v\n", releaseYear, err)
break
} else {
var moviePage []Movie
err = attributevalue.UnmarshalListOfMaps(response.Items, &moviePage)
if err != nil {
log.Printf("Couldn't unmarshal query response. Here's why: %v\n", err)
break
} else {
movies = append(movies, moviePage...)
}
}
}
}
return movies, err
}
```
Define a Movie struct that is used in this example.
```
import (
"archive/zip"
"bytes"
"encoding/json"
"fmt"
"io"
"log"
"net/http"
"github.com/aws/aws-sdk-go-v2/feature/dynamodb/attributevalue"
"github.com/aws/aws-sdk-go-v2/service/dynamodb/types"
)
// Movie encapsulates data about a movie. Title and Year are the composite primary key
// of the movie in Amazon DynamoDB. Title is the sort key, Year is the partition key,
// and Info is additional data.
type Movie struct {
Title string `dynamodbav:"title"`
Year int `dynamodbav:"year"`
Info map[string]interface{} `dynamodbav:"info"`
}
// GetKey returns the composite primary key of the movie in a format that can be
// sent to DynamoDB.
func (movie Movie) GetKey() map[string]types.AttributeValue {
title, err := attributevalue.Marshal(movie.Title)
if err != nil {
panic(err)
}
year, err := attributevalue.Marshal(movie.Year)
if err != nil {
panic(err)
}
return map[string]types.AttributeValue{"title": title, "year": year}
}
// String returns the title, year, rating, and plot of a movie, formatted for the example.
func (movie Movie) String() string {
return fmt.Sprintf("%v\n\tReleased: %v\n\tRating: %v\n\tPlot: %v\n",
movie.Title, movie.Year, movie.Info["rating"], movie.Info["plot"])
}
```
+ For API details, see [Query](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/service/dynamodb#Client.Query) in *Amazon SDK for Go API Reference*.
------
#### [ Java ]
**SDK for Java 2.x**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2/example_code/dynamodb#code-examples).
Queries a table by using [DynamoDbClient](http://docs.aws.amazon.com/sdk-for-java/latest/reference/software/amazon/awssdk/services/dynamodb/DynamoDbClient.html).
```
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
import software.amazon.awssdk.services.dynamodb.model.AttributeValue;
import software.amazon.awssdk.services.dynamodb.model.DynamoDbException;
import software.amazon.awssdk.services.dynamodb.model.QueryRequest;
import software.amazon.awssdk.services.dynamodb.model.QueryResponse;
import java.util.HashMap;
/**
* Before running this Java V2 code example, set up your development
* environment, including your credentials.
*
* For more information, see the following documentation topic:
*
* https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/get-started.html
*
* To query items from an Amazon DynamoDB table using the AWS SDK for Java V2,
* its better practice to use the
* Enhanced Client. See the EnhancedQueryRecords example.
*/
public class Query {
public static void main(String[] args) {
final String usage = """
Usage:
Where:
tableName - The Amazon DynamoDB table to put the item in (for example, Music3).
partitionKeyName - The partition key name of the Amazon DynamoDB table (for example, Artist).
partitionKeyVal - The value of the partition key that should match (for example, Famous Band).
""";
if (args.length != 3) {
System.out.println(usage);
System.exit(1);
}
String tableName = args[0];
String partitionKeyName = args[1];
String partitionKeyVal = args[2];
// For more information about an alias, see:
// https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.ExpressionAttributeNames.html
String partitionAlias = "#a";
System.out.format("Querying %s", tableName);
System.out.println("");
Region region = Region.US_EAST_1;
DynamoDbClient ddb = DynamoDbClient.builder()
.region(region)
.build();
int count = queryTable(ddb, tableName, partitionKeyName, partitionKeyVal, partitionAlias);
System.out.println("There were " + count + " record(s) returned");
ddb.close();
}
public static int queryTable(DynamoDbClient ddb, String tableName, String partitionKeyName, String partitionKeyVal,
String partitionAlias) {
// Set up an alias for the partition key name in case it's a reserved word.
HashMap attrNameAlias = new HashMap();
attrNameAlias.put(partitionAlias, partitionKeyName);
// Set up mapping of the partition name with the value.
HashMap attrValues = new HashMap<>();
attrValues.put(":" + partitionKeyName, AttributeValue.builder()
.s(partitionKeyVal)
.build());
QueryRequest queryReq = QueryRequest.builder()
.tableName(tableName)
.keyConditionExpression(partitionAlias + " = :" + partitionKeyName)
.expressionAttributeNames(attrNameAlias)
.expressionAttributeValues(attrValues)
.build();
try {
QueryResponse response = ddb.query(queryReq);
return response.count();
} catch (DynamoDbException e) {
System.err.println(e.getMessage());
System.exit(1);
}
return -1;
}
}
```
Queries a table by using `DynamoDbClient` and a secondary index.
```
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
import software.amazon.awssdk.services.dynamodb.model.AttributeValue;
import software.amazon.awssdk.services.dynamodb.model.DynamoDbException;
import software.amazon.awssdk.services.dynamodb.model.QueryRequest;
import software.amazon.awssdk.services.dynamodb.model.QueryResponse;
import java.util.HashMap;
import java.util.Map;
/**
* Before running this Java V2 code example, set up your development
* environment, including your credentials.
*
* For more information, see the following documentation topic:
*
* https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/get-started.html
*
* Create the Movies table by running the Scenario example and loading the Movie
* data from the JSON file. Next create a secondary
* index for the Movies table that uses only the year column. Name the index
* **year-index**. For more information, see:
*
* https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GSI.html
*/
public class QueryItemsUsingIndex {
public static void main(String[] args) {
String tableName = "Movies";
Region region = Region.US_EAST_1;
DynamoDbClient ddb = DynamoDbClient.builder()
.region(region)
.build();
queryIndex(ddb, tableName);
ddb.close();
}
public static void queryIndex(DynamoDbClient ddb, String tableName) {
try {
Map expressionAttributesNames = new HashMap<>();
expressionAttributesNames.put("#year", "year");
Map expressionAttributeValues = new HashMap<>();
expressionAttributeValues.put(":yearValue", AttributeValue.builder().n("2013").build());
QueryRequest request = QueryRequest.builder()
.tableName(tableName)
.indexName("year-index")
.keyConditionExpression("#year = :yearValue")
.expressionAttributeNames(expressionAttributesNames)
.expressionAttributeValues(expressionAttributeValues)
.build();
System.out.println("=== Movie Titles ===");
QueryResponse response = ddb.query(request);
response.items()
.forEach(movie -> System.out.println(movie.get("title").s()));
} catch (DynamoDbException e) {
System.err.println(e.getMessage());
System.exit(1);
}
}
}
```
+ For API details, see [Query](https://docs.amazonaws.cn/goto/SdkForJavaV2/dynamodb-2012-08-10/Query) in *Amazon SDK for Java 2.x API Reference*.
------
#### [ JavaScript ]
**SDK for JavaScript (v3)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javascriptv3/example_code/dynamodb#code-examples).
This example uses the document client to simplify working with items in DynamoDB. For API details see [QueryCommand](https://docs.amazonaws.cn/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-lib-dynamodb/Class/QueryCommand/).
```
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { QueryCommand, DynamoDBDocumentClient } from "@aws-sdk/lib-dynamodb";
const client = new DynamoDBClient({});
const docClient = DynamoDBDocumentClient.from(client);
export const main = async () => {
const command = new QueryCommand({
TableName: "CoffeeCrop",
KeyConditionExpression:
"OriginCountry = :originCountry AND RoastDate > :roastDate",
ExpressionAttributeValues: {
":originCountry": "Ethiopia",
":roastDate": "2023-05-01",
},
ConsistentRead: true,
});
const response = await docClient.send(command);
console.log(response);
return response;
};
```
+ For more information, see [Amazon SDK for JavaScript Developer Guide](https://docs.amazonaws.cn/sdk-for-javascript/v3/developer-guide/dynamodb-example-query-scan.html#dynamodb-example-table-query-scan-querying).
+ For API details, see [Query](https://docs.amazonaws.cn/AWSJavaScriptSDK/v3/latest/client/dynamodb/command/QueryCommand) in *Amazon SDK for JavaScript API Reference*.
**SDK for JavaScript (v2)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javascript/example_code/dynamodb#code-examples).
```
// Load the AWS SDK for Node.js
var AWS = require("aws-sdk");
// Set the region
AWS.config.update({ region: "REGION" });
// Create DynamoDB document client
var docClient = new AWS.DynamoDB.DocumentClient({ apiVersion: "2012-08-10" });
var params = {
ExpressionAttributeValues: {
":s": 2,
":e": 9,
":topic": "PHRASE",
},
KeyConditionExpression: "Season = :s and Episode > :e",
FilterExpression: "contains (Subtitle, :topic)",
TableName: "EPISODES_TABLE",
};
docClient.query(params, function (err, data) {
if (err) {
console.log("Error", err);
} else {
console.log("Success", data.Items);
}
});
```
+ For more information, see [Amazon SDK for JavaScript Developer Guide](https://docs.amazonaws.cn/sdk-for-javascript/v2/developer-guide/dynamodb-example-query-scan.html#dynamodb-example-table-query-scan-querying).
+ For API details, see [Query](https://docs.amazonaws.cn/goto/AWSJavaScriptSDK/dynamodb-2012-08-10/Query) in *Amazon SDK for JavaScript API Reference*.
------
#### [ Kotlin ]
**SDK for Kotlin**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/kotlin/services/dynamodb#code-examples).
```
suspend fun queryDynTable(
tableNameVal: String,
partitionKeyName: String,
partitionKeyVal: String,
partitionAlias: String,
): Int {
val attrNameAlias = mutableMapOf()
attrNameAlias[partitionAlias] = partitionKeyName
// Set up mapping of the partition name with the value.
val attrValues = mutableMapOf()
attrValues[":$partitionKeyName"] = AttributeValue.S(partitionKeyVal)
val request =
QueryRequest {
tableName = tableNameVal
keyConditionExpression = "$partitionAlias = :$partitionKeyName"
expressionAttributeNames = attrNameAlias
this.expressionAttributeValues = attrValues
}
DynamoDbClient.fromEnvironment { region = "us-east-1" }.use { ddb ->
val response = ddb.query(request)
return response.count
}
}
```
+ For API details, see [Query](https://sdk.amazonaws.com/kotlin/api/latest/index.html) in *Amazon SDK for Kotlin API reference*.
------
#### [ PHP ]
**SDK for PHP**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code/dynamodb#code-examples).
```
$birthKey = [
'Key' => [
'year' => [
'N' => "$birthYear",
],
],
];
$result = $service->query($tableName, $birthKey);
public function query(string $tableName, $key)
{
$expressionAttributeValues = [];
$expressionAttributeNames = [];
$keyConditionExpression = "";
$index = 1;
foreach ($key as $name => $value) {
$keyConditionExpression .= "#" . array_key_first($value) . " = :v$index,";
$expressionAttributeNames["#" . array_key_first($value)] = array_key_first($value);
$hold = array_pop($value);
$expressionAttributeValues[":v$index"] = [
array_key_first($hold) => array_pop($hold),
];
}
$keyConditionExpression = substr($keyConditionExpression, 0, -1);
$query = [
'ExpressionAttributeValues' => $expressionAttributeValues,
'ExpressionAttributeNames' => $expressionAttributeNames,
'KeyConditionExpression' => $keyConditionExpression,
'TableName' => $tableName,
];
return $this->dynamoDbClient->query($query);
}
```
+ For API details, see [Query](https://docs.amazonaws.cn/goto/SdkForPHPV3/dynamodb-2012-08-10/Query) in *Amazon SDK for PHP API Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: Invokes a query that returns DynamoDB items with the specified SongTitle and Artist.**
```
$invokeDDBQuery = @{
TableName = 'Music'
KeyConditionExpression = ' SongTitle = :SongTitle and Artist = :Artist'
ExpressionAttributeValues = @{
':SongTitle' = 'Somewhere Down The Road'
':Artist' = 'No One You Know'
} | ConvertTo-DDBItem
}
Invoke-DDBQuery @invokeDDBQuery | ConvertFrom-DDBItem
```
**Output:**
```
Name Value
---- -----
Genre Country
Artist No One You Know
Price 1.94
CriticRating 9
SongTitle Somewhere Down The Road
AlbumTitle Somewhat Famous
```
+ For API details, see [Query](https://docs.aws.amazon.com/powershell/v4/reference) in *Amazon Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: Invokes a query that returns DynamoDB items with the specified SongTitle and Artist.**
```
$invokeDDBQuery = @{
TableName = 'Music'
KeyConditionExpression = ' SongTitle = :SongTitle and Artist = :Artist'
ExpressionAttributeValues = @{
':SongTitle' = 'Somewhere Down The Road'
':Artist' = 'No One You Know'
} | ConvertTo-DDBItem
}
Invoke-DDBQuery @invokeDDBQuery | ConvertFrom-DDBItem
```
**Output:**
```
Name Value
---- -----
Genre Country
Artist No One You Know
Price 1.94
CriticRating 9
SongTitle Somewhere Down The Road
AlbumTitle Somewhat Famous
```
+ For API details, see [Query](https://docs.aws.amazon.com/powershell/v5/reference) in *Amazon Tools for PowerShell Cmdlet Reference (V5)*.
------
#### [ Python ]
**SDK for Python (Boto3)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/dynamodb#code-examples).
Query items by using a key condition expression.
```
class Movies:
"""Encapsulates an Amazon DynamoDB table of movie data.
Example data structure for a movie record in this table:
{
"year": 1999,
"title": "For Love of the Game",
"info": {
"directors": ["Sam Raimi"],
"release_date": "1999-09-15T00:00:00Z",
"rating": 6.3,
"plot": "A washed up pitcher flashes through his career.",
"rank": 4987,
"running_time_secs": 8220,
"actors": [
"Kevin Costner",
"Kelly Preston",
"John C. Reilly"
]
}
}
"""
def __init__(self, dyn_resource):
"""
:param dyn_resource: A Boto3 DynamoDB resource.
"""
self.dyn_resource = dyn_resource
# The table variable is set during the scenario in the call to
# 'exists' if the table exists. Otherwise, it is set by 'create_table'.
self.table = None
def query_movies(self, year):
"""
Queries for movies that were released in the specified year.
:param year: The year to query.
:return: The list of movies that were released in the specified year.
"""
try:
response = self.table.query(KeyConditionExpression=Key("year").eq(year))
except ClientError as err:
logger.error(
"Couldn't query for movies released in %s. Here's why: %s: %s",
year,
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
else:
return response["Items"]
```
Query items and project them to return a subset of data.
```
class UpdateQueryWrapper:
def __init__(self, table):
self.table = table
def query_and_project_movies(self, year, title_bounds):
"""
Query for movies that were released in a specified year and that have titles
that start within a range of letters. A projection expression is used
to return a subset of data for each movie.
:param year: The release year to query.
:param title_bounds: The range of starting letters to query.
:return: The list of movies.
"""
try:
response = self.table.query(
ProjectionExpression="#yr, title, info.genres, info.actors[0]",
ExpressionAttributeNames={"#yr": "year"},
KeyConditionExpression=(
Key("year").eq(year)
& Key("title").between(
title_bounds["first"], title_bounds["second"]
)
),
)
except ClientError as err:
if err.response["Error"]["Code"] == "ValidationException":
logger.warning(
"There's a validation error. Here's the message: %s: %s",
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
else:
logger.error(
"Couldn't query for movies. Here's why: %s: %s",
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
else:
return response["Items"]
```
+ For API details, see [Query](https://docs.amazonaws.cn/goto/boto3/dynamodb-2012-08-10/Query) in *Amazon SDK for Python (Boto3) API Reference*.
------
#### [ Ruby ]
**SDK for Ruby**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/ruby/example_code/dynamodb#code-examples).
```
class DynamoDBBasics
attr_reader :dynamo_resource, :table
def initialize(table_name)
client = Aws::DynamoDB::Client.new(region: 'us-east-1')
@dynamo_resource = Aws::DynamoDB::Resource.new(client: client)
@table = @dynamo_resource.table(table_name)
end
# Queries for movies that were released in the specified year.
#
# @param year [Integer] The year to query.
# @return [Array] The list of movies that were released in the specified year.
def query_items(year)
response = @table.query(
key_condition_expression: '#yr = :year',
expression_attribute_names: { '#yr' => 'year' },
expression_attribute_values: { ':year' => year }
)
rescue Aws::DynamoDB::Errors::ServiceError => e
puts("Couldn't query for movies released in #{year}. Here's why:")
puts("\t#{e.code}: #{e.message}")
raise
else
response.items
end
```
+ For API details, see [Query](https://docs.amazonaws.cn/goto/SdkForRubyV3/dynamodb-2012-08-10/Query) in *Amazon SDK for Ruby API Reference*.
------
#### [ Rust ]
**SDK for Rust**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/rustv1/examples/dynamodb#code-examples).
Find the movies made in the specified year.
```
pub async fn movies_in_year(
client: &Client,
table_name: &str,
year: u16,
) -> Result, MovieError> {
let results = client
.query()
.table_name(table_name)
.key_condition_expression("#yr = :yyyy")
.expression_attribute_names("#yr", "year")
.expression_attribute_values(":yyyy", AttributeValue::N(year.to_string()))
.send()
.await?;
if let Some(items) = results.items {
let movies = items.iter().map(|v| v.into()).collect();
Ok(movies)
} else {
Ok(vec![])
}
}
```
+ For API details, see [Query](https://docs.rs/aws-sdk-dynamodb/latest/aws_sdk_dynamodb/client/struct.Client.html#method.query) in *Amazon SDK for Rust API reference*.
------
#### [ SAP ABAP ]
**SDK for SAP ABAP**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/sap-abap/services/dyn#code-examples).
```
TRY.
" Query movies for a given year .
DATA(lt_attributelist) = VALUE /aws1/cl_dynattributevalue=>tt_attributevaluelist(
( NEW /aws1/cl_dynattributevalue( iv_n = |{ iv_year }| ) ) ).
DATA(lt_key_conditions) = VALUE /aws1/cl_dyncondition=>tt_keyconditions(
( VALUE /aws1/cl_dyncondition=>ts_keyconditions_maprow(
key = 'year'
value = NEW /aws1/cl_dyncondition(
it_attributevaluelist = lt_attributelist
iv_comparisonoperator = |EQ|
) ) ) ).
oo_result = lo_dyn->query(
iv_tablename = iv_table_name
it_keyconditions = lt_key_conditions ).
DATA(lt_items) = oo_result->get_items( ).
"You can loop over the results to get item attributes.
LOOP AT lt_items INTO DATA(lt_item).
DATA(lo_title) = lt_item[ key = 'title' ]-value.
DATA(lo_year) = lt_item[ key = 'year' ]-value.
ENDLOOP.
DATA(lv_count) = oo_result->get_count( ).
MESSAGE 'Item count is: ' && lv_count TYPE 'I'.
CATCH /aws1/cx_dynresourcenotfoundex.
MESSAGE 'The table or index does not exist' TYPE 'E'.
ENDTRY.
```
+ For API details, see [Query](https://docs.amazonaws.cn/sdk-for-sap-abap/v1/api/latest/index.html) in *Amazon SDK for SAP ABAP API reference*.
------
#### [ Swift ]
**SDK for Swift**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/swift/example_code/dynamodb#code-examples).
```
import AWSDynamoDB
/// Get all the movies released in the specified year.
///
/// - Parameter year: The release year of the movies to return.
///
/// - Returns: An array of `Movie` objects describing each matching movie.
///
func getMovies(fromYear year: Int) async throws -> [Movie] {
do {
guard let client = self.ddbClient else {
throw MoviesError.UninitializedClient
}
let input = QueryInput(
expressionAttributeNames: [
"#y": "year"
],
expressionAttributeValues: [
":y": .n(String(year))
],
keyConditionExpression: "#y = :y",
tableName: self.tableName
)
// Use "Paginated" to get all the movies.
// This lets the SDK handle the 'lastEvaluatedKey' property in "QueryOutput".
let pages = client.queryPaginated(input: input)
var movieList: [Movie] = []
for try await page in pages {
guard let items = page.items else {
print("Error: no items returned.")
continue
}
// Convert the found movies into `Movie` objects and return an array
// of them.
for item in items {
let movie = try Movie(withItem: item)
movieList.append(movie)
}
}
return movieList
} catch {
print("ERROR: getMovies:", dump(error))
throw error
}
}
```
+ For API details, see [Query](https://sdk.amazonaws.com/swift/api/awsdynamodb/latest/documentation/awsdynamodb/dynamodbclient/query(input:)) in *Amazon SDK for Swift API reference*.
------
For more DynamoDB examples, see [Code examples for DynamoDB using Amazon SDKs](service_code_examples.md).
To create a global secondary index for your table, proceed to [Step 6: (Optional) Delete your DynamoDB table to clean up resources](getting-started-step-6.md).
# Step 6: (Optional) Delete your DynamoDB table to clean up resources
If you no longer need the Amazon DynamoDB table that you created for the tutorial, you can delete it. This step helps ensure that you aren't charged for resources that you aren't using. You can use the DynamoDB console or the Amazon CLI to delete the `Music` table that you created in [Step 1: Create a table in DynamoDB](getting-started-step-1.md).
For more information about table operations in DynamoDB, see [Working with tables and data in DynamoDB](WorkingWithTables.md).
## Amazon Web Services Management Console
To delete the `Music` table using the console:
1. Open the DynamoDB console at [https://console.amazonaws.cn/dynamodb/](https://console.amazonaws.cn/dynamodb/).
1. In the left navigation pane, choose **Tables**.
1. Choose the checkbox beside the **Music** table in the table list.
1. Choose **Delete**.
## Amazon CLI
The following Amazon CLI example deletes the `Music` table using `delete-table`.
```
aws dynamodb delete-table --table-name Music
```
## Amazon SDK
The following code examples show how to delete a DynamoDB table using an Amazon SDK.
------
#### [ .NET ]
**Amazon SDK for .NET (v4)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/dotnetv4/DynamoDB#code-examples).
```
///
/// Deletes a DynamoDB table.
///
/// The name of the table to delete.
/// A Boolean value indicating the success of the operation.
public async Task DeleteTableAsync(string tableName)
{
try
{
var request = new DeleteTableRequest
{
TableName = tableName,
};
var response = await _amazonDynamoDB.DeleteTableAsync(request);
Console.WriteLine($"Table {response.TableDescription.TableName} successfully deleted.");
return true;
}
catch (ResourceNotFoundException ex)
{
Console.WriteLine($"Table {tableName} was not found and cannot be deleted. {ex.Message}");
return false;
}
catch (AmazonDynamoDBException ex)
{
Console.WriteLine($"An Amazon DynamoDB error occurred while deleting table {tableName}. {ex.Message}");
return false;
}
catch (Exception ex)
{
Console.WriteLine($"An error occurred while deleting table {tableName}. {ex.Message}");
return false;
}
}
```
+ For API details, see [DeleteTable](https://docs.amazonaws.cn/goto/DotNetSDKV4/dynamodb-2012-08-10/DeleteTable) in *Amazon SDK for .NET API Reference*.
------
#### [ Bash ]
**Amazon CLI with Bash script**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/aws-cli/bash-linux/dynamodb#code-examples).
```
###############################################################################
# function dynamodb_delete_table
#
# This function deletes a DynamoDB table.
#
# Parameters:
# -n table_name -- The name of the table to delete.
#
# Returns:
# 0 - If successful.
# 1 - If it fails.
###############################################################################
function dynamodb_delete_table() {
local table_name response
local option OPTARG # Required to use getopts command in a function.
# bashsupport disable=BP5008
function usage() {
echo "function dynamodb_delete_table"
echo "Deletes an Amazon DynamoDB table."
echo " -n table_name -- The name of the table to delete."
echo ""
}
# Retrieve the calling parameters.
while getopts "n:h" option; do
case "${option}" in
n) table_name="${OPTARG}" ;;
h)
usage
return 0
;;
\?)
echo "Invalid parameter"
usage
return 1
;;
esac
done
export OPTIND=1
if [[ -z "$table_name" ]]; then
errecho "ERROR: You must provide a table name with the -n parameter."
usage
return 1
fi
iecho "Parameters:\n"
iecho " table_name: $table_name"
iecho ""
response=$(aws dynamodb delete-table \
--table-name "$table_name")
local error_code=${?}
if [[ $error_code -ne 0 ]]; then
aws_cli_error_log $error_code
errecho "ERROR: AWS reports delete-table operation failed.$response"
return 1
fi
return 0
}
```
The utility functions used in this example.
```
###############################################################################
# function iecho
#
# This function enables the script to display the specified text only if
# the global variable $VERBOSE is set to true.
###############################################################################
function iecho() {
if [[ $VERBOSE == true ]]; then
echo "$@"
fi
}
###############################################################################
# function errecho
#
# This function outputs everything sent to it to STDERR (standard error output).
###############################################################################
function errecho() {
printf "%s\n" "$*" 1>&2
}
##############################################################################
# function aws_cli_error_log()
#
# This function is used to log the error messages from the AWS CLI.
#
# See https://docs.aws.amazon.com/cli/latest/topic/return-codes.html#cli-aws-help-return-codes.
#
# The function expects the following argument:
# $1 - The error code returned by the AWS CLI.
#
# Returns:
# 0: - Success.
#
##############################################################################
function aws_cli_error_log() {
local err_code=$1
errecho "Error code : $err_code"
if [ "$err_code" == 1 ]; then
errecho " One or more S3 transfers failed."
elif [ "$err_code" == 2 ]; then
errecho " Command line failed to parse."
elif [ "$err_code" == 130 ]; then
errecho " Process received SIGINT."
elif [ "$err_code" == 252 ]; then
errecho " Command syntax invalid."
elif [ "$err_code" == 253 ]; then
errecho " The system environment or configuration was invalid."
elif [ "$err_code" == 254 ]; then
errecho " The service returned an error."
elif [ "$err_code" == 255 ]; then
errecho " 255 is a catch-all error."
fi
return 0
}
```
+ For API details, see [DeleteTable](https://docs.amazonaws.cn/goto/aws-cli/dynamodb-2012-08-10/DeleteTable) in *Amazon CLI Command Reference*.
------
#### [ C\$1\$1 ]
**SDK for C\$1\$1**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/cpp/example_code/dynamodb#code-examples).
```
//! Delete an Amazon DynamoDB table.
/*!
\sa deleteTable()
\param tableName: The DynamoDB table name.
\param clientConfiguration: AWS client configuration.
\return bool: Function succeeded.
*/
bool AwsDoc::DynamoDB::deleteTable(const Aws::String &tableName,
const Aws::Client::ClientConfiguration &clientConfiguration) {
Aws::DynamoDB::DynamoDBClient dynamoClient(clientConfiguration);
Aws::DynamoDB::Model::DeleteTableRequest request;
request.SetTableName(tableName);
const Aws::DynamoDB::Model::DeleteTableOutcome &result = dynamoClient.DeleteTable(
request);
if (result.IsSuccess()) {
std::cout << "Your table \""
<< result.GetResult().GetTableDescription().GetTableName()
<< " was deleted.\n";
}
else {
std::cerr << "Failed to delete table: " << result.GetError().GetMessage()
<< std::endl;
}
return result.IsSuccess();
}
```
+ For API details, see [DeleteTable](https://docs.amazonaws.cn/goto/SdkForCpp/dynamodb-2012-08-10/DeleteTable) in *Amazon SDK for C\$1\$1 API Reference*.
------
#### [ CLI ]
**Amazon CLI**
**To delete a table**
The following `delete-table` example deletes the `MusicCollection` table.
```
aws dynamodb delete-table \
--table-name MusicCollection
```
Output:
```
{
"TableDescription": {
"TableStatus": "DELETING",
"TableSizeBytes": 0,
"ItemCount": 0,
"TableName": "MusicCollection",
"ProvisionedThroughput": {
"NumberOfDecreasesToday": 0,
"WriteCapacityUnits": 5,
"ReadCapacityUnits": 5
}
}
}
```
For more information, see [Deleting a Table](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/WorkingWithTables.Basics.html#WorkingWithTables.Basics.DeleteTable) in the *Amazon DynamoDB Developer Guide*.
+ For API details, see [DeleteTable](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/dynamodb/delete-table.html) in *Amazon CLI Command Reference*.
------
#### [ Go ]
**SDK for Go V2**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/gov2/dynamodb#code-examples).
```
import (
"context"
"errors"
"log"
"time"
"github.com/aws/aws-sdk-go-v2/aws"
"github.com/aws/aws-sdk-go-v2/feature/dynamodb/attributevalue"
"github.com/aws/aws-sdk-go-v2/feature/dynamodb/expression"
"github.com/aws/aws-sdk-go-v2/service/dynamodb"
"github.com/aws/aws-sdk-go-v2/service/dynamodb/types"
)
// TableBasics encapsulates the Amazon DynamoDB service actions used in the examples.
// It contains a DynamoDB service client that is used to act on the specified table.
type TableBasics struct {
DynamoDbClient *dynamodb.Client
TableName string
}
// DeleteTable deletes the DynamoDB table and all of its data.
func (basics TableBasics) DeleteTable(ctx context.Context) error {
_, err := basics.DynamoDbClient.DeleteTable(ctx, &dynamodb.DeleteTableInput{
TableName: aws.String(basics.TableName)})
if err != nil {
log.Printf("Couldn't delete table %v. Here's why: %v\n", basics.TableName, err)
}
return err
}
```
+ For API details, see [DeleteTable](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/service/dynamodb#Client.DeleteTable) in *Amazon SDK for Go API Reference*.
------
#### [ Java ]
**SDK for Java 2.x**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2/example_code/dynamodb#code-examples).
```
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.dynamodb.model.DynamoDbException;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
import software.amazon.awssdk.services.dynamodb.model.DeleteTableRequest;
/**
* Before running this Java V2 code example, set up your development
* environment, including your credentials.
*
* For more information, see the following documentation topic:
*
* https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/get-started.html
*/
public class DeleteTable {
public static void main(String[] args) {
final String usage = """
Usage:
Where:
tableName - The Amazon DynamoDB table to delete (for example, Music3).
**Warning** This program will delete the table that you specify!
""";
if (args.length != 1) {
System.out.println(usage);
System.exit(1);
}
String tableName = args[0];
System.out.format("Deleting the Amazon DynamoDB table %s...\n", tableName);
Region region = Region.US_EAST_1;
DynamoDbClient ddb = DynamoDbClient.builder()
.region(region)
.build();
deleteDynamoDBTable(ddb, tableName);
ddb.close();
}
public static void deleteDynamoDBTable(DynamoDbClient ddb, String tableName) {
DeleteTableRequest request = DeleteTableRequest.builder()
.tableName(tableName)
.build();
try {
ddb.deleteTable(request);
} catch (DynamoDbException e) {
System.err.println(e.getMessage());
System.exit(1);
}
System.out.println(tableName + " was successfully deleted!");
}
}
```
+ For API details, see [DeleteTable](https://docs.amazonaws.cn/goto/SdkForJavaV2/dynamodb-2012-08-10/DeleteTable) in *Amazon SDK for Java 2.x API Reference*.
------
#### [ JavaScript ]
**SDK for JavaScript (v3)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javascriptv3/example_code/dynamodb#code-examples).
```
import { DeleteTableCommand, DynamoDBClient } from "@aws-sdk/client-dynamodb";
const client = new DynamoDBClient({});
export const main = async () => {
const command = new DeleteTableCommand({
TableName: "DecafCoffees",
});
const response = await client.send(command);
console.log(response);
return response;
};
```
+ For API details, see [DeleteTable](https://docs.amazonaws.cn/AWSJavaScriptSDK/v3/latest/client/dynamodb/command/DeleteTableCommand) in *Amazon SDK for JavaScript API Reference*.
**SDK for JavaScript (v2)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javascript/example_code/dynamodb#code-examples).
```
// Load the AWS SDK for Node.js
var AWS = require("aws-sdk");
// Set the region
AWS.config.update({ region: "REGION" });
// Create the DynamoDB service object
var ddb = new AWS.DynamoDB({ apiVersion: "2012-08-10" });
var params = {
TableName: process.argv[2],
};
// Call DynamoDB to delete the specified table
ddb.deleteTable(params, function (err, data) {
if (err && err.code === "ResourceNotFoundException") {
console.log("Error: Table not found");
} else if (err && err.code === "ResourceInUseException") {
console.log("Error: Table in use");
} else {
console.log("Success", data);
}
});
```
+ For more information, see [Amazon SDK for JavaScript Developer Guide](https://docs.amazonaws.cn/sdk-for-javascript/v2/developer-guide/dynamodb-examples-using-tables.html#dynamodb-examples-using-tables-deleting-a-table).
+ For API details, see [DeleteTable](https://docs.amazonaws.cn/goto/AWSJavaScriptSDK/dynamodb-2012-08-10/DeleteTable) in *Amazon SDK for JavaScript API Reference*.
------
#### [ Kotlin ]
**SDK for Kotlin**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/kotlin/services/dynamodb#code-examples).
```
suspend fun deleteDynamoDBTable(tableNameVal: String) {
val request =
DeleteTableRequest {
tableName = tableNameVal
}
DynamoDbClient.fromEnvironment { region = "us-east-1" }.use { ddb ->
ddb.deleteTable(request)
println("$tableNameVal was deleted")
}
}
```
+ For API details, see [DeleteTable](https://sdk.amazonaws.com/kotlin/api/latest/index.html) in *Amazon SDK for Kotlin API reference*.
------
#### [ PHP ]
**SDK for PHP**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php/example_code/dynamodb#code-examples).
```
public function deleteTable(string $TableName)
{
$this->customWaiter(function () use ($TableName) {
return $this->dynamoDbClient->deleteTable([
'TableName' => $TableName,
]);
});
}
```
+ For API details, see [DeleteTable](https://docs.amazonaws.cn/goto/SdkForPHPV3/dynamodb-2012-08-10/DeleteTable) in *Amazon SDK for PHP API Reference*.
------
#### [ PowerShell ]
**Tools for PowerShell V4**
**Example 1: Deletes the specified table. You are prompted for confirmation before the operation proceeds.**
```
Remove-DDBTable -TableName "myTable"
```
**Example 2: Deletes the specified table. You are not prompted for confirmation before the operation proceeds.**
```
Remove-DDBTable -TableName "myTable" -Force
```
+ For API details, see [DeleteTable](https://docs.aws.amazon.com/powershell/v4/reference) in *Amazon Tools for PowerShell Cmdlet Reference (V4)*.
**Tools for PowerShell V5**
**Example 1: Deletes the specified table. You are prompted for confirmation before the operation proceeds.**
```
Remove-DDBTable -TableName "myTable"
```
**Example 2: Deletes the specified table. You are not prompted for confirmation before the operation proceeds.**
```
Remove-DDBTable -TableName "myTable" -Force
```
+ For API details, see [DeleteTable](https://docs.aws.amazon.com/powershell/v5/reference) in *Amazon Tools for PowerShell Cmdlet Reference (V5)*.
------
#### [ Python ]
**SDK for Python (Boto3)**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/dynamodb#code-examples).
```
class Movies:
"""Encapsulates an Amazon DynamoDB table of movie data.
Example data structure for a movie record in this table:
{
"year": 1999,
"title": "For Love of the Game",
"info": {
"directors": ["Sam Raimi"],
"release_date": "1999-09-15T00:00:00Z",
"rating": 6.3,
"plot": "A washed up pitcher flashes through his career.",
"rank": 4987,
"running_time_secs": 8220,
"actors": [
"Kevin Costner",
"Kelly Preston",
"John C. Reilly"
]
}
}
"""
def __init__(self, dyn_resource):
"""
:param dyn_resource: A Boto3 DynamoDB resource.
"""
self.dyn_resource = dyn_resource
# The table variable is set during the scenario in the call to
# 'exists' if the table exists. Otherwise, it is set by 'create_table'.
self.table = None
def delete_table(self):
"""
Deletes the table.
"""
try:
self.table.delete()
self.table = None
except ClientError as err:
logger.error(
"Couldn't delete table. Here's why: %s: %s",
err.response["Error"]["Code"],
err.response["Error"]["Message"],
)
raise
```
+ For API details, see [DeleteTable](https://docs.amazonaws.cn/goto/boto3/dynamodb-2012-08-10/DeleteTable) in *Amazon SDK for Python (Boto3) API Reference*.
------
#### [ Ruby ]
**SDK for Ruby**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/ruby/example_code/dynamodb#code-examples).
```
# Encapsulates an Amazon DynamoDB table of movie data.
class Scaffold
attr_reader :dynamo_resource, :table_name, :table
def initialize(table_name)
client = Aws::DynamoDB::Client.new(region: 'us-east-1')
@dynamo_resource = Aws::DynamoDB::Resource.new(client: client)
@table_name = table_name
@table = nil
@logger = Logger.new($stdout)
@logger.level = Logger::DEBUG
end
# Deletes the table.
def delete_table
@table.delete
@table = nil
rescue Aws::DynamoDB::Errors::ServiceError => e
puts("Couldn't delete table. Here's why:")
puts("\t#{e.code}: #{e.message}")
raise
end
```
+ For API details, see [DeleteTable](https://docs.amazonaws.cn/goto/SdkForRubyV3/dynamodb-2012-08-10/DeleteTable) in *Amazon SDK for Ruby API Reference*.
------
#### [ Rust ]
**SDK for Rust**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/rustv1/examples/dynamodb#code-examples).
```
pub async fn delete_table(client: &Client, table: &str) -> Result {
let resp = client.delete_table().table_name(table).send().await;
match resp {
Ok(out) => {
println!("Deleted table");
Ok(out)
}
Err(e) => Err(Error::Unhandled(e.into())),
}
}
```
+ For API details, see [DeleteTable](https://docs.rs/aws-sdk-dynamodb/latest/aws_sdk_dynamodb/client/struct.Client.html#method.delete_table) in *Amazon SDK for Rust API reference*.
------
#### [ SAP ABAP ]
**SDK for SAP ABAP**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/sap-abap/services/dyn#code-examples).
```
TRY.
lo_dyn->deletetable( iv_tablename = iv_table_name ).
" Wait till the table is actually deleted.
lo_dyn->get_waiter( )->tablenotexists(
iv_max_wait_time = 200
iv_tablename = iv_table_name ).
MESSAGE 'Table ' && iv_table_name && ' deleted.' TYPE 'I'.
CATCH /aws1/cx_dynresourcenotfoundex.
MESSAGE 'The table ' && iv_table_name && ' does not exist' TYPE 'E'.
CATCH /aws1/cx_dynresourceinuseex.
MESSAGE 'The table cannot be deleted since it is in use' TYPE 'E'.
ENDTRY.
```
+ For API details, see [DeleteTable](https://docs.amazonaws.cn/sdk-for-sap-abap/v1/api/latest/index.html) in *Amazon SDK for SAP ABAP API reference*.
------
#### [ Swift ]
**SDK for Swift**
There's more on GitHub. Find the complete example and learn how to set up and run in the [Amazon Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/swift/example_code/dynamodb#code-examples).
```
import AWSDynamoDB
///
/// Deletes the table from Amazon DynamoDB.
///
func deleteTable() async throws {
do {
guard let client = self.ddbClient else {
throw MoviesError.UninitializedClient
}
let input = DeleteTableInput(
tableName: self.tableName
)
_ = try await client.deleteTable(input: input)
} catch {
print("ERROR: deleteTable:", dump(error))
throw error
}
}
```
+ For API details, see [DeleteTable](https://sdk.amazonaws.com/swift/api/awsdynamodb/latest/documentation/awsdynamodb/dynamodbclient/deletetable(input:)) in *Amazon SDK for Swift API reference*.
------
For more DynamoDB examples, see [Code examples for DynamoDB using Amazon SDKs](service_code_examples.md).
# Continue learning about DynamoDB
For more information about using Amazon DynamoDB, see the following topics:
+ [Working with tables and data in DynamoDB](WorkingWithTables.md)
+ [Working with items and attributes in DynamoDB](WorkingWithItems.md)
+ [Querying tables in DynamoDB](Query.md)
+ [Using Global Secondary Indexes in DynamoDB](GSI.md)
+ [Working with transactionsExample code](transactions.md)
+ [In-memory acceleration with DynamoDB Accelerator (DAX)](DAX.md)
+ [Programming with DynamoDB and the Amazon SDKs](Programming.md)
# Generate infrastructure code for Amazon DynamoDB using Console-to-Code
Amazon Q Developer's Console-to-Code feature simplifies infrastructure management for Amazon DynamoDB by transforming manual table creation steps into reproducible automation code. This capability helps developers efficiently scale database resource configuration across their environments. For more information, see [Automating Amazon Web Services services with Amazon Q Developer Console-to-Code](https://docs.amazonaws.cn/amazonq/latest/qdeveloper-ug/console-to-code.html).
Console-to-Code captures detailed DynamoDB table configurations, including partition keys, sort keys, provisioned throughput settings, and secondary indexes, and converts these into precise infrastructure-as-code templates. Using generative AI, the tool ensures generated code maintains the parameter compatibility established during your console workflow.
Developers can generate DynamoDB infrastructure code in multiple formats, such as:
+ Amazon Cloud Development Kit (Amazon CDK) in TypeScript, Python, and Java
+ Amazon CloudFormation in YAML or JSON
This approach allows teams to:
+ Standardize database resource management
+ Implement version-controlled infrastructure
+ Reduce manual configuration errors
Console-to-Code for Amazon DynamoDB is available in all commercial Amazon Regions, providing a powerful solution for transforming manual configurations into automated, reproducible infrastructure code.
## How it works
When using Console-to-Code with DynamoDB, the process typically involves:
1. **Prototyping in the console** – Use the DynamoDB console to create and configure resources like tables. See [Connect to Amazon DynamoDB](https://docs.amazonaws.cn/amazondynamodb/latest/developerguide/GettingStartedDynamoDB.html) for more information.
1. **Recording actions** – Console-to-Code records these actions as you perform them.
1. **Code generation** – The feature uses Amazon Q Developer's generative AI capabilities to transform your console actions into reusable code in your preferred format.
1. **Code customization** – You can then copy or download this code and further customize it for your production workloads.
## Benefits of using Console-to-Code with DynamoDB
**Simplified automation**
Convert manual DynamoDB table creation and configuration into reusable code with a single click.
**Best practices**
Generated code follows Amazon guided best practices for reliable deployments.
**Bridge between console and code**
You don't have to choose between using the Amazon Web Services Management Console or Infrastructure-as-Code (IaC). You can use both approaches together.
**Accelerated development**
Get started quickly with automation code that can be further customized for production use.
## Example use cases
+ Creating DynamoDB tables with specific attributes, keys, and capacity settings
+ Setting up Global Secondary Indexes and Local Secondary Indexes
+ Configuring auto-scaling policies for DynamoDB tables
+ Establishing backup and restore configurations
+ Creating and managing DynamoDB Streams
## Getting started
To start using Console-to-Code with DynamoDB:
1. Sign in to the Amazon Web Services Management Console and open the DynamoDB console at [https://console.aws.amazon.com/dynamodbv2/](https://console.aws.amazon.com/dynamodbv2/).
1. Begin creating or modifying DynamoDB resources through the console interface.
1. Use the Console-to-Code feature to generate code for your actions in your preferred format.
1. Copy or download the generated code and customize it as needed for your specific requirements.
For more information and detailed instructions on how to use Console-to-Code, see [Automating Amazon Web Services services with Amazon Q Developer Console-to-Code](https://docs.amazonaws.cn/amazonq/latest/qdeveloper-ug/console-to-code.html) in the *Amazon Q Developer User Guide*.