DynamoDB Partition Key - The Ultimate Guide [w/ Code Examples]
Written by Charlie Fish
Published on September 25th, 2022
Time to 10x your DynamoDB productivity with Dynobase [learn more]
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 can not have two items with the same partition key in the same table.
The partition key of the table is immutable, meaning you can not 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 indexes. 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
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 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.
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
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
Partition Key vs Hash Key
Working with Partition Key in DynamoDB (Code Examples)
Query All Items With Partition Key
This will query your database and return all/multiple items with the partition key (
pk) attribute equal to
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 By Partition Key
This will get a single item where the partition key (
pk) attribute is equal to
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
This command is almost identical to the Get By Partition Key shown above, except we are using the
deleteItem command instead of the
Change/Update Partition Key
This command will modify the
firstname.lastname@example.org for the item where the partition key (
pk) attribute is equal to
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
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:
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.