Document client abstraction in DynamoDB

Introduction

The document client abstraction makes it easy to work with DynamoDB by letting you use simple JavaScript objects instead of complex low-level commands.

When you want to save a new item to a DynamoDB table using simple JavaScript objects.

When you need to read an item from DynamoDB without dealing with raw attribute values.

When updating or deleting items in DynamoDB using easy-to-understand code.

When you want to avoid writing verbose code for data conversion between your app and DynamoDB.

Syntax

DynamoDB

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

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

// To put an item
await docClient.send(new PutCommand({
  TableName: "YourTableName",
  Item: { key1: "value1", key2: 123 }
}));

// To get an item
const result = await docClient.send(new GetCommand({
  TableName: "YourTableName",
  Key: { key1: "value1" }
}));

The Document Client automatically converts JavaScript objects to DynamoDB format and back.

You use commands like PutCommand and GetCommand with the document client to perform operations.

Examples

Stores a user object with simple keys and values.

DynamoDB

await docClient.send(new PutCommand({
  TableName: "Users",
  Item: { userId: "123", name: "Alice", age: 30 }
}));

Retrieves the user with userId '123' and prints the JavaScript object.

DynamoDB

const data = await docClient.send(new GetCommand({
  TableName: "Users",
  Key: { userId: "123" }
}));
console.log(data.Item);

If the item is missing, the result's Item is undefined.

DynamoDB

// Edge case: Getting an item that does not exist
const data = await docClient.send(new GetCommand({
  TableName: "Users",
  Key: { userId: "999" }
}));
console.log(data.Item); // undefined

Sample Program

This program shows how to use the document client to get an item before and after inserting it. It prints the item state before and after the PutCommand.

DynamoDB

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

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

  console.log("Before putting item:");
  let getResult = await docClient.send(new GetCommand({
    TableName: "TestTable",
    Key: { id: "1" }
  }));
  console.log(getResult.Item); // Should be undefined if no item

  await docClient.send(new PutCommand({
    TableName: "TestTable",
    Item: { id: "1", name: "John Doe", age: 25 }
  }));

  console.log("After putting item:");
  getResult = await docClient.send(new GetCommand({
    TableName: "TestTable",
    Key: { id: "1" }
  }));
  console.log(getResult.Item); // Should show the inserted item
}

run().catch(console.error);

Important Notes

The document client simplifies working with DynamoDB by handling data conversion automatically.

Time complexity depends on the operation (e.g., GetCommand is O(1) for primary key access).

Common mistake: forgetting to await the send() method, which causes unexpected behavior.

Use the document client when you want clean, readable code without manual data marshaling.

Summary

The document client lets you use plain JavaScript objects with DynamoDB.

It hides the complexity of DynamoDB's data format conversions.

You use commands like PutCommand and GetCommand with the document client to perform operations.