dynamodb-example-document-client.md

Using the DynamoDB Document Client

This Node.js code example shows:

• How to access a DynamoDB table using the document client.

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, as well as converts annotated response data to native JavaScript types.

For more information on the DynamoDB Document Client class, see AWS.DynamoDB.DocumentClient in the API Reference. For more information on 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 the document client. The code uses the SDK for JavaScript to query and scan tables using these methods of the DynamoDB Document Client class:

• get

• put

• update

• query

• delete

Prerequisite Tasks

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

• Install Node.js. For more information, see the Node.js website.

• 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.

Configuring the SDK

Configure the SDK for JavaScript by creating a global configuration object then setting the region for your code. In this example, the region is set to us-west-2.

// Load the SDK for JavaScript
var AWS = require('aws-sdk');
// Set the region 
AWS.config.update({region: 'us-west-2'});

Getting an Item from a Table

Create a Node.js module with the file name ddbdoc_get.js. Be sure to configure the SDK as previously shown. To access DynamoDB, create an AWS.DynamoDB.DocumentClient object. 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 get method of the DynamoDB document client.

// Load the AWS SDK for Node.js
var AWS = require('aws-sdk');
// Set the region 
AWS.config.update({region: 'REGION'});

// Create DynamoDB document client
var docClient = new AWS.DynamoDB.DocumentClient({apiVersion: '2012-08-10'});

var params = {
 TableName: 'EPISODES_TABLE',
 Key: {'KEY_NAME': VALUE}
};

docClient.get(params, function(err, data) {
  if (err) {
    console.log("Error", err);
  } else {
    console.log("Success", data.Item);
  }
});

To run the example, type the following at the command line.

node ddbdoc_get.js

This sample code can be found here on GitHub.

Putting an Item in a Table

Create a Node.js module with the file name ddbdoc_put.js. Be sure to configure the SDK as previously shown. To access DynamoDB, create an AWS.DynamoDB.DocumentClient object. 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 as well as names and values for attributes to set on the item. Call the put method of the DynamoDB document client.

// Load the AWS SDK for Node.js
var AWS = require('aws-sdk');
// Set the region 
AWS.config.update({region: 'REGION'});

// Create DynamoDB document client
var docClient = new AWS.DynamoDB.DocumentClient({apiVersion: '2012-08-10'});

var params = {
  TableName: 'TABLE',
  Item: {
    'HASHKEY': VALUE,
    'ATTRIBUTE_1': 'STRING_VALUE',
    'ATTRIBUTE_2': VALUE_2
  }
};

docClient.put(params, function(err, data) {
  if (err) {
    console.log("Error", err);
  } else {
    console.log("Success", data);
  }
});

To run the example, type the following at the command line.

node ddbdoc_put.js

This sample code can be found here on GitHub.

Updating an Item in a Table

Create a Node.js module with the file name ddbdoc_update.js. Be sure to configure the SDK as previously shown. To access DynamoDB, create an AWS.DynamoDB.DocumentClient object. 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 update method of the DynamoDB document client.

// Load the AWS SDK for Node.js
var AWS = require('aws-sdk');
// Set the region
AWS.config.update({region: 'REGION'});

// Create DynamoDB document client
var docClient = new AWS.DynamoDB.DocumentClient({apiVersion: '2012-08-10'});

// Create variables to hold numeric key values
var season = SEASON_NUMBER;
var episode = EPISODES_NUMBER;

var params = {
  TableName: 'EPISODES_TABLE',
  Key: {
    'Season' : season,
    'Episode' : episode
  },
  UpdateExpression: 'set Title = :t, Subtitle = :s',
  ExpressionAttributeValues: {
    ':t' : 'NEW_TITLE',
    ':s' : 'NEW_SUBTITLE'
  }
};

docClient.update(params, function(err, data) {
  if (err) {
    console.log("Error", err);
  } else {
    console.log("Success", data);
  }
});

To run the example, type the following at the command line.

node ddbdoc_update.js

This sample code can be found here on GitHub.

Querying a Table

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.js. Be sure to configure the SDK as previously shown. To access DynamoDB, create an AWS.DynamoDB.DocumentClient object. 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 query method of the DynamoDB document client.

// Load the AWS SDK for Node.js
var AWS = require('aws-sdk');
// Set the region 
AWS.config.update({region: 'REGION'});

// Create DynamoDB document client
var docClient = new AWS.DynamoDB.DocumentClient({apiVersion: '2012-08-10'});

var params = {
  ExpressionAttributeValues: {
    ':s': 2,
    ':e': 9,
    ':topic': 'PHRASE'
   },
 KeyConditionExpression: 'Season = :s and Episode > :e',
 FilterExpression: 'contains (Subtitle, :topic)',
 TableName: 'EPISODES_TABLE'
};

docClient.query(params, function(err, data) {
  if (err) {
    console.log("Error", err);
  } else {
    console.log("Success", data.Items);
  }
});

To run the example, type the following at the command line.

node ddbdoc_query.js

This sample code can be found here on GitHub.

Deleting an Item from a Table

Create a Node.js module with the file name ddbdoc_delete.js. Be sure to configure the SDK as previously shown. To access DynamoDB, create an AWS.DynamoDB.DocumentClient 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 as well as a the name and value of the hashkey of the item you want to delete. Call the delete method of the DynamoDB document client.

// Load the AWS SDK for Node.js
var AWS = require('aws-sdk');
// Set the region 
AWS.config.update({region: 'REGION'});

// Create DynamoDB document client
var docClient = new AWS.DynamoDB.DocumentClient({apiVersion: '2012-08-10'});

var params = {
  Key: {
    'HASH_KEY': VALUE
  },
  TableName: 'TABLE'
};

docClient.delete(params, function(err, data) {
  if (err) {
    console.log("Error", err);
  } else {
    console.log("Success", data);
  }
});

To run the example, type the following at the command line.

node ddbdoc_delete.js

This sample code can be found here on GitHub.