Options
All
  • Public
  • Public/Protected
  • All
Menu

Module @aws-sdk/lib-dynamodb

@aws-sdk/lib-dynamodb

NPM version NPM downloads

Overview

The document client simplifies working with items in Amazon DynamoDB by abstracting away the notion of attribute values. This abstraction annotates native JavaScript types supplied as input parameters, as well as converts annotated response data to native JavaScript types.

Marshalling Input and Unmarshalling Response Data

The document client affords developers the use of native JavaScript types instead of AttributeValues to simplify the JavaScript development experience with Amazon DynamoDB. JavaScript objects passed in as parameters are marshalled into AttributeValue shapes required by Amazon DynamoDB. Responses from DynamoDB are unmarshalled into plain JavaScript objects by the DocumentClient. The DocumentClient does not accept AttributeValues in favor of native JavaScript types.

JavaScript Type DynamoDB AttributeValue
String S
Number / BigInt N
Boolean BOOL
null NULL
Array L
Object M
Set<Uint8Array, Blob, ...> BS
Set<Number, BigInt> NS
Set<String> SS
Uint8Array, Buffer, File, Blob... B

Example

Here is an example list which is sent to DynamoDB client in an operation:

{ "L": [{ "NULL": true }, { "BOOL": false }, { "N": 1 }, { "S": "two" }] }

The DynamoDB document client abstracts the attribute values as follows in both input and output:

[null, false, 1, "two"]

Usage

To create document client you need to create DynamoDB client first as follows:

import { DynamoDBClient } from "@aws-sdk/client-dynamodb"; // ES6 import
// const { DynamoDBClient } = require("@aws-sdk/client-dynamodb"); // CommonJS import

// Bare-bones DynamoDB Client
const client = new DynamoDBClient({});
import { DynamoDB } from "@aws-sdk/client-dynamodb"; // ES6 import
// const { DynamoDB } = require("@aws-sdk/client-dynamodb"); // CommonJS import

// Full DynamoDB Client
const client = new DynamoDB({});

The bare-bones clients are more modular. They reduce bundle size and improve loading performance over full clients as explained in blog post on modular packages in AWS SDK for JavaScript.

Constructor

Once DynamoDB client is created, you can either create the bare-bones document client or full document client as follows:

import { DynamoDBDocumentClient } from "@aws-sdk/lib-dynamodb"; // ES6 import
// const { DynamoDBDocumentClient } = require("@aws-sdk/lib-dynamodb"); // CommonJS import

// Bare-bones document client
const ddbDocClient = DynamoDBDocumentClient.from(client); // client is DynamoDB client
import { DynamoDBDocument } from "@aws-sdk/lib-dynamodb"; // ES6 import
// const { DynamoDBDocument } = require("@aws-sdk/lib-dynamodb"); // CommonJS import

// Full document client
const ddbDocClient = DynamoDBDocument.from(client); // client is DynamoDB client

Configuration

The configuration for marshalling and unmarshalling can be sent as an optional second parameter during creation of document client as follows:

const marshallOptions = {
  // Whether to automatically convert empty strings, blobs, and sets to `null`.
  convertEmptyValues: false, // false, by default.
  // Whether to remove undefined values while marshalling.
  removeUndefinedValues: false, // false, by default.
  // Whether to convert typeof object to map attribute.
  convertClassInstanceToMap: false, // false, by default.
};

const unmarshallOptions = {
  // Whether to return numbers as a string instead of converting them to native JavaScript numbers.
  wrapNumbers: false, // false, by default.
};

const translateConfig = { marshallOptions, unmarshallOptions };

const client = new DynamoDBClient({});
const ddbDocClient = DynamoDBDocument.from(client, translateConfig);

Calling operations

You can call the document client operations using command objects on bare-bones client as follows:

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

// ... DynamoDB client creation

const ddbDocClient = DynamoDBDocumentClient.from(client);
// Call using bare-bones client and Command object.
await ddbDocClient.send(
  new PutCommand({
    TableName,
    Item: {
      id: "1",
      content: "content from DynamoDBDocumentClient",
    },
  })
);

