DynamoDB via SDK Best Practices

This is the checklist to run before and after building on DynamoDB from the SDK. Each item is a rule stated positively with a one-line rationale.

Work top to bottom - the groups run roughly in dependency order, from key design outward to capacity and cost. Most rules apply whether you provision from the SDK or from IaC.

How to Use This List

Treat each box as an audit question against your own table and access code.
The groups run from foundation outward: design first, then reads, writes, lifecycle, and capacity.
Rules are SDK-agnostic - they hold for boto3 and AWS SDK v3 alike.
Revisit the list whenever you add an access pattern, an index, or a new entity type.

A - Key & Data Modeling

Design from access patterns, not entities. List every read and write with its runtime inputs before choosing keys, so each becomes a targeted lookup.
Make the most common read a Query on one partition. If a frequent read forces a Scan, the key design is wrong - fix the model, not the query.
Use a high-cardinality partition key. Spread items across many partitions so no single key concentrates traffic.
Encode entity type into keys. Prefixes like USER# and ORDER# keep item types distinct, sortable, and self-describing in a shared table.
Add GSIs for secondary patterns, and keep them sparse. Only write the index key onto items that pattern needs, so the index stays small and cheap.

Model keys around the query you will run most.

# --- Python (boto3) ---
from boto3.dynamodb.conditions import Key
 
# Access pattern "orders for a customer" -> Query on the partition key.
resp = table.query(KeyConditionExpression=Key("pk").eq("CUSTOMER#c-1"))

// --- TypeScript (AWS SDK v3) ---
import { QueryCommand } from "@aws-sdk/lib-dynamodb";
 
// Access pattern "orders for a customer" -> Query on the partition key.
const resp = await doc.send(new QueryCommand({
  TableName: "App",
  KeyConditionExpression: "pk = :p",
  ExpressionAttributeValues: { ":p": "CUSTOMER#c-1" },
}));

B - Efficient Reads

Prefer Query over Scan everywhere. Query reads one partition; Scan reads the whole table and grows costlier with size.
Narrow with key conditions, not filters. A FilterExpression runs after the read and still bills for scanned items; a KeyConditionExpression does not.
Paginate on LastEvaluatedKey. Each read caps at 1 MB - loop with ExclusiveStartKey until it is absent, or you silently drop data.
Project only the attributes you need. ProjectionExpression trims payload; for large items it saves real bandwidth.
Request strong consistency only when needed. Eventually consistent reads cost half as much; reserve ConsistentRead for read-after-write correctness.
Cache hot reads. For read-heavy, latency-sensitive paths, DAX or an application cache cuts read capacity and latency.

C - Safe & Efficient Writes

