AWS DynamoDB integration

Overview

AWS DynamoDB action node for NoSQL key-value and document database operations. Supports create/update (PutItem), get (GetItem), get many (Scan or Query with pagination), and delete (DeleteItem). Uses the AWS SDK v3 DynamoDB Document Client for automatic type marshalling between JavaScript native types and DynamoDB attribute types. Supports condition expressions, projection expressions, filter expressions, expression attribute names/values, secondary index queries, and configurable read consistency.

Node Type

Action — processes input items and produces output

Input / Output

Direction	Port(s)
Input	Input
Output	Output, Error

Credentials

This tool requires AWS DynamoDB credentials. See the Credentials Guide for setup instructions.

Resources

Resource	Value
Item	item

Operations

Operation	Value	Description
Create or Update	upsert	Create a new item, or replace the current one if it already exists (PutItem)
Delete	delete	Delete an item by primary key
Get	get	Get a single item by primary key
Get Many	getAll	Get many items via Scan or Query

Parameters

Item: Create or Update

Parameter	Type	Required	Default	Description
Table Name	string	Yes	—	The DynamoDB table name. You can find table names in the AWS DynamoDB console.
Data to Send	options	No	defineBelow	Whether to auto-map input data or define fields manually.
				Options: autoMapInputData (use when node input properties match destination column names), defineBelow (set the value for each destination column)
Inputs to Ignore	string	No	—	Comma-separated list of input properties to skip. Leave empty to send all properties. (shown when Data to Send is autoMapInputData)
Fields to Send	fixedCollection	No	{}	(shown when Data to Send is defineBelow)
— Field ID	string	No	—	The attribute name in DynamoDB.
— Field Value	string	No	—	The attribute value.
Additional Fields	collection	No	{}
				Options: N, stronglyConsistentRead
— Condition Expression	string	No	—	A condition that must be satisfied for a conditional upsert to succeed. See AWS PutItem API docs.
— Expression Attribute Values	fixedCollection	No	{}	Substitution tokens for attribute names in an expression. Only needed when Condition Expression is set.
— — Attribute	string	No	—
— — Type	options	No	S
				Options: N, S
— — Value	string	No	—
— Expression Attribute Names	fixedCollection	No	{}	Substitution tokens for attribute names in an expression.
— — Key	string	No	—
— — Value	string	No	—

Item: Delete

Parameter	Type	Required	Default	Description
Table Name	string	Yes	—	The DynamoDB table name. You can find table names in the AWS DynamoDB console.
Return	options	No	NONE	Whether to return the item attributes as they appeared before deletion.
				Options: ALL_OLD (return the content of the old item), NONE (nothing is returned)
Keys	fixedCollection	No	{}	Item’s primary key. For a simple primary key, provide only the partition key. For a composite key, provide both partition key and sort key.
				Options: B
— Key	string	No	—
— Type	options	No	S
				Options: B, N, S
— Value	string	No	—
Simplify	boolean	No	true	Whether to return a simplified version of the response instead of the raw data. (shown when Return is ALL_OLD)
Additional Fields	collection	No	{}
				Options: N, stronglyConsistentRead
— Condition Expression	string	No	—	A condition that must be satisfied for a conditional delete to succeed.
— Expression Attribute Names	fixedCollection	No	{}	Substitution tokens for attribute names in an expression.
— — Key	string	No	—
— — Value	string	No	—
— Expression Attribute Values	fixedCollection	No	{}	Substitution tokens for attribute values in an expression. Only needed when Condition Expression is set.
— — Attribute	string	No	—
— — Type	options	No	S
				Options: N, S
— — Value	string	No	—

Item: Get

Parameter	Type	Required	Default	Description
Table Name	string	Yes	—	The DynamoDB table name. You can find table names in the AWS DynamoDB console.
Select (getSelect)	options	No	ALL_ATTRIBUTES	Which attributes GetItem returns for the single item. “SPECIFIC_ATTRIBUTES” narrows the read to the Attributes to Select listed under Additional Fields. GetItem has no COUNT mode — to count items use the getAll operation.
				Options: ALL_ATTRIBUTES, ALL_PROJECTED_ATTRIBUTES, SPECIFIC_ATTRIBUTES (select them in Attributes to Select under Additional Fields)