You can also call operations on full client as follows:

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

// ... DynamoDB client creation

const ddbDocClient = DynamoDBDocument.from(client);
// Call using full client.
await ddbDocClient.put({
  TableName,
  Item: {
    id: "2",
    content: "content from DynamoDBDocument",
  },
});

Client and Command middleware stacks

As with other AWS SDK for JavaScript v3 clients, you can apply middleware functions both on the client itself and individual Commands.

For individual Commands, here are examples of how to add middleware before and after both marshalling and unmarshalling. We will use QueryCommand as an example. Others follow the same pattern.

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

const client = new DynamoDBClient({
  /*...*/
});
const doc = DynamoDBDocumentClient.from(client);
const command = new QueryCommand({
  /*...*/
});

Before and after marshalling:

command.middlewareStack.addRelativeTo(
  (next) => async (args) => {
    console.log("pre-marshall", args.input);
    return next(args);
  },
  {
    relation: "before",
    toMiddleware: "DocumentMarshall",
  }
);
command.middlewareStack.addRelativeTo(
  (next) => async (args) => {
    console.log("post-marshall", args.input);
    return next(args);
  },
  {
    relation: "after",
    toMiddleware: "DocumentMarshall",
  }
);

Before and after unmarshalling:

command.middlewareStack.addRelativeTo(
  (next) => async (args) => {
    const result = await next(args);
    console.log("pre-unmarshall", result.output.Items);
    return result;
  },
  {
    relation: "after", // <- after for pre-unmarshall
    toMiddleware: "DocumentUnmarshall",
  }
);
command.middlewareStack.addRelativeTo(
  (next) => async (args) => {
    const result = await next(args);
    console.log("post-unmarshall", result.output.Items);
    return result;
  },
  {
    relation: "before", // <- before for post-unmarshall
    toMiddleware: "DocumentUnmarshall",
  }
);

Destroying document client

The destroy() call on document client is a no-op as document client does not create a new DynamoDB client. You need to call destroy() on DynamoDB client to clean resources used by it as shown below.

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

// Perform operations on document client.

ddbDocClient.destroy(); // no-op
client.destroy(); // destroys DynamoDBClient

Index

References

Classes

Interfaces

Type aliases

Functions

References

BatchExecuteStatementCommand

Re-exports BatchExecuteStatementCommand

BatchExecuteStatementCommand

Re-exports BatchExecuteStatementCommand

BatchExecuteStatementCommandInput

Re-exports BatchExecuteStatementCommandInput

BatchExecuteStatementCommandInput

Re-exports BatchExecuteStatementCommandInput

BatchExecuteStatementCommandOutput

Re-exports BatchExecuteStatementCommandOutput

BatchExecuteStatementCommandOutput

Re-exports BatchExecuteStatementCommandOutput

BatchGetCommand

Re-exports BatchGetCommand

BatchGetCommand

Re-exports BatchGetCommand

BatchGetCommandInput

Re-exports BatchGetCommandInput

BatchGetCommandInput

Re-exports BatchGetCommandInput

BatchGetCommandOutput

Re-exports BatchGetCommandOutput

BatchGetCommandOutput

Re-exports BatchGetCommandOutput

BatchWriteCommand

Re-exports BatchWriteCommand

BatchWriteCommand

Re-exports BatchWriteCommand

BatchWriteCommandInput

Re-exports BatchWriteCommandInput

BatchWriteCommandInput

Re-exports BatchWriteCommandInput

BatchWriteCommandOutput

Re-exports BatchWriteCommandOutput

BatchWriteCommandOutput

Re-exports BatchWriteCommandOutput

DeleteCommand

Re-exports DeleteCommand

DeleteCommand

Re-exports DeleteCommand

DeleteCommandInput

Re-exports DeleteCommandInput

DeleteCommandInput

Re-exports DeleteCommandInput

DeleteCommandOutput

Re-exports DeleteCommandOutput

DeleteCommandOutput

Re-exports DeleteCommandOutput

