We announced the upcoming end-of-support for AWS SDK for JavaScript v2.
We recommend that you migrate to AWS SDK for JavaScript v3. For dates, additional details, and information on how to migrate, please refer to the linked announcement.

Class: AWS.DynamoDB.DocumentClient

Inherits:
Object
  • Object
show all
Defined in:
lib/dynamodb/document_client.js

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 N
Boolean BOOL
null NULL
Array L
Object M
Buffer, File, Blob, ArrayBuffer, DataView, and JavaScript typed arrays B

Support for Sets

The DocumentClient offers a convenient way to create sets from JavaScript Arrays. The type of set is inferred from the first element in the array. DynamoDB supports string, number, and binary sets. To learn more about supported types see the Amazon DynamoDB Data Model Documentation For more information see createSet()

Constructor Summary collapse

Method Summary collapse

Constructor Details

new AWS.DynamoDB.DocumentClient(options) ⇒ void

Creates a DynamoDB document client with a set of configuration options.

Options Hash (options):

  • params (map) —

    An optional map of parameters to bind to every request sent by this service object.

  • service (AWS.DynamoDB) —

    An optional pre-configured instance of the AWS.DynamoDB service object. This instance's config will be copied to a new instance used by this client. You should not need to retain a reference to the input object, and may destroy it or allow it to be garbage collected.

  • convertEmptyValues (Boolean) —

    set to true if you would like the document client to convert empty values (0-length strings, binary buffers, and sets) to be converted to NULL types when persisting to DynamoDB.

  • wrapNumbers (Boolean) —

    Set to true to return numbers as a NumberValue object instead of converting them to native JavaScript numbers. This allows for the safe round-trip transport of numbers of arbitrary size.

See Also:

Method Details

batchGet(params, callback) ⇒ AWS.Request

Returns the attributes of one or more items from one or more tables by delegating to AWS.DynamoDB.batchGetItem().

Supply the same parameters as AWS.DynamoDB.batchGetItem() with AttributeValues substituted by native JavaScript types.

Service Reference:

Examples:

Get items from multiple tables

var params = {
  RequestItems: {
    'Table-1': {
      Keys: [
        {
           HashKey: 'haskey',
           NumberRangeKey: 1
        }
      ]
    },
    'Table-2': {
      Keys: [
        { foo: 'bar' },
      ]
    }
  }
};

var documentClient = new AWS.DynamoDB.DocumentClient();

documentClient.batchGet(params, function(err, data) {
  if (err) console.log(err);
  else console.log(data);
});

Calling the batchGet operation

var params = {
  RequestItems: { /* required */
    '<TableArn>': {
      Keys: [ /* required */
        {
          '<AttributeName>': someValue /* "str" | 10 | true | false | null | [1, "a"] | {a: "b"} */,
          /* '<AttributeName>': ... */
        },
        /* more items */
      ],
      AttributesToGet: [
        'STRING_VALUE',
        /* more items */
      ],
      ConsistentRead: true || false,
      ExpressionAttributeNames: {
        '<ExpressionAttributeNameVariable>': 'STRING_VALUE',
        /* '<ExpressionAttributeNameVariable>': ... */
      },
      ProjectionExpression: 'STRING_VALUE'
    },
    /* '<TableArn>': ... */
  },
  ReturnConsumedCapacity: INDEXES | TOTAL | NONE
};
documentclient.batchGet(params, function(err, data) {
  if (err) console.log(err, err.stack); // an error occurred
  else     console.log(data);           // successful response
});

Parameters:

  • params (Object) —
    • RequestItems — (map<map>)
      • Keys — required — (Array<map<map>>) — a serializable JavaScript object. For information about the supported types see the DynamoDB Data Model
      • AttributesToGet — (Array<String>)
      • ConsistentRead — (Boolean)
      • ProjectionExpression — (String)
      • ExpressionAttributeNames — (map<String>)
    • ReturnConsumedCapacity — (String) Possible values include:
      • "INDEXES"
      • "TOTAL"
      • "NONE"

Callback (callback):

  • function(err, data) { ... }

    Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.

    Context (this):

    • (AWS.Response) —

      the response object containing error, data properties, and the original request object.

    Parameters:

    • err (Error) —

      the error object returned from the request. Set to null if the request is successful.

    • data (Object) —

      the de-serialized data returned from the request. Set to null if a request error occurs. The data object has the following properties:

      • Responses — (map<Array<map<map>>>) — a serializable JavaScript object. For information about the supported types see the DynamoDB Data Model
      • UnprocessedKeys — (map<map>)
        • Keys — required — (Array<map<map>>) — a serializable JavaScript object. For information about the supported types see the DynamoDB Data Model
        • AttributesToGet — (Array<String>)
        • ConsistentRead — (Boolean)
        • ProjectionExpression — (String)
        • ExpressionAttributeNames — (map<String>)
      • ConsumedCapacity — (Array<map>)
        • TableName — (String)
        • CapacityUnits — (Float)
        • ReadCapacityUnits — (Float)
        • WriteCapacityUnits — (Float)
        • Table — (map)
          • ReadCapacityUnits — (Float)
          • WriteCapacityUnits — (Float)
          • CapacityUnits — (Float)
        • LocalSecondaryIndexes — (map<map>)
          • ReadCapacityUnits — (Float)
          • WriteCapacityUnits — (Float)
          • CapacityUnits — (Float)
        • GlobalSecondaryIndexes — (map<map>)
          • ReadCapacityUnits — (Float)
          • WriteCapacityUnits — (Float)
          • CapacityUnits — (Float)

Returns:

  • (AWS.Request) —

    a handle to the operation request for subsequent event callback registration.

See Also:

batchWrite(params, callback) ⇒ AWS.Request

Puts or deletes multiple items in one or more tables by delegating to AWS.DynamoDB.batchWriteItem().

Supply the same parameters as AWS.DynamoDB.batchWriteItem() with AttributeValues substituted by native JavaScript types.

Service Reference:

Examples:

Write to and delete from a table

var params = {
  RequestItems: {
    'Table-1': [
      {
        DeleteRequest: {
          Key: { HashKey: 'someKey' }
        }
      },
      {
        PutRequest: {
          Item: {
            HashKey: 'anotherKey',
            NumAttribute: 1,
            BoolAttribute: true,
            ListAttribute: [1, 'two', false],
            MapAttribute: { foo: 'bar' }
          }
        }
      }
    ]
  }
};

var documentClient = new AWS.DynamoDB.DocumentClient();

documentClient.batchWrite(params, function(err, data) {
  if (err) console.log(err);
  else console.log(data);
});

Calling the batchWrite operation

var params = {
  RequestItems: { /* required */
    '<TableArn>': [
      {
        DeleteRequest: {
          Key: { /* required */
            '<AttributeName>': someValue /* "str" | 10 | true | false | null | [1, "a"] | {a: "b"} */,
            /* '<AttributeName>': ... */
          }
        },
        PutRequest: {
          Item: { /* required */
            '<AttributeName>': someValue /* "str" | 10 | true | false | null | [1, "a"] | {a: "b"} */,
            /* '<AttributeName>': ... */
          }
        }
      },
      /* more items */
    ],
    /* '<TableArn>': ... */
  },
  ReturnConsumedCapacity: INDEXES | TOTAL | NONE,
  ReturnItemCollectionMetrics: SIZE | NONE
};
documentclient.batchWrite(params, function(err, data) {
  if (err) console.log(err, err.stack); // an error occurred
  else     console.log(data);           // successful response
});

