Cosmos: Document behavior and pitfalls when documents are missing mapped properties

[divega]

This is the documentation part of the decision recorded at dotnet/efcore#13131 (comment)

The short version is that in a schema-less database like Cosmos DB it is valid for each document in a container to contain completely different set of properties. In an object mapping situation this translates into some of the mapped properties being absent. Cosmos DB provides a function IS_DEFINED() that can be used in queries to test for this situation. Note also that a property not being defined is different (albeit one can argue only slightly) from the value being null.

One common scenario we expect this will happen is when Cosmos DB provider users add properties to classes for which they have already stored instances in the database: The existing instances will be missing those new properties.

[divega]

Another important aspect of missing properties is that due to limitations on how Cosmos DB indexes work, an ORDER BY on a property can cause document instances that are missing the property to be filtered out from the results.

This was going to be fixed as part of an improvement to index layouts for Cosmos DB, but I am not sure if it is working. It should be easy to test...