DynamoDB: Create if Not Exists (Guide w/ Code Examples)

PutCommand normally replaces an existing item. Add attribute_not_exists(pk) to reject a write when that full primary key already exists; the check and write happen atomically.

Install @aws-sdk/client-dynamodb and @aws-sdk/lib-dynamodb, use an ES module on a supported Node.js runtime, and configure an AWS Region and credentials. The examples use an existing Orders table with String keys pk and sk unless an index or timestamp key is described.

import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, PutCommand } from "@aws-sdk/lib-dynamodb";

const ddb = DynamoDBDocumentClient.from(new DynamoDBClient({}));

await ddb.send(new PutCommand({
  TableName: "Orders",
  Item: { pk: "CUSTOMER#123", sk: "ORDER#001", status: "PENDING" },
  ConditionExpression: "attribute_not_exists(pk)",
}));

Handle ConditionalCheckFailedException as an existing-item conflict. For a composite primary key, the condition applies to the item identified by both key attributes.

Reference: AWS PutItem API. For related access patterns, see DynamoDB query examples.