Parameters:

  • params (Object) —
    • RequestItems — (map<Array<map>>)
      • PutRequest — (map)
        • Item — required — (map<map>) — a serializable JavaScript object. For information about the supported types see the DynamoDB Data Model
      • DeleteRequest — (map)
        • Key — required — (map<map>) — a serializable JavaScript object. For information about the supported types see the DynamoDB Data Model
    • ReturnConsumedCapacity — (String) Possible values include:
      • "INDEXES"
      • "TOTAL"
      • "NONE"
    • ReturnItemCollectionMetrics — (String) Possible values include:
      • "SIZE"
      • "NONE"

Callback (callback):

  • function(err, data) { ... }

    Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.

    Context (this):

    • (AWS.Response) —

      the response object containing error, data properties, and the original request object.

    Parameters:

    • err (Error) —

      the error object returned from the request. Set to null if the request is successful.

    • data (Object) —

      the de-serialized data returned from the request. Set to null if a request error occurs. The data object has the following properties:

      • UnprocessedItems — (map<Array<map>>)
        • PutRequest — (map)
          • Item — required — (map<map>) — a serializable JavaScript object. For information about the supported types see the DynamoDB Data Model
        • DeleteRequest — (map)
          • Key — required — (map<map>) — a serializable JavaScript object. For information about the supported types see the DynamoDB Data Model
      • ItemCollectionMetrics — (map<Array<map>>)
        • ItemCollectionKey — (map<map>) — a serializable JavaScript object. For information about the supported types see the DynamoDB Data Model
        • SizeEstimateRangeGB — (Array<Float>)
      • ConsumedCapacity — (Array<map>)
        • TableName — (String)
        • CapacityUnits — (Float)
        • ReadCapacityUnits — (Float)
        • WriteCapacityUnits — (Float)
        • Table — (map)
          • ReadCapacityUnits — (Float)
          • WriteCapacityUnits — (Float)
          • CapacityUnits — (Float)
        • LocalSecondaryIndexes — (map<map>)
          • ReadCapacityUnits — (Float)
          • WriteCapacityUnits — (Float)
          • CapacityUnits — (Float)
        • GlobalSecondaryIndexes — (map<map>)
          • ReadCapacityUnits — (Float)
          • WriteCapacityUnits — (Float)
          • CapacityUnits — (Float)

Returns:

  • (AWS.Request) —

    a handle to the operation request for subsequent event callback registration.

See Also:

createSet(list, options) ⇒ void

Creates a set of elements inferring the type of set from the type of the first element. Amazon DynamoDB currently supports the number sets, string sets, and binary sets. For more information about DynamoDB data types see the documentation on the Amazon DynamoDB Data Model.

Examples:

Creating a number set

var documentClient = new AWS.DynamoDB.DocumentClient();

var params = {
  Item: {
    hashkey: 'hashkey'
    numbers: documentClient.createSet([1, 2, 3]);
  }
};

documentClient.put(params, function(err, data) {
  if (err) console.log(err);
  else console.log(data);
});

Parameters:

  • list (Array) —

    Collection to represent your DynamoDB Set

  • options (map) —
    • validate [Boolean] set to true if you want to validate the type of each element in the set. Defaults to false.

delete(params, callback) ⇒ AWS.Request

Deletes a single item in a table by primary key by delegating to AWS.DynamoDB.deleteItem()

Supply the same parameters as AWS.DynamoDB.deleteItem() with AttributeValues substituted by native JavaScript types.

Service Reference:

Examples:

Delete an item from a table

var params = {
  TableName : 'Table',
  Key: {
    HashKey: 'hashkey',
    NumberRangeKey: 1
  }
};

var documentClient = new AWS.DynamoDB.DocumentClient();

documentClient.delete(params, function(err, data) {
  if (err) console.log(err);
  else console.log(data);
});

Calling the delete operation

var params = {
  Key: { /* required */
    '<AttributeName>': someValue /* "str" | 10 | true | false | null | [1, "a"] | {a: "b"} */,
    /* '<AttributeName>': ... */
  },
  TableName: 'STRING_VALUE', /* required */
  ConditionExpression: 'STRING_VALUE',
  ConditionalOperator: AND | OR,
  Expected: {
    '<AttributeName>': {
      AttributeValueList: [
        someValue /* "str" | 10 | true | false | null | [1, "a"] | {a: "b"} */,
        /* more items */
      ],
      ComparisonOperator: EQ | NE | IN | LE | LT | GE | GT | BETWEEN | NOT_NULL | NULL | CONTAINS | NOT_CONTAINS | BEGINS_WITH,
      Exists: true || false,
      Value: someValue /* "str" | 10 | true | false | null | [1, "a"] | {a: "b"} */
    },
    /* '<AttributeName>': ... */
  },
  ExpressionAttributeNames: {
    '<ExpressionAttributeNameVariable>': 'STRING_VALUE',
    /* '<ExpressionAttributeNameVariable>': ... */
  },
  ExpressionAttributeValues: {
    '<ExpressionAttributeValueVariable>': someValue /* "str" | 10 | true | false | null | [1, "a"] | {a: "b"} */,
    /* '<ExpressionAttributeValueVariable>': ... */
  },
  ReturnConsumedCapacity: INDEXES | TOTAL | NONE,
  ReturnItemCollectionMetrics: SIZE | NONE,
  ReturnValues: NONE | ALL_OLD | UPDATED_OLD | ALL_NEW | UPDATED_NEW,
  ReturnValuesOnConditionCheckFailure: ALL_OLD | NONE
};
documentclient.delete(params, function(err, data) {
  if (err) console.log(err, err.stack); // an error occurred
  else     console.log(data);           // successful response
});

Parameters:

  • params (Object) —
    • TableName — (String)
    • Key — (map<map>) — a serializable JavaScript object. For information about the supported types see the DynamoDB Data Model
    • Expected — (map<map>)
      • Value — a serializable JavaScript object. For information about the supported types see the DynamoDB Data Model
      • Exists — (Boolean)
      • ComparisonOperator — (String) Possible values include:
        • "EQ"
        • "NE"
        • "IN"
        • "LE"
        • "LT"
        • "GE"
        • "GT"
        • "BETWEEN"
        • "NOT_NULL"
        • "NULL"
        • "CONTAINS"
        • "NOT_CONTAINS"
        • "BEGINS_WITH"
      • AttributeValueList — (Array<map>) — a serializable JavaScript object. For information about the supported types see the DynamoDB Data Model
    • ConditionalOperator — (String) Possible values include:
      • "AND"
      • "OR"
    • ReturnValues — (String) Possible values include:
      • "NONE"
      • "ALL_OLD"
      • "UPDATED_OLD"
      • "ALL_NEW"
      • "UPDATED_NEW"
    • ReturnConsumedCapacity — (String) Possible values include:
      • "INDEXES"
      • "TOTAL"
      • "NONE"
    • ReturnItemCollectionMetrics — (String) Possible values include:
      • "SIZE"
      • "NONE"
    • ConditionExpression — (String)
    • ExpressionAttributeNames — (map<String>)
    • ExpressionAttributeValues — (map<map>) — a serializable JavaScript object. For information about the supported types see the DynamoDB Data Model
    • ReturnValuesOnConditionCheckFailure — (String) Possible values include:
      • "ALL_OLD"
      • "NONE"

