Azure-docs: Confusing description of throughput assignment

[zepedaherbey]

Under Logical Partitions, you mention the following:
"...the throughput that you provision on the container are automatically (horizontally) partitioned across a set of logical partitions."

Then, under Physical Partitions you state the following:
"Throughput provisioned for a container is divided evenly among physical partitions"

But, we also know that multiple logical partitions can be mapped to the same physical partition.

This is a little confusing. My understanding was that if I allocate 400 RU's/s at the container level, I have 400 RU's/s available for each logical partition. Is my understanding consistent with the way Cosmos DB works? or does the fact that there is not a 1-1 mapping between physical and logical partitions change things?

Thanks

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: 9da32a62-a60f-1013-bb2f-688c67a446ec
• Version Independent ID: 7a2bf261-0a20-30f0-837d-cf02700034aa
• Content: Partitioning and horizontal scaling in Azure Cosmos DB
• Content Source: articles/cosmos-db/partition-data.md
• Service: cosmos-db
• GitHub Login: @rimman
• Microsoft Alias: rimman

[rimman]

Azure Cosmos DB provides throughput guarantees at the container level if you provision throughput on a container or at the database level, if you provision throughput on database. There is no reserved throughput at individual partition key level. As long as your requests are distributed across sufficient number of partition keys you should be able to drive the utilization very high. I hope this helps. Please follow these best practices for partitioning https://docs.microsoft.com/en-us/azure/cosmos-db/partitioning-overview#choose-partitionkey (this will ensure you that you will drive the utilization of the provisioned throughput).

[zepedaherbey]

So, I understand that if we allocate 1000 RU/s to the container, and we have 5 partitions, each partition will have a limit of 200 RU/s.
From a purely throughput perspective, what is the motivation to have a partition key? Why not just put everything under the same partition?
You mention that we could have "hot spots" but this doesn't seem to be any different with partitions. I am confused...
Thanks

[Mike-Ubezzi-MSFT]

Hi @zepedaherbey, want provide a link to a Stack Overflow thread: Why is cosmos db creating 5 partitions for a same partition key value? where this is discussed in greater detail.

When using the Unlimited collection size, by default you will be provisioned 5 physical partition key ranges. This number can change, but as of May 2018, 5 is the default. You can think of each physical partition as a "server". So your data will be spread amongst 5 physical "servers". As your data size grows, your data will automatically be re-distributed against more physical partitions. That's why getting partition key correct upfront in your design is so important.

The problem in your scenario of having the same Partition Key (PK) for all 200k records is that you will have hot spots. You have 5 physical "servers" but only one will ever be used. The other 4 will go idle, and the result is that you'll have less performance for the same price point. You're paying for 50k RU/s but will ever only be able to use 10k RU/s. Change your PK to something that is more uniformly distributed. This will vary of course how you read the data. If you give more detail about the docs you're storing then we may be able to help give a recommendation. If you're simply doing point lookups (calling ReadDocumentAsync() by each Document ID) then you can safely partition on the ID field of the document. This will spread all 200k of your docs across all 5 physical partitions and your 50k RU/s throughput will be maximized. Once you effectively do this, you will probably see that you can reduce the RU usage to something much lower and save a ton of money. With only 200k records each at 2.1KB, you probably could go low as 2500 RU/s (1/20th of the cost you're paying now).

*Server is in quotes because each physical partition is actually a collection of many servers that are load-balanced for high availability and also throughput (depending on your consistency level).

We will now proceed to close this thread. If there are specific documentation edit that need to be made, please comment and we will gladly take these into consideration or you free to contribute.

[zepedaherbey]

Thank you for the response. This was helpful but did not quite address my concern. The reference you provided deals with an - unlimited collection size -.
In our case, we would like to start with a small volume of data (say 2 GB). We know that per logical partition, you allow up to 10 GB. In this case, all of our data fits into a single partition. As it relates to the demand for this data, it will also be a relatively low because this is an internal app.
Given these small numbers, why would I need multiple partitions? Why not allocate the full 400 RU/s to a single partition?

[rimman]

@zepedaherbey

The response above is conflating physical and logical partitions. Il want to make a clear distinction between logical and physical partitions - these are not the same thing.

• Logical partitions are controlled by the user. These are represented as partition keys – and users are instructed to choose a partition key that (1) distributes throughput for a given workload as evenly as possible across a high cardinality of values (2) efficiently routes queries – with attention focused on frequently run, high QPS queries and (3) ensures a given partition key value should not exceed size + throughput bounds.

• Physical partitions are the underlying infrastructure and are controlled by the service – users do not have any knobs/levers for tuning this – and this is expected to evolve over time as we refresh the underlying hardware (the above Stackoverflow response is already obsolete). The size of the physical partition is not material – as Cosmos DB will manage and redistribute logical partitions across a dynamic number of physical partitions.

Our external customers should be designing their applications - in which they should honor best practices for choosing logical partition keys.

When you start out with small volume (2GB) and let's say 400RUs (it may end up on a single physical partition) - but we still ask you to provide a logical partition key, just in case your data/workloads start to scale. Behind the scene - we do the transparent partition management and provide the SLAs for the throughput provisioned at the level of granularity at which you've provisioned throughput (e.g., container or database). I hope this helps. Thanks.

I highly recommend you watch this:
https://www.youtube.com/watch?v=bQBeTeYUrR8

Thanks!

[Mike-Ubezzi-MSFT]

Thank you for the additional dialog! Want to add the Cosmos DB UserVoice as a channel to provide product specific feedback and make product feature requests. The link filters on Partitions but feel free to modify the filter based upon other keywords or UpVote and comment on existing entries.

[zepedaherbey]

@rimman,
We are revisiting this issue.
In this article this statement is mentioned a couple of times:
(1)
"Most small Cosmos containers have many logical partitions but only require a single physical partition"

You state:
(2)
"When you start out with small volume (2GB) and let's say 400RUs (it may end up on a single physical partition)"

I would like clarification on the "Most" in statement (1) ad the "it may.." on statement (2).

I am particularly interested in knowing under what conditions is a container allocated one (and only one) physical partition.

Thanks

[Mike-Ubezzi-MSFT]

@zepedaherbey This user has moved onto a new role. I can make @markjbrown aware of your inquiry or you can create a new issue if there is a specific area of the document you feel needs some clarification. In the current document, the Logical partitions section has the following statement:

Groups of items that have specific values for foodGroup, such as Beef Products, Baked Products, and Sausages and Luncheon Meats, form distinct logical partitions.

In this example the container has a partition key of /foodGroup and this creates a set of logical partitions based upon the foodGroup values listed, and each are 1 GB in size, all 4 logical partitions will be placed upon a single physical partition.

If these logical partitions grow in size over time (say 15GB each) and/or the RU requirements exceed 10k RUs, then this container will expand to 2 or more physical partitions. I say _and/or_ because the limit of a physical partition is 50GB or 10k RUs and if either threshold is exceeded by a logical partition in the collection or by the collection itself, then the Cosmos DB service will expand the collection to additional physical partitions.