The AWS SDK for JavaScript V3 API Reference Guide describes in detail all the API operations for the AWS SDK for JavaScript version 3 (V3).
Using the DynamoDB Document Client
This Node.js code example shows:
How to access a DynamoDB table using the DynamoDB utilities.
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
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 class:
getItem
putItem
updateItem
query
deleteItem
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:
-
Set up the project environment to run these Node.js examples, and install the required AWS SDK for JavaScript and third-party modules. Follow the instructions on GitHub
. Create a shared configurations file with your user credentials. For more information about providing a shared credentials file, see Loading credentials in Node.js from the shared credentials file.
Create a DynamoDB table whose items you can access. For more information about creating a DynamoDB table using the SDK for JavaScript, see Creating and using tables in DynamoDB. You can also use the DynamoDB console
to create a table.
Important
These examples use ECMAScript6 (ES6). This requires Node.js version 13.x or higher. To download and install the latest version of
Node.js, see Node.js downloads.
However, if you prefer to use CommonJS syntax, please refer to JavaScript ES6/CommonJS syntax.
Note
For information about the data types used in these examples, see Supported data types and naming rules in Amazon DynamoDB.
Getting an Item from a Table
Create a libs
directory, and create a Node.js module with the file name ddbDocClient.js
. Copy and paste the code below into it,
which creates the DynamoDB document client object. Replace REGION
with your AWS region.
import { DynamoDBClient } from "@aws-sdk/client-dynamodb"; import { DynamoDBDocumentClient } from "@aws-sdk/lib-dynamodb"; export const docClient = DynamoDBDocumentClient.from(new DynamoDBClient({}));
This code is available here on GitHub
In the libs
directory create a Node.js module with the file name ddbClient.js
. Copy and paste the code below into it,
which creates the DynamoDB client object. Replace REGION
with your AWS region.
import { DynamoDBClient } from "@aws-sdk/client-dynamodb"; export const client = new DynamoDBClient({ region: "us-east-1" })
This code is available here on GitHub
Create a Node.js module with the file name ddbdoc_get_item.js
. Be sure to
configure the SDK as previously shown, including installing the required clients
and packages. This includes the @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 ddbdoc_get_item.js // To use JavaScript, enter 'node ddbdoc_get_item.js
This example code can be found here on GitHub
Putting an Item in a Table
Create a libs
directory, and create a Node.js module with the file name ddbDocClient.js
. Copy and paste the code below into it,
which creates the DynamoDB document client object. Replace REGION
with your AWS region.
import { DynamoDBClient } from "@aws-sdk/client-dynamodb"; import { DynamoDBDocumentClient } from "@aws-sdk/lib-dynamodb"; export const docClient = DynamoDBDocumentClient.from(new DynamoDBClient({}));
This code is available here on GitHub
In the libs
directory create a Node.js module with the file name ddbClient.js
. Copy and paste the code below into it,
which creates the DynamoDB client object. Replace REGION
with your AWS region.
import { DynamoDBClient } from "@aws-sdk/client-dynamodb"; export const client = new DynamoDBClient({ region: "us-east-1" })
This code is available here on GitHub
Create a Node.js module with the file name ddbdoc_put_item.js
. Be sure to
configure the SDK as previously shown, including installing the required clients
and packages. This includes the @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 ddbdoc_put_item.js // To use JavaScript, enter 'node ddbdoc_put_item.js'
This example code can be found here on GitHub
Updating an Item in a Table
Create a libs
directory, and create a Node.js module with the file name ddbDocClient.js
. Copy and paste the code below into it,
which creates the DynamoDB document client object. Replace REGION
with your AWS region.
import { DynamoDBClient } from "@aws-sdk/client-dynamodb"; import { DynamoDBDocumentClient } from "@aws-sdk/lib-dynamodb"; export const docClient = DynamoDBDocumentClient.from(new DynamoDBClient({}));
This code is available here on GitHub
In the libs
directory create a Node.js module with the file name ddbClient.js
. Copy and paste the code below into it,
which creates the DynamoDB client object. Replace REGION
with your AWS region.
import { DynamoDBClient } from "@aws-sdk/client-dynamodb"; export const client = new DynamoDBClient({ region: "us-east-1" })
This code is available here on GitHub
Create a Node.js module with the file name ddbdoc_update_item.js
. Be sure
to configure the SDK as previously shown, including installing the required clients
and packages. This includes the @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 ddbdoc_update_item.js
This example code can be found here on GitHub
Querying a Table
Create a libs
directory, and create a Node.js module with the file name ddbDocClient.js
. Copy and paste the code below into it,
which creates the DynamoDB document client object. Replace REGION
with your AWS region.
import { DynamoDBClient } from "@aws-sdk/client-dynamodb"; import { DynamoDBDocumentClient } from "@aws-sdk/lib-dynamodb"; export const docClient = DynamoDBDocumentClient.from(new DynamoDBClient({}));
This code is available here on GitHub
In the libs
directory create a Node.js module with the file name ddbClient.js
. Copy and paste the code below into it,
which creates the DynamoDB client object. Replace REGION
with your AWS region.
import { DynamoDBClient } from "@aws-sdk/client-dynamodb"; export const client = new DynamoDBClient({ region: "us-east-1" })
This code is available here on GitHub
This example queries a table that contains episode information about a video series, returning the episode titles and subtitles of second season episodes past episode 9 that contain a specified phrase in their subtitle.
Create a Node.js module with the file name ddbdoc_query_item.js
. Be sure
to configure the SDK as previously shown, including installing the required clients
and packages. This includes the @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 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 ddbdoc_query_item.js
This example code can be found here on GitHub
Deleting an Item from a Table
Create a libs
directory, and create a Node.js module with the file name ddbDocClient.js
. Copy and paste the code below into it,
which creates the DynamoDB document client object. Replace REGION
with your AWS region.
import { DynamoDBClient } from "@aws-sdk/client-dynamodb"; import { DynamoDBDocumentClient } from "@aws-sdk/lib-dynamodb"; export const docClient = DynamoDBDocumentClient.from(new DynamoDBClient({}));
This code is available here on GitHub
In the libs
directory create a Node.js module with the file name ddbClient.js
. Copy and paste the code below into it,
which creates the DynamoDB client object. Replace REGION
with your AWS region.
import { DynamoDBClient } from "@aws-sdk/client-dynamodb"; export const client = new DynamoDBClient({ region: "us-east-1" })
This code is available here on GitHub
Create a Node.js module with the file name ddbdoc_delete_item.js
. Be sure
to configure the SDK as previously shown, including installing the required clients
and packages. This includes the @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 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 ddbdoc_delete_item.js
This example code can be found here on GitHub