Callback (callback):

  • function(err, data) { ... }

    Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.

    Context (this):

    • (AWS.Response) —

      the response object containing error, data properties, and the original request object.

    Parameters:

    • err (Error) —

      the error object returned from the request. Set to null if the request is successful.

    • data (Object) —

      the de-serialized data returned from the request. Set to null if a request error occurs. The data object has the following properties:

      • Attributes — (map<map>) — a serializable JavaScript object. For information about the supported types see the DynamoDB Data Model
      • ConsumedCapacity — (map)
        • TableName — (String)
        • CapacityUnits — (Float)
        • ReadCapacityUnits — (Float)
        • WriteCapacityUnits — (Float)
        • Table — (map)
          • ReadCapacityUnits — (Float)
          • WriteCapacityUnits — (Float)
          • CapacityUnits — (Float)
        • LocalSecondaryIndexes — (map<map>)
          • ReadCapacityUnits — (Float)
          • WriteCapacityUnits — (Float)
          • CapacityUnits — (Float)
        • GlobalSecondaryIndexes — (map<map>)
          • ReadCapacityUnits — (Float)
          • WriteCapacityUnits — (Float)
          • CapacityUnits — (Float)
      • ItemCollectionMetrics — (map)
        • ItemCollectionKey — (map<map>) — a serializable JavaScript object. For information about the supported types see the DynamoDB Data Model
        • SizeEstimateRangeGB — (Array<Float>)

Returns:

  • (AWS.Request) —

    a handle to the operation request for subsequent event callback registration.

See Also:

get(params, callback) ⇒ AWS.Request

Returns a set of attributes for the item with the given primary key by delegating to AWS.DynamoDB.getItem().

Supply the same parameters as AWS.DynamoDB.getItem() with AttributeValues substituted by native JavaScript types.

Service Reference:

Examples:

Get an item from a table

var params = {
  TableName : 'Table',
  Key: {
    HashKey: 'hashkey'
  }
};

var documentClient = new AWS.DynamoDB.DocumentClient();

documentClient.get(params, function(err, data) {
  if (err) console.log(err);
  else console.log(data);
});

Calling the get operation

var params = {
  Key: { /* required */
    '<AttributeName>': someValue /* "str" | 10 | true | false | null | [1, "a"] | {a: "b"} */,
    /* '<AttributeName>': ... */
  },
  TableName: 'STRING_VALUE', /* required */
  AttributesToGet: [
    'STRING_VALUE',
    /* more items */
  ],
  ConsistentRead: true || false,
  ExpressionAttributeNames: {
    '<ExpressionAttributeNameVariable>': 'STRING_VALUE',
    /* '<ExpressionAttributeNameVariable>': ... */
  },
  ProjectionExpression: 'STRING_VALUE',
  ReturnConsumedCapacity: INDEXES | TOTAL | NONE
};
documentclient.get(params, function(err, data) {
  if (err) console.log(err, err.stack); // an error occurred
  else     console.log(data);           // successful response
});

Parameters:

  • params (Object) —
    • TableName — (String)
    • Key — (map<map>) — a serializable JavaScript object. For information about the supported types see the DynamoDB Data Model
    • AttributesToGet — (Array<String>)
    • ConsistentRead — (Boolean)
    • ReturnConsumedCapacity — (String) Possible values include:
      • "INDEXES"
      • "TOTAL"
      • "NONE"
    • ProjectionExpression — (String)
    • ExpressionAttributeNames — (map<String>)

Callback (callback):

  • function(err, data) { ... }

    Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.

    Context (this):

    • (AWS.Response) —

      the response object containing error, data properties, and the original request object.

    Parameters:

    • err (Error) —

      the error object returned from the request. Set to null if the request is successful.

    • data (Object) —

      the de-serialized data returned from the request. Set to null if a request error occurs. The data object has the following properties:

      • Item — (map<map>) — a serializable JavaScript object. For information about the supported types see the DynamoDB Data Model
      • ConsumedCapacity — (map)
        • TableName — (String)
        • CapacityUnits — (Float)
        • ReadCapacityUnits — (Float)
        • WriteCapacityUnits — (Float)
        • Table — (map)
          • ReadCapacityUnits — (Float)
          • WriteCapacityUnits — (Float)
          • CapacityUnits — (Float)
        • LocalSecondaryIndexes — (map<map>)
          • ReadCapacityUnits — (Float)
          • WriteCapacityUnits — (Float)
          • CapacityUnits — (Float)
        • GlobalSecondaryIndexes — (map<map>)
          • ReadCapacityUnits — (Float)
          • WriteCapacityUnits — (Float)
          • CapacityUnits — (Float)

Returns:

  • (AWS.Request) —

    a handle to the operation request for subsequent event callback registration.

See Also:

put(params, callback) ⇒ AWS.Request

Creates a new item, or replaces an old item with a new item by delegating to AWS.DynamoDB.putItem().

Supply the same parameters as AWS.DynamoDB.putItem() with AttributeValues substituted by native JavaScript types.

Service Reference:

Examples:

Create a new item in a table

var params = {
  TableName : 'Table',
  Item: {
     HashKey: 'haskey',
     NumAttribute: 1,
     BoolAttribute: true,
     ListAttribute: [1, 'two', false],
     MapAttribute: { foo: 'bar'},
     NullAttribute: null
  }
};

var documentClient = new AWS.DynamoDB.DocumentClient();

documentClient.put(params, function(err, data) {
  if (err) console.log(err);
  else console.log(data);
});

Calling the put operation

var params = {
  Item: { /* required */
    '<AttributeName>': someValue /* "str" | 10 | true | false | null | [1, "a"] | {a: "b"} */,
    /* '<AttributeName>': ... */
  },
  TableName: 'STRING_VALUE', /* required */
  ConditionExpression: 'STRING_VALUE',
  ConditionalOperator: AND | OR,
  Expected: {
    '<AttributeName>': {
      AttributeValueList: [
        someValue /* "str" | 10 | true | false | null | [1, "a"] | {a: "b"} */,
        /* more items */
      ],
      ComparisonOperator: EQ | NE | IN | LE | LT | GE | GT | BETWEEN | NOT_NULL | NULL | CONTAINS | NOT_CONTAINS | BEGINS_WITH,
      Exists: true || false,
      Value: someValue /* "str" | 10 | true | false | null | [1, "a"] | {a: "b"} */
    },
    /* '<AttributeName>': ... */
  },
  ExpressionAttributeNames: {
    '<ExpressionAttributeNameVariable>': 'STRING_VALUE',
    /* '<ExpressionAttributeNameVariable>': ... */
  },
  ExpressionAttributeValues: {
    '<ExpressionAttributeValueVariable>': someValue /* "str" | 10 | true | false | null | [1, "a"] | {a: "b"} */,
    /* '<ExpressionAttributeValueVariable>': ... */
  },
  ReturnConsumedCapacity: INDEXES | TOTAL | NONE,
  ReturnItemCollectionMetrics: SIZE | NONE,
  ReturnValues: NONE | ALL_OLD | UPDATED_OLD | ALL_NEW | UPDATED_NEW,
  ReturnValuesOnConditionCheckFailure: ALL_OLD | NONE
};
documentclient.put(params, function(err, data) {
  if (err) console.log(err, err.stack); // an error occurred
  else     console.log(data);           // successful response
});

