DynamoDB PutItem with the AWS CLI

aws dynamodb put-item writes a whole item, creating it or replacing any existing item with the same primary key. The item goes in --item as DynamoDB JSON — every value wrapped with its type.

Code

aws dynamodb put-item \
  --table-name Music \
  --item '{
    "Artist":     {"S": "Arturo Sandoval"},
    "SongTitle":  {"S": "Cubano Chant"},
    "AlbumTitle": {"S": "Danzon"},
    "Year":       {"N": "1994"},
    "Awards":     {"N": "0"}
  }' \
  --condition-expression "attribute_not_exists(Artist) AND attribute_not_exists(SongTitle)" \
  --region us-east-1

On success the command prints nothing and exits 0. If the item already exists, the condition fails:

An error occurred (ConditionalCheckFailedException) when calling the PutItem operation:
The conditional request failed

Explanation

• --item — DynamoDB JSON containing the full primary key plus any other attributes. Numbers use the N type as strings ({"N": "1994"}).
• Put replaces — without a condition, put-item silently overwrites an existing item with the same key. Use update-item to change a few attributes without clobbering the rest.
• --condition-expression — attribute_not_exists(<key>) makes this a create-only insert; it errors with ConditionalCheckFailedException when the item already exists.
• Add --return-values ALL_OLD to print the overwritten item.
• Tip: for large items or awkward shell quoting, use --item file://song.json.

Do it visually

Hand-writing DynamoDB JSON is error-prone. The DynamoDB Expression Builder builds the condition expression and hands you a ready-to-run CLI command.

To add and edit items in a GUI — a form per attribute, type pickers, copy-as-CLI — download DynoTable.

Related guides

• DynamoDB condition expressions — attribute_not_exists, optimistic locking, and more.
• DynamoDB data types — how each attribute type is written in DynamoDB JSON.