DynamoDBDocument

Re-exports DynamoDBDocument

DynamoDBDocumentClient

Re-exports DynamoDBDocumentClient

DynamoDBDocumentClientResolvedConfig

Re-exports DynamoDBDocumentClientResolvedConfig

DynamoDBDocumentPaginationConfiguration

Re-exports DynamoDBDocumentPaginationConfiguration

DynamoDBDocumentPaginationConfiguration

Re-exports DynamoDBDocumentPaginationConfiguration

ExecuteStatementCommand

Re-exports ExecuteStatementCommand

ExecuteStatementCommand

Re-exports ExecuteStatementCommand

ExecuteStatementCommandInput

Re-exports ExecuteStatementCommandInput

ExecuteStatementCommandInput

Re-exports ExecuteStatementCommandInput

ExecuteStatementCommandOutput

Re-exports ExecuteStatementCommandOutput

ExecuteStatementCommandOutput

Re-exports ExecuteStatementCommandOutput

ExecuteTransactionCommand

Re-exports ExecuteTransactionCommand

ExecuteTransactionCommand

Re-exports ExecuteTransactionCommand

ExecuteTransactionCommandInput

Re-exports ExecuteTransactionCommandInput

ExecuteTransactionCommandInput

Re-exports ExecuteTransactionCommandInput

ExecuteTransactionCommandOutput

Re-exports ExecuteTransactionCommandOutput

ExecuteTransactionCommandOutput

Re-exports ExecuteTransactionCommandOutput

GetCommand

Re-exports GetCommand

GetCommand

Re-exports GetCommand

GetCommandInput

Re-exports GetCommandInput

GetCommandInput

Re-exports GetCommandInput

GetCommandOutput

Re-exports GetCommandOutput

GetCommandOutput

Re-exports GetCommandOutput

PutCommand

Re-exports PutCommand

PutCommand

Re-exports PutCommand

PutCommandInput

Re-exports PutCommandInput

PutCommandInput

Re-exports PutCommandInput

PutCommandOutput

Re-exports PutCommandOutput

PutCommandOutput

Re-exports PutCommandOutput

QueryCommand

Re-exports QueryCommand

QueryCommand

Re-exports QueryCommand

QueryCommandInput

Re-exports QueryCommandInput

QueryCommandInput

Re-exports QueryCommandInput

QueryCommandOutput

Re-exports QueryCommandOutput

QueryCommandOutput

Re-exports QueryCommandOutput

ScanCommand

Re-exports ScanCommand

ScanCommand

Re-exports ScanCommand

ScanCommandInput

Re-exports ScanCommandInput

ScanCommandInput

Re-exports ScanCommandInput

ScanCommandOutput

Re-exports ScanCommandOutput

ScanCommandOutput

Re-exports ScanCommandOutput

ServiceInputTypes

Re-exports ServiceInputTypes

ServiceOutputTypes

Re-exports ServiceOutputTypes

TransactGetCommand

Re-exports TransactGetCommand

TransactGetCommand

Re-exports TransactGetCommand

TransactGetCommandInput

Re-exports TransactGetCommandInput

TransactGetCommandInput

Re-exports TransactGetCommandInput

TransactGetCommandOutput

Re-exports TransactGetCommandOutput

TransactGetCommandOutput

Re-exports TransactGetCommandOutput

TransactWriteCommand

Re-exports TransactWriteCommand

TransactWriteCommand

Re-exports TransactWriteCommand

TransactWriteCommandInput

Re-exports TransactWriteCommandInput

TransactWriteCommandInput

Re-exports TransactWriteCommandInput

TransactWriteCommandOutput

Re-exports TransactWriteCommandOutput

TransactWriteCommandOutput

Re-exports TransactWriteCommandOutput

TranslateConfig

Re-exports TranslateConfig

UpdateCommand

Re-exports UpdateCommand

UpdateCommand

Re-exports UpdateCommand

UpdateCommandInput

Re-exports UpdateCommandInput

UpdateCommandInput

Re-exports UpdateCommandInput

UpdateCommandOutput

