DynamoDB Basics — Comprehensive Reference

Audience: Developers, architects, and interview candidates who need a complete grounding in DynamoDB from first principles through production-ready patterns.

1. What Is DynamoDB?

Amazon DynamoDB is a fully managed, serverless, key-value and document NoSQL database built for any scale. It delivers single-digit millisecond latency at any throughput level, without manual sharding, schema migrations, or capacity tuning by default.

2. Core Concepts

2.1 Table

A DynamoDB table is the top-level container for data. Unlike a relational table, it does not enforce a fixed schema across all items. Every item in the same table can have different attributes, except for the primary key.

Table: customer-orders
  Item → { order_id: "ORD-001", customer: "alice", amount: 59.99 }
  Item → { order_id: "ORD-002", customer: "bob", amount: 12.00, promo: "SAVE10" }
  Item → { order_id: "ORD-003", customer: "alice", note: "gift", amount: 200.00 }

2.2 Item

An item is a single record in a table. It is a collection of attributes. Each item must include the primary key attributes. All other attributes are optional and can vary per item.

2.3 Attribute

An attribute is a named value stored in an item. Think of it as a field in a JSON object.

Supported Data Types

Number storage note: Numbers are stored as strings internally to avoid floating-point precision loss. All numeric comparisons still work correctly.

3. Primary Keys

The primary key is the single most important design decision in DynamoDB. It determines how data is partitioned, how it is retrieved, and what access patterns are efficient.

3.1 Simple Primary Key (Partition Key Only)

Only a partition key is defined. Each item must have a unique partition key value.

PK = user_id
  "user123" → { name: "Alice", email: "alice@example.com" }
  "user456" → { name: "Bob",   email: "bob@example.com" }

Good for: Lookups where you always know the exact key. GetItem by user ID is the canonical example.

3.2 Composite Primary Key (Partition Key + Sort Key)

Both a partition key and a sort key are defined. Items with the same partition key are grouped together and sorted by the sort key. This is the most powerful and most commonly used key design.

PK = user_id  |  SK = order_date
  "user123"  |  "2024-01-01"  →  first order
  "user123"  |  "2024-03-15"  →  second order
  "user456"  |  "2024-02-10"  →  another user's order

Good for: Time-series data, hierarchical relationships, one-to-many relationships, ordered retrieval within a group.

3.3 Partition Key Design Rules

3.4 Hot Partition Mitigation

If your workload puts too much traffic on a single partition key:

