dynamo.adapter Integration Documentation

Overview

The dynamo.adapter serves as an integration layer for Amazon DynamoDB within the Vantage analytics and data platform. It allows users to perform both read and write operations on DynamoDB tables, manage table schemas, and execute schema introspection. The integration is built with AWS SDK for JavaScript to provide a seamless connection to DynamoDB, enabling easy manipulation of data with enhanced security through encrypted credentials.

Settings

The dynamo.adapter consists of various settings that configure its behavior and parameters for connecting to a DynamoDB instance. Below is a detailed explanation of each setting.

1. Region

• Input Type: String
• Description: Specifies the AWS region where the DynamoDB instance is hosted. Adjusting this value allows users to connect to different regional deployments of DynamoDB to align with specific data locality requirements.
• Default Value: us-east-1.

2. AccessKeyId

• Input Type: String
• Description: The identification key used to authenticate API requests made to DynamoDB. Modifying this will change the identity under which the operations are executed, thus affecting access permissions.
• Default Value: None (must be set by the user).

3. SecretAccessKey

• Input Type: String
• Description: A secret key used in conjunction with AccessKeyId to authenticate API requests to DynamoDB. Changing this key will invalidate the previous credentials, resulting in access issues if not kept consistent.
• Default Value: None (must be set by the user).

Functionality

The dynamo.adapter operates by instantiating a DynamoDBClient using the provided credentials.

Connection Testing

The function testConnection checks whether the integration can successfully connect to the DynamoDB instance by attempting to list the tables. It returns true if successful, or false along with an error message if a connection issue occurs.

Schema Introspection

• listTables: Retrieves and lists all DynamoDB tables in the specified region.
• describeTable: Provides detailed information about specific tables, including key schema, data attributes, global secondary indexes, item count, and status.

Read Operations

The adapter supports the following read operations:

• query
• scan
• getItem
• batchGetItem

The function executeReadOnly can be used to perform any of these operations, ensuring compliance with read-only permissions.

Write Operations

The adapter supports the following write operations:

• putItem
• updateItem
• deleteItem
• batchWriteItem

The function executeWrite is designed to carry out these operations while enforcing write operation permissions.

Table Management

The integration allows users to create tables with the createTable method, which requires the table name, key schema, and attribute definitions, as well as optional throughput settings. It determines the billing mode based on whether provisioned throughput is specified.

Cleanup

Finally, the close method is used to clean up resources and close the connection to the DynamoDB client when operations are completed.

Use Cases & Examples

Use Case 1: Data Migration

An organization wants to migrate its existing user profile data stored in a relational database to a DynamoDB instance for improved scalability and performance.

Use Case 2: Analytics Dashboard

A business needs to dynamically query markets based on product performance stored in a DynamoDB table for real-time analytics on a dashboard platform.

Detailed Example

Use Case: Analytics Dashboard

Configuration: In order to query product performance data from the Products table, the following configuration could be utilized:

{
  "settings": {
    "region": "us-west-2",
    "accessKeyId": "YOUR_ACCESS_KEY_ID",
    "secretAccessKey": "YOUR_SECRET_ACCESS_KEY"
  },
  "operation": "query",
  "params": {
    "TableName": "Products",
    "KeyConditionExpression": "ProductID = :productId",
    "ExpressionAttributeValues": {
      ":productId": { "S": "12345" }
    }
  }
}

This configuration specifies that the integration connects to a DynamoDB instance in the us-west-2 region, authenticates with provided keys, and performs a query operation to retrieve product details relevant to a specific ProductID.