Over the years, customers have asked us for help in designing applications around specific scenarios they were trying to achieve. In some cases, these centered around implementing certain patterns using a JSON-based NoSQL database. Some of these patterns are very common in the NoSQL world, but not well understood by those new to NoSQL databases. Other patterns were very specific to the Cosmos DB service itself in demonstrating how to leverage specific capabilities to solve difficult architectural challenges.

We’ve been capturing these patterns and sharing them with customers individually. We felt now was a good time to publish some of these more broadly to make more discoverable by users. The result is Azure Cosmos DB Design Patterns. A repository on GitHub that includes a wide variety of samples that show how to implement specific patterns to that will allow you to solve design-related challenges when using Azure Cosmos DB for your solutions.

To help share these, we’ve created a blog post series on each of them. Each post will focus on a specific design pattern with a corresponding sample application that’s featured in this repository. We hope you enjoy and find this series useful.

Azure Cosmos DB design pattern: Attribute array

This post will focus on the attribute array pattern. The attribute array pattern creates JSON arrays consisting of multiple similar properties or fields grouped together in a child array versus having as individual properties on the parent object.

The main advantage of this pattern is that rather than creating multiple indexes for every property/field, there is only one path to index. In cases where you have to add another property/field later, it can be easily added to the collection. You can add this attribute easily versus the typical data model change and reindex procedure necessary for property-based attributes. This pattern is especially useful in optimizing indexing in scenarios with sparse properties that may not always contain a value or where the property is not defined when null.

Let’s dive into the Attribute Array NoSQL design pattern using Azure Cosmos DB, illustrated through two practical scenarios:

Scenario 1: Managing Product Sizes

Imagine you’re running an e-commerce website and need to track product sizes like Small, Medium, and Large for different inventory items. In a traditional SQL database, you might create separate fields for each size (e.g., SizeSmall, SizeMedium, SizeLarge). However, with Azure Cosmos DB’s Attribute Array pattern, you can create a more optimized and flexible structure.

Instead of fixed fields on the parent, you use an array property called “Sizes” containing objects with size names and counts. This allows you to easily add new sizes without altering your database schema. Here’s a simplified JSON example:

{
  "id": "unique_product_id",
  "name": "Product Name",
  "category": "Product Category",
  "price": 29.99,
  "sizes": [
    { "name": "Small", "count": 50 },
    { "name": "Medium", "count": 75 },
    { "name": "Large", "count": 60 }
  ]
}

With this setup, querying for products with a count greater than 50 for any size becomes straightforward, using a JOIN expression:

SELECT VALUE p FROM pr