DynamoDB Batch

Performs bulk DynamoDB operations — insert/delete many items at once (BatchWrite) or retrieve many items by key at once (BatchGet). Handles chunking and retry automatically.

Inputs

payload.tableName string

Overrides the Table Name set in the node config.

payload.batchOperation string

Override the operation at runtime: "batchWrite" or "batchGet".

payload.puts array

Array of item objects to insert (BatchWrite). Each item must include all key attributes.

payload.deletes array

Array of key objects to delete (BatchWrite). Example: [{ id: "epic-A", sk: "token" }]

payload.keys array

Array of key objects to retrieve (BatchGet). Example: [{ id: "epic-A", sk: "token" }]

Outputs

Output 1 — Success (BatchWrite)

payload.success boolean

true when the batch completed (even if some items were unprocessed).

payload.processed number

Total items successfully written.

payload.unprocessed number

Items that could not be written after all retry attempts. Should be 0. If > 0, consider re-queuing.

payload.putCount number

Number of items in the puts array.

payload.deleteCount number

Number of items in the deletes array.

Output 1 — Success (BatchGet)

payload.items array

Array of retrieved items. Order is not guaranteed.

payload.found number

Number of items returned.

payload.requested number

Number of keys requested. If found < requested, some keys did not exist in the table.

Output 2 — Error

payload.errorType string

Human-readable error category.

payload.solution string

Suggested fix.

How to Use — BatchWrite

1. Set Operation to BatchWrite.
2. Set msg.payload.puts to an array of item objects to insert. Each item must include all key attributes.
3. Optionally set msg.payload.deletes to an array of key objects to delete.
4. The node automatically chunks into batches of 25 and retries any UnprocessedItems with exponential backoff.
5. Check msg.payload.unprocessed on output 1 — if > 0, some items were not written after all retries.

How to Use — BatchGet

1. Set Operation to BatchGet (or override at runtime via msg.payload.batchOperation).
2. Set msg.payload.keys to an array of key objects to retrieve.
3. The node chunks into batches of 100 and returns all found items in msg.payload.items.
4. Missing keys are silently absent — no error. Compare found vs requested to detect gaps.

ConnectHealth Example

Bulk-insert FHIR Patient demographics into DynamoDB after a bulk export:

// BatchWrite — insert 500 patients at once:
msg.payload = {
  puts: patients.map(p => ({
    id: "patient#" + p.id,
    sk: "demographics",
    name: p.name,
    dob: p.birthDate,
    mrn: p.identifier
  }))
};
// Output 1: { success: true, processed: 500, unprocessed: 0 }

// BatchGet — retrieve tokens for multiple integrations:
msg.payload = {
  batchOperation: "batchGet",
  keys: [
    { id: "epic-hospital-A", sk: "oauth_token" },
    { id: "cerner-clinic-B", sk: "oauth_token" },
    { id: "hl7-gateway-X",   sk: "session" }
  ]
};
// Output 1: { items: [...], found: 3, requested: 3 }

Best Practices

• Check msg.payload.unprocessed after BatchWrite — a non-zero value means some items were throttled and need to be re-queued.
• BatchGet does not error on missing keys — always compare found vs requested to detect items that don't exist.
• For very large datasets (10,000+ items), use a Function node to split the array into smaller chunks and loop through them, rather than sending everything in one message.
• BatchWrite supports mixed puts and deletes in one call — use this for atomic swap operations.