1. Write sharding: Append a random suffix (user_id#1, user_id#2, ..., user_id#N) and scatter writes across N logical partitions. Reads must aggregate across shards.
2. Attribute bucketing: Use a time bucket as part of the partition key (user_id#2024-03) so traffic is distributed by time.
3. DAX in front: Cache hot reads to reduce RCU pressure on a single partition.

4. Indexes

4.1 Local Secondary Index (LSI)

An LSI shares the partition key with the base table but uses a different sort key. It gives you an alternate ordering of items within the same partition.

Base table:   PK = user_id,  SK = created_at
LSI:          PK = user_id,  SK = status
→ Now you can query all items for a user filtered by status within that partition

4.2 Global Secondary Index (GSI)

A GSI has its own partition key and optional sort key, completely independent of the base table. It lets you query the same data from a different angle.

Base table:   PK = order_id
GSI:          PK = customer_id,  SK = order_date
→ Now you can query all orders for a customer sorted by date

GSI projection strategy: - KEYS_ONLY: only index keys are stored in the index — cheapest - INCLUDE: explicitly named attributes are included — balance between cost and query needs - ALL: every attribute is replicated — most flexible but most expensive

4.3 LSI vs GSI Comparison

5. Capacity Modes

5.1 On-Demand Mode

DynamoDB automatically scales to accommodate any request rate. You pay per read/write request consumed.

5.2 Provisioned Mode

You specify RCU and WCU targets in advance. You pay for the provisioned capacity whether it is used or not.

5.3 Capacity Unit Math

Size rounding: Items are rounded up to the nearest 1 KB for writes, and to the nearest 4 KB for reads. A 1.5 KB item counts as 2 WCU.

6. Read and Write Operations

6.1 Single-Item Operations

6.2 Batch Operations

Important: Batch operations are not atomic. Individual operations within a batch can fail independently. You must handle UnprocessedItems / UnprocessedKeys in your retry logic.

6.3 Query

Reads all items that share a partition key, with optional sort key filtering.

• Always requires a partition key value
• Sort key can be filtered with =, <, >, BETWEEN, begins_with
• Results can be paginated with ExclusiveStartKey / LastEvaluatedKey
• Can be scanned in forward or reverse sort order
• Much cheaper than Scan because it is a bounded, targeted read

response = table.query(
    KeyConditionExpression=Key("PK").eq("SESSION#abc") & Key("SK").begins_with("TURN#"),
    ScanIndexForward=False,   # descending sort order (latest turns first)
    Limit=10
)

6.4 Scan

Reads every item in a table or index sequentially.

• No key requirement — reads everything
• Very expensive at scale; avoid in hot paths
• Can be parallelized using Segment and TotalSegments for bulk export jobs
• Add a FilterExpression to limit returned data, but filtered items still consume RCU

# Parallel scan across 4 workers
response = table.scan(TotalSegments=4, Segment=worker_id)

6.5 Filter Expression vs Key Condition Expression

This is a critical distinction. A FilterExpression that discards 90% of results still bills you for reading 100% of them. Design key patterns so the key condition does most of the filtering.

7. Writes in Depth

7.1 Conditional Writes

Write only proceeds if a condition is true. If the condition fails, DynamoDB returns ConditionalCheckFailedException.

# Only insert if the item does not already exist
table.put_item(
    Item={"PK": "SESSION#abc", "SK": "META", "status": "active"},
    ConditionExpression="attribute_not_exists(PK)"
)

# Atomic counter increment — only if counter is below limit
table.update_item(
    Key={"PK": "COUNTER#daily", "SK": "2024-03-28"},
    UpdateExpression="SET count = count + :inc",
    ConditionExpression="count < :limit",
    ExpressionAttributeValues={":inc": 1, ":limit": 1000}
)

7.2 UpdateExpression Operators

Multiple clauses can be combined: SET updated_at = :ts REMOVE old_field ADD view_count :one

7.3 Transactions

TransactWriteItems and TransactGetItems provide all-or-nothing semantics across up to 100 items.

client.transact_write_items(
    TransactItems=[
        {
            "Put": {
                "TableName": "orders",
                "Item": {"PK": "ORDER#999", "status": "placed", "amount": 99},
                "ConditionExpression": "attribute_not_exists(PK)"
            }
        },
        {
            "Update": {
                "TableName": "inventory",
                "Key": {"PK": "SKU#X1"},
                "UpdateExpression": "SET stock = stock - :one",
                "ConditionExpression": "stock > :zero",
                "ExpressionAttributeValues": {":one": 1, ":zero": 0}
            }
        }
    ]
)

Transaction costs: Each item in a transaction consumes 2× the normal RCU or WCU. Use transactions only when atomicity genuinely matters.

8. TTL (Time to Live)

DynamoDB TTL automatically deletes expired items without consuming WCU.

Best practice: Always enforce expiry in application logic by checking ttl < time.time() on reads. Do not rely solely on DynamoDB's physical deletion timing.

import time

def is_expired(item: dict) -> bool:
    ttl_value = item.get("ttl")
    return ttl_value is not None and ttl_value < int(time.time())

9. DynamoDB Streams

Streams capture a time-ordered sequence of item-level changes (inserts, updates, deletes) with a 24-hour retention window.

Stream View Types

Common Use Cases

• Trigger downstream Lambda processing on item changes
• Replicate data to ElasticSearch / OpenSearch for full-text search
• Invalidate caches when source data changes
• Build event sourcing pipelines
• Drive analytics aggregation in real time
• Maintain materialized views across tables

DynamoDB item change
  → Stream record (change event)
    → Lambda trigger (reads stream in batches)
      → Process: update search index, publish to SNS, write to S3, etc.

10. DAX (DynamoDB Accelerator)

DAX is an in-memory read/write-through cache for DynamoDB that delivers microsecond response times.

DAX has two internal caches: - Item cache: Caches individual GetItem results - Query cache: Caches Query and Scan result sets by parameter hash

11. Consistency Models

Eventually Consistent Reads

• Returns a response that may not reflect a very recent write (typically within a second)
• Half the RCU cost of strongly consistent reads
• Default for Query and Scan
• Suitable for most read workloads where slight staleness is acceptable

Strongly Consistent Reads

• Always reflects the most recent successfully completed write
• Full RCU cost
• Available only on base table reads and LSI reads (not GSI)
• Use when correctness is critical: financial balances, inventory counts, idempotency checks

12. Single-Table Design Principles

Single-table design is the practice of storing multiple entity types in one DynamoDB table, differentiated by key patterns.

Why Do It?

• Reduces the number of network round trips (fetch related entities in one Query)
• Avoids cross-table joins at the application layer
• Leads to better cost and latency characteristics when entities are accessed together

How to Differentiate Entity Types

Access Pattern Mapping Template

Before building the schema, enumerate every access pattern:

Map every access pattern before writing a single line of code. DynamoDB schemas are hard to migrate later.

13. Common Pitfalls

14. DynamoDB vs Other Databases — Quick Reference

15. Key Vocabulary for Interviews