Parameters:

  • params (Object) —
    • TableName — (String)
    • Item — (map<map>) — a serializable JavaScript object. For information about the supported types see the DynamoDB Data Model
    • Expected — (map<map>)
      • Value — a serializable JavaScript object. For information about the supported types see the DynamoDB Data Model
      • Exists — (Boolean)
      • ComparisonOperator — (String) Possible values include:
        • "EQ"
        • "NE"
        • "IN"
        • "LE"
        • "LT"
        • "GE"
        • "GT"
        • "BETWEEN"
        • "NOT_NULL"
        • "NULL"
        • "CONTAINS"
        • "NOT_CONTAINS"
        • "BEGINS_WITH"
      • AttributeValueList — (Array<map>) — a serializable JavaScript object. For information about the supported types see the DynamoDB Data Model
    • ReturnValues — (String) Possible values include:
      • "NONE"
      • "ALL_OLD"
      • "UPDATED_OLD"
      • "ALL_NEW"
      • "UPDATED_NEW"
    • ReturnConsumedCapacity — (String) Possible values include:
      • "INDEXES"
      • "TOTAL"
      • "NONE"
    • ReturnItemCollectionMetrics — (String) Possible values include:
      • "SIZE"
      • "NONE"
    • ConditionalOperator — (String) Possible values include:
      • "AND"
      • "OR"
    • ConditionExpression — (String)
    • ExpressionAttributeNames — (map<String>)
    • ExpressionAttributeValues — (map<map>) — a serializable JavaScript object. For information about the supported types see the DynamoDB Data Model
    • ReturnValuesOnConditionCheckFailure — (String) Possible values include:
      • "ALL_OLD"
      • "NONE"

Callback (callback):

  • function(err, data) { ... }

    Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.

    Context (this):

    • (AWS.Response) —

      the response object containing error, data properties, and the original request object.

    Parameters:

    • err (Error) —

      the error object returned from the request. Set to null if the request is successful.

    • data (Object) —

      the de-serialized data returned from the request. Set to null if a request error occurs. The data object has the following properties:

      • Attributes — (map<map>) — a serializable JavaScript object. For information about the supported types see the DynamoDB Data Model
      • ConsumedCapacity — (map)
        • TableName — (String)
        • CapacityUnits — (Float)
        • ReadCapacityUnits — (Float)
        • WriteCapacityUnits — (Float)
        • Table — (map)
          • ReadCapacityUnits — (Float)
          • WriteCapacityUnits — (Float)
          • CapacityUnits — (Float)
        • LocalSecondaryIndexes — (map<map>)
          • ReadCapacityUnits — (Float)
          • WriteCapacityUnits — (Float)
          • CapacityUnits — (Float)
        • GlobalSecondaryIndexes — (map<map>)
          • ReadCapacityUnits — (Float)
          • WriteCapacityUnits — (Float)
          • CapacityUnits — (Float)
      • ItemCollectionMetrics — (map)
        • ItemCollectionKey — (map<map>) — a serializable JavaScript object. For information about the supported types see the DynamoDB Data Model
        • SizeEstimateRangeGB — (Array<Float>)

Returns:

  • (AWS.Request) —

    a handle to the operation request for subsequent event callback registration.

See Also:

query(params, callback) ⇒ AWS.Request

Directly access items from a table by primary key or a secondary index.

Supply the same parameters as AWS.DynamoDB.query() with AttributeValues substituted by native JavaScript types.

Service Reference:

Examples:

Query an index

var params = {
  TableName: 'Table',
  IndexName: 'Index',
  KeyConditionExpression: 'HashKey = :hkey and RangeKey > :rkey',
  ExpressionAttributeValues: {
    ':hkey': 'key',
    ':rkey': 2015
  }
};

var documentClient = new AWS.DynamoDB.DocumentClient();

documentClient.query(params, function(err, data) {
   if (err) console.log(err);
   else console.log(data);
});

Calling the query operation

var params = {
  TableName: 'STRING_VALUE', /* required */
  AttributesToGet: [
    'STRING_VALUE',
    /* more items */
  ],
  ConditionalOperator: AND | OR,
  ConsistentRead: true || false,
  ExclusiveStartKey: {
    '<AttributeName>': someValue /* "str" | 10 | true | false | null | [1, "a"] | {a: "b"} */,
    /* '<AttributeName>': ... */
  },
  ExpressionAttributeNames: {
    '<ExpressionAttributeNameVariable>': 'STRING_VALUE',
    /* '<ExpressionAttributeNameVariable>': ... */
  },
  ExpressionAttributeValues: {
    '<ExpressionAttributeValueVariable>': someValue /* "str" | 10 | true | false | null | [1, "a"] | {a: "b"} */,
    /* '<ExpressionAttributeValueVariable>': ... */
  },
  FilterExpression: 'STRING_VALUE',
  IndexName: 'STRING_VALUE',
  KeyConditionExpression: 'STRING_VALUE',
  KeyConditions: {
    '<AttributeName>': {
      ComparisonOperator: EQ | NE | IN | LE | LT | GE | GT | BETWEEN | NOT_NULL | NULL | CONTAINS | NOT_CONTAINS | BEGINS_WITH, /* required */
      AttributeValueList: [
        someValue /* "str" | 10 | true | false | null | [1, "a"] | {a: "b"} */,
        /* more items */
      ]
    },
    /* '<AttributeName>': ... */
  },
  Limit: 'NUMBER_VALUE',
  ProjectionExpression: 'STRING_VALUE',
  QueryFilter: {
    '<AttributeName>': {
      ComparisonOperator: EQ | NE | IN | LE | LT | GE | GT | BETWEEN | NOT_NULL | NULL | CONTAINS | NOT_CONTAINS | BEGINS_WITH, /* required */
      AttributeValueList: [
        someValue /* "str" | 10 | true | false | null | [1, "a"] | {a: "b"} */,
        /* more items */
      ]
    },
    /* '<AttributeName>': ... */
  },
  ReturnConsumedCapacity: INDEXES | TOTAL | NONE,
  ScanIndexForward: true || false,
  Select: ALL_ATTRIBUTES | ALL_PROJECTED_ATTRIBUTES | SPECIFIC_ATTRIBUTES | COUNT
};
documentclient.query(params, function(err, data) {
  if (err) console.log(err, err.stack); // an error occurred
  else     console.log(data);           // successful response
});