Re-exports UpdateCommandOutput

UpdateCommandOutput

Re-exports UpdateCommandOutput

paginateQuery

Re-exports paginateQuery

paginateQuery

Re-exports paginateQuery

paginateScan

Re-exports paginateScan

paginateScan

Re-exports paginateScan

Type aliases

AllNodes

AllNodes: { children?: KeyNode[] | AllNodes }

Type declaration

BatchExecuteStatementCommandInput

BatchExecuteStatementCommandInput: Omit<__BatchExecuteStatementCommandInput, "Statements"> & { Statements: (Omit<BatchStatementRequest, "Parameters"> & { Parameters?: NativeAttributeValue[] })[] | undefined }

BatchExecuteStatementCommandOutput

BatchExecuteStatementCommandOutput: Omit<__BatchExecuteStatementCommandOutput, "Responses"> & { Responses?: (Omit<BatchStatementResponse, "Item"> & { Item?: Record<string, NativeAttributeValue> })[] }

BatchGetCommandInput

BatchGetCommandInput: Omit<__BatchGetItemCommandInput, "RequestItems"> & { RequestItems: Record<string, Omit<KeysAndAttributes, "Keys"> & { Keys: Record<string, NativeAttributeValue>[] | undefined }> | undefined }

BatchGetCommandOutput

BatchGetCommandOutput: Omit<__BatchGetItemCommandOutput, "Responses" | "UnprocessedKeys"> & { Responses?: Record<string, Record<string, NativeAttributeValue>[]>; UnprocessedKeys?: Record<string, Omit<KeysAndAttributes, "Keys"> & { Keys: Record<string, NativeAttributeValue>[] | undefined }> }

BatchWriteCommandInput

BatchWriteCommandInput: Omit<__BatchWriteItemCommandInput, "RequestItems"> & { RequestItems: Record<string, (Omit<WriteRequest, "PutRequest" | "DeleteRequest"> & { DeleteRequest?: Omit<DeleteRequest, "Key"> & { Key: Record<string, NativeAttributeValue> | undefined }; PutRequest?: Omit<PutRequest, "Item"> & { Item: Record<string, NativeAttributeValue> | undefined } })[]> | undefined }

BatchWriteCommandOutput

BatchWriteCommandOutput: Omit<__BatchWriteItemCommandOutput, "UnprocessedItems" | "ItemCollectionMetrics"> & { ItemCollectionMetrics?: Record<string, (Omit<ItemCollectionMetrics, "ItemCollectionKey"> & { ItemCollectionKey?: Record<string, NativeAttributeValue> })[]>; UnprocessedItems?: Record<string, (Omit<WriteRequest, "PutRequest" | "DeleteRequest"> & { DeleteRequest?: Omit<DeleteRequest, "Key"> & { Key: Record<string, NativeAttributeValue> | undefined }; PutRequest?: Omit<PutRequest, "Item"> & { Item: Record<string, NativeAttributeValue> | undefined } })[]> }

DeleteCommandInput

DeleteCommandInput: Omit<__DeleteItemCommandInput, "Key" | "Expected" | "ExpressionAttributeValues"> & { Expected?: Record<string, Omit<ExpectedAttributeValue, "Value" | "AttributeValueList"> & { AttributeValueList?: NativeAttributeValue[]; Value?: NativeAttributeValue }>; ExpressionAttributeValues?: Record<string, NativeAttributeValue>; Key: Record<string, NativeAttributeValue> | undefined }

DeleteCommandOutput

DeleteCommandOutput: Omit<__DeleteItemCommandOutput, "Attributes" | "ItemCollectionMetrics"> & { Attributes?: Record<string, NativeAttributeValue>; ItemCollectionMetrics?: Omit<ItemCollectionMetrics, "ItemCollectionKey"> & { ItemCollectionKey?: Record<string, NativeAttributeValue> } }

DynamoDBDocumentClientResolvedConfig

DynamoDBDocumentClientResolvedConfig: DynamoDBClientResolvedConfig & { translateConfig?: TranslateConfig }