Simplify	boolean	No	true	Whether to return a simplified version of the response instead of the raw data. (shown when Select is ALL_PROJECTED_ATTRIBUTES, ALL_ATTRIBUTES)
Keys	fixedCollection	No	{}	Item’s primary key. For a simple primary key, provide only the partition key. For a composite key, provide both partition key and sort key.
				Options: B
— Key	string	No	—
— Type	options	No	S
				Options: B, N, S
— Value	string	No	—
Additional Fields	collection	No	{}
				Options: N, stronglyConsistentRead
— Attributes to Select	string	No	—	Comma-separated list of attributes to retrieve (projection expression).
— Expression Attribute Names	fixedCollection	No	{}	Substitution tokens for attribute names in an expression.
— — Key	string	No	—
— — Value	string	No	—
— Read Type	options	No	eventuallyConsistentRead	Type of read to perform on the table.
				Options: stronglyConsistentRead, eventuallyConsistentRead

Item: Get Many

Parameter	Type	Required	Default	Description
Table Name	string	Yes	—	The DynamoDB table name. You can find table names in the AWS DynamoDB console.
Scan	boolean	No	false	Whether to use Scan (reads all items) or Query (uses key condition). Scan is less efficient but does not require a key condition expression.
Key Condition Expression	string	Yes	—	Condition to determine items to retrieve. Must perform an equality test on a single partition key value, e.g. “partitionKeyName = :partitionkeyval”. (shown when Scan is false)
Expression Attribute Values	fixedCollection	No	{}	Substitution tokens for attribute values in an expression.
				Options: N
— Attribute	string	No	—
— Type	options	No	S
				Options: N, S
— Value	string	No	—
Return All	boolean	No	false	Whether to return all results or only up to a given limit.
Limit	number	No	50	Max number of results to return. (shown when Return All is false)
Select (select)	options	No	ALL_ATTRIBUTES	The DynamoDB Select mode for the Query or Scan behind getAll. “COUNT” returns only Count and ScannedCount — no items, no projection and no limit are applied.
				Options: ALL_ATTRIBUTES, ALL_PROJECTED_ATTRIBUTES, COUNT, SPECIFIC_ATTRIBUTES (select them in Attributes to Select under Options)
Simplify	boolean	No	true	Whether to return a simplified version of the response instead of the raw data. (shown when Select is ALL_PROJECTED_ATTRIBUTES, ALL_ATTRIBUTES, SPECIFIC_ATTRIBUTES)
Options	collection	No	{}
— Index Name	string	No	—	Name of the secondary index to query. Can be any local or global secondary index on the table.
— Attributes to Select	string	No	—	Comma-separated list of attributes to retrieve. These can include scalars, sets, or elements of a JSON document.
— Filter Expression	string	No	—	Conditions applied after the Query but before data is returned. Items that do not satisfy this expression are not returned. (shown when /scan is false)
— Expression Attribute Names	fixedCollection	No	{}	Substitution tokens for attribute names in an expression.
— — Key	string	No	—
— — Value	string	No	—

All Operations

Parameter	Type	Required	Default	Description
Filter Expression	string	No	—	A filter expression to apply during Scan. Items that do not satisfy this expression are discarded. Leave empty to return all items. (shown when Scan is true)
Max Concurrency	number	No	10	Maximum number of items to process concurrently.

Output Data

Results are merged onto the input item’s JSON, so the properties you started with remain available alongside the DynamoDB attributes. The Document Client marshals DynamoDB attribute types to native JSON, so values arrive as plain strings, numbers, booleans, lists and maps — not as {"S": "..."} wrappers. Binary data on the input item is forwarded.

Operation	Output
upsert	One item per input item, carrying the attributes that were written.
get	One item per input item, carrying the item’s attributes. A key that matches nothing produces the input item unchanged.
delete	One item per input item. With Return set to NONE the item carries success: true; with ALL_OLD it carries the attributes as they were immediately before deletion.
getAll	Fans out — one output item per row returned. A Scan or Query that matches nothing emits one item, which is the input item passed through unchanged.
getAll with Select = COUNT	One item per input item carrying Count and ScannedCount instead of rows.

With Simplify on (the default), attributes with no value are dropped from the result; turn it off to keep the response exactly as DynamoDB returned it.