Parameters:

  • params (Object) —
    • TableName — (String)
    • IndexName — (String)
    • Select — (String) Possible values include:
      • "ALL_ATTRIBUTES"
      • "ALL_PROJECTED_ATTRIBUTES"
      • "SPECIFIC_ATTRIBUTES"
      • "COUNT"
    • AttributesToGet — (Array<String>)
    • Limit — (Integer)
    • ConsistentRead — (Boolean)
    • KeyConditions — (map<map>)
      • AttributeValueList — (Array<map>) — a serializable JavaScript object. For information about the supported types see the DynamoDB Data Model
      • ComparisonOperator — required — (String) Possible values include:
        • "EQ"
        • "NE"
        • "IN"
        • "LE"
        • "LT"
        • "GE"
        • "GT"
        • "BETWEEN"
        • "NOT_NULL"
        • "NULL"
        • "CONTAINS"
        • "NOT_CONTAINS"
        • "BEGINS_WITH"
    • QueryFilter — (map<map>)
      • AttributeValueList — (Array<map>) — a serializable JavaScript object. For information about the supported types see the DynamoDB Data Model
      • ComparisonOperator — required — (String) Possible values include:
        • "EQ"
        • "NE"
        • "IN"
        • "LE"
        • "LT"
        • "GE"
        • "GT"
        • "BETWEEN"
        • "NOT_NULL"
        • "NULL"
        • "CONTAINS"
        • "NOT_CONTAINS"
        • "BEGINS_WITH"
    • ConditionalOperator — (String) Possible values include:
      • "AND"
      • "OR"
    • ScanIndexForward — (Boolean)
    • ExclusiveStartKey — (map<map>) — a serializable JavaScript object. For information about the supported types see the DynamoDB Data Model
    • ReturnConsumedCapacity — (String) Possible values include:
      • "INDEXES"
      • "TOTAL"
      • "NONE"
    • ProjectionExpression — (String)
    • FilterExpression — (String)
    • KeyConditionExpression — (String)
    • ExpressionAttributeNames — (map<String>)
    • ExpressionAttributeValues — (map<map>) — a serializable JavaScript object. For information about the supported types see the DynamoDB Data Model

Callback (callback):

  • function(err, data) { ... }

    Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.

    Context (this):

    • (AWS.Response) —

      the response object containing error, data properties, and the original request object.

    Parameters:

    • err (Error) —

      the error object returned from the request. Set to null if the request is successful.

    • data (Object) —

      the de-serialized data returned from the request. Set to null if a request error occurs. The data object has the following properties:

      • Items — (Array<map<map>>) — a serializable JavaScript object. For information about the supported types see the DynamoDB Data Model
      • Count — (Integer)
      • ScannedCount — (Integer)
      • LastEvaluatedKey — (map<map>) — a serializable JavaScript object. For information about the supported types see the DynamoDB Data Model
      • ConsumedCapacity — (map)
        • TableName — (String)
        • CapacityUnits — (Float)
        • ReadCapacityUnits — (Float)
        • WriteCapacityUnits — (Float)
        • Table — (map)
          • ReadCapacityUnits — (Float)
          • WriteCapacityUnits — (Float)
          • CapacityUnits — (Float)
        • LocalSecondaryIndexes — (map<map>)
          • ReadCapacityUnits — (Float)
          • WriteCapacityUnits — (Float)
          • CapacityUnits — (Float)
        • GlobalSecondaryIndexes — (map<map>)
          • ReadCapacityUnits — (Float)
          • WriteCapacityUnits — (Float)
          • CapacityUnits — (Float)

Returns:

  • (AWS.Request) —

    a handle to the operation request for subsequent event callback registration.

See Also:

scan(params, callback) ⇒ AWS.Request

Returns one or more items and item attributes by accessing every item in a table or a secondary index.

Supply the same parameters as AWS.DynamoDB.scan() with AttributeValues substituted by native JavaScript types.

Service Reference:

Examples:

Scan the table with a filter expression

var params = {
  TableName : 'Table',
  FilterExpression : 'Year = :this_year',
  ExpressionAttributeValues : {':this_year' : 2015}
};

var documentClient = new AWS.DynamoDB.DocumentClient();

documentClient.scan(params, function(err, data) {
   if (err) console.log(err);
   else console.log(data);
});

Calling the scan operation

var params = {
  TableName: 'STRING_VALUE', /* required */
  AttributesToGet: [
    'STRING_VALUE',
    /* more items */
  ],
  ConditionalOperator: AND | OR,
  ConsistentRead: true || false,
  ExclusiveStartKey: {
    '<AttributeName>': someValue /* "str" | 10 | true | false | null | [1, "a"] | {a: "b"} */,
    /* '<AttributeName>': ... */
  },
  ExpressionAttributeNames: {
    '<ExpressionAttributeNameVariable>': 'STRING_VALUE',
    /* '<ExpressionAttributeNameVariable>': ... */
  },
  ExpressionAttributeValues: {
    '<ExpressionAttributeValueVariable>': someValue /* "str" | 10 | true | false | null | [1, "a"] | {a: "b"} */,
    /* '<ExpressionAttributeValueVariable>': ... */
  },
  FilterExpression: 'STRING_VALUE',
  IndexName: 'STRING_VALUE',
  Limit: 'NUMBER_VALUE',
  ProjectionExpression: 'STRING_VALUE',
  ReturnConsumedCapacity: INDEXES | TOTAL | NONE,
  ScanFilter: {
    '<AttributeName>': {
      ComparisonOperator: EQ | NE | IN | LE | LT | GE | GT | BETWEEN | NOT_NULL | NULL | CONTAINS | NOT_CONTAINS | BEGINS_WITH, /* required */
      AttributeValueList: [
        someValue /* "str" | 10 | true | false | null | [1, "a"] | {a: "b"} */,
        /* more items */
      ]
    },
    /* '<AttributeName>': ... */
  },
  Segment: 'NUMBER_VALUE',
  Select: ALL_ATTRIBUTES | ALL_PROJECTED_ATTRIBUTES | SPECIFIC_ATTRIBUTES | COUNT,
  TotalSegments: 'NUMBER_VALUE'
};
documentclient.scan(params, function(err, data) {
  if (err) console.log(err, err.stack); // an error occurred
  else     console.log(data);           // successful response
});

