TablesItemsAttributesPartition KeySort KeyPartitions400 KB Limit

DynamoDB Core Concepts & Data Model

DynamoDB is not a flexible NoSQL database — it's a purpose-built engine that trades query flexibility for guaranteed performance at any scale. Every concept is interconnected.

45 min read9 sections

What is DynamoDB & Why It Exists

DynamoDB is widely misused because people treat it like a flexible . It is not. DynamoDB is a purpose-built engine for predictable, single-digit millisecond latency at any scale. That guarantee comes with a cost: you must define your access patterns upfront.

Amazon built DynamoDB after the 2004 holiday season outage that cost millions in revenue. The internal Dynamo paper (2007) described a system that would never go down, never slow down, and never require manual intervention. DynamoDB is the managed evolution of that vision — fully serverless, multi-AZ by default, with data across three Availability Zones automatically.

🏎️

The Race Track vs The Open Road

PostgreSQL is an open road — you can drive anywhere, take any turn, explore any route. DynamoDB is a race track — the lanes are fixed, but within those lanes you get guaranteed speed that no open road can match. If you try to leave the track (query outside your access patterns), you crash into a wall. The entire skill of DynamoDB is designing the right track before you start driving.

DynamoDB's Position in AWS

AWS Ecosystem Integration

✅Fully managed — no servers, no patching, no cluster management
✅Multi-AZ by default — data replicated across 3 Availability Zones
✅Global Tables — multi-region active-active replication
✅Integrates natively with Lambda, API Gateway, AppSync, Kinesis, S3
✅On-demand or provisioned capacity — pay per request or reserve throughput

What DynamoDB is NOT

DynamoDB Limitations

❌Not a relational database — no joins, no foreign keys, no SQL
❌Not a flexible document store — schema-on-read only appears true
❌Not the right tool for ad-hoc querying or analytics
❌Not a replacement for PostgreSQL when you need ACID across entities
❌Not easy to learn — steep learning curve, especially data modeling

The Fundamental Trade

🔑 The Core Mental Model

DynamoDB makes one deliberate trade: you define access patterns upfront, and DynamoDB guarantees performance for those patterns forever. Queries outside your access patterns are expensive or impossible. This is not a bug — it is the entire design philosophy.

When DynamoDB is the Right Choice

✅ Use DynamoDB When

Access patterns are known and stable
Massive scale with no operational overhead
Single-digit ms latency at any RPS
Serverless architectures (pay per request)
Simple key-value or key-document lookups

❌ Avoid DynamoDB When

Complex queries, ad-hoc reporting
Relational data with many relationships
Small scale where simplicity matters more
Team lacks DynamoDB experience
Need full-text search or analytics

Scenario	DynamoDB	Better Alternative
Known access patterns, massive scale	✅ Ideal	—
Ad-hoc queries, complex filtering	❌	PostgreSQL, MongoDB
Strong consistency across items	Limited (transactions expensive)	PostgreSQL
Full-text search	❌	Elasticsearch + DynamoDB Streams
Multi-region active-active	✅ Global Tables	CockroachDB, Cassandra
Serverless, zero ops	✅	FaunaDB, PlanetScale
Relational with joins	❌	PostgreSQL, Aurora

Attributes & Data Types

Attributes are name-value pairs within an item. Attribute names are UTF-8, case-sensitive, with a maximum length of 64 KB.

Scalar Types

Type	Code	Description	Example
String	S	UTF-8 encoded text	"hello"
Number	N	Arbitrary precision (stored as string internally)	42, 3.14
Binary	B	Base64 encoded bytes	Compressed/encrypted data
Boolean	BOOL	true or false	true
Null	NULL	Represents unknown/undefined	true (the value is literally 'true')

Set Types (Unordered, Unique Values)

Type	Code	Use Case
String Set	SS	Tags, categories, permissions
Number Set	NS	Scores, IDs, quantities
Binary Set	BS	Hashes, fingerprints

Document Types

Type	Code	Description
List	L	Ordered collection, any types (like JSON array)
Map	M	Unordered key-value pairs (like JSON object)

Nesting Limit

Maps and Lists can be nested up to 32 levels deep. Numbers are stored as strings internally — no float/int distinction, arbitrary precision. This means no floating-point rounding errors.

Primary Keys

The primary key is the single most important design decision in DynamoDB. It determines how data is distributed, what queries are possible, and what performance you get. Keys are immutable — you cannot update a primary key, only delete and reinsert.

Two Types of Primary Keys

Simple Primary Key (Partition Key Only)

Single attribute uniquely identifies each item
Use when: natural unique ID exists, no range queries needed
Example: userId for a users table
Only supports GetItem (exact lookup)

Composite Primary Key (PK + SK)

Combination uniquely identifies each item
Items with same PK are co-located, sorted by SK
Enables range queries within a partition
Example: userId (PK) + createdAt (SK) for orders

Key Attribute Types

Only String, Number, or Binary are allowed as key attributes. No Booleans, no Lists, no Maps. This constraint is permanent and cannot be changed after table creation.

key-schema.tstypescript

// Simple primary key — partition key only
const usersTable = {
  TableName: "Users",
  KeySchema: [
    { AttributeName: "userId", KeyType: "HASH" }  // Partition key
  ]
};

// Composite primary key — partition key + sort key
const ordersTable = {
  TableName: "Orders",
  KeySchema: [
    { AttributeName: "userId", KeyType: "HASH" },   // Partition key
    { AttributeName: "createdAt", KeyType: "RANGE" } // Sort key
  ]
};

1 / 9