How to Use PutItem in DynamoDB: Syntax and Example

Use PutItem in DynamoDB to add a new item or replace an existing item in a table by specifying the table name and the item attributes as key-value pairs. The operation requires a primary key and can include other attributes to store data.

Syntax

The PutItem operation requires specifying the TableName and the Item to insert or replace. The Item is a map of attribute names to their values, where each value is typed (e.g., string, number).

Optional parameters include ConditionExpression to control when the item is inserted, and ReturnValues to get information about the operation result.

plaintext

PutItem {
  TableName: "YourTableName",
  Item: {
    "PrimaryKeyAttribute": { S: "PrimaryKeyValue" },
    "Attribute1": { S: "Value1" },
    "Attribute2": { N: "123" }
  },
  ConditionExpression: "attribute_not_exists(PrimaryKeyAttribute)",
  ReturnValues: "ALL_OLD"
}

Example

This example shows how to use the AWS SDK for JavaScript (v3) to put an item into a DynamoDB table named Users. It inserts a user with UserId as the primary key and additional attributes.

javascript

import { DynamoDBClient, PutItemCommand } from "@aws-sdk/client-dynamodb";

const client = new DynamoDBClient({ region: "us-east-1" });

async function putUser() {
  const params = {
    TableName: "Users",
    Item: {
      "UserId": { S: "user123" },
      "Name": { S: "Alice" },
      "Age": { N: "30" }
    }
  };

  try {
    const command = new PutItemCommand(params);
    const result = await client.send(command);
    console.log("PutItem succeeded:", result);
  } catch (error) {
    console.error("PutItem failed:", error);
  }
}

putUser();

Output

PutItem succeeded: {}

Common Pitfalls

• Not specifying the primary key attributes in the Item causes the operation to fail.
• Using incorrect data types for attribute values (e.g., string instead of number) leads to errors.
• Overwriting existing items unintentionally if ConditionExpression is not used to prevent it.
• Forgetting to await the asynchronous call in SDKs can cause unexpected behavior.

javascript

/* Wrong: Missing primary key attribute */
const paramsWrong = {
  TableName: "Users",
  Item: {
    "Name": { S: "Bob" }
  }
};

/* Right: Include primary key attribute */
const paramsRight = {
  TableName: "Users",
  Item: {
    "UserId": { S: "user456" },
    "Name": { S: "Bob" }
  }
};

Quick Reference

Parameter	Description
TableName	Name of the DynamoDB table
Item	Map of attribute names to typed values to insert
ConditionExpression	Optional condition to control insertion
ReturnValues	Optional info to return about replaced item
Primary Key	Must be included in Item to identify the record

Key Takeaways

PutItem inserts or replaces a single item in a DynamoDB table by specifying TableName and Item.

Always include the primary key attributes in the Item to avoid errors.

Use ConditionExpression to prevent overwriting existing items unintentionally.

Attribute values must be typed correctly (e.g., S for string, N for number).

PutItem is asynchronous in SDKs; await the call to handle results properly.