Parameters:

  • params (Object) —
    • TableName — (String)
    • IndexName — (String)
    • AttributesToGet — (Array<String>)
    • Limit — (Integer)
    • Select — (String) Possible values include:
      • "ALL_ATTRIBUTES"
      • "ALL_PROJECTED_ATTRIBUTES"
      • "SPECIFIC_ATTRIBUTES"
      • "COUNT"
    • ScanFilter — (map<map>)
      • AttributeValueList — (Array<map>) — a serializable JavaScript object. For information about the supported types see the DynamoDB Data Model
      • ComparisonOperator — required — (String) Possible values include:
        • "EQ"
        • "NE"
        • "IN"
        • "LE"
        • "LT"
        • "GE"
        • "GT"
        • "BETWEEN"
        • "NOT_NULL"
        • "NULL"
        • "CONTAINS"
        • "NOT_CONTAINS"
        • "BEGINS_WITH"
    • ConditionalOperator — (String) Possible values include:
      • "AND"
      • "OR"
    • ExclusiveStartKey — (map<map>) — a serializable JavaScript object. For information about the supported types see the DynamoDB Data Model
    • ReturnConsumedCapacity — (String) Possible values include:
      • "INDEXES"
      • "TOTAL"
      • "NONE"
    • TotalSegments — (Integer)
    • Segment — (Integer)
    • ProjectionExpression — (String)
    • FilterExpression — (String)
    • ExpressionAttributeNames — (map<String>)
    • ExpressionAttributeValues — (map<map>) — a serializable JavaScript object. For information about the supported types see the DynamoDB Data Model
    • ConsistentRead — (Boolean)

Callback (callback):

  • function(err, data) { ... }

    Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.

    Context (this):

    • (AWS.Response) —

      the response object containing error, data properties, and the original request object.

    Parameters:

    • err (Error) —

      the error object returned from the request. Set to null if the request is successful.

    • data (Object) —

      the de-serialized data returned from the request. Set to null if a request error occurs. The data object has the following properties:

      • Items — (Array<map<map>>) — a serializable JavaScript object. For information about the supported types see the DynamoDB Data Model
      • Count — (Integer)
      • ScannedCount — (Integer)
      • LastEvaluatedKey — (map<map>) — a serializable JavaScript object. For information about the supported types see the DynamoDB Data Model
      • ConsumedCapacity — (map)
        • TableName — (String)
        • CapacityUnits — (Float)
        • ReadCapacityUnits — (Float)
        • WriteCapacityUnits — (Float)
        • Table — (map)
          • ReadCapacityUnits — (Float)
          • WriteCapacityUnits — (Float)
          • CapacityUnits — (Float)
        • LocalSecondaryIndexes — (map<map>)
          • ReadCapacityUnits — (Float)
          • WriteCapacityUnits — (Float)
          • CapacityUnits — (Float)
        • GlobalSecondaryIndexes — (map<map>)
          • ReadCapacityUnits — (Float)
          • WriteCapacityUnits — (Float)
          • CapacityUnits — (Float)

Returns:

  • (AWS.Request) —

    a handle to the operation request for subsequent event callback registration.

See Also:

transactGet(params, callback) ⇒ AWS.Request

Atomically retrieves multiple items from one or more tables (but not from indexes) in a single account and region.

Supply the same parameters as AWS.DynamoDB.transactGetItems() with AttributeValues substituted by native JavaScript types.

Service Reference:

Examples:

Get items from multiple tables

var params = {
  TransactItems: [{
    Get: {
      TableName : 'Table0',
      Key: {
        HashKey: 'hashkey0'
      }
    }
  }, {
    Get: {
      TableName : 'Table1',
      Key: {
        HashKey: 'hashkey1'
      }
    }
  }]
};

documentClient.transactGet(params, function(err, data) {
  if (err) console.log(err);
  else console.log(data);
});

Calling the transactGet operation

var params = {
  TransactItems: [ /* required */
    {
      Get: { /* required */
        Key: { /* required */
          '<AttributeName>': someValue /* "str" | 10 | true | false | null | [1, "a"] | {a: "b"} */,
          /* '<AttributeName>': ... */
        },
        TableName: 'STRING_VALUE', /* required */
        ExpressionAttributeNames: {
          '<ExpressionAttributeNameVariable>': 'STRING_VALUE',
          /* '<ExpressionAttributeNameVariable>': ... */
        },
        ProjectionExpression: 'STRING_VALUE'
      }
    },
    /* more items */
  ],
  ReturnConsumedCapacity: INDEXES | TOTAL | NONE
};
documentclient.transactGet(params, function(err, data) {
  if (err) console.log(err, err.stack); // an error occurred
  else     console.log(data);           // successful response
});

Parameters:

  • params (Object) —
    • TransactItems — (Array<map>)
      • Get — required — (map)
        • Key — required — (map<map>) — a serializable JavaScript object. For information about the supported types see the DynamoDB Data Model
        • TableName — required — (String)
        • ProjectionExpression — (String)
        • ExpressionAttributeNames — (map<String>)
    • ReturnConsumedCapacity — (String) Possible values include:
      • "INDEXES"
      • "TOTAL"
      • "NONE"

Callback (callback):

  • function(err, data) { ... }

    Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.

    Context (this):

    • (AWS.Response) —

      the response object containing error, data properties, and the original request object.

    Parameters:

    • err (Error) —

      the error object returned from the request. Set to null if the request is successful.

    • data (Object) —

      the de-serialized data returned from the request. Set to null if a request error occurs. The data object has the following properties:

      • ConsumedCapacity — (Array<map>)
        • TableName — (String)
        • CapacityUnits — (Float)
        • ReadCapacityUnits — (Float)
        • WriteCapacityUnits — (Float)
        • Table — (map)
          • ReadCapacityUnits — (Float)
          • WriteCapacityUnits — (Float)
          • CapacityUnits — (Float)
        • LocalSecondaryIndexes — (map<map>)
          • ReadCapacityUnits — (Float)
          • WriteCapacityUnits — (Float)
          • CapacityUnits — (Float)
        • GlobalSecondaryIndexes — (map<map>)
          • ReadCapacityUnits — (Float)
          • WriteCapacityUnits — (Float)
          • CapacityUnits — (Float)
      • Responses — (Array<map>)
        • Item — (map<map>) — a serializable JavaScript object. For information about the supported types see the DynamoDB Data Model

Returns:

  • (AWS.Request) —

    a handle to the operation request for subsequent event callback registration.

See Also:

transactWrite(params, callback) ⇒ AWS.Request

Synchronous write operation that groups up to 100 action requests.

Supply the same parameters as AWS.DynamoDB.transactWriteItems() with AttributeValues substituted by native JavaScript types.

Service Reference:

Examples:

Get items from multiple tables

var params = {
  TransactItems: [{
    Put: {
      TableName : 'Table0',
      Item: {
        HashKey: 'haskey',
        NumAttribute: 1,
        BoolAttribute: true,
        ListAttribute: [1, 'two', false],
        MapAttribute: { foo: 'bar'},
        NullAttribute: null
      }
    }
  }, {
    Update: {
      TableName: 'Table1',
      Key: { HashKey : 'hashkey' },
      UpdateExpression: 'set #a = :x + :y',
      ConditionExpression: '#a < :MAX',
      ExpressionAttributeNames: {'#a' : 'Sum'},
      ExpressionAttributeValues: {
        ':x' : 20,
        ':y' : 45,
        ':MAX' : 100,
      }
    }
  }]
};

documentClient.transactWrite(params, function(err, data) {
  if (err) console.log(err);
  else console.log(data);
});

Calling the transactWrite operation

