DynamoDB Key Concepts

Every attribute in a DynamoDB item holds a value, and that value has a type. DynamoDB supports several data types — from simple text and numbers to complex lists and maps. Choosing the right type for each attribute keeps your data accurate and your queries efficient.

The Three Categories of Data Types

DynamoDB groups all its data types into three main categories:

• Scalar Types — hold one single value
• Document Types — hold complex, nested data
• Set Types — hold multiple unique values of the same type

Scalar Types

Scalar types are the building blocks. Each one stores a single, simple value.

String (S)

Stores text. It can be a name, an email address, a city, or any sequence of characters.

"Name": { "S": "Ananya Kapoor" }
"City": { "S": "Delhi" }

String values are case-sensitive. "Delhi" and "delhi" are treated as two different values.

Number (N)

Stores numeric values — integers or decimals. DynamoDB stores numbers as strings internally but treats them as numbers for comparison and sorting.

"Age":    { "N": "32" }
"Price":  { "N": "1499.99" }

Boolean (BOOL)

Stores either true or false. Use this for yes/no flags.

"IsActive":    { "BOOL": true }
"EmailVerified": { "BOOL": false }

Null (NULL)

Represents the intentional absence of a value. Use it to indicate that a field exists but has no data yet.

"MiddleName": { "NULL": true }

Binary (B)

Stores raw binary data — for example, an encrypted string, an image thumbnail, or compressed content. The data must be Base64-encoded when sent to DynamoDB.

"ProfilePicture": { "B": "dGhpcyBpcyBhIHRlc3Q=" }

Document Types

Document types let you nest data inside an attribute. This is useful for storing structured information that belongs together as a group.

Map (M)

A Map stores a collection of key-value pairs — like a mini-document inside an attribute. Think of it like a folder within a folder.

"Address": {
  "M": {
    "Street": { "S": "12 MG Road" },
    "City":   { "S": "Bengaluru" },
    "PIN":    { "N": "560001" }
  }
}

A Map can contain any other data type inside it, including other Maps (nested Maps).

List (L)

A List stores an ordered collection of values. The values can be of different types. Think of it like a numbered bullet list.

"Tags": {
  "L": [
    { "S": "Electronics" },
    { "S": "Computers" },
    { "N": "2024" }
  ]
}

Lists preserve insertion order, so the first item you add stays first.

Diagram: Nested Data with Map and List

ITEM: Product
┌─────────────────────────────────────────────────────┐
│ ProductID:   "P999"          (String - Primary Key) │
│ Name:        "Gaming Laptop" (String)               │
│ Price:       75000           (Number)               │
│ InStock:     true            (Boolean)              │
│                                                     │
│ Specs (Map):                                        │
│  ├─ RAM:  "16GB"             (String)               │
│  ├─ CPU:  "Intel i7"        (String)                │
│  └─ Storage: "512GB SSD"    (String)                │
│                                                     │
│ Tags (List):                                        │
│  ├─ [0] "Gaming"            (String)                │
│  ├─ [1] "Laptops"           (String)                │
│  └─ [2] "Best Seller"       (String)                │
└─────────────────────────────────────────────────────┘

Set Types

Sets store multiple values of the same type. All values in a set must be unique — duplicates are automatically removed. Sets have no guaranteed order.

String Set (SS)

A collection of unique string values.

"Hobbies": {
  "SS": ["Cricket", "Photography", "Reading"]
}

Number Set (NS)

A collection of unique numeric values.

"WinningScores": {
  "NS": ["95", "87", "102"]
}

Binary Set (BS)

A collection of unique binary values. Rarely used directly, but available for specialized use cases like storing multiple encrypted tokens.

Set vs List — When to Use Which

Data Type Rules for Primary Keys

Primary key attributes (Partition Key and Sort Key) can only be of three types: String, Number, or Binary. You cannot use Boolean, List, Map, or Set as a primary key.

Summary of All Data Types