DynamoDB Tables

Creating a DynamoDB table takes one command. Getting it right matters more than usual because the key schema can never be changed, no migration, no ALTER TABLE. Changing a partition key means creating a new table and copying every item across.

Everything else, capacity mode, indexes, streams, TTL, backups, can be changed later. So the decision worth slowing down for is the keys, and that decision comes from your access patterns rather than from the shape of your data.

Creating a table

aws dynamodb create-table --table-name Orders \
  --attribute-definitions \
    AttributeName=customerId,AttributeType=S \
    AttributeName=orderDate,AttributeType=S \
  --key-schema \
    AttributeName=customerId,KeyType=HASH \
    AttributeName=orderDate,KeyType=RANGE \
  --billing-mode PAY_PER_REQUEST \
  --deletion-protection-enabled \
  --tags Key=Environment,Value=production

aws dynamodb wait table-exists --table-name Orders
aws dynamodb describe-table --table-name Orders \
  --query 'Table.[TableStatus,ItemCount,TableSizeBytes,BillingModeSummary.BillingMode]'

[ "ACTIVE", 0, 0, "PAY_PER_REQUEST" ]

ItemCount and TableSizeBytes update roughly every six hours, so a freshly loaded table reporting zero items is normal rather than a failed import.

Attribute definitions only describe keys

This trips up nearly everyone coming from SQL. --attribute-definitions is not a schema. It declares the types of attributes used in keys and indexes, and nothing else. Every other attribute is arbitrary and per-item:

aws dynamodb put-item --table-name Orders --item '{
  "customerId": {"S": "C-4821"},
  "orderDate":  {"S": "2026-09-16"},
  "amount":     {"N": "149.99"},
  "items":      {"L": [{"S": "SKU-1"}, {"S": "SKU-2"}]},
  "giftNote":   {"S": "Happy birthday"}
}'

Nothing declared amount, items or giftNote, and the next item need not have them. The corollary is that declaring an attribute you do not use in a key is an error:

Only three key types exist: S (string), N (number) and B (binary).

Turn on deletion protection

aws dynamodb update-table --table-name Orders --deletion-protection-enabled

A delete-table call is immediate and takes every item with it. Deletion protection costs nothing, and it is the cheapest insurance in DynamoDB. Set it on every table that is not disposable, including in your Terraform or CloudFormation so a destroy in the wrong workspace fails loudly.

Backups: two different things

Point-in-time recovery gives continuous backup with second-level granularity for the last 35 days:

aws dynamodb update-continuous-backups --table-name Orders \
  --point-in-time-recovery-specification PointInTimeRecoveryEnabled=true

aws dynamodb restore-table-to-point-in-time \
  --source-table-name Orders \
  --target-table-name Orders-restored \
  --restore-date-time 2026-09-16T09:00:00Z

On-demand backups are explicit snapshots that live until you delete them, which is what you want before a risky migration or for retention beyond 35 days:

aws dynamodb create-backup --table-name Orders --backup-name pre-migration-2026-09-16
aws dynamodb list-backups --table-name Orders --query 'BackupSummaries[].[BackupName,BackupStatus]'

The constraint that surprises people: a restore always creates a new table. You cannot restore in place. Recovery therefore means restoring alongside, verifying, then repointing the application, so practise it before you need it, and note that indexes, TTL, streams and capacity settings are not all carried over automatically.

Table classes

aws dynamodb update-table --table-name AuditLog \
  --table-class STANDARD_INFREQUENT_ACCESS

STANDARD_INFREQUENT_ACCESS cuts storage cost substantially and raises read and write cost. It pays off when storage dominates the bill. Audit logs, historical events, anything large and rarely read. For a table serving live traffic it usually costs more. Compare TableSizeBytes against consumed capacity before switching.

Global tables

Multi-region, multi-writer replication:

aws dynamodb update-table --table-name Orders \
  --replica-updates '[{"Create": {"RegionName": "us-east-1"}}]'

Replication is asynchronous and conflicts resolve last writer wins, by the timestamp DynamoDB records. That is fine for data owned by one region at a time and wrong for anything where two regions might update the same item concurrently, a counter, an inventory level, because one update is simply discarded. Streams must be enabled, and the same key schema applies to every replica.

Loading and exporting in bulk

aws dynamodb import-table \
  --s3-bucket-source S3Bucket=my-imports,S3KeyPrefix=orders/ \
  --input-format DYNAMODB_JSON \
  --table-creation-parameters '{
    "TableName":"OrdersImported",
    "AttributeDefinitions":[{"AttributeName":"customerId","AttributeType":"S"}],
    "KeySchema":[{"AttributeName":"customerId","KeyType":"HASH"}],
    "BillingMode":"PAY_PER_REQUEST"
  }'

Import from S3 consumes no write capacity and is dramatically cheaper than looping put-item, but it can only create a new table, not add to an existing one. Export to S3 similarly consumes no read capacity and is the right way to feed Athena or a data pipeline:

aws dynamodb export-table-to-point-in-time \
  --table-arn "$TABLE_ARN" --s3-bucket my-exports --export-format DYNAMODB_JSON

Export requires PITR to be enabled.

Common errors

create-table is not idempotent. Check with describe-table first.

You declared an attribute that is not part of a key or index, or omitted one that is.

Right table name, wrong region. The most common cause by some distance. DynamoDB tables are regional.

Deletion protection is on. That is it working.

Quick reference

Key takeaways

• The key schema is permanent. Changing it means a new table and a full copy.
• Attribute definitions describe keys only: every other attribute is arbitrary per item.
• Declaring an unused attribute fails the call. Only key and index attributes belong there.
• Enable deletion protection everywhere. It is free and delete-table is instant.
• PITR covers 35 days; on-demand backups cover longer. They are different features.
• Every restore creates a new table. Practise the repoint before you need it.
• Import and export via S3 consume no capacity and are far cheaper than item-by-item loops.
• Global tables resolve conflicts last-writer-wins, which silently discards concurrent updates.

Check your understanding

<MCQExercise exercise={{ id: 'aws-ddb-tables-quiz1', title: 'A create-table call that keeps failing', description: 'A create-table command declares attribute definitions for customerId, orderDate and amount, with customerId as HASH and orderDate as RANGE. It fails validation. Why?', options: [ { id: 'a', text: 'AttributeDefinitions may only contain attributes used in the key schema or an index, and amount is neither' }, { id: 'b', text: 'Numeric attributes cannot be declared in AttributeDefinitions' }, { id: 'c', text: 'A table may define at most two attributes in total' }, { id: 'd', text: 'amount must also be added to the key schema as a second RANGE key' }, ], correctId: 'a', explanation: 'AttributeDefinitions is not a schema. DynamoDB is schemaless apart from keys. Its only job is to declare the types of attributes that appear in the key schema or in an index, so every entry must be used by one of those. Declaring amount, which is an ordinary attribute, makes the definitions and the key schema disagree and the call is rejected. Remove it: you can still write amount on any item, with any type, without declaring it anywhere.', wrongExplanations: { b: 'Numbers are a valid key type (N). The problem is that this attribute is not a key at all.', c: 'There is no such limit; a table with several indexes legitimately declares many attributes.', d: 'DynamoDB supports exactly one partition key and at most one sort key. A second RANGE key is not possible.', }, }} />

<MCQExercise exercise={{ id: 'aws-ddb-tables-quiz2', title: 'Recovering from a bad write', description: 'A faulty deployment corrupted records over two hours. The table has point-in-time recovery enabled. What does recovery actually involve?', options: [ { id: 'a', text: 'Restore to a new table at a timestamp before the deployment, verify it, then repoint the application. PITR cannot restore in place' }, { id: 'b', text: 'Run restore-table-to-point-in-time against the existing table to roll it back in place' }, { id: 'c', text: 'Replay DynamoDB Streams in reverse to undo the writes' }, { id: 'd', text: 'Nothing is possible, because PITR only protects against table deletion' }, ], correctId: 'a', explanation: 'PITR restores to any second within the last 35 days, but always into a new table. There is no in-place rollback. So recovery is a three-step operation: restore alongside the live table, verify the data is what you expect, then cut the application over. That is worth rehearsing before an incident, partly for the cutover and partly because a restored table does not automatically carry across every setting: check indexes, TTL, streams, capacity mode and deletion protection afterwards.', wrongExplanations: { b: 'The API requires a target table name distinct from the source. In-place restore does not exist.', c: 'Streams retain only 24 hours of changes and are not designed for reversal; replaying them backwards is not a supported operation.', d: 'PITR protects against any data loss within the window, including bad writes. Deletion protection is the separate feature that guards against dropping the table.', }, }} />