EF Core Azure Cosmos DB Provider Limitations

The Azure Cosmos DB database provider targets the Azure Cosmos DB NoSQL store, which is a document database. Most EF Core providers target relational databases. Document databases and relational databases behave in fundamentally different ways. EF Core does not attempt to hide these differences; rather EF Core provides common patterns that can be used successfully across both kinds of database, together with features tailed to a particular provider that follow best practices for a given type of database. If a feature of EF Core is a pit-of-failure for a certain kind of database, then typically the database provider will not implement that feature, and instead help steer uses towards a pit-of-success approach.

Common EF Core patterns that either do not apply, or are a pit-of-failure, when using a document database include:

• Schema migration is not supported, since there is no defined schema for the documents. However, there could be other mechanisms for dealing with evolving data shapes that do make sense with Azure Cosmos DB NoSQL, For example, Schema versioning pattern with Cosmos DB, and Cosmos data migration.
• Reverse-engineering (scaffolding) a model from an existing database is not supported. Again, this is not supported because there is no defined database schema to scaffold from. However, see Use shape of documents in the Cosmos database to scaffold a schema.
• Schema concepts defined on the EF model, like indexes and constraints, are ignored when using a document database, since there is no schema. Note that Azure Cosmos DB NoSQL performs automatic indexing of documents.
• Loading graphs of related entities from different documents is not supported. Document databases are not designed to perform joins across many documents; doing so would be very inefficient. Instead, it is more common to denormalize data so that everything needed is in one, or a small number, of documents. However, there are some forms of cross-document relationships that could be handled--see Limited Include support for Cosmos.

Warning

Since there are no sync versions of the low level methods EF Core relies on, the corresponding functionality is currently implemented by calling .Wait() on the returned Task. This means that using methods like SaveChanges, or ToList instead of their async counterparts could lead to a deadlock in your application

Beyond the differences in relational and document databases, and limitations in the SDK, the EF Core provider for Azure Cosmos DB NoSQL does not include everything that could be implemented using the combination of EF Core and the Cosmos SDK. Potential enhancements in this area are tracked by issues in the EF Core GitHub repo marked with the label area-cosmos The best way to indicate the importance of an issue is to vote (👍) for it. This data will then feed into the planning process for the next release.