Partition and Sort Keys

In DynamoDB, your Primary Key is the most important decision you will make. Unlike SQL where you can query any column with an index, in DynamoDB, your Primary Key determines how your data is physically stored and retrieved.

There are two types of Primary Keys:

  1. Simple Primary Key: Just a Partition Key.
  2. Composite Primary Key: A Partition Key and a Sort Key.

1. The Partition Key (PK)

The Partition Key (also known as the Hash Key) is used by DynamoDB to distribute your data across multiple physical partitions (servers).

How it Works

  1. DynamoDB takes the value of your PK (e.g., USER#123).
  2. It runs it through an internal hash function.
  3. The resulting hash determines which physical partition stores the data.

[!WARNING] High Cardinality: You must choose a PK with high cardinality (many unique values). If you choose a PK with low cardinality (e.g., Status which is only “ACTIVE” or “INACTIVE”), you will create Hot Partitions, where one server handles all the traffic while others sit idle.

2. The Sort Key (SK)

The Sort Key (also known as the Range Key) is used to organize data within a single partition.

  • Ordered Storage: Items with the same PK are stored physically close together, sorted by the SK value (UTF-8 binary order).
  • Range Queries: This allows you to perform powerful queries like “Get all orders for User X between Date A and Date B”.

3. Composite Primary Key (PK + SK)

This is the standard for Single-Table Design.

  • Uniqueness: The combination of PK + SK must be unique. You can have multiple items with the same PK, as long as their SK is different.
  • Item Collection: All items sharing the same PK are called an Item Collection.

4. Interactive: Key Distribution Visualizer

See how DynamoDB uses the Partition Key to distribute data across physical nodes.

Partition 1 (0-33)
Partition 2 (34-66)
Partition 3 (67-100)

5. Code Implementation

In Single-Table Design, we typically use generic names like PK and SK for our key attributes so they can hold different types of values (e.g., a User ID or an Order ID).

import software.amazon.awssdk.enhanced.dynamodb.mapper.annotations.*;

@DynamoDbBean
public class SingleTableItem {
    private String pk;
    private String sk;
    private String data; // Other attributes...

    @DynamoDbPartitionKey
    @DynamoDbAttribute("PK")
    public String getPk() { return pk; }
    public void setPk(String pk) { this.pk = pk; }

    @DynamoDbSortKey
    @DynamoDbAttribute("SK")
    public String getSk() { return sk; }
    public void setSk(String sk) { this.sk = sk; }
}

package main

import "github.com/aws/aws-sdk-go-v2/feature/dynamodb/attributevalue"

// SingleTableItem represents a generic item in our table
type SingleTableItem struct {
    PK   string `dynamodbav:"PK"`
    SK   string `dynamodbav:"SK"`
    Data string `dynamodbav:"Data,omitempty"`
}

// Example: Creating a Key
func main() {
    userKey := SingleTableItem{
        PK: "USER#123",
        SK: "METADATA",
    }
    // ready to marshal...
}

6. Summary

  • PK: Determines where the data lives (Partition). Must be high cardinality to avoid hotspots.
  • SK: Determines the order of data. Enables range queries (begins_with, between).
  • Composite Key: The combination of PK + SK uniquely identifies an item.