Merge pull request #2 from brmur/2409_smallupdates

DynamoDB Utilties examples

javascriptv3/example_code/dynamodb/README.md

@@ -17,8 +17,8 @@ instructions.
 
 2. Install the dependencies listed in the package.json.
 
-**Note**: These include the client module for the AWS services required in these example, 
-which is *@aws-sdk/client-dynamodb*.
+**Note**: These include the client modules for the AWS services required in these example, 
+which are *@aws-sdk/client-dynamodb* and *@aws-sdk/util-dynamodb*.
 ```
 npm install ts-node -g // If using JavaScript, enter 'npm install node -g' instead
 cd javascriptv3/example_code/dynamodb

javascriptv3/example_code/dynamodb/package.json

@@ -8,6 +8,7 @@
   "dependencies": {
     "@aws-sdk/client-dynamodb": "^1.0.0-gamma.6",
     "@aws-sdk/node-http-handler": "^1.0.0-gamma.5",
+    "@aws-sdk/util-dynamodb": "^1.0.0-gamma.5",
     "@aws-sdk/types": "^0.1.0-gamma.6",
     "ts-node": "^9.0.0"
   },

javascriptv3/example_code/dynamodb/src/ddbdoc_delete_item.ts

@@ -0,0 +1,60 @@
+/* Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+SPDX-License-Identifier: Apache-2.0
+
+ABOUT THIS NODE.JS EXAMPLE: This example works with AWS SDK for JavaScript version 3 (v3),
+which is pending release.  The preview version of the SDK is available
+at https://github.com/aws/aws-sdk-js-v3. This example is in the 'AWS SDK for JavaScript v3 Developer Guide' at
+https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/dynamodb-example-document-client.html.
+
+Purpose:
+ddbdoc_get_item.ts demonstrates how to use DynamoDB utilities to delete an item from an Amazon DynamoDB table.
+
+Inputs (replace in code):
+- TABLE_NAME
+- REGION
+- primaryKey
+- sortKey (only required if table has sort key)
+- VALUE_1: Value for the primary key (The format for the datatype must match the schema. For example, if the primaryKey is a number, VALUE_1 has no inverted commas.)
+- VALUE_2: Value for the primary key (The format for the datatype must match the schema.)
+
+Running the code:
+ts-node ddbdoc_get_item.ts
+*/
+// snippet-start:[dynamodb.JavaScript.docClient.deleteV3]
+
+// Import required AWS SDK clients and commands for Node.js
+const { DynamoDB } = require("@aws-sdk/client-dynamodb");
+const { marshall, unmarshall } = require("@aws-sdk/util-dynamodb");
+
+// Set the parameters
+const params = {
+  TableName: "TABLE_NAME",
+  /*
+  Convert the key JavaScript object you are deleting to the required DynamoDB format. The format of values specifies
+  the datatype. The following list demonstrates different datatype formatting requirements:
+  HashKey: "hashKey",
+  NumAttribute: 1,
+  BoolAttribute: true,
+  ListAttribute: [1, "two", false],
+  MapAttribute: { foo: "bar" },
+  NullAttribute: null
+   */
+  Key: marshall({
+    primaryKey: VALUE_1, // For example, "Season: 2"
+    sortKey: VALUE_2, // For example,  "Episode: 1" (only required if table has sort key)
+  }),
+};
+
+// Create DynamoDB document client
+const client = new DynamoDB({ region: "us-east-1" });
+
+const run = async () => {
+  try {
+    const { Item } = await client.deleteItem(params);
+    console.log("Success -deleted");
+  } catch (err) {
+    console.log("Error", err);
+  }
+};
+run();
+// snippet-end:[dynamodb.JavaScript.docClient.deleteV3]

javascriptv3/example_code/dynamodb/src/ddbdoc_get_item.ts

@@ -0,0 +1,63 @@
+/* Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+SPDX-License-Identifier: Apache-2.0
+
+ABOUT THIS NODE.JS EXAMPLE: This example works with AWS SDK for JavaScript version 3 (v3),
+which is pending release.  The preview version of the SDK is available
+at https://github.com/aws/aws-sdk-js-v3. This example is in the 'AWS SDK for JavaScript v3 Developer Guide' at
+https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/dynamodb-example-document-client.html.
+
+Purpose:
+ddbdoc_get_item.ts demonstrates how to use DynamoDB utilities to retrieve a set of attributes for an item in an Amazon DynamoDB table..
+
+Inputs (replace in code):
+- TABLE_NAME
+- REGION
+- primaryKey
+- sortKey (only required if table has sort key)
+- VALUE_1: Value for the primary key (The format for the datatype must match the schema. For example, if the primaryKey is a number, VALUE_1 has no inverted commas.)
+- VALUE_2: Value for the primary key (The format for the datatype must match the schema.)
+
+Running the code:
+ts-node ddbdoc_get_item.ts
+*/
+// snippet-start:[dynamodb.JavaScript.docClient.getV3]
+
+// Import required AWS SDK clients and commands for Node.js
+const { DynamoDB } = require("@aws-sdk/client-dynamodb");
+const { marshall, unmarshall } = require("@aws-sdk/util-dynamodb");
+
+// Set the parameters
+const params = {
+  TableName: "TABLE_NAME",
+  /*
+  Convert the key JavaScript object you are retrieving to the required DynamoDB format. The format of values specifies
+  the datatype. The following list demonstrates different datatype formatting requirements:
+  HashKey: "hashKey",
+  NumAttribute: 1,
+  BoolAttribute: true,
+  ListAttribute: [1, "two", false],
+  MapAttribute: { foo: "bar" },
+  NullAttribute: null
+   */
+  Key: marshall({
+    primaryKey: VALUE, // For example, "Season: 2"
+    sortKey: VALUE, // For example,  "Episode: 1" (only required if table has sort key)
+  }),
+};
+
+// Create DynamoDB document client
+const client = new DynamoDB({ region: "REGION" });
+
+const run = async () => {
+  try {
+    const { Item } = await client.getItem(params);
+    // Convert the DynamoDB record you retrieved into a JavaScript object
+    unmarshall(Item);
+    // Print the JavaScript object to console
+    console.log(Item);
+  } catch (err) {
+    console.log("Error", err);
+  }
+};
+run();
+// snippet-end:[dynamodb.JavaScript.docClient.getV3]

javascriptv3/example_code/dynamodb/src/ddbdoc_put_item.ts

@@ -0,0 +1,62 @@
+/* Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+SPDX-License-Identifier: Apache-2.0
+
+ABOUT THIS NODE.JS EXAMPLE: This example works with AWS SDK for JavaScript version 3 (v3),
+which is pending release.  The preview version of the SDK is available
+at https://github.com/aws/aws-sdk-js-v3. This example is in the 'AWS SDK for JavaScript v3 Developer Guide' at
+https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/dynamodb-example-document-client.html.
+
+Purpose:
+ddbdoc_put_item.ts demonstrates how to use DynamoDB utilities to create or replace an item in an Amazon DynamoDB table.
+
+Inputs (replace in code):
+- TABLE_NAME
+- REGION
+- primaryKey
+- sortKey (only required if table has sort key)
+- VALUE_1: Value for the primary key (The format for the datatype must match the schema. For example, if the primaryKey is a number, VALUE_1 has no inverted commas.)
+- VALUE_2: Value for the primary key (The format for the datatype must match the schema.)
+- NEW_ATTRIBUTE_1
+- NEW_ATTRIBUTE_1_VALUE
+
+Running the code:
+ts-node ddbdoc_put_item.ts
+*/
+// snippet-start:[dynamodb.JavaScript.docClient.putV3]
+
+// Import required AWS SDK clients and commands for Node.js
+const { DynamoDB } = require("@aws-sdk/client-dynamodb");
+const { marshall, unmarshall } = require("@aws-sdk/util-dynamodb");
+
+// Set the parameters
+const TableName = "TABLE_NAME";
+/*
+Convert the key JavaScript object you are creating or replacing to the required DynamoDB format. The format
+of values specifies the datatype. The following list demonstrates different datatype formatting requirements:
+HashKey: "hashKey",
+NumAttribute: 1,
+BoolAttribute: true,
+ListAttribute: [1, "two", false],
+MapAttribute: { foo: "bar" },
+NullAttribute: null
+ */
+const input = {
+    primaryKey: VALUE, // For example, "Season: 2"
+    sortKey: VALUE // For example,  "Episode: 2" (only required if table has sort key)
+    NEW_ATTRIBUTE_1: NEW_ATTRIBUTE_1_VALUE //For example "'Title': 'The Beginning'"
+};
+// Marshall util converts then JavaScript object to DynamoDB format
+const Item = marshall(input);
+
+// Create DynamoDB document client
+const client = new DynamoDB({ region:"REGION" });
+
+const run = async () => {
+    try {
+        const data = await client.putItem({ TableName, Item });
+        console.log('Success - put')}
+    catch(err){
+        console.log('Error', err)}
+}
+run();
+// snippet-end:[dynamodb.JavaScript.docClient.putV3]

javascriptv3/example_code/dynamodb/src/ddbdoc_query_item.ts

@@ -0,0 +1,63 @@
+/* Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+SPDX-License-Identifier: Apache-2.0
+
+ABOUT THIS NODE.JS EXAMPLE: This example works with AWS SDK for JavaScript version 3 (v3),
+which is pending release.  The preview version of the SDK is available
+at https://github.com/aws/aws-sdk-js-v3. This example is in the 'AWS SDK for JavaScript v3 Developer Guide' at
+https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/dynamodb-example-document-client.html.
+
+Purpose:
+ddbdoc_update_query.ts demonstrates how to use DynamoDB utilities to retrieve items from an Amazon DynamoDB table.
+
+Inputs (replace in code):
+- TABLE_NAME
+- REGION
+
+Running the code:
+ts-node ddbdoc_update_query.ts
+*/
+// snippet-start:[dynamodb.JavaScript.docClient.queryV3]
+
+// Import required AWS SDK clients and commands for Node.js
+const { DynamoDB } = require("@aws-sdk/client-dynamodb");
+const { marshall, unmarshall } = require("@aws-sdk/util-dynamodb");
+
+// Set the parameters
+const params = {
+  TableName: "TABLE_NAME",
+  /*
+  Convert the JavaScript object defining the objects to the required DynamoDB format.The format of values
+  specifies the datatype. The following list demonstrates different datatype formatting requirements:
+  HashKey: "hashKey",
+  NumAttribute: 1,
+  BoolAttribute: true,
+  ListAttribute: [1, "two", false],
+  MapAttribute: { foo: "bar" },
+  NullAttribute: null
+   */
+  ExpressionAttributeValues: marshall({
+    ":s": 2,
+    ":e": 9,
+    ":topic": "The Return",
+  }),
+  // Specifies the values that define the range of the retrieved items. In this case, items in Season 2 before episode 9.
+  KeyConditionExpression: "Season = :s and Episode > :e",
+  // Filter that returns only episodes that meet previous criteria and have the subtitle 'The Return'
+  FilterExpression: "contains (Subtitle, :topic)",
+};
+
+// Create DynamoDB document client
+const client = new DynamoDB({ region: "us-east-1" });
+
+const run = async () => {
+  try {
+    const data = await client.query(params);
+    console.log("Success - query");
+    console.log(data.Items);
+  } catch (err) {
+    console.log("Error", err);
+  }
+};
+run();
+
+// snippet-end:[dynamodb.JavaScript.docClient.queryV3]

javascriptv3/example_code/dynamodb/src/ddbdoc_update_item.ts

@@ -0,0 +1,65 @@
+/* Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+SPDX-License-Identifier: Apache-2.0
+
+ABOUT THIS NODE.JS EXAMPLE: This example works with AWS SDK for JavaScript version 3 (v3),
+which is pending release.  The preview version of the SDK is available
+at https://github.com/aws/aws-sdk-js-v3. This example is in the 'AWS SDK for JavaScript v3 Developer Guide' at
+https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/dynamodb-example-document-client.html.
+
+Purpose:
+ddbdoc_update_item.ts demonstrates how to use DynamoDB utilities to create or update an item in an Amazon DynamoDB table.
+
+Inputs (replace in code):
+- TABLE_NAME
+- REGION
+- NEW_ATTRIBUTE_VALUE_1
+- NEW_ATTRIBUTE_VALUE_2
+
+Running the code:
+ts-node ddbdoc_update_item.ts
+*/
+// snippet-start:[dynamodb.JavaScript.docClient.updateV3]
+
+// Import required AWS SDK clients and commands for Node.js
+const { DynamoDB } = require("@aws-sdk/client-dynamodb");
+const { marshall, unmarshall } = require("@aws-sdk/util-dynamodb");
+
+// Set the parameters
+const params = {
+  TableName: "TABLE_NAME",
+  // Convert the key JavaScript object you are deleting to the required DynamoDB format
+  Key: marshall({
+    primaryKey: VALUE, // For example, "Season: 2"
+    sortKey: VALUE, // For example,  "Episode: 1" (only required if table has sort key)
+  }),
+  // Define expressions for the new or updated attributes
+  UpdateExpression: "set ATTRIBUTE_NAME_1 = :t, ATTRIBUTE_NAME_2 = :s", // For example, "'set Title = :t, Subtitle = :s'"
+  /*
+  Convert the attribute JavaScript object you are deleting to the required DynamoDB format. The format of values
+  specifies the datatype. The following list demonstrates different datatype formatting requirements:
+  HashKey: "hashKey",
+  NumAttribute: 1,
+  BoolAttribute: true,
+  ListAttribute: [1, "two", false],
+  MapAttribute: { foo: "bar" },
+  NullAttribute: null
+   */
+  ExpressionAttributeValues: marshall({
+    ":t": NEW_ATTRIBUTE_VALUE_1, // For example "':t' : 'NEW_TITLE'"
+    ":s": NEW_ATTRIBUTE_VALUE_2, // For example " ':s' : 'NEW_SUBTITLE'"
+  }),
+};
+
+// Create DynamoDB document client
+const client = new DynamoDB({ region: "REGION" });
+
+const run = async () => {
+  try {
+    const { Item } = await client.updateItem(params);
+    console.log("Success - updated");
+  } catch (err) {
+    console.log("Error", err);
+  }
+};
+run();
+// snippet-end:[dynamodb.JavaScript.docClient.updateV3]

javascriptv3/example_code/dynamodb/src/metadata.yaml

@@ -34,6 +34,21 @@ files:
   - path: ddb_scan.ts
     services:
       - dynamodb
+  - path: ddbdoc_delete_item.ts
+    services:
+      - dynamodb
+  - path: ddbdoc_get_item.ts
+    services:
+      - dynamodb
+  - path: ddbdoc_put_item.ts
+    services:
+      - dynamodb
+  - path: ddbdoc_update_item.ts
+    services:
+      - dynamodb
+  - path: ddbdoc_query_item.ts
+    services:
+      - dynamodb
   - path: QueryExample/ddb_batchwriteitem_tv.ts
     services:
       - dynamodb