Differentiate between partition keys & partition key ranges in Azure Cosmos DB

Question

I'm having difficulty understanding the difference between the partition keys & the partition key ranges in Cosmos DB. I understand generally that a partition key in cosmos db is a JSON property/path within each document that is used to evenly distribute data among multiple partitions to avoid any uneven "hot partitions" -- and partition key decides the physical placement of documents.

But its not clear to me what the partition key range is...is this just a range of literal partition keys starting from first to last grouped by each individual partition in the collection? I know the ranges can be found by performing a GET request to the endpoint https://{databaseaccount}.documents.azure.com/dbs/{db-id}/colls/{coll-id}/pkranges but just conceptionally want to be sure I understand. Also still not clear on how to granularly view the specific partition key that a specific document belongs to.

https://learn.microsoft.com/en-us/rest/api/cosmos-db/get-partition-key-ranges

Answer 1

You define property on your documents that you want to use as a partition key. Cosmos db hashes value of that property for all documents in collection and maps different partition keys to different physical partitions. Over time, your collection will grow and you might end up having, for example, 100 logical partition distributed over 5 physical partitions.

Partition key ranges are just collections of partition keys grouped by physical partitions they are mapped to. So, in this example, you would get 5 pkranges with min/max partition key value for each.

Notice that pkranges might change because in future, as your collection grows, physical partitions will get split causing some partition keys to be moved to new physical partition causing part of the previous range to be moved to new location.