This is the 2nd part of the article about Cosmos DB Modeling Methodology. In the first part I covered the theory, and now let’s review an example from the e-commerce industry which is usually well understood by a majority of us.

Conceptual Data Model

Use Cases

Let’s review a couple of use cases describing the business of a company owning the e-commerce platform.

A customer registers an account with different profile details, like addresses, contacts, and billing information.

A customer places orders, which consists of a set of ordered items. An order includes payment information and shipping details. An order is usually bound to one of the warehouses, to ship items from, but could be split into different packaged and shipped separately.

E-commerce platform sells a bunch of different product items. The system constantly monitors their availability in warehouses located in different countries.

The company is multinational and sells the same product items in different countries in different sizes, variants, and options. Therefore, they are represented differently on e-commerce websites depending on the country.

The list of use cases is simplified and not complete. But it shows already a pretty good level of complexity

Let’s translate this business definition into the conceptual data model with a set of entities and relationships.

In the diagram later, the crow-foot notation is used to reflect a multiplicity of relationships. In addition, the entities positioning approach is applied to represent one-to-many relationships from left to right.

/uploads/stories/how-to-apply-cosmos-db-modeling-methodology-using-ddd-aggregates-dot-part-2/db1.jpg?1658259230742

Conceptual Data Model

Application workflow

The application workflow is complex and consists of many different queries. Let’s select the good representative ones which involve the entities described in the conceptual data model.

The queries could be logically split into the following categories:

1. Display Product specific:

Retrieve all the display products by country ID
Retrieve all the product display information including sizes, variants, and options for a particular country ID and SKU
Create new display products, sizes, variants, options

2. Product Item specific:

Retrieve the product item availability information for a particular warehouse

3. Account specific:

Create an account
Update or delete an account by the account ID
Retrieve the Bank Accounts for a certain account (by account ID)
Add bank account for a certain account (for account ID)
Retrieve/Update address information about an account by the account ID and address type
Retrieve the contract information for an account
Retrieve all the orders for an account

4. Order specific:

Retrieve all the orders details by order ID
Store the order information along with the order items
Retrieve all the order status history by order ID
Create package information for a particular order along with shipment information
Retrieve the payment information for an order

DDD design: aggregate definitions

Based on the conceptual data diagram as well as application workflow let’s identify the aggregates along with anchors, non-anchors, and value objects.

Distinguishing entities and value objects

First, let’s distinguish between the Entities and Value Objects.

This kind of separation comes mainly from the business logic and nature of the data. As you remember from the definitions, we need to evaluate the importance of the entity’s identity and the importance of what they are versus who or which they are.

An Account, Credit Card, Bank Account, Contacts, Order, Payment, Package, Product Item, Warehouse, Country, and Shipping Method pretty obviously represent objects with distinguishable identifiers, so let’s treat them as Entities.

Order status history is a real-world event of changing the actual status, so they should be treated as Entities as well.

Display Product is a Product Item represented in a particular Country along with a set of available options, sizes, and variants. It also has an identifier and is distinguishable so another Entity.

Unlike Display Product, objects like Size, Variant, and Options are mainly valuable by their attributes rather than identifier, so they are Value Objects.

Similarly Main Address, Ship Address, Order Type, Payment Method, Credit Card Type, and Order Status are containers with important descriptive information, they are valuable mainly by a set of attributes rather than their identifiers and should be treated as Value Objects.

Order Item cannot leave without parent order, so doesn’t have its own globally unique identifier. Order Items are value objects bound to Orders.

Aggregate boundaries

Since one of the main functionalities of the e-commerce system is placing the orders and delivering the goods, the Order entity is the first anchor entity we identify.

Accounts, Product Items, and Warehouses are referenced and shared by many orders, are concentrate lots of functionality around themselves, so they must be roots of their own Aggregates.

Display Product serves as a separate part of functionality responsible for UI representation of products in different locations around the globe. So, it is a separate aggregate.

Country and Shipping Method are dictionaries referenced in many places so they cannot be part of other aggregates and should be anchor entities.

We identified 7 Anchor Entities forming the skeleton for their 7 aggregates. Let’s now put the boundaries for these aggregates, assigning the rest of the entities and value objects to them.

