# What Is the DocumentClient in AWS SDK for JavaScript v3?

> Discover the AWS SDK for JavaScript v3 DocumentClient. This high-level abstraction simplifies DynamoDB interactions by handling data marshalling automatically.

- Repository: [Amazon Web Services/agent-toolkit-for-aws](https://github.com/aws/agent-toolkit-for-aws)
- Tags: deep-dive
- Published: 2026-06-27

---

**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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/skills/core-skills/aws-sdk-js-v3-usage/references/dynamodb.md):

```javascript
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:

```javascript
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:

```javascript
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:

```javascript
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()`:

```javascript
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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/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.