Reference attributes downstream by name, e.g. {{ $json.userId }} or {{ $json.Count }}.

Example Configuration

Write the incoming item straight into a table, dropping workflow-only properties:

{
  "type": "aws_dynamodb",
  "parameters": {
    "resource": "item",
    "operation": "upsert",
    "tableName": "users",
    "dataToSend": "autoMapInputData",
    "inputsToIgnore": "_error,_metadata"
  }
}

Write named attributes only, and refuse to overwrite an existing row:

{
  "type": "aws_dynamodb",
  "parameters": {
    "resource": "item",
    "operation": "upsert",
    "tableName": "users",
    "dataToSend": "defineBelow",
    "fieldsUi": {
      "fieldValues": [
        { "fieldId": "userId", "fieldValue": "{{ $json.id }}" },
        { "fieldId": "email", "fieldValue": "{{ $json.email }}" },
        { "fieldId": "status", "fieldValue": "active" }
      ]
    },
    "additionalFields": {
      "conditionExpression": "attribute_not_exists(userId)"
    }
  }
}

Read one item by composite key, strongly consistent:

{
  "type": "aws_dynamodb",
  "parameters": {
    "resource": "item",
    "operation": "get",
    "tableName": "orders",
    "select": "ALL_ATTRIBUTES",
    "simple": true,
    "keysUi": {
      "keyValues": [
        { "key": "customerId", "type": "S", "value": "{{ $json.customerId }}" },
        { "key": "orderDate", "type": "S", "value": "{{ $json.orderDate }}" }
      ]
    },
    "additionalFields": {
      "readType": "stronglyConsistentRead",
      "projectionExpression": "customerId, orderDate, total"
    }
  }
}

Query a partition and page through every match:

{
  "type": "aws_dynamodb",
  "parameters": {
    "resource": "item",
    "operation": "getAll",
    "tableName": "orders",
    "scan": false,
    "keyConditionExpression": "customerId = :cid",
    "eavUi": {
      "eavValues": [
        { "attribute": ":cid", "type": "S", "value": "{{ $json.customerId }}" }
      ]
    },
    "returnAll": true,
    "select": "ALL_ATTRIBUTES",
    "simple": true
  }
}

Scan a table with a filter, capped at 50 rows:

{
  "type": "aws_dynamodb",
  "parameters": {
    "resource": "item",
    "operation": "getAll",
    "tableName": "users",
    "scan": true,
    "filterExpression": "#st = :active",
    "eavUi": {
      "eavValues": [
        { "attribute": ":active", "type": "S", "value": "active" }
      ]
    },
    "returnAll": false,
    "limit": 50,
    "select": "ALL_ATTRIBUTES",
    "options": {
      "eanUi": {
        "eanValues": [
          { "key": "#st", "value": "status" }
        ]
      }
    }
  }
}

Query a global secondary index and return only the matching count:

{
  "type": "aws_dynamodb",
  "parameters": {
    "resource": "item",
    "operation": "getAll",
    "tableName": "orders",
    "scan": false,
    "keyConditionExpression": "email = :email",
    "eavUi": {
      "eavValues": [
        { "attribute": ":email", "type": "S", "value": "{{ $json.email }}" }
      ]
    },
    "select": "COUNT",
    "options": {
      "indexName": "email-index"
    }
  }
}

Delete by key and keep a copy of what was removed:

{
  "type": "aws_dynamodb",
  "parameters": {
    "resource": "item",
    "operation": "delete",
    "tableName": "users",
    "keysUi": {
      "keyValues": [
        { "key": "userId", "type": "S", "value": "{{ $json.id }}" }
      ]
    },
    "returnValues": "ALL_OLD",
    "simple": true
  }
}

Error Handling

Mode	Behavior
stop	Halts workflow on first error
continue	Skips failed items, passes successful ones through
errorPort	Routes failed items to Error output port

Tips

AWS DynamoDB puts, gets, scans, queries and deletes items in a DynamoDB table. It is the right tool when a workflow must read or write a NoSQL item by its key, or fetch many items by a key condition or a full scan, in DynamoDB rather than a relational database or a spreadsheet. It returns items as plain JSON with native types unmarshalled, getAll paging through the results, and the written or deleted key for the other operations.