Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

The Amazon SDK for JavaScript V3 API Reference Guide describes in detail all the API operations for the Amazon SDK for JavaScript version 3 (V3).

Using the DynamoDB Document Client

This Node.js code example shows:

The Scenario

The DynamoDB Document Client simplifies working with items by abstracting the notion of attribute values. This abstraction annotates native JavaScript types supplied as input parameters, and converts annotated response data to native JavaScript types.

For more information about the DynamoDB Document Client, see @aws-sdk/lib-dynamodb README on GitHub. For more information about programming with Amazon DynamoDB, see Programming with DynamoDB in the Amazon DynamoDB Developer Guide.

In this example, you use a series of Node.js modules to perform basic operations on a DynamoDB table using DynamoDB utilities. The code uses the SDK for JavaScript to query and scan tables using these methods of the DynamoDB Document Client class:

For more information on configuring the DynamoDB Document Client, see @aws-sdk/lib-dynamodb.

Prerequisite Tasks

To set up and run this example, first complete these tasks:

Getting an Item from a Table

Create a Node.js module with the file name get.js. Be sure to configure the SDK as previously shown, including installing the required clients and packages. This includes @aws-sdk/lib-dynamodb, a library package that provides document client functionality to @aws-sdk/client-dynamodb. Next, set the configuration as shown below for marshalling and unmarshalling - as an optional second parameter - during creation of document client. Next, create the clients. Now create a JSON object containing the parameters needed get an item from the table, which in this example includes the name of the table, the name of the hash key in that table, and the value of the hash key for the item you want to get. Call the GetCommand method of the DynamoDB Document Client.

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

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

export const main = async () => {
  const command = new GetCommand({
    TableName: "AngryAnimals",
    Key: {
      CommonName: "Shoebill",
    },
  });

  const response = await docClient.send(command);
  console.log(response);
  return response;
};

To run the example, enter the following at the command prompt.

node get.js

This example code can be found here on GitHub.

Putting an Item in a Table

Create a Node.js module with the file name put.js. Be sure to configure the SDK as previously shown, including installing the required clients and packages. This includes @aws-sdk/lib-dynamodb, a library package that provides document client functionality to @aws-sdk/client-dynamodb. Next, set the configuration as shown below for marshalling and unmarshalling - as an optional second parameter - during creation of document client. Next, create the clients. Create a JSON object containing the parameters needed to write an item to the table, which in this example includes the name of the table and a description of the item to add or update that includes the hashkey and value and names and values for attributes to set on the item. Call the PutCommand method of the DynamoDB Document Client.

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

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

export const main = async () => {
  const command = new PutCommand({
    TableName: "HappyAnimals",
    Item: {
      CommonName: "Shiba Inu",
    },
  });

  const response = await docClient.send(command);
  console.log(response);
  return response;
};

To run the example, enter the following at the command prompt.

node put.js

This example code can be found here on GitHub.

Updating an Item in a Table

Create a Node.js module with the file name update.js. Be sure to configure the SDK as previously shown, including installing the required clients and packages. This includes @aws-sdk/lib-dynamodb, a library package that provides document client functionality to @aws-sdk/client-dynamodb. Next, set the configuration as shown below for marshalling and unmarshalling - as an optional second parameter - during creation of document client. Next, create the clients. Create a JSON object containing the parameters needed to write an item to the table, which in this example includes the name of the table, the key of the item to update, a set of UpdateExpressions that define the attributes of the item to update with tokens you assign values to in the ExpressionAttributeValues parameters.Call the UpdateCommand method of the DynamoDB Document Client.

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

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

export const main = async () => {
  const command = new UpdateCommand({
    TableName: "Dogs",
    Key: {
      Breed: "Labrador",
    },
    UpdateExpression: "set Color = :color",
    ExpressionAttributeValues: {
      ":color": "black",
    },
    ReturnValues: "ALL_NEW",
  });

  const response = await docClient.send(command);
  console.log(response);
  return response;
};

To run the example, enter the following at the command prompt.

node update.js

This example code can be found here on GitHub.

Querying a Table

Create a Node.js module with the file name query.js. Be sure to configure the SDK as previously shown, including installing the required clients and packages. This includes @aws-sdk/lib-dynamodb, a library package that provides document client functionality to @aws-sdk/client-dynamodb. Create a JSON object containing the parameters needed to query the table, which in this example includes the table name, the ExpressionAttributeValues needed by the query, and a KeyConditionExpression that uses those values to define which items the query returns. Call the QueryCommand method of the DynamoDB Document Client.

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

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

export const main = async () => {
  const command = new QueryCommand({
    TableName: "CoffeeCrop",
    KeyConditionExpression:
      "OriginCountry = :originCountry AND RoastDate > :roastDate",
    ExpressionAttributeValues: {
      ":originCountry": "Ethiopia",
      ":roastDate": "2023-05-01",
    },
    ConsistentRead: true,
  });

  const response = await docClient.send(command);
  console.log(response);
  return response;
};

To run the example, enter the following at the command prompt.

node query.js

This example code can be found here on GitHub.

Deleting an Item from a Table

Create a Node.js module with the file name delete.js. Be sure to configure the SDK as previously shown, including installing the required clients and packages. This includes @aws-sdk/lib-dynamodb, a library package that provides document client functionality to @aws-sdk/client-dynamodb. Next, set the configuration as shown below for marshalling and unmarshalling - as an optional second parameter - during creation of document client. Next, create the clients. To access DynamoDB, create a DynamoDB object. Create a JSON object containing the parameters needed to delete an item in the table, which in this example includes the name of the table and the name and value of the hashkey of the item you want to delete. Call the DeleteCommand method of the DynamoDB Document Client.

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

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

export const main = async () => {
  const command = new DeleteCommand({
    TableName: "Sodas",
    Key: {
      Flavor: "Cola",
    },
  });

  const response = await docClient.send(command);
  console.log(response);
  return response;
};

To run the example, enter the following at the command prompt.

node delete.js

This example code can be found here on GitHub.