Use the document interface. Plain objects via boto3.resource / lib-dynamodb beat hand-writing {"S": ...} typed values.
Guard writes with condition expressions. attribute_not_exists for safe inserts and a version check for optimistic locking prevent lost updates.
Reserve transactions for real atomicity. TransactWriteItems costs about double - use it only when several items must change together.
Batch bulk writes in 25s. BatchWriteItem (or boto3's batch_writer) cuts round trips; resend UnprocessedItems.
Make writes idempotent. Use ClientRequestToken on transactions and idempotent upserts so retries do not double-apply.

Guard an insert so a retry or race never overwrites existing data.

# --- Python (boto3) ---
# Insert-only: fails with ConditionalCheckFailedException if it already exists.
table.put_item(
    Item={"pk": "USER#u-1", "sk": "PROFILE", "email": "ada@x.io"},
    ConditionExpression="attribute_not_exists(pk)",
)

// --- TypeScript (AWS SDK v3) ---
import { PutCommand } from "@aws-sdk/lib-dynamodb";
 
// Insert-only: fails with ConditionalCheckFailedException if it already exists.
await doc.send(new PutCommand({
  TableName: "App",
  Item: { pk: "USER#u-1", sk: "PROFILE", email: "ada@x.io" },
  ConditionExpression: "attribute_not_exists(pk)",
}));

D - Data Lifecycle

Enable TTL for ephemeral items. Set a Unix-epoch expiresAt attribute and let DynamoDB delete expired items for free instead of scanning to clean up.
Filter out not-yet-deleted TTL items. TTL deletion is asynchronous (up to ~48 hours), so exclude expired items in queries if freshness matters.
Keep items small. Large items cost more capacity per operation; offload big blobs to S3 and store the key.
Avoid unbounded item collections. Shard a growing partition (for example USER#u-1#2026) before it nears the 10 GB partition limit.
Use streams for derived data. React to changes via DynamoDB Streams rather than dual-writing to a second store.

Turn on TTL so expired sessions clean themselves up.

# --- Python (boto3) ---
import boto3, time
ddb = boto3.client("dynamodb", region_name="us-east-1")
 
# 1. Enable TTL on the 'expiresAt' attribute (Unix epoch seconds).
ddb.update_time_to_live(
    TableName="Sessions",
    TimeToLiveSpecification={"Enabled": True, "AttributeName": "expiresAt"},
)
# 2. Write an item that expires in one hour.
boto3.resource("dynamodb").Table("Sessions").put_item(
    Item={"sid": "s-1", "expiresAt": int(time.time()) + 3600},
)

// --- TypeScript (AWS SDK v3) ---
import { DynamoDBClient, UpdateTimeToLiveCommand } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, PutCommand } from "@aws-sdk/lib-dynamodb";
 
const base = new DynamoDBClient({ region: "us-east-1" });
const doc = DynamoDBDocumentClient.from(base);
 
// 1. Enable TTL on the 'expiresAt' attribute (Unix epoch seconds).
await base.send(new UpdateTimeToLiveCommand({
  TableName: "Sessions",
  TimeToLiveSpecification: { Enabled: true, AttributeName: "expiresAt" },
}));
// 2. Write an item that expires in one hour.
await doc.send(new PutCommand({
  TableName: "Sessions",
  Item: { sid: "s-1", expiresAt: Math.floor(Date.now() / 1000) + 3600 },
}));

E - Capacity & Cost

Start on-demand, then measure. PAY_PER_REQUEST needs no tuning and costs nothing idle; switch to provisioned once traffic is steady.
Auto scale provisioned capacity. Target-track utilization near 70% with a sane Min/Max, and scale each GSI too.
Watch for hot partitions. Monitor throttling; a hot key throttles even with ample total capacity - reshape the key or shard writes.
Treat throttling as retryable. ProvisionedThroughputExceededException is retried with backoff by the SDK; persistent throttling means raise capacity.
Change billing mode deliberately. Mode switches are limited to once per 24 hours, so decide from metrics, not per incident.

F - Operations & Observability

Reuse clients across invocations. Initialize the client at module scope so warm Lambda invocations skip re-creating it.
Alarm on ConsumedCapacity and throttles. CloudWatch metrics surface hot partitions and under-provisioning before users feel them.
Tag tables for cost attribution. Consistent tags make spend, cleanup, and ownership discoverable.
Log the request id on failures. Capture RequestId / $metadata.requestId so AWS support can trace a call.
Test against DynamoDB Local or moto. Verify key design, queries, and conditions offline and free in CI before touching real tables.

FAQs

What is the single most important DynamoDB habit?

Designing from access patterns first. List the exact reads and writes with their runtime inputs, then choose keys and indexes so each becomes a Query on a single partition. Almost every other best practice follows from this.

How do I avoid hot partitions?

Pick a high-cardinality partition key so load spreads across many partitions. If a low-cardinality key is unavoidable, add a shard suffix and fan reads across the shards. Monitor throttling to catch hotspots early.

Why prefer Query over Scan?

Query reads only items under one partition key and stays cheap at any size. Scan reads the entire table and filters afterward, so its cost grows with the data. A Scan on a request path signals a modeling problem.

Does a FilterExpression save capacity?

No. Filters run after DynamoDB reads and meters the items, so they trim what is returned but not what you pay for. Narrow with a KeyConditionExpression or a GSI to actually reduce cost.

How does TTL help with cleanup?

Set a Unix-epoch timestamp attribute and enable TTL on it. DynamoDB deletes expired items automatically at no capacity cost, replacing a scan-and-delete job. Deletion is asynchronous, so filter out expired items in queries if needed.

When should I use transactions?

Only when several items must change atomically - a transfer, a uniqueness constraint across items, an invariant spanning entities. They cost about double the write capacity, so a single conditional write is preferable when it suffices.

Which billing mode should I choose?

Start with on-demand for new or unpredictable traffic - no tuning, nothing when idle. Move to provisioned with auto scaling once metrics show steady, forecastable load, where reserved capacity is meaningfully cheaper.

How do I make writes safe under concurrency?

Attach condition expressions: attribute_not_exists for safe inserts, and a version-number check for optimistic locking. For multi-item invariants use TransactWriteItems, and add a ClientRequestToken to make retries idempotent.

How should I test DynamoDB code?

Run integration tests against DynamoDB Local (Docker or JAR) for real API behavior, and use moto or client mocks for fast unit tests. Both run offline and free, so CI never needs a live, billed table.

Do these rules apply with IaC too?

Mostly yes. Access-pattern-first design, sparse GSIs, TTL, auto scaling, tagging, and rate-based alarms are architectural habits that hold whether you create the table from the SDK or from CloudFormation, CDK, or Terraform.

DynamoDB's Access-Pattern-First Design Model - the mindset behind group A.
Queries, Scans & Filter Expressions - the efficient-read rules in group B.
Transactions & Conditional Writes - the safe-write rules in group C.
On-Demand vs Provisioned Capacity - the capacity and cost rules in group E.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).