ExecuteStatementCommandInput

ExecuteStatementCommandInput: Omit<__ExecuteStatementCommandInput, "Parameters"> & { Parameters?: NativeAttributeValue[] }

ExecuteStatementCommandOutput

ExecuteStatementCommandOutput: Omit<__ExecuteStatementCommandOutput, "Items" | "LastEvaluatedKey"> & { Items?: Record<string, NativeAttributeValue>[]; LastEvaluatedKey?: Record<string, NativeAttributeValue> }

ExecuteTransactionCommandInput

ExecuteTransactionCommandInput: Omit<__ExecuteTransactionCommandInput, "TransactStatements"> & { TransactStatements: (Omit<ParameterizedStatement, "Parameters"> & { Parameters?: NativeAttributeValue[] })[] | undefined }

ExecuteTransactionCommandOutput

ExecuteTransactionCommandOutput: Omit<__ExecuteTransactionCommandOutput, "Responses"> & { Responses?: (Omit<ItemResponse, "Item"> & { Item?: Record<string, NativeAttributeValue> })[] }

GetCommandInput

GetCommandInput: Omit<__GetItemCommandInput, "Key"> & { Key: Record<string, NativeAttributeValue> | undefined }

GetCommandOutput

GetCommandOutput: Omit<__GetItemCommandOutput, "Item"> & { Item?: Record<string, NativeAttributeValue> }

KeyNode

KeyNode: { children?: KeyNode[] | AllNodes; key: string }

Type declaration

PutCommandInput

PutCommandInput: Omit<__PutItemCommandInput, "Item" | "Expected" | "ExpressionAttributeValues"> & { Expected?: Record<string, Omit<ExpectedAttributeValue, "Value" | "AttributeValueList"> & { AttributeValueList?: NativeAttributeValue[]; Value?: NativeAttributeValue }>; ExpressionAttributeValues?: Record<string, NativeAttributeValue>; Item: Record<string, NativeAttributeValue> | undefined }

PutCommandOutput

PutCommandOutput: Omit<__PutItemCommandOutput, "Attributes" | "ItemCollectionMetrics"> & { Attributes?: Record<string, NativeAttributeValue>; ItemCollectionMetrics?: Omit<ItemCollectionMetrics, "ItemCollectionKey"> & { ItemCollectionKey?: Record<string, NativeAttributeValue> } }

QueryCommandInput

QueryCommandInput: Omit<__QueryCommandInput, "KeyConditions" | "QueryFilter" | "ExclusiveStartKey" | "ExpressionAttributeValues"> & { ExclusiveStartKey?: Record<string, NativeAttributeValue>; ExpressionAttributeValues?: Record<string, NativeAttributeValue>; KeyConditions?: Record<string, Omit<Condition, "AttributeValueList"> & { AttributeValueList?: NativeAttributeValue[] }>; QueryFilter?: Record<string, Omit<Condition, "AttributeValueList"> & { AttributeValueList?: NativeAttributeValue[] }> }

QueryCommandOutput

QueryCommandOutput: Omit<__QueryCommandOutput, "Items" | "LastEvaluatedKey"> & { Items?: Record<string, NativeAttributeValue>[]; LastEvaluatedKey?: Record<string, NativeAttributeValue> }

ScanCommandInput

ScanCommandInput: Omit<__ScanCommandInput, "ScanFilter" | "ExclusiveStartKey" | "ExpressionAttributeValues"> & { ExclusiveStartKey?: Record<string, NativeAttributeValue>; ExpressionAttributeValues?: Record<string, NativeAttributeValue>; ScanFilter?: Record<string, Omit<Condition, "AttributeValueList"> & { AttributeValueList?: NativeAttributeValue[] }> }

ScanCommandOutput

ScanCommandOutput: Omit<__ScanCommandOutput, "Items" | "LastEvaluatedKey"> & { Items?: Record<string, NativeAttributeValue>[]; LastEvaluatedKey?: Record<string, NativeAttributeValue> }

ServiceInputTypes

ServiceOutputTypes

