DestinationsOtherAmazon DynamoDB

Amazon DynamoDB

Write data to Amazon DynamoDB tables using BatchWriteItem and PutItem operations. Use Zeotap to materialize model results, enriched profiles, or lookup tables into DynamoDB for low-latency key-value access.

Prerequisites

  • An AWS account with DynamoDB access
  • A DynamoDB table created in the target region with the appropriate partition key (and optional sort key) defined
  • An IAM user or role with dynamodb:BatchWriteItem, dynamodb:PutItem, and dynamodb:DescribeTable permissions on the target table
  • AWS access key ID and secret access key for the IAM user

Permissions

The IAM policy attached to your credentials must include the following actions on the target table:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "dynamodb:BatchWriteItem",
        "dynamodb:PutItem",
        "dynamodb:DescribeTable"
      ],
      "Resource": "arn:aws:dynamodb:REGION:ACCOUNT_ID:table/TABLE_NAME"
    }
  ]
}

Replace REGION, ACCOUNT_ID, and TABLE_NAME with your actual values.

Authentication

DynamoDB uses AWS Access Keys for authentication.

  1. In the AWS Console, navigate to IAM > Users > your user > Security credentials
  2. Click Create access key and copy the Access Key ID and Secret Access Key
  3. Enter both values in Zeotap when configuring the destination

Configuration

FieldTypeRequiredDescription
AWS RegionSelectYesThe AWS region where your DynamoDB table is located (e.g., us-east-1)

Target Settings

FieldTypeRequiredDescription
Table NameTextYesThe name of the DynamoDB table to write to

Supported Operations

Sync Modes

ModeSupportedDescription
UpsertYesWrites items using PutItem semantics — creates new items or fully replaces existing items with the same partition key
InsertYesWrites new items to the table. Items with duplicate keys will overwrite existing items (DynamoDB PutItem behavior)
Update—Not supported. DynamoDB PutItem replaces the entire item rather than merging individual attributes
Mirror—Not supported. DynamoDB does not support efficient full-table replacement

Audience Sync Modes

ModeSupported
Add—
Remove—
Mirror—
Upsert—

DynamoDB does not have a native list or audience membership concept, so audience sync modes are not supported.

Features

  • Field Mapping: Yes — map source columns to DynamoDB attribute names
  • Schema Introspection: No — DynamoDB is schemaless; attribute names are defined by the data you write

How It Works

  1. Batch preparation: Zeotap converts each row into a DynamoDB attribute map with appropriate type descriptors (S for strings, N for numbers, BOOL for booleans, NULL for null values)
  2. Chunked writes: Rows are sent using the BatchWriteItem API in chunks of up to 25 items per request (the DynamoDB maximum)
  3. Unprocessed items: If DynamoDB returns unprocessed items (due to throughput throttling), they are reported as errors in the sync run
  4. Authentication: All requests are signed using AWS Signature Version 4 (SigV4) with your access key credentials

Type Mapping

Source TypeDynamoDB Type
StringS (String)
Number (integer or float)N (Number)
BooleanBOOL (Boolean)
NullNULL
Complex (object, array)S (JSON-serialized string)

Empty strings are stored as NULL since DynamoDB does not allow empty string attribute values.

Rate Limits

DynamoDB throughput depends on your table’s provisioned capacity or on-demand configuration:

  • On-demand mode: Automatically scales to handle any traffic level. Initial throughput accommodates up to 40,000 write request units per second
  • Provisioned mode: Limited to the write capacity units (WCUs) you configure. Each WCU supports one write per second for items up to 1 KB
  • BatchWriteItem: Accepts up to 25 items per request, with a total payload limit of 16 MB
  • Individual item size: Maximum 400 KB per item

If you encounter ProvisionedThroughputExceededException errors, consider switching to on-demand mode or increasing your provisioned WCUs.

Best Practices

  • Define partition keys carefully: Ensure your mapped fields include the table’s partition key (and sort key if applicable). Items without the correct key attributes will fail
  • Use on-demand capacity for variable or bursty sync workloads to avoid throttling
  • Keep items small: DynamoDB has a 400 KB item size limit. Avoid syncing large text or JSON fields
  • Monitor throughput: Use CloudWatch metrics (ConsumedWriteCapacityUnits, ThrottledRequests) to track sync impact on your table

Troubleshooting

Access denied / 403 error

Verify that the IAM user’s policy includes dynamodb:BatchWriteItem, dynamodb:PutItem, and dynamodb:DescribeTable on the target table ARN. Double-check the region in the table ARN matches your configuration.

Table not found / ResourceNotFoundException

Confirm the table name is spelled correctly and exists in the configured AWS region. Table names are case-sensitive.

Provisioned throughput exceeded

Your table’s write capacity is insufficient for the sync volume. Switch to on-demand capacity mode or increase provisioned WCUs in the AWS Console.

Validation error on items

DynamoDB requires that every item includes the table’s partition key attribute (and sort key if defined). Ensure your field mapping includes these key attributes.

Items larger than 400 KB

DynamoDB rejects items exceeding 400 KB. Reduce the number of mapped fields or avoid syncing large text/JSON columns.

Unprocessed items in batch

When DynamoDB cannot process all items in a BatchWriteItem request (usually due to throttling), Zeotap reports them as failed rows. Increase table capacity or reduce sync frequency to resolve.

AirtableElasticsearch