var params = {
  TransactItems: [ /* required */
    {
      ConditionCheck: {
        ConditionExpression: 'STRING_VALUE', /* required */
        Key: { /* required */
          '<AttributeName>': someValue /* "str" | 10 | true | false | null | [1, "a"] | {a: "b"} */,
          /* '<AttributeName>': ... */
        },
        TableName: 'STRING_VALUE', /* required */
        ExpressionAttributeNames: {
          '<ExpressionAttributeNameVariable>': 'STRING_VALUE',
          /* '<ExpressionAttributeNameVariable>': ... */
        },
        ExpressionAttributeValues: {
          '<ExpressionAttributeValueVariable>': someValue /* "str" | 10 | true | false | null | [1, "a"] | {a: "b"} */,
          /* '<ExpressionAttributeValueVariable>': ... */
        },
        ReturnValuesOnConditionCheckFailure: ALL_OLD | NONE
      },
      Delete: {
        Key: { /* required */
          '<AttributeName>': someValue /* "str" | 10 | true | false | null | [1, "a"] | {a: "b"} */,
          /* '<AttributeName>': ... */
        },
        TableName: 'STRING_VALUE', /* required */
        ConditionExpression: 'STRING_VALUE',
        ExpressionAttributeNames: {
          '<ExpressionAttributeNameVariable>': 'STRING_VALUE',
          /* '<ExpressionAttributeNameVariable>': ... */
        },
        ExpressionAttributeValues: {
          '<ExpressionAttributeValueVariable>': someValue /* "str" | 10 | true | false | null | [1, "a"] | {a: "b"} */,
          /* '<ExpressionAttributeValueVariable>': ... */
        },
        ReturnValuesOnConditionCheckFailure: ALL_OLD | NONE
      },
      Put: {
        Item: { /* required */
          '<AttributeName>': someValue /* "str" | 10 | true | false | null | [1, "a"] | {a: "b"} */,
          /* '<AttributeName>': ... */
        },
        TableName: 'STRING_VALUE', /* required */
        ConditionExpression: 'STRING_VALUE',
        ExpressionAttributeNames: {
          '<ExpressionAttributeNameVariable>': 'STRING_VALUE',
          /* '<ExpressionAttributeNameVariable>': ... */
        },
        ExpressionAttributeValues: {
          '<ExpressionAttributeValueVariable>': someValue /* "str" | 10 | true | false | null | [1, "a"] | {a: "b"} */,
          /* '<ExpressionAttributeValueVariable>': ... */
        },
        ReturnValuesOnConditionCheckFailure: ALL_OLD | NONE
      },
      Update: {
        Key: { /* required */
          '<AttributeName>': someValue /* "str" | 10 | true | false | null | [1, "a"] | {a: "b"} */,
          /* '<AttributeName>': ... */
        },
        TableName: 'STRING_VALUE', /* required */
        UpdateExpression: 'STRING_VALUE', /* required */
        ConditionExpression: 'STRING_VALUE',
        ExpressionAttributeNames: {
          '<ExpressionAttributeNameVariable>': 'STRING_VALUE',
          /* '<ExpressionAttributeNameVariable>': ... */
        },
        ExpressionAttributeValues: {
          '<ExpressionAttributeValueVariable>': someValue /* "str" | 10 | true | false | null | [1, "a"] | {a: "b"} */,
          /* '<ExpressionAttributeValueVariable>': ... */
        },
        ReturnValuesOnConditionCheckFailure: ALL_OLD | NONE
      }
    },
    /* more items */
  ],
  ClientRequestToken: 'STRING_VALUE',
  ReturnConsumedCapacity: INDEXES | TOTAL | NONE,
  ReturnItemCollectionMetrics: SIZE | NONE
};
documentclient.transactWrite(params, function(err, data) {
  if (err) console.log(err, err.stack); // an error occurred
  else     console.log(data);           // successful response
});

Parameters:

  • params (Object) —
    • TransactItems — (Array<map>)
      • ConditionCheck — (map)
        • Key — required — (map<map>) — a serializable JavaScript object. For information about the supported types see the DynamoDB Data Model
        • TableName — required — (String)
        • ConditionExpression — required — (String)
        • ExpressionAttributeNames — (map<String>)
        • ExpressionAttributeValues — (map<map>) — a serializable JavaScript object. For information about the supported types see the DynamoDB Data Model
        • ReturnValuesOnConditionCheckFailure — (String) Possible values include:
          • "ALL_OLD"
          • "NONE"
      • Put — (map)
        • Item — required — (map<map>) — a serializable JavaScript object. For information about the supported types see the DynamoDB Data Model
        • TableName — required — (String)
        • ConditionExpression — (String)
        • ExpressionAttributeNames — (map<String>)
        • ExpressionAttributeValues — (map<map>) — a serializable JavaScript object. For information about the supported types see the DynamoDB Data Model
        • ReturnValuesOnConditionCheckFailure — (String) Possible values include:
          • "ALL_OLD"
          • "NONE"
      • Delete — (map)
        • Key — required — (map<map>) — a serializable JavaScript object. For information about the supported types see the DynamoDB Data Model
        • TableName — required — (String)
        • ConditionExpression — (String)
        • ExpressionAttributeNames — (map<String>)
        • ExpressionAttributeValues — (map<map>) — a serializable JavaScript object. For information about the supported types see the DynamoDB Data Model
        • ReturnValuesOnConditionCheckFailure — (String) Possible values include:
          • "ALL_OLD"
          • "NONE"
      • Update — (map)
        • Key — required — (map<map>) — a serializable JavaScript object. For information about the supported types see the DynamoDB Data Model
        • UpdateExpression — required — (String)
        • TableName — required — (String)
        • ConditionExpression — (String)
        • ExpressionAttributeNames — (map<String>)
        • ExpressionAttributeValues — (map<map>) — a serializable JavaScript object. For information about the supported types see the DynamoDB Data Model
        • ReturnValuesOnConditionCheckFailure — (String) Possible values include:
          • "ALL_OLD"
          • "NONE"
    • ReturnConsumedCapacity — (String) Possible values include:
      • "INDEXES"
      • "TOTAL"
      • "NONE"
    • ReturnItemCollectionMetrics — (String) Possible values include:
      • "SIZE"
      • "NONE"
    • ClientRequestToken — (String) If a token is not provided, the SDK will use a version 4 UUID.

Callback (callback):

  • function(err, data) { ... }

    Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.

    Context (this):

    • (AWS.Response) —

      the response object containing error, data properties, and the original request object.

    Parameters:

    • err (Error) —

      the error object returned from the request. Set to null if the request is successful.

    • data (Object) —

      the de-serialized data returned from the request. Set to null if a request error occurs. The data object has the following properties:

      • ConsumedCapacity — (Array<map>)
        • TableName — (String)
        • CapacityUnits — (Float)
        • ReadCapacityUnits — (Float)
        • WriteCapacityUnits — (Float)
        • Table — (map)
          • ReadCapacityUnits — (Float)
          • WriteCapacityUnits — (Float)
          • CapacityUnits — (Float)
        • LocalSecondaryIndexes — (map<map>)
          • ReadCapacityUnits — (Float)
          • WriteCapacityUnits — (Float)
          • CapacityUnits — (Float)
        • GlobalSecondaryIndexes — (map<map>)
          • ReadCapacityUnits — (Float)
          • WriteCapacityUnits — (Float)
          • CapacityUnits — (Float)
      • ItemCollectionMetrics — (map<Array<map>>)
        • ItemCollectionKey — (map<map>) — a serializable JavaScript object. For information about the supported types see the DynamoDB Data Model
        • SizeEstimateRangeGB — (Array<Float>)