TransactGetCommandInput

TransactGetCommandInput: Omit<__TransactGetItemsCommandInput, "TransactItems"> & { TransactItems: (Omit<TransactGetItem, "Get"> & { Get: (Omit<Get, "Key"> & { Key: Record<string, NativeAttributeValue> | undefined }) | undefined })[] | undefined }

TransactGetCommandOutput

TransactGetCommandOutput: Omit<__TransactGetItemsCommandOutput, "Responses"> & { Responses?: (Omit<ItemResponse, "Item"> & { Item?: Record<string, NativeAttributeValue> })[] }

TransactWriteCommandInput

TransactWriteCommandInput: Omit<__TransactWriteItemsCommandInput, "TransactItems"> & { TransactItems: (Omit<TransactWriteItem, "ConditionCheck" | "Put" | "Delete" | "Update"> & { ConditionCheck?: Omit<ConditionCheck, "Key" | "ExpressionAttributeValues"> & { ExpressionAttributeValues?: Record<string, NativeAttributeValue>; Key: Record<string, NativeAttributeValue> | undefined }; Delete?: Omit<Delete, "Key" | "ExpressionAttributeValues"> & { ExpressionAttributeValues?: Record<string, NativeAttributeValue>; Key: Record<string, NativeAttributeValue> | undefined }; Put?: Omit<Put, "Item" | "ExpressionAttributeValues"> & { ExpressionAttributeValues?: Record<string, NativeAttributeValue>; Item: Record<string, NativeAttributeValue> | undefined }; Update?: Omit<Update, "Key" | "ExpressionAttributeValues"> & { ExpressionAttributeValues?: Record<string, NativeAttributeValue>; Key: Record<string, NativeAttributeValue> | undefined } })[] | undefined }

TransactWriteCommandOutput

TransactWriteCommandOutput: Omit<__TransactWriteItemsCommandOutput, "ItemCollectionMetrics"> & { ItemCollectionMetrics?: Record<string, (Omit<ItemCollectionMetrics, "ItemCollectionKey"> & { ItemCollectionKey?: Record<string, NativeAttributeValue> })[]> }

TranslateConfig

TranslateConfig: { marshallOptions?: marshallOptions; unmarshallOptions?: unmarshallOptions }

Type declaration

UpdateCommandInput

UpdateCommandInput: Omit<__UpdateItemCommandInput, "Key" | "AttributeUpdates" | "Expected" | "ExpressionAttributeValues"> & { AttributeUpdates?: Record<string, Omit<AttributeValueUpdate, "Value"> & { Value?: NativeAttributeValue }>; Expected?: Record<string, Omit<ExpectedAttributeValue, "Value" | "AttributeValueList"> & { AttributeValueList?: NativeAttributeValue[]; Value?: NativeAttributeValue }>; ExpressionAttributeValues?: Record<string, NativeAttributeValue>; Key: Record<string, NativeAttributeValue> | undefined }

UpdateCommandOutput

UpdateCommandOutput: Omit<__UpdateItemCommandOutput, "Attributes" | "ItemCollectionMetrics"> & { Attributes?: Record<string, NativeAttributeValue>; ItemCollectionMetrics?: Omit<ItemCollectionMetrics, "ItemCollectionKey"> & { ItemCollectionKey?: Record<string, NativeAttributeValue> } }

Functions

Private Const makePagedClientRequest

Private Const makePagedClientRequest

Private Const makePagedRequest

Private Const makePagedRequest

Const marshallInput

paginateQuery

paginateScan

Const processAllKeysInObj

  • processAllKeysInObj(obj: any, processFunc: Function, children?: KeyNode[] | AllNodes): any

Const processKeyInObj

  • processKeyInObj(obj: any, processFunc: Function, children?: KeyNode[] | AllNodes): any

Const processKeysInObj

  • processKeysInObj(obj: any, processFunc: Function, keyNodes: KeyNode[]): any

Const processObj

  • processObj(obj: any, processFunc: Function, children?: KeyNode[] | AllNodes): any

Const unmarshallOutput