DynamoDB via SDK Best Practices

This is the checklist to run before and after building on DynamoDB from the SDK. Each item is a rule stated positively with a one-line rationale.

Work top to bottom - the groups run roughly in dependency order, from key design outward to capacity and cost. Most rules apply whether you provision from the SDK or from IaC.

How to Use This List

Treat each box as an audit question against your own table and access code.
The groups run from foundation outward: design first, then reads, writes, lifecycle, and capacity.
Rules are SDK-agnostic - they hold for boto3 and AWS SDK v3 alike.
Revisit the list whenever you add an access pattern, an index, or a new entity type.

A - Key & Data Modeling

Design from access patterns, not entities. List every read and write with its runtime inputs before choosing keys, so each becomes a targeted lookup.
Make the most common read a Query on one partition. If a frequent read forces a Scan, the key design is wrong - fix the model, not the query.
Use a high-cardinality partition key. Spread items across many partitions so no single key concentrates traffic.
Encode entity type into keys. Prefixes like USER# and ORDER# keep item types distinct, sortable, and self-describing in a shared table.
Add GSIs for secondary patterns, and keep them sparse. Only write the index key onto items that pattern needs, so the index stays small and cheap.

Model keys around the query you will run most.

# --- Python (boto3) ---
from boto3.dynamodb.conditions import Key
 
# Access pattern "orders for a customer" -> Query on the partition key.
resp = table.query(KeyConditionExpression=Key("pk").eq("CUSTOMER#c-1"))

// --- TypeScript (AWS SDK v3) ---
import { QueryCommand } from "@aws-sdk/lib-dynamodb";
 
// Access pattern "orders for a customer" -> Query on the partition key.
const resp = await doc.send(new QueryCommand({
  TableName: "App",
  KeyConditionExpression: "pk = :p",
  ExpressionAttributeValues: { ":p": "CUSTOMER#c-1" },
}));

B - Efficient Reads

Prefer Query over Scan everywhere. Query reads one partition; Scan reads the whole table and grows costlier with size.
Narrow with key conditions, not filters. A FilterExpression runs after the read and still bills for scanned items; a KeyConditionExpression does not.
Paginate on LastEvaluatedKey. Each read caps at 1 MB - loop with ExclusiveStartKey until it is absent, or you silently drop data.
Project only the attributes you need. ProjectionExpression trims payload; for large items it saves real bandwidth.
Request strong consistency only when needed. Eventually consistent reads cost half as much; reserve ConsistentRead for read-after-write correctness.
Cache hot reads. For read-heavy, latency-sensitive paths, DAX or an application cache cuts read capacity and latency.

C - Safe & Efficient Writes

