After a lot of reading (and a Pluralsight course) about CosmosDB and also a lot of chatting to other developers about this technology I came to a conclusion.

Some people have only a vague understanding of what CosmosDB really is, which results in the same StackOverflow questions over and over again.

In this different type of blog I will straight up list some facts about CosmosDB that people seem to get wrong, or simply don't know about.

(If i get something wrong, please politely let me know.)

  1. The partition key value of a document cannot change. This means that if you ever try to update the partition key of a document you will get an error and if you upsert it, a new document will be created with the same id but a different partition key.
  2. Your partition key should be a property that is likely to take as many values as possible. Once you max out each partition's size, it's game over for this collection.
  3. The partition key set in a collection can NEVER change. Once a collection is created with a particular partition key your only option is to migrate this collection to another one. Also, if you create a collection with no partition key you can never add one in the future.
  4. If you desperately need to change the partition key of a document, your only option is deleting the document and adding it from scratch with the changed value.
  5. The Id is not actually a bad option for a partition key.
  6. You cannot have more than one partition key per collection even though the SDKs make it look like you can.
  7. The id value is only unique inside it's own partition. The only way to have your id value to be truly unique is to set the id property as the collection partition key.
  8. Databases, Collections, Documents, Offers and pretty much everything in CosmosDB inherit from a single type, the Resource.
  9. If you don't care about instant indexing, changing the Indexing mode to Lazy will actually prioritise document manipulation/querying operations over document indexing. This offers better performance for your application.
  10. Selecting only specific columns on a query will reduce the RU charge for this operation.
  11. Operations like Count are cheaper if done via the SDK's Count method and not with the select value count(1) from c query.
  12. Cross partition queries cost A LOT more than partition specific ones, so specify your partition key value whenever you can while querying.
  13. CosmosDB charges based on the maximum collection throughput hourly. This means that if you have a collection provisioned on 400 RU/s, even if you increase RU/s to 1000 for one second, you will be charged for 1000 RU/s for this hour.
  14. You can override the Indexing policy and enable scan at the query level of on operations by setting the x-ms-documentdb-query-enable-scan header.
  15. CosmosDB does NOT support partial document updates yet. However the CosmosDB team is working on it.
  16. Cross-partition ORDER BY with many results will cost A LOT. (Like seriously, a lot a lot)
  17. Every collection by default is provisioned with string properties indexed as Hash. This means, you can only do exact equality querying but not ORDER BY, TOP etc.
  18. CosmosDB is not meant to be used for asset storage, that's why each document has a size limit of 2 MB. Use Azure Blob Storage for that.
  19. The Azure CosmosDB Emulator only fully supports the SQL API and the MongoDB API. Table, Graph, and Cassandra containers are not fully supported.
  20. There is a C# library called Cosmonaut which will make the usage of CosmosDB in your C# application insanely straightforward. Give it a go.