DynamoDB Partition Key - The Ultimate Guide [w/ Code Examples]

What is a Partition Key in DynamoDB?

In any database, it is critical to think about how you will query and access your data. Asking your database to search through many items/objects before returning the one you want degrades the performance of your database, especially as you scale up the number of items/objects you store.

In DynamoDB, you can think about the partition key as the primary entry point for making these queries more efficient. If you don't have a sort key, then this partition key is the singular key that you will use to query your data on the table. If you have a sort key, it is recommended that you read the guide on DynamoDB Composite Key.

Each partition key (if you do not have a sort key) must be unique across the table. This means you cannot have two items with the same partition key in the same table.

The partition key of the table is immutable, meaning you cannot change it once the table is created. Along with the table partition key being immutable, the partition key value of an item is also immutable.

Partition keys are also used in global secondary indexes (GSIs). The primary difference here is that the partition key in a global index does not have to be unique. Additionally, the value of an index partition key is mutable and can be modified by doing an updateItem command.

Why Do I Need a Partition Key in DynamoDB?

The partition key is one of the primary concepts in DynamoDB and is how DynamoDB organizes and stores your data behind the scenes. Therefore, DynamoDB requires that every table have a partition key defined. The partition key helps distribute data across multiple partitions, ensuring scalability and performance.

The Best Practices You Should Follow For DynamoDB Partition Keys

Choosing The Right Partition Key

Since the partition key is the primary entry point for querying your data, it is critical that you choose the right partition key. As you might have heard before, it is important to define the access patterns for your application. This will help inform you on what partition key to use. Luckily, Dynobase provides a Single Table Design Tool that includes the ability to Plan Access Patterns.

Naming Convention

The most common naming convention for a partition key is pk. This is recommended because it allows for a clear name while also not discriminating depending on the type/model each item represents. For example, if you have a User model and a Post model, it can be tempting to use userID & postID respectively. However, DynamoDB only allows you a single partition key per table. Therefore, this would not be possible with single table design.

Additionally, it isn't uncommon to see id be used as the partition key if you don't have a sort key. If you have a sort key, this isn't as recommended, because it isn't as clear which attribute is the partition key vs the sort key.

Partition Key vs Other Key Types

Partition Key vs Composite Key

A composite key is a combination of both the sort key and the partition key. This allows for more complex queries and can help in scenarios where you need to store multiple items with the same partition key but different sort keys.

Partition Key vs Hash Key

Hash Key is a synonym for Partition Key. They are the same thing. You will commonly see the term Hash Key used in tools such as Terraform, Dynamoose, and more.

Working with Partition Key in DynamoDB (Code Examples)

Query All Items With Partition Key

DynamoDBClient.query({
    "TableName": "myTable",
    "KeyConditionExpression": "#pk = :pk",
    "ExpressionAttributeNames": {
        "#pk": "pk"
    },
    "ExpressionAttributeValues": {
        ":pk": "myPartitionKey"
    }
})
DynamoDBClient.query({
    "TableName": "myTable",
    "KeyConditionExpression": "#pk = :pk",
    "ExpressionAttributeNames": {
        "#pk": "pk"
    },
    "ExpressionAttributeValues": {
        ":pk": "myPartitionKey"
    }
})

This will query your database and return all/multiple items with the partition key (pk) attribute equal to myPartitionKey.

If you do not have a sort key, it is recommended that you use the get command since the partition key is unique across all items in the table. Otherwise, it is possible to return multiple items, and it is an application decision if you need to get all items (in which case you should use query) or you know the sort key, and you only need a single item (in which case you should use get).

Get By Partition Key

DynamoDBClient.getItem({
    "TableName": "myTable",
    "Key": {
        "pk": {
            "S": "myPartitionKey"
        }
    }
})
DynamoDBClient.getItem({
    "TableName": "myTable",
    "Key": {
        "pk": {
            "S": "myPartitionKey"
        }
    }
})

This will get a single item where the partition key (pk) attribute is equal to myPartitionKey.

If you have a sort key, this command will fail since it is possible to have multiple items in your table with the same partition key but different sort keys. In this case, you must specify the sort key as well or use the query command (shown above).

Delete By Partition Key