Returns:

  • (AWS.Request) —

    a handle to the operation request for subsequent event callback registration.

See Also:

update(params, callback) ⇒ AWS.Request

Edits an existing item's attributes, or adds a new item to the table if it does not already exist by delegating to AWS.DynamoDB.updateItem().

Supply the same parameters as AWS.DynamoDB.updateItem() with AttributeValues substituted by native JavaScript types.

Service Reference:

Examples:

Update an item with expressions

var params = {
  TableName: 'Table',
  Key: { HashKey : 'hashkey' },
  UpdateExpression: 'set #a = :x + :y',
  ConditionExpression: '#a < :MAX',
  ExpressionAttributeNames: {'#a' : 'Sum'},
  ExpressionAttributeValues: {
    ':x' : 20,
    ':y' : 45,
    ':MAX' : 100,
  }
};

var documentClient = new AWS.DynamoDB.DocumentClient();

documentClient.update(params, function(err, data) {
   if (err) console.log(err);
   else console.log(data);
});

Calling the update operation

var params = {
  Key: { /* required */
    '<AttributeName>': someValue /* "str" | 10 | true | false | null | [1, "a"] | {a: "b"} */,
    /* '<AttributeName>': ... */
  },
  TableName: 'STRING_VALUE', /* required */
  AttributeUpdates: {
    '<AttributeName>': {
      Action: ADD | PUT | DELETE,
      Value: someValue /* "str" | 10 | true | false | null | [1, "a"] | {a: "b"} */
    },
    /* '<AttributeName>': ... */
  },
  ConditionExpression: 'STRING_VALUE',
  ConditionalOperator: AND | OR,
  Expected: {
    '<AttributeName>': {
      AttributeValueList: [
        someValue /* "str" | 10 | true | false | null | [1, "a"] | {a: "b"} */,
        /* more items */
      ],
      ComparisonOperator: EQ | NE | IN | LE | LT | GE | GT | BETWEEN | NOT_NULL | NULL | CONTAINS | NOT_CONTAINS | BEGINS_WITH,
      Exists: true || false,
      Value: someValue /* "str" | 10 | true | false | null | [1, "a"] | {a: "b"} */
    },
    /* '<AttributeName>': ... */
  },
  ExpressionAttributeNames: {
    '<ExpressionAttributeNameVariable>': 'STRING_VALUE',
    /* '<ExpressionAttributeNameVariable>': ... */
  },
  ExpressionAttributeValues: {
    '<ExpressionAttributeValueVariable>': someValue /* "str" | 10 | true | false | null | [1, "a"] | {a: "b"} */,
    /* '<ExpressionAttributeValueVariable>': ... */
  },
  ReturnConsumedCapacity: INDEXES | TOTAL | NONE,
  ReturnItemCollectionMetrics: SIZE | NONE,
  ReturnValues: NONE | ALL_OLD | UPDATED_OLD | ALL_NEW | UPDATED_NEW,
  ReturnValuesOnConditionCheckFailure: ALL_OLD | NONE,
  UpdateExpression: 'STRING_VALUE'
};
documentclient.update(params, function(err, data) {
  if (err) console.log(err, err.stack); // an error occurred
  else     console.log(data);           // successful response
});

Parameters:

  • params (Object) —
    • TableName — (String)
    • Key — (map<map>) — a serializable JavaScript object. For information about the supported types see the DynamoDB Data Model
    • AttributeUpdates — (map<map>)
      • Value — a serializable JavaScript object. For information about the supported types see the DynamoDB Data Model
      • Action — (String) Possible values include:
        • "ADD"
        • "PUT"
        • "DELETE"
    • Expected — (map<map>)
      • Value — a serializable JavaScript object. For information about the supported types see the DynamoDB Data Model
      • Exists — (Boolean)
      • ComparisonOperator — (String) Possible values include:
        • "EQ"
        • "NE"
        • "IN"
        • "LE"
        • "LT"
        • "GE"
        • "GT"
        • "BETWEEN"
        • "NOT_NULL"
        • "NULL"
        • "CONTAINS"
        • "NOT_CONTAINS"
        • "BEGINS_WITH"
      • AttributeValueList — (Array<map>) — a serializable JavaScript object. For information about the supported types see the DynamoDB Data Model
    • ConditionalOperator — (String) Possible values include:
      • "AND"
      • "OR"
    • ReturnValues — (String) Possible values include:
      • "NONE"
      • "ALL_OLD"
      • "UPDATED_OLD"
      • "ALL_NEW"
      • "UPDATED_NEW"
    • ReturnConsumedCapacity — (String) Possible values include:
      • "INDEXES"
      • "TOTAL"
      • "NONE"
    • ReturnItemCollectionMetrics — (String) Possible values include:
      • "SIZE"
      • "NONE"
    • UpdateExpression — (String)
    • ConditionExpression — (String)
    • ExpressionAttributeNames — (map<String>)
    • ExpressionAttributeValues — (map<map>) — a serializable JavaScript object. For information about the supported types see the DynamoDB Data Model
    • ReturnValuesOnConditionCheckFailure — (String) Possible values include:
      • "ALL_OLD"
      • "NONE"

Callback (callback):

  • function(err, data) { ... }

    Called when a response from the service is returned. If a callback is not supplied, you must call AWS.Request.send() on the returned request object to initiate the request.

    Context (this):

    • (AWS.Response) —

      the response object containing error, data properties, and the original request object.

    Parameters:

    • err (Error) —

      the error object returned from the request. Set to null if the request is successful.

    • data (Object) —

      the de-serialized data returned from the request. Set to null if a request error occurs. The data object has the following properties:

      • Attributes — (map<map>) — a serializable JavaScript object. For information about the supported types see the DynamoDB Data Model
      • ConsumedCapacity — (map)
        • TableName — (String)
        • CapacityUnits — (Float)
        • ReadCapacityUnits — (Float)
        • WriteCapacityUnits — (Float)
        • Table — (map)
          • ReadCapacityUnits — (Float)
          • WriteCapacityUnits — (Float)
          • CapacityUnits — (Float)
        • LocalSecondaryIndexes — (map<map>)
          • ReadCapacityUnits — (Float)
          • WriteCapacityUnits — (Float)
          • CapacityUnits — (Float)
        • GlobalSecondaryIndexes — (map<map>)
          • ReadCapacityUnits — (Float)
          • WriteCapacityUnits — (Float)
          • CapacityUnits — (Float)
      • ItemCollectionMetrics — (map)
        • ItemCollectionKey — (map<map>) — a serializable JavaScript object. For information about the supported types see the DynamoDB Data Model
        • SizeEstimateRangeGB — (Array<Float>)

Returns:

  • (AWS.Request) —

    a handle to the operation request for subsequent event callback registration.

See Also: