Skip to main content

AWSDynamoDB

Latest Version: 1.0.0

AWS DynamoDB is a fully managed NoSQL database service. This library uses AWS DynamoDB Rest API to provide low-level API actions for managing database tables and indexes, and for creating, reading, updating and deleting data.

You can view the library’s source code on GitHub. Click here to see information on the available versions of this library.

Note The AWSDynamoDB library uses AWSRequestV4 for all requests, so the AWSRequestV4 library must also be included in your agent code.

To add this library copy and paste the following lines to the top of your agent code:

#require "AWSRequestV4.class.nut:1.0.2"
#require "AWSDynamoDB.agent.lib.nut:1.0.0"

Class Usage

Constructor: AWSDynamoDB(region, accessKeyId, secretAccessKey)

Parameters

Parameter Type Description
region String AWS region
accessKeyId String AWS access key
secretAccessKey String AWS secret access key

Access keys can be generated with IAM.

Example

#require "AWSRequestV4.class.nut:1.0.2"
#require "AWSDynamoDB.agent.lib.nut:1.0.0"

const AWS_DYNAMO_ACCESS_KEY_ID = "YOUR_KEY_ID";
const AWS_DYNAMO_SECRET_ACCESS_KEY = "YOUR_KEY";
const AWS_DYNAMO_REGION = "YOUR_REGION";

db <- AWSDynamoDB(AWS_DYNAMO_REGION, AWS_DYNAMO_ACCESS_KEY_ID, AWS_DYNAMO_SECRET_ACCESS_KEY);

Class Methods

action(actionType, actionParams, callback)

This method performs a specified action (eg. get batch item) with the required parameters (actionParams) for the specified action type.

Parameters

Parameter Type Description
actionType Constant The type of the Amazon CloudWatch Logs action that you want to perform (see ‘Action Types’, below)
actionParams Table Table of action-specific parameters (see ‘Action Types’, below)
callback Function Callback function that takes one parameter: a response table

Response Table

The format of the response table general to all callback functions.

Key Type Description
body String A DynamoDB response in a function specific structure that is JSON encoded. See each action parameter response, below, for details
statuscode Integer An HTTP status code
headers Table See ‘Headers’, below

Headers

The response table’s headers key is a table containing the following keys:

Key Type Description
x-amzn-requestid String An Amazon request ID
content-type String The content type eg. "text/XML"
date String The date and time at which the response was sent
content-length String The length of the content
x-amz-crc32 String Checksum of the UTF-8 encoded bytes in the HTTP response

Action Types

Action Type Description
AWS_DYNAMO_DB_ACTION_BATCH_GET_ITEM Returns the attributes of one or more items from one or more tables
AWS_DYNAMO_DB_ACTION_BATCH_WRITE_ITEM Puts or deletes multiple items in one or more tables
AWS_DYNAMO_DB_ACTION_CREATE_TABLE Adds a new table to your account
AWS_DYNAMO_DB_ACTION_DELETE_ITEM Deletes a single existing item
AWS_DYNAMO_DB_ACTION_DELETE_TABLE Deletes a single existing table
AWS_DYNAMO_DB_ACTION_DESCRIBE_LIMITS Returns the current provisioned-capacity limits for your AWS account
AWS_DYNAMO_DB_ACTION_DESCRIBE_TABLE Returns information about a single existing table
AWS_DYNAMO_DB_ACTION_GET_ITEM Returns a single existing item
AWS_DYNAMO_DB_ACTION_LIST_TABLES Returns a list of table names
AWS_DYNAMO_DB_ACTION_PUT_ITEM Uploads a single item
AWS_DYNAMO_DB_ACTION_QUERY Initiate a database query operation
AWS_DYNAMO_DB_ACTION_SCAN Returns one or more items and item attributes
AWS_DYNAMO_DB_ACTION_UPDATE_ITEM Modifies a single existing item
AWS_DYNAMO_DB_ACTION_UPDATE_TABLE Modifies a single existing table

Specific actions of the types listed above are configured by passing information into action()’s actionParams parameter as a table with the following action type-specific keys.

AWS_DYNAMO_DB_ACTION_BATCH_GET_ITEM

This action returns the attributes of one or more items from one or more tables. You identify requested items by primary key. For more detail please see the AWS DynamoDB documentation.

Parameters Table Keys

Key Type Required Description
RequestItems Table Yes A map of one or more table names and, for each table, a list of operations to be performed (DeleteRequest or PutRequest)
ReturnConsumedCapacity String No Valid values: INDEXES, TOTAL, NONE.
INDEXES returns aggregate ConsumedCapacity for the operation, and ConsumedCapacity for each table and secondary index.
TOTAL returns only aggregate ConsumedCapacity.
NONE (default) returns no ConsumedCapacity details

Response

The response table contains a key, body, which is a table that includes the following JSON encoded keys:

Key Type Description
ConsumedCapacity Array of tables The capacity units consumed by the entire batch read operation
Responses Table Each object in Responses consists of a table name, along with a map of attribute data consisting of the data type and attribute value
UnprocessedKeys Table A map of tables and their respective keys that were not processed with the current response

Example

Note Follows from AWS_DYNAMO_DB_ACTION_BATCH_WRITE_ITEM Example

local getParams = {
  "RequestItems": {
    "testTable2": {
      "Keys": [
          { "deviceId": {"S": imp.configparams.deviceid},
                "time": {"S": itemTime1} },
          { "deviceId": {"S": imp.configparams.deviceid},
                "time": {"S": itemTime2} }
      ]
    }
  }
};

db.action(AWS_DYNAMO_DB_ACTION_BATCH_GET_ITEM, getParams, function(response) {
  local arrayOfReturnedItems = http.jsondecode(response.body).Responses.testTable2;
})

AWS_DYNAMO_DB_ACTION_BATCH_WRITE_ITEM

This action puts or deletes multiple items into or from one or more tables. For more detail please see the AWS DynamoDB documentation.

Parameters Table Keys

Key Type Required Description
RequestItems Table Yes See here
ReturnConsumedCapacity String No Valid values: INDEXES, TOTAL, NONE.
INDEXES returns aggregate ConsumedCapacity for the operation, and ConsumedCapacity for each table and secondary index.
TOTAL returns only aggregate ConsumedCapacity.
NONE (default) returns no ConsumedCapacity details
ReturnItemCollectionMetrics String No Valid values: SIZE, NONE.
Determines whether item collection metrics are returned. If set to SIZE, the response includes statistics about item collections. If set to NONE (default), no statistics are returned

Response

The response table contains a key, body, which is a table that includes the following JSON encoded keys:

Key Type Description
ConsumedCapacity Array of tables The capacity units consumed by the entire batch write operation
ItemCollectionMetrics Array of tables A list of tables that were processed by the batch action and, for each table, information about any item collections that were affected by individual delete or put operations
UnprocessedItems Array of tables A map of tables and requests against those tables that were not processed. The value of UnprocessedItems is in the same form as requestItems, so you can provide this value directly to a subsequent batch read operation

Example

// Writing to an existing table called testTable2 with key schema seen in create table
local writeParams = {
  "RequestItems": {
    "testTable2": [
      { "PutRequest": { "Item": { "deviceId": { "S": imp.configparams.deviceid },
                                  "time": { "S": itemTime1 },
                                  "batchNumber": { "N": "1" } } }
      },
      { "PutRequest": { "Item": { "deviceId": { "S": imp.configparams.deviceid },
                                  "time": { "S": itemTime2 },
                                  "batchNumber": { "N": "2" } } }
      }
    ]
  }
};

db.action(AWS_DYNAMO_DB_ACTION_BATCH_WRITE_ITEM, writeParams, function(response) {
  if (response.statuscode >= 200 && response.statuscode < 300) {
    server.log("Batch write successful");
  } else {
    server.log("Batch write unsuccessful");
  }
})

AWS_DYNAMO_DB_ACTION_CREATE_TABLE

This action adds a new table to your account. In an AWS account, table names must be unique within each region. For more detail please see the AWS DynamoDB documentation.

Parameters Table Keys

Key Type Required Description
AttributeDefinitions Array of tables Yes See here
KeySchema Array of tables Yes See here
ProvisionedThroughput Table Yes See here
TableName String Yes The name of the table to create
GlobalSecondaryIndexes Array of tables No See here. Default: null
LocalSecondaryIndexes Array of tables No See here. Default: null
StreamSpecifiation Table No See here. Default: null

Response

The response table contains a key, body, which is a table that includes the following JSON encoded keys:

Key Type Description
TableDescription Table Represents the properties of a table (see here)

Example

local randNum = (1.0 * math.rand() / RAND_MAX) * 1001;
local tableName = "testTable." + randNum;
local params = {
  "AttributeDefinitions": [
      { "AttributeName": "deviceId",
        "AttributeType": "S" },
      { "AttributeName": "time",
        "AttributeType": "S" } ],
  "KeySchema": [
      { "AttributeName": "deviceId",
        "KeyType": "HASH" },
      { "AttributeName": "time",
        "KeyType": "RANGE" } ],
  "ProvisionedThroughput": { "ReadCapacityUnits": 5,
                             "WriteCapacityUnits": 5 },
  "TableName": tableName
};

db.action(AWS_DYNAMO_DB_ACTION_CREATE_TABLE, params, function(response) {
  if (response.statuscode >= 200 && response.statuscode < 300) {
    server.log("Table creation successful");
  } else {
    server.log("Table creation unsuccessful");
  }
}.bindenv(this));

AWS_DYNAMO_DB_ACTION_DELETE_ITEM

This action deletes a single item in a table by primary key. For more detail please see the AWS DynamoDB documentation.

Parameters Table Keys

Key Type Required Description
Key Table Yes A map of attribute names to AttributeValue objects, representing the primary key of the item to delete
TableName String Yes The name of the table from which to delete the item
ConditionalExpression String No A condition that must be satisfied in order for a conditional delete action to succeed. Default: null
ExpressionAttributeNames Table No One or more substitution tokens for attribute names in an expression. Default: null
ExpressionAttributeValues Table No One or more values that can be substituted in an expression. Default: null
ReturnConsumedCapacity String No Valid values: INDEXES, TOTAL, NONE.
INDEXES returns aggregate ConsumedCapacity for the operation, and ConsumedCapacity for each table and secondary index.
TOTAL returns only aggregate ConsumedCapacity.
NONE (default) returns no ConsumedCapacity details
ReturnItemCollectionMetrics String No Valid values: SIZE, NONE.
Determines whether item collection metrics are returned. If set to SIZE, the response includes statistics about item collections. If set to NONE (default), no statistics are returned
ReturnValues String No Valid values: ALL_OLD, NONE.
Use ALL_OLD if you want to get the item attributes as they appeared before they were deleted, else NONE (default) where nothing is returned

Response

The response table contains a key, body, which is a table that includes the following JSON encoded keys:

Key Type Description
Attributes Table The attribute values as they appeared before the PutItem operation (see here)
ConsumedCapacity Table The capacity units consumed by the PutItem operation (see here)
ItemCollectionMetrics Table Information about item collections, if any, that were affected by the put operation (see here)

Example

local tableName = "YOUR_TABLE_NAME";
local itemTime = time().tostring();

local deleteParams = {
  "Key": { "deviceId": { "S": imp.configparams.deviceid },
           "time": { "S": itemTime } },
  "TableName": tableName,
};

db.action(AWS_DYNAMO_DB_ACTION_DELETE_ITEM, deleteParams, function(response) {
  if (response.statuscode >= 200 && response.statuscode < 300) {
    server.log("Successfully deleted item");
  } else {
    server.log("Error: " + response.statuscode);
  }
});

AWS_DYNAMO_DB_ACTION_DELETE_TABLE

This action deletes a single table. For more details please see the AWS DynamoDB documentation.

Parameters Table Keys

Key Type Required Description
TableName String Yes The name of the table to delete

Response

The response table contains a key, body, which is a table that includes the following JSON encoded keys:

Key Type Description
TableDescription Table Represents the properties of a table (see here)

Example

local params = { "TableName": tableName };

db.action(AWS_DYNAMO_DB_ACTION_DELETE_TABLE, params, function(response) {
  if (response.statuscode >= 200 && response.statuscode < 300) {
    server.log("Successfully deleted Table");
  } else {
    server.log("Error: " + response.statuscode);
  }
});

AWS_DYNAMO_DB_ACTION_DESCRIBE_LIMITS

This action returns the current provisioned-capacity limits for your AWS account in a region, both for the region as a whole and for any one DynamoDB table that you create there. For more detail please see the AWS DynamoDB documentation.

This action requires no action parameters — pass in an empty table as per the example below.

Response

The response table contains a key, body, which is a table that includes the following JSON encoded keys:

Key Type Description
AccountMaxReadCapacityUnits Integer The maximum total read capacity units that your account allows you to provision across all of your tables in this region
AccountMaxWriteCapacityUnits Integer The maximum total write capacity units that your account allows you to provision across all of your tables in this region
TableMaxReadCapacityUnits Integer The maximum read capacity units that your account allows you to provision for a new table that you are creating in this region, including the read capacity units provisioned for its global secondary indexes (GSIs)
TableMaxWriteCapacityUnits Integer The maximum write capacity units that your account allows you to provision for a new table that you are creating in this region, including the write capacity units provisioned for its global secondary indexes (GSIs)

Example

db.action(AWS_DYNAMO_DB_ACTION_DESCRIBE_LIMITS, {}, function(response) {
  if (response.statuscode >= 200 && response.statuscode < 300) {
    server.log("AccountMaxReadCapacityUnits: " + http.jsondecode(response.body).AccountMaxReadCapacityUnits);
  } else {
    server.log("Error: " + response.statuscode);
  }
});

AWS_DYNAMO_DB_ACTION_DESCRIBE_TABLE

This action returns information about the table, including the current status of the table, when it was created, the primary key schema, and any indexes on the table. For more details please see the AWS DynamoDB documentation.

Parameters Table Keys

Key Type Required Description
TableName String Yes The name of the table to describe

Response

The response table contains a key, body, which is a table that includes the following JSON encoded keys:

Key Type Description
Table Table See here

Example

local tableName = "YOUR_TABLE_NAME";
local params = { "TableName": tableName };
db.action(AWS_DYNAMO_DB_ACTION_DESCRIBE_TABLE, params, function(response) {
  server.log("The name of the table described is " + http.jsondecode(response.body).Table.TableName);
});

AWS_DYNAMO_DB_ACTION_GET_ITEM

This action returns a set of attributes for the item with the given primary key. For more details please see the AWS DynamoDB documentation.

Parameters Table Keys

Key Type Required Description
Key Table Yes See here
TableName String Yes The name of the table containing the requested item
AttributesToGet Array of strings No See here. Default: null
ConsistentRead Boolean No If set to true, then the operation uses strongly consistent reads; otherwise, the operation uses eventually consistent reads. Default: false
ExpressionAttributeNames Table No One or more substitution tokens for attribute names in an expression. Default: null
ProjectionExpression String No String that identifies one or more attributes to retrieve from the table. These attributes can include scalars, sets or elements of a JSON document. The attributes in the expression must be separated by commas. Default: null
ReturnConsumedCapacity String No Valid values: INDEXES, TOTAL, NONE.
INDEXES returns aggregate ConsumedCapacity for the operation, and ConsumedCapacity for each table and secondary index.
TOTAL returns only aggregate ConsumedCapacity.
NONE (default) returns no ConsumedCapacity details

Response

The response table contains a key, body, which is a table that includes the following JSON encoded keys:

Key Type Description
ConsumedCapacity Table The capacity units consumed by the GetItem operation (see here)
Item Table A map of attribute names to AttributeValue objects (see here)

Example

local tableName = "YOUR_TABLE_NAME";
local itemTime = time().tostring();
local getParams = {
  "Key": { "deviceId": { "S": imp.configparams.deviceid },
           "time": { "S": itemTime } },
  "TableName": tableName,
  "AttributesToGet": [ "time", "status" ],
  "ConsistentRead": false
};

db.action(AWS_DYNAMO_DB_ACTION_GET_ITEM, getParams, function(response) {
  server.log( "retrieved time: " + http.jsondecode(response.body).Item.time.S);
});

AWS_DYNAMO_DB_ACTION_LIST_TABLES

This action returns an array of table names associated with the current account and endpoint. For more details please see the AWS DynamoDB documentation.

Parameters Table Keys

Key Type Required Description
ExclusiveStartTableName String No The first table name that this operation will evaluate. Default: null
Limit Integer No A maximum number of table names to return. Default: 100

Response

The response table contains a key, body, which is a table that includes the following JSON encoded keys:

Key Type Description
LastEvaluatedTableName String The name of the last table in the current page of results
TableNames Array of strings The names of the tables associated with the current account at the current endpoint. The maximum size of this array is 100

Example

local params = { "Limit": 10 };

db.action(AWS_DYNAMO_DB_ACTION_LIST_TABLES, params, function(response) {
  if (response.statuscode >= 200 && response.statuscode < 300) {
    local arrayOfTableNames = http.jsondecode(response.body).TableNames;
  } else {
    server.log("error " + response.statuscode);
  }
});

AWS_DYNAMO_DB_ACTION_PUT_ITEM

This action creates a new item, or replaces an old item with a new item. For more details please see the AWS DynamoDB documentation.

Parameters Table Keys

Key Type Required Description
Item Table Yes A map of attribute name/value pairs, one for each attribute. Only the primary key attributes are required; you can optionally provide other attribute name-value pairs for the item
TableName String Yes The name of the table to contain the item
ConditionalExpression String No A condition that must be satisfied in order for a conditional put action to succeed. Default: null
AttributesToGet Array of strings No See here. Default: null
ExpressionAttributeNames Table No One or more substitution tokens for attribute names in an expression. Default: null
ExpressionAttributeValues Table No One or more values that can be substituted in an expression (see here). Default: null
ReturnConsumedCapacity String No Valid values: INDEXES, TOTAL, NONE.
INDEXES returns aggregate ConsumedCapacity for the operation, and ConsumedCapacity for each table and secondary index.
TOTAL returns only aggregate ConsumedCapacity.
NONE (default) returns no ConsumedCapacity details
ReturnItemCollectionMetrics String No Valid Values: SIZE, NONE.
If set to SIZE, the response includes statistics about item collections. If set to NONE (default), no statistics are returned
ReturnValues String No Valid Values: ALL_OLD, NONE.
If set to ALL_OLD, then if the action overwrote an attribute name-value pair, the content of the old item is returned. If set to NONE (default), nothing is returned

Response

The response table contains a key, body, which is a table that includes the following JSON encoded keys:

Key Type Description
Attributes Table The attribute values as they appeared before the PutItem operation (see here)
ConsumedCapacity Table The capacity units consumed by the PutItem operation (see here)
ItemCollectionMetrics Table Information about item collections, if any, that were affected by the put operation (see here)

Example

local tableName = "YOUR_TABLE_NAME";
local putParams = { "TableName": tableName,
                    "Item": { "deviceId": { "S": imp.configparams.deviceid },
                              "time": { "S": itemTime },
                              "status": { "BOOL": true } }
};

db.action(AWS_DYNAMO_DB_ACTION_PUT_ITEM, putParams, function(response) {
  if (response.statuscode == 200) {
    server.log("Successfully put in item");
  } else {
    server.log("failed to put item, error: " + response.statuscode);
  }
});

AWS_DYNAMO_DB_ACTION_QUERY

This action is a query operation that uses the primary key of a table or a secondary index to directly access items from that table or index. For more details please see the AWS DynamoDB documentation.

Parameters Table Keys

Key Type Required Description
TableName String Yes The name of the table containing the requested items
AttributesToGet Array of strings No See here. Default: null
ConditionalOperator String No See here. Default: null
ConsistentRead Boolean No If set to true, the operation uses strongly consistent reads; otherwise, the operation uses eventually consistent reads. Default: false
ExclusiveStartKey Table No The primary key of the first item that this operation will evaluate. Default: null
ExpressionAttributeNames Table No One or more substitution tokens for attribute names in an expression. Default: null
ExpressionAttributeValues Table No One or more values that can be substituted in an expression. Default: null
FilterExpression String No See here. Default: null
IndexName String No The name of an index to query. This index can be any local secondary index or global secondary index on the table. Default: null
KeyConditionExpression String No The condition that specifies the key value(s) for items to be retrieved by the query action. Default: null
Limit Integer No The maximum number of items to evaluate (not necessarily the number of matching items). Default: 1
ProjectionExpression String No A string that identifies one or more attributes to retrieve from the table. Default: null
ReturnConsumedCapacity String No Valid values: INDEXES, TOTAL, NONE.
INDEXES returns aggregate ConsumedCapacity for the operation, and ConsumedCapacity for each table and secondary index.
TOTAL returns only aggregate ConsumedCapacity.
NONE (default) returns no ConsumedCapacity details
ScanIndexForward Boolean No Specifies the order for index traversal: if true (default), the traversal is performed in ascending order; if false, the traversal is performed in descending order
Select String No The attributes to be returned in the result. You can retrieve all item attributes, specific item attributes, the count of matching items, or in the case of an index, some or all of the attributes projected into the index. Default: null

Response

The response table contains a key, body, which is a table that includes the following JSON encoded keys:

Key Type Description
ConsumedCapacity Table See here
Count Integer The number of items in the response
Items Array of Tables An array of item attributes that match the query criteria. Each element in this array consists of an attribute name and the value for that attribute
LastEvaluatedKey Table The primary key of the item where the operation stopped, inclusive of the previous result set. Use this value to start a new operation, excluding this value in the new request
ScannedCount Integer The number of items evaluated, before any query filter is applied. A high ScannedCount value with few, or no, Count results indicates an inefficient query operation

Example

local params = { "TableName": tableName,
                 "KeyConditionExpression": "deviceId = :deviceId",
                 "ExpressionAttributeValues": { ":deviceId": { "S": imp.configparams.deviceid } }
};

db.action(AWS_DYNAMO_DB_ACTION_QUERY, params, function(response) {
  if (response.statuscode >= 200 && response.statuscode < 300) {
    server.log("The time stored is: " +  http.jsondecode(response.body).Items[0].time.S);
  } else {
    server.log("error: " + response.statuscode);
  }
});

AWS_DYNAMO_DB_ACTION_SCAN

This action returns one or more items and item attributes by accessing every item in a table or a secondary index. For more details please see the AWS DynamoDB documentation.

Parameters Table Keys

Key Type Required Description
TableName String Yes The name of the table containing the requested items; or, if you provide IndexName, the name of the table to which that index belongs
AttributesToGet Array of strings No See here. Default: null
ConditionalOperator String No See here. Default: null
ConsistentRead Boolean No If set to true, the operation uses strongly consistent reads; otherwise, the operation uses eventually consistent reads. Default: false
ExclusiveStartKey Table No The primary key of the first item that this operation will evaluate. Default: null
ExpressionAttributeNames Table No One or more substitution tokens for attribute names in an expression. Default: null
ExpressionAttributeValues table No One or more values that can be substituted in an expression. Default: null
FilterExpression String No One or more values that can be substituted in an expression. Default: null
IndexName String No The name of a secondary index to scan. Default: null
Limit Integer No The maximum number of items to evaluate (not necessarily the number of matching items). Default: 1
ProjectionExpression String No A string that identifies one or more attributes to retrieve from the table. Default: null
ReturnConsumedCapacity String No Valid values: INDEXES, TOTAL, NONE.
INDEXES returns aggregate ConsumedCapacity for the operation, and ConsumedCapacity for each table and secondary index.
TOTAL returns only aggregate ConsumedCapacity.
NONE (default) returns no ConsumedCapacity details
Segment Integer No For a parallel scan request, Segment identifies an individual segment to be scanned by an application worker. Default: null
Select String No The attributes to be returned in the result. You can retrieve all item attributes, specific item attributes, the count of matching items, or in the case of an index, some or all of the attributes projected into the index. Default: null
TotalSegments Integer No For a parallel scan request, TotalSegments represents the total number of segments into which the scan operation will be divided. Default: null

Response

The response table contains a key, body, which is a table that includes the following JSON encoded keys:

Key Type Description
ConsumedCapacity Table See here
Count Integer The number of items in the response
Items Array of Tables An array of item attributes that match the query criteria. Each element in this array consists of an attribute name and the value for that attribute
LastEvaluatedKey Table The primary key of the item where the operation stopped, inclusive of the previous result set. Use this value to start a new operation, excluding this value in the new request
ScannedCount Integer The number of items evaluated, before any query filter is applied. A high ScannedCount value with few, or no, Count results indicates an inefficient query operation

Example

local params = { "TableName": tableName, };

db.action(AWS_DYNAMO_DB_ACTION_SCAN, params, function(response) {
  if (response.statuscode >= 200 && response.statuscode < 300) {
    // Returned deviceId from scan
    // NOTE this example requires the table created in the CreateTable example
    local deviceId = http.jsondecode(response.body).Items[0].deviceId.S;
  } else {
    server.log("error: " + response.statuscode);
  }
});

AWS_DYNAMO_DB_ACTION_UPDATE_ITEM