DynamoDBClient.deleteItem({
    "TableName": "myTable",
    "Key": {
        "pk": {
            "S": "myPartitionKey"
        }
    }
})
DynamoDBClient.deleteItem({
    "TableName": "myTable",
    "Key": {
        "pk": {
            "S": "myPartitionKey"
        }
    }
})

This command is almost identical to the Get By Partition Key shown above, except we are using the deleteItem command instead of the getItem command.

Change/Update Partition Key

DynamoDBClient.updateItem({
    "TableName": "myTable",
    "Key": {
        "pk": {
            "S": "myPartitionKey"
        }
    },
    "UpdateExpression": "SET #email = :email",
    "ExpressionAttributeNames": {
        "#email": "email"
    },
    "ExpressionAttributeValues": {
        ":email": {
            "S": "test@test.com"
        }
    }
})
DynamoDBClient.updateItem({
    "TableName": "myTable",
    "Key": {
        "pk": {
            "S": "myPartitionKey"
        }
    },
    "UpdateExpression": "SET #email = :email",
    "ExpressionAttributeNames": {
        "#email": "email"
    },
    "ExpressionAttributeValues": {
        ":email": {
            "S": "test@test.com"
        }
    }
})

This command will modify the email attribute to equal test@test.com for the item where the partition key (pk) attribute is equal to myPartitionKey.

It is important to note that you are not able to modify the partition key of an existing object. It is considered immutable. If you want to change the partition key, you must delete the item and create a new item with the new partition key. If you find yourself needing to do this often, it is recommended that you think about your access patterns and consider if there is a better method you can use, as deleting & creating a new item results in two separate operations, increasing latency and cost.

Frequently Asked Questions

Is the DynamoDB partition key the same as the primary key of a table?

If you do not have a sort key (in which case the composite key would be the primary key) and you are referring to the partition key of the table itself, then yes, the partition key is the same as the primary key of the table in that specific instance.

Can I change the partition key in DynamoDB?

You can not change the partition key of a table. It is immutable. Additionally, the value of a partition key in an item is also immutable and can not be changed.

The one exception to this is that the value of a partition key in a global index is mutable and can be changed by doing an updateItem command.

Can I use Date as partition key in DynamoDB?

Yes. You can either store it as a string or a number.

Can a DynamoDB table have multiple partition keys?

While you can only have a single partition key per DynamoDB table, you can create global indexes that have a different partition key than the table itself. This is useful if you want to query your data in a different way than the primary table.

Can a DynamoDB table store multiple items with the same partition key?

A DynamoDB table can only store multiple items with the same partition key if you have defined a sort key & the combination of the partition key and sort key is unique. If you do not have a sort key, then the partition key must be unique across all items in the table.

The exception to this is if you have a global index with a different partition key than the table itself. These items can have the same global index partition key across multiple items in the same DynamoDB table.

Can multiple DynamoDB tables have the same partition key?

Yes. You can reuse the same partition key across multiple DynamoDB tables.

What data types can be used for the partition key in DynamoDB?

The partition key can be any of the following data types:

• String
• Number
• Binary

What is the DynamoDB partition key size limit?

The DynamoDB partition key value size limit is 2048 bytes. There is also a minimum length of 1 byte for the partition key value.

What other limits apply to the DynamoDB partition key?

There is no practical limit on the number of distinct partition key values.

Additional Considerations for Partition Keys

When designing your DynamoDB table, it's important to consider the distribution of your partition keys. A well-distributed partition key ensures that your data is evenly spread across multiple partitions, which helps maintain performance and scalability. Avoid using monotonically increasing keys, such as timestamps, as they can lead to hot partitions and degrade performance. Instead, consider using a composite key or adding a random suffix to your partition key to distribute the load more evenly.

Another important consideration is the impact of partition keys on your read and write capacity units (RCUs and WCUs). Since DynamoDB charges based on the number of RCUs and WCUs consumed, an inefficient partition key design can lead to higher costs. By carefully planning your access patterns and partition key strategy, you can optimize both performance and cost.

Lastly, remember that DynamoDB's performance characteristics are influenced by the size of the items and the number of attributes. While the partition key itself has a size limit, the overall item size, including all attributes, should also be considered to ensure efficient storage and retrieval.