What Is the DocumentClient in AWS SDK for JavaScript v3?

The DocumentClient is a high-level abstraction from the @aws-sdk/lib-dynamodb package that automatically converts JavaScript objects to DynamoDB's native attribute-value format and vice versa, eliminating the need for manual data marshalling.

The DocumentClient simplifies DynamoDB operations in the AWS SDK for JavaScript v3 by providing an ergonomic wrapper around the low-level DynamoDBClient. According to the aws/agent-toolkit-for-aws repository—specifically documented in skills/core-skills/aws-sdk-js-v3-usage/references/dynamodb.md—this client lets you work with plain JavaScript objects instead of complex DynamoDB JSON structures.

How the DocumentClient Architecture Works

The DocumentClient follows a layered architecture that delegates network operations to the base client while handling data transformation automatically.

Base Client Dependency

The DocumentClient requires a pre-configured DynamoDBClient instance as its foundation. This low-level client handles signed HTTP requests, retry logic, and middleware configuration.

Wrapper Instantiation

You create the DocumentClient using the static DynamoDBDocumentClient.from() method. This factory method accepts the base client and optional configuration parameters, returning a wrapped instance that intercepts and transforms data before sending requests to DynamoDB.

High-Level Command Objects

Instead of low-level commands like PutItemCommand or GetItemCommand, the DocumentClient uses specialized commands from @aws-sdk/lib-dynamodb including:

• PutCommand
• GetCommand
• QueryCommand
• DeleteCommand

These commands accept native JavaScript types and automatically handle the conversion to DynamoDB's attribute-value format.

Customization Options

The wrapper supports optional marshallOptions and unmarshallOptions configurations that control how data types are converted, such as handling BigInt values, Set objects, or empty string treatment.

Creating a DocumentClient Instance

To instantiate the DocumentClient, first create the low-level DynamoDBClient, then wrap it using DynamoDBDocumentClient.from() as shown in the reference file skills/core-skills/aws-sdk-js-v3-usage/references/dynamodb.md:

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

// Low-level client (region, credentials, etc.)
const ddbClient = new DynamoDBClient({ region: "us-east-1" });

// Document client that wraps the low-level client
const docClient = DynamoDBDocumentClient.from(ddbClient);

Performing CRUD Operations

The DocumentClient streamlines common DynamoDB operations by accepting plain objects directly.

Inserting Items with PutCommand

Use PutCommand to store JavaScript objects without manual attribute mapping:

import { PutCommand } from "@aws-sdk/lib-dynamodb";

await docClient.send(
  new PutCommand({
    TableName: "Products",
    Item: {
      ProductId: "123",
      Name: "Coffee Mug",
      Price: 12.99,
      Tags: ["kitchen", "ceramic"]
    }
  })
);

Retrieving Items with GetCommand

The GetCommand returns unmarshalled JavaScript objects automatically:

import { GetCommand } from "@aws-sdk/lib-dynamodb";

const { Item } = await docClient.send(
  new GetCommand({
    TableName: "Products",
    Key: { ProductId: "123" }
  })
);

console.log(Item); // { ProductId: '123', Name: 'Coffee Mug', … }

Querying with QueryCommand

Complex queries work with native JavaScript types for expression values:

import { QueryCommand } from "@aws-sdk/lib-dynamodb";

const result = await docClient.send(
  new QueryCommand({
    TableName: "Orders",
    IndexName: "CustomerIndex",
    KeyConditionExpression: "CustomerId = :cid",
    ExpressionAttributeValues: { ":cid": "C001" }
  })
);

console.log(result.Items);

Configuring Marshall Options

You can customize data transformation behavior by passing options to DynamoDBDocumentClient.from():

const customDocClient = DynamoDBDocumentClient.from(ddbClient, {
  marshallOptions: {
    convertEmptyValues: true,      // Treat empty strings as null
    removeUndefinedValues: true   // Omit undefined fields
  },
  unmarshallOptions: {
    wrapNumbers: false             // Return numbers as native JS numbers
  }
});

Summary

• The DocumentClient from @aws-sdk/lib-dynamodb wraps the low-level DynamoDBClient to provide automatic data marshalling.
• Create instances using DynamoDBDocumentClient.from(baseClient, options?) as documented in skills/core-skills/aws-sdk-js-v3-usage/references/dynamodb.md.
• Use high-level commands (PutCommand, GetCommand, QueryCommand) that accept and return plain JavaScript objects.
• Configure marshallOptions and unmarshallOptions to customize handling of empty values, undefined fields, and number wrapping.
• The architecture preserves all security, retry, and middleware behaviors from the underlying client while simplifying the programming model.

Frequently Asked Questions

What is the difference between DynamoDBClient and DocumentClient in AWS SDK for JavaScript v3?

The DynamoDBClient is the low-level client that sends signed HTTP requests to DynamoDB using the raw attribute-value format. The DocumentClient is a high-level wrapper that automatically converts between JavaScript objects and DynamoDB's native format, allowing you to work with plain objects instead of complex typed JSON structures.

Do I need to install a separate package for the DocumentClient?

Yes. While the DynamoDBClient comes from @aws-sdk/client-dynamodb, the DocumentClient requires the separate package @aws-sdk/lib-dynamodb. You must import DynamoDBDocumentClient from this package and use its from() method to wrap your base client.

How does the DocumentClient handle data type conversion?

The client automatically marshals JavaScript types (strings, numbers, booleans, arrays, objects) to DynamoDB's attribute-value format when sending requests. On responses, it unmarshals the data back to native JavaScript values. You can customize this behavior through marshallOptions and unmarshallOptions parameters, such as converting empty strings to null or wrapping numbers as strings.

Can I use the DocumentClient with transactions?

Yes. The @aws-sdk/lib-dynamodb package provides high-level transaction commands like TransactGetCommand and TransactWriteCommand that work with the DocumentClient. These commands accept plain JavaScript objects for item inputs and automatically handle the marshalling required for DynamoDB transactional operations.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}