This action updates an existing item.For more details please see the AWS DynamoDB documentation.

Parameters Table Keys

Key Type Required Description
Key Table Yes The primary key of the item to be updated (see here)
TableName String Yes The name of the table containing the item to update
AttributesUpdates Table No See here. Default: null
ConditionalExpression String No A condition that must be satisfied in order for a conditional update operation to succeed. Default: null
ExpressionAttributeNames Table No One or more substitution tokens for attribute names in an expression. Default: null
ExpressionAttributeValues Table No One or more values that can be substituted in an expression. Default: null
ReturnConsumedCapacity String No Valid values: INDEXES, TOTAL, NONE.
INDEXES returns aggregate ConsumedCapacity for the operation, and ConsumedCapacity for each table and secondary index.
TOTAL returns only aggregate ConsumedCapacity.
NONE (default) returns no ConsumedCapacity details
ReturnItemCollectionMetrics String No Determines whether item collection metrics are returned. If set to SIZE, the response includes statistics about item collections. If set to NONE (default), no statistics are returned
ReturnValues String No Valid values: ALL_OLD, All_NEW, UPDATED_OLD, UPDATED_NEW, NONE.
Use ReturnValues if you want to get the item attributes as they appeared either before or after they were updated. Use ALL_OLD for all attributes prior to being changed; All_NEW for all attributes after the change; UPDATED_OLD for all attributes that were changed but returns values prior to change; UPDATED_NEW for all attributes that were changed but returns values after the change; or NONE (default) to have nothing returned
UpdateExpression String No An expression that defines one or more attributes to be updated, the action to be performed on them, and new value(s) for them. Default: null

Response

The response table contains a key, body, which is a table that includes the following JSON encoded keys:

Key Type Description
Attributes Table See here
ConsumedCapacity Table See here
ItemCollectionMetrics Table See here

Example

NOTE This example follows from the AWS_DYNAMO_DB_ACTION_PUT_ITEM example.

local updateParams = {
  "Key": { "deviceId": { "S": imp.configparams.deviceid },
           "time": { "S": itemTime } },
  "TableName": tableName,
  "UpdateExpression": "SET newVal = :newVal",
  "ExpressionAttributeValues": { ":newVal": {"S":"this is a new value"} },
  "ReturnValues": "UPDATED_NEW"
};

db.action(AWS_DYNAMO_DB_ACTION_UPDATE_ITEM, updateParams, function(response) {
  if (response.statuscode >= 200 && response.statuscode < 300) {
    server.log("New attribute was Successfully entered with a value: " + http.jsondecode(response.body).Attributes.newVal.S);
  } else {
    server.log("error: " + response.statuscode);
  }
});

AWS_DYNAMO_DB_ACTION_UPDATE_TABLE

This action modifies the provisioned throughput settings, global secondary indexes, or DynamoDB Streams settings for a given table. For more details please see the AWS DynamoDB documentation.

Parameters Table Keys

Key Type Required Description
TableName String Yes The name of the table to be updated
AttributeDefinitions Table No An Array of attributes that describe the key schema for the table and indexes. Default: null
GlobalSecondaryIndexUpdates Array of tables No An array of one or more global secondary indexes for the table (see here). Default: null
ProvisionedThroughput Table No The new provisioned throughput settings for the specified table or index (see here). Default: null
StreamSpecification Table No Represents the DynamoDB Streams configuration for the table (see here). Default: null

Response

The response table contains a key, body, which is a table that includes the following JSON encoded keys:

Key Type Description
TableDescription Table Represents the properties of a table

Example

local params = { "TableName": _tablename,
                 "ProvisionedThroughput": { "ReadCapacityUnits": 6,
                                            "WriteCapacityUnits": 6 }
};

db.action(AWS_DYNAMO_DB_ACTION_UPDATE_TABLE, params, function(response) {
  if (response.statuscode >= 200 && response.statuscode < 300) {
    server.log("New attribute was Successfully entered with a value: " + http.jsondecode(response.body).Attributes.newVal.S);
  } else {
    server.log("error: " + response.statuscode);
  }
});

Release History

The Electric Imp Dev Center documents the latest version of the library. For past versions, please see the Electric Imp public GitHub repos listed below.

Version Source Code Notes
1.0.0 GitHub Initial release

License

The AWSDynamoDB library is licensed under the MIT License.