<!-- BusyBot node reference — https://busybot.net/tools/aws-dynamodb/ -->

> Node: AWS DynamoDB (`aws_dynamodb`) · Action · v1
> Category: Data & Storage · Credentials: AWS DynamoDB (`awsDynamoDbApi`)
> Updated: 2026-08-16

# AWS DynamoDB

> Create, read, update, and delete items in AWS DynamoDB

## 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.

**Category:** Data & Storage  
**Tool Name:** `aws_dynamodb`  
**Version:** 1

**Appearance:** Icon: `lucide-Database` | Color: `#FF9900`

## 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](https://busybot.net/credentials/aws-dynamo-db-api/) 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 | `{}` | The attributes to write, one row per attribute. _(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 | `{}` | Optional settings for the write. |
| — Condition Expression | `string` | No | — | A condition that must be satisfied for a conditional upsert to succeed. See AWS PutItem API docs. |
| — Expression Attribute Values (`eavUi`) | `fixedCollection` | No | `{}` | Substitution tokens for attribute names in an expression. Only needed when Condition Expression is set. |
| — — Attribute | `string` | No | — | The token used in the expression, for example `:status`. |
| — — Type | `options` | No | `S` | The DynamoDB attribute type of the value. |
| | | | | Options: `N` (number), `S` (string) |
| — — Value | `string` | No | — | The value substituted for the token. |
| — Expression Attribute Names (`eanUi`) | `fixedCollection` | No | `{}` | Substitution tokens for attribute names in an expression. |
| — — Key | `string` | No | — | The token used in the expression, for example `#name`. |
| — — Value | `string` | No | — | The real attribute name the token stands for. |

#### 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. |
| 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. |
| — Key | `string` | No | — | The key attribute name. |
| — Type | `options` | No | `S` | The DynamoDB attribute type of the key. |
| | | | | Options: `B` (binary), `N` (number), `S` (string) |
| — Value | `string` | No | — | The key value to match. |
| 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) |
| 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 | `{}` | Optional settings for the delete. |
| — Condition Expression | `string` | No | — | A condition that must be satisfied for a conditional delete to succeed. |
| — Expression Attribute Names (`eanUi`) | `fixedCollection` | No | `{}` | Substitution tokens for attribute names in an expression. |
| — — Key | `string` | No | — | The token used in the expression, for example `#name`. |
| — — Value | `string` | No | — | The real attribute name the token stands for. |
| — Expression Attribute Values (`expressionAttributeUi`) | `fixedCollection` | No | `{}` | Substitution tokens for attribute values in an expression. Only needed when Condition Expression is set. |
| — — Attribute | `string` | No | — | The token used in the expression, for example `:status`. |
| — — Type | `options` | No | `S` | The DynamoDB attribute type of the value. |
| | | | | Options: `N` (number), `S` (string) |
| — — Value | `string` | No | — | The value substituted for the token. |

#### 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. |
| 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. |
| — Key | `string` | No | — | The key attribute name. |
| — Type | `options` | No | `S` | The DynamoDB attribute type of the key. |
| | | | | Options: `B` (binary), `N` (number), `S` (string) |
| — Value | `string` | No | — | The key value to match. |
| Select | `options` | No | `ALL_ATTRIBUTES` | Which attributes to return. |
| | | | | 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`)_ |
| Additional Fields | `collection` | No | `{}` | Optional settings for the read. |
| — Attributes to Select | `string` | No | — | Comma-separated list of attributes to retrieve (projection expression). |
| — Expression Attribute Names (`eanUi`) | `fixedCollection` | No | `{}` | Substitution tokens for attribute names in an expression. |
| — — Key | `string` | No | — | The token used in the expression, for example `#name`. |
| — — Value | `string` | No | — | The real attribute name the token stands for. |
| — 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`)_ |
| 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`)_ |
| Expression Attribute Values | `fixedCollection` | No | `{}` | Substitution tokens for attribute values in an expression. |
| — Attribute | `string` | No | — | The token used in the expression, for example `:id`. |
| — Type | `options` | No | `S` | The DynamoDB attribute type of the value. |
| | | | | Options: `N` (number), `S` (string) |
| — Value | `string` | No | — | The value substituted for the token. |
| 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. Accepts 1–100. _(shown when Return All is `false`)_ |
| Select | `options` | No | `ALL_ATTRIBUTES` | Which attributes to return. |
| | | | | 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 | `{}` | Optional settings for the Scan or Query. |
| — 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 (`eanUi`) | `fixedCollection` | No | `{}` | Substitution tokens for attribute names in an expression. |
| — — Key | `string` | No | — | The token used in the expression, for example `#name`. |
| — — Value | `string` | No | — | The real attribute name the token stands for. |

#### All Operations

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Max Concurrency | `number` | No | `10` | Maximum number of items to process concurrently. Accepts 1–100. |

## 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 }}`.

## Usage Examples

- Get a user record from DynamoDB by primary key
- Create or update an item in a DynamoDB table
- Scan all items in a DynamoDB table
- Query items using a key condition expression
- Delete an item from DynamoDB by partition key and sort key

## Example Configuration

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

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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

Create, read, update, and delete items in AWS DynamoDB NoSQL tables using the AWS SDK.