How to Use DynamoDB Document Client: Simple Guide

Use the DynamoDB Document Client to interact with DynamoDB in a simple way by working with native JavaScript objects instead of raw DynamoDB types. Initialize it from the AWS SDK, then call methods like get, put, or query with plain objects to read or write data.

Syntax

The DynamoDB Document Client simplifies working with DynamoDB by letting you use plain JavaScript objects. You first create a client instance, then call methods like get, put, update, or delete with parameters describing your operation.

Each method takes an object with keys like TableName and Key or Item. The client handles converting data to DynamoDB format and back.

javascript

const { DynamoDBClient } = require("@aws-sdk/client-dynamodb");
const { DynamoDBDocumentClient, GetCommand, PutCommand } = require("@aws-sdk/lib-dynamodb");

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

// Example: Get an item
const getParams = {
  TableName: "MyTable",
  Key: { id: "123" }
};
const getCommand = new GetCommand(getParams);
const data = await docClient.send(getCommand);

// Example: Put an item
const putParams = {
  TableName: "MyTable",
  Item: { id: "123", name: "Alice" }
};
const putCommand = new PutCommand(putParams);
await docClient.send(putCommand);

Example

This example shows how to put a new item into a DynamoDB table and then get it back using the Document Client. It uses simple JavaScript objects for input and output.

javascript

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

async function runExample() {
  const client = new DynamoDBClient({ region: "us-east-1" });
  const docClient = DynamoDBDocumentClient.from(client);

  const tableName = "Users";
  const userId = "user123";

  // Put a new user item
  const putParams = {
    TableName: tableName,
    Item: { id: userId, name: "John Doe", age: 30 }
  };
  await docClient.send(new PutCommand(putParams));

  // Get the user item back
  const getParams = {
    TableName: tableName,
    Key: { id: userId }
  };
  const result = await docClient.send(new GetCommand(getParams));

  console.log("Retrieved item:", result.Item);
}

runExample();

Output

Retrieved item: { id: 'user123', name: 'John Doe', age: 30 }

Common Pitfalls

• Not initializing the Document Client correctly: You must create a DynamoDBClient first and then create the Document Client from it.
• Using raw DynamoDB types: The Document Client expects plain JavaScript objects, not the low-level DynamoDB attribute value format.
• Forgetting to await async calls: All send calls return promises, so use await or handle promises properly.
• Incorrect keys or table names: Make sure your TableName and Key match your DynamoDB table schema exactly.

javascript

/* Wrong way: Using raw DynamoDB types */
const wrongPutParams = {
  TableName: "MyTable",
  Item: {
    id: { S: "123" }, // raw DynamoDB type
    name: { S: "Alice" }
  }
};

/* Right way: Use plain JavaScript objects */
const rightPutParams = {
  TableName: "MyTable",
  Item: {
    id: "123",
    name: "Alice"
  }
};

Quick Reference

Here is a quick summary of common Document Client methods and their main parameters:

Method	Purpose	Key Parameters
GetCommand	Retrieve an item	TableName, Key
PutCommand	Add or replace an item	TableName, Item
UpdateCommand	Modify attributes of an item	TableName, Key, UpdateExpression, ExpressionAttributeValues
DeleteCommand	Remove an item	TableName, Key
QueryCommand	Find items by key condition	TableName, KeyConditionExpression, ExpressionAttributeValues

Key Takeaways

Initialize DynamoDB Document Client from DynamoDBClient for easy JavaScript object handling.

Use plain JavaScript objects for items and keys, not raw DynamoDB attribute types.

Always await the async send calls to get results or confirm writes.

Double-check your table names and key structure to avoid errors.

Use commands like GetCommand and PutCommand with clear parameters for common operations.