The Entities like Main and Ship Address of an account, Credit Card, Bank Account, and Contact are always queried in the context of a particular Account, that is why we move these Entities to the Account aggregate.

Similarly, Order Payments, Delivering Packages, and Order Status History are always queried in the context of particular Order, that is why we move these Entities to the Order aggregate.

Finally, all the Value Objects are automatically assigned to the aggregates in which their parents are sitting.

Aggregates view

As a result of the Aggregates definition exercise, we identified 7 aggregates that could be named after their anchor entities: Country, Display Product, Account, Order, Product Item, Shipping Method, and Warehouse.

The Aggregate boundaries are reflected in the diagram.

/uploads/stories/how-to-apply-cosmos-db-modeling-methodology-using-ddd-aggregates-dot-part-2/db3.jpg?1658259824023

Aggregates Design

Mapping aggregates to LDM

Let’s review the process of Mapping the Aggregates to the Cosmos DB documents and containers.

MR1

According to the mapping rule MR1 initially, we define the 7 containers which we could name after the Anchor Entities: DisplayProduct, Account, Order, ProductItem, Country, Shipping Method, and Warehouse.

MR2

MR2 defines the partition key for each container: identifiers of the Anchor entities, which in our example are equal to ProductID, AccountID, OrderID, ItemID, CountryID, ShippingMethodID, and WarehouseID respectively.

MR3

According to the MR3 we map non-anchor entities to separate document types in the same containers as the anchor entities they are connected to:

Credit Card, Bank Account, Contact in the Account container
Payment, Package, Order Status History in Order container

MR4

MR4 tells us what to do with value objects. Here we need to evaluate the growth rate and relationship type with related entities.

In our example, many Value Objects are uniquely defined by the related Entities. This is true for Main Address, Shipp Address, Contact Type, Order Type, Payment Method, Credit Card Type, and Order Status.

In the case of Sizes, Variants, and Options we have a one-to-few relationship type. This is true also for the Order->Order Item relationship.

According to the Query Usage Statistics, we see the update operations on these Value Objects are performed rarely.

Taking into account these observations we can model all the value objects mentioned above as JSON objects embedded in parent document types.

In contrast to the previous ones, the Item Availability value object could potentially grow significantly in the scope of each Item, since the number of Warehouses in which Items are stored could grow significantly. The frequency of updates could be really high as well. So according to the rule MR4, we map Product Availability to a separate document type in the scope of ProductItem Container rather than embed it to the parent Product Item document type.

MR5

According to the mapping rule MR5, we prepare the separate Dictionary Container to place the orphaned anchor entities of Country, Warehouse, and Shipping Method

MR6

All the document types connected to anchor entities from other containers reference them storing the proper identifiers of parent documents.

Let’s reflect the results of the mapping in the diagram.

/uploads/stories/how-to-apply-cosmos-db-modeling-methodology-using-ddd-aggregates-dot-part-2/db4.jpg?1658260457223

LDM: Cosmos Containers, Document Types and embedded JSON Objects

Physical optimization

There could be done a series of physical optimization in this example, let’s consider two of them.

Using the query statistics, we observe the querying of the Orders by the AccountID is very popular and widely used. Since the Order container is the biggest container, the number of physical partitions could grow to at least dozens of them. Under these circumstances, the usage of the index based on AccountID inside the Order container becomes not very efficient. So as an optimization for this scenario we put the copy of the Order documents to the Account Container which is partitioned by AccountID. In such a case we dramatically optimized this particular request.

Another observation we have is the dictionary Country is actually never changed document type. So, we could change the type of relationship—instead of referencing Country by CountryID in all the documents we could embed all the required country attributes into those documents. This will make the read request more efficient by removing the extra lookup request for country attributes by country ID.

After the optimization, the final data model will look like on a diagram below:

/uploads/stories/how-to-apply-cosmos-db-modeling-methodology-using-ddd-aggregates-dot-part-2/db5.jpg?1658260794381

Conclusion

This article introduced a methodology for building a Cosmos data model based on series of logical steps. The methodology uses the DDD Aggregate building approach and Cosmos modeling best practices.

Using this methodology, you can build data models with any level of complexity for both greenfield projects and large legacy migrations.