Use the document interface. Plain objects via boto3.resource / lib-dynamodb beat hand-writing {"S": ...} typed values.
Guard writes with condition expressions. attribute_not_exists for safe inserts and a version check for optimistic locking prevent lost updates.
Reserve transactions for real atomicity. TransactWriteItems costs about double - use it only when several items must change together.
Batch bulk writes in 25s. BatchWriteItem (or boto3's batch_writer) cuts round trips; resend UnprocessedItems.
Make writes idempotent. Use ClientRequestToken on transactions and idempotent upserts so retries do not double-apply.

Guard an insert so a retry or race never overwrites existing data.

# --- Python (boto3) ---
# Insert-only: fails with ConditionalCheckFailedException if it already exists.
table.put_item(
    Item={"pk": "USER#u-1", "sk": "PROFILE", "email": "ada@x.io"},
    ConditionExpression="attribute_not_exists(pk)",
)

// --- TypeScript (AWS SDK v3) ---
import { PutCommand } from "@aws-sdk/lib-dynamodb";
 
// Insert-only: fails with ConditionalCheckFailedException if it already exists.
await doc.send(new PutCommand({
  TableName: "App",
  Item: { pk: "USER#u-1", sk: "PROFILE", email: "ada@x.io" },
  ConditionExpression: "attribute_not_exists(pk)",
}));

D - Data Lifecycle

Enable TTL for ephemeral items. Set a Unix-epoch expiresAt attribute and let DynamoDB delete expired items for free instead of scanning to clean up.
Filter out not-yet-deleted TTL items. TTL deletion is asynchronous (up to ~48 hours), so exclude expired items in queries if freshness matters.
Keep items small. Large items cost more capacity per operation; offload big blobs to S3 and store the key.
Avoid unbounded item collections. Shard a growing partition (for example USER#u-1#2026) before it nears the 10 GB partition limit.
Use streams for derived data. React to changes via DynamoDB Streams rather than dual-writing to a second store.

Turn on TTL so expired sessions clean themselves up.

# --- Python (boto3) ---
import boto3, time
ddb = boto3.client("dynamodb", region_name="us-east-1")
 
# 1. Enable TTL on the 'expiresAt' attribute (Unix epoch seconds).
ddb.update_time_to_live(
    TableName="Sessions",
    TimeToLiveSpecification={"Enabled": True, "AttributeName": "expiresAt"},
)
# 2. Write an item that expires in one hour.
boto3.resource("dynamodb").Table("Sessions").put_item(
    Item={"sid": "s-1", "expiresAt": int(time.time()) + 3600},
)

// --- TypeScript (AWS SDK v3) ---
import { DynamoDBClient, UpdateTimeToLiveCommand } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, PutCommand } from "@aws-sdk/lib-dynamodb";
 
const base = new DynamoDBClient({ region: "us-east-1" });
const doc = DynamoDBDocumentClient.from(base);
 
// 1. Enable TTL on the 'expiresAt' attribute (Unix epoch seconds).
await base.send(new UpdateTimeToLiveCommand({
  TableName: "Sessions",
  TimeToLiveSpecification: { Enabled: true, AttributeName: "expiresAt" },
}));
// 2. Write an item that expires in one hour.
await doc.send(new PutCommand({
  TableName: "Sessions",
  Item: { sid: "s-1", expiresAt: Math.floor(Date.now() / 1000) + 3600 },
}));

E - Capacity & Cost

Start on-demand, then measure. PAY_PER_REQUEST needs no tuning and costs nothing idle; switch to provisioned once traffic is steady.
Auto scale provisioned capacity. Target-track utilization near 70% with a sane Min/Max, and scale each GSI too.
Watch for hot partitions. Monitor throttling; a hot key throttles even with ample total capacity - reshape the key or shard writes.
Treat throttling as retryable. ProvisionedThroughputExceededException is retried with backoff by the SDK; persistent throttling means raise capacity.
Change billing mode deliberately. Mode switches are limited to once per 24 hours, so decide from metrics, not per incident.

F - Operations & Observability

Reuse clients across invocations. Initialize the client at module scope so warm Lambda invocations skip re-creating it.
Alarm on ConsumedCapacity and throttles. CloudWatch metrics surface hot partitions and under-provisioning before users feel them.
Tag tables for cost attribution. Consistent tags make spend, cleanup, and ownership discoverable.
Log the request id on failures. Capture RequestId / $metadata.requestId so AWS support can trace a call.
Test against DynamoDB Local or moto. Verify key design, queries, and conditions offline and free in CI before touching real tables.

FAQs

What is the single most important DynamoDB habit?

How do I avoid hot partitions?

Why prefer Query over Scan?

Does a FilterExpression save capacity?

No. Filters run after DynamoDB reads and meters the items, so they trim what is returned but not what you pay for. Narrow with a KeyConditionExpression or a GSI to actually reduce cost.

How does TTL help with cleanup?

When should I use transactions?

Which billing mode should I choose?

How do I make writes safe under concurrency?

How should I test DynamoDB code?

Do these rules apply with IaC too?

DynamoDB's Access-Pattern-First Design Model - the mindset behind group A.
Queries, Scans & Filter Expressions - the efficient-read rules in group B.
Transactions & Conditional Writes - the safe-write rules in group C.
On-Demand vs Provisioned Capacity - the capacity and cost rules in group E.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).

DynamoDB via SDK Best Practices

Buscar na documentação

DynamoDB via SDK Best Practices