AWS1 input → 2 outputs

DynamoDB Query

Retrieves multiple items from a DynamoDB table using a key condition, with optional sort key filtering, attribute filtering, and pagination.

Inputs

payload.tableName string: Overrides the Table Name set in the node config.
payload.keyConditionExpression string: Full KeyConditionExpression — overrides both Simple and Advanced mode config.
payload.expressionAttributeNames object: Attribute name aliases for expressions (#pk → id).
payload.expressionAttributeValues object: Attribute value aliases for expressions (:pk → "epic-A").
payload.filterExpression string: Filter applied after key lookup (non-key attributes).
payload.nextToken object: Pagination cursor from a previous query's msg.dynamodb.nextToken.

Outputs

Output 1 — Success

payload.items array: Array of matching items for this page.
payload.count number: Number of items returned after filtering.
payload.scannedCount number: Number of items read from the index before filtering (may be higher than count).
dynamodb.nextToken object | null: Pagination cursor for the next page. null when no more pages exist.

Output 2 — Error

payload.errorType string: Human-readable error category.
payload.solution string: Suggested fix.

How to Use

Select an AWS config node and enter the Table Name.
Choose Simple Mode to use the visual key builder, or Advanced Mode to write raw expressions.
In Simple Mode, enter the Partition Key name and value — this is always required by AWS DynamoDB.
Optionally add a Sort Key condition to narrow results within the partition.
Optionally add Filters via the Visual Filter Builder to filter by non-key attributes.
Set a Limit for paginated APIs, or enable Auto-paginate to collect all pages.
Wire Output 1 to process the items array, and Output 2 for errors.

Query vs Scan

Always prefer Query over Scan. Query uses the key index (fast, cost-efficient). Scan reads the entire table (slow, expensive). Use Query whenever you know the partition key value.

Sort Key Operators

= operator: Exact match. Example: sk = "oauth_token"
begins_with operator: Sort key starts with the given string. Example: begins_with(sk, "session#") — great for prefixed sort keys.
between operator: Sort key falls between two values (inclusive). Requires SK Value and SK Value 2.
<, <=, >, >= operators: Range comparisons. Useful for timestamp-based sort keys.

FilterExpression vs KeyCondition

A KeyCondition limits what DynamoDB reads from the disk. A FilterExpression narrows the results after DynamoDB has read the items from the disk. It does not reduce the number of items read — you are still charged for reading all items in the partition matching the key condition. Use the Filter Builder for non-key attributes only.

Pagination

Set a Limit to get one page at a time. The next-page cursor is in msg.dynamodb.nextToken. Pass it back as msg.payload.nextToken to get the next page. Enable Auto-paginate to collect all pages in one message automatically — use with caution on large datasets.

ConnectHealth Example

Get all active session records for a specific workflow, ordered by time (sort key prefix):

// Simple Mode config:
// Partition Key Name: id   Value: workflow-abc-123
// Sort Key Name: sk        Operator: begins_with   Value: session#
// Filter: status = active

// Output 1:
msg.payload = {
  items: [
    { id: "workflow-abc-123", sk: "session#2024-01-01T10:00:00", status: "active" },
    { id: "workflow-abc-123", sk: "session#2024-02-15T14:30:00", status: "active" }
  ],
  count: 2,
  scannedCount: 5 // Dynamo read 5, but filtered out 3 non-active ones
};
msg.dynamodb.nextToken = null; // no more pages

Best Practices

Always set a Limit in production — unbounded queries on large partitions can be slow and expensive.
Design sort keys with a prefix pattern (e.g. session#, audit#) so you can use begins_with to retrieve related items efficiently.
Use a GSI (Global Secondary Index) and the Index Name field to query on non-key attributes (e.g. query by patientId even when the table key is integrationId).
If scannedCount is much larger than count, your FilterExpression is filtering many items — consider restructuring your key design to push the filter into the key condition.

// Simple Mode config: // Partition Key Name: id Value: workflow-abc-123 // Sort Key Name: sk Operator: begins_with Value: session# // Filter: status = active // Output 1: msg.payload = { items: [ { id: "workflow-abc-123", sk: "session#2024-01-01T10:00:00", status: "active" }, { id: "workflow-abc-123", sk: "session#2024-02-15T14:30:00", status: "active" } ], count: 2, scannedCount: 5 // Dynamo read 5, but filtered out 3 non-active ones }; msg.dynamodb.nextToken = null; // no more pages