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 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 products p JOIN s IN p.sizes WHERE s.count > 50

You can also easily write queries that calculate aggregates such as Sum() by one or more or all sizes. or count the number of attributes in the array itself. There are lots of different ways that storing properties that have denote the same or similar attributes becomes much easier to manage when you store these as a child array in a document. As your product range expands, you won’t need to change your database structure, making it adaptable to evolving needs.

Scenario 2: Handling Room Attributes

Suppose you’re managing hotel rooms with varying attributes like prices in different currencies and sizes measured in square meters and square feet. In a traditional SQL database, you might have separate fields for PriceUSD, PriceEUR, SizeSquareMeters, and SizeSquareFeet or possibly even different tables for hotel rooms in Europe versus the US. Using an Attribute Array approach however, you can create a much simpler data model which is easier to maintain and easier to query.

Instead of predefined fields, you use arrays for the different attributes of prices and sizes:

{
  "id": "unique_room_id",
  "prices": [
    { "currency": "USD", "price": 149.99 },
    { "currency": "EUR", "price": 129.99 }
  ],
  "sizes": [
    { "unitMeasurement": "SquareMeters", "size": 30 },
    { "unitMeasurement": "SquareFeet", "size": 323 }
  ]
}

Now, if you want to find rooms with prices exceeding 750 in any currency or sizes greater than 200 in any unit, you can easily construct queries:

SELECT VALUE r FROM rooms r JOIN p IN r.prices WHERE p.price > 750
SELECT VALUE r FROM rooms r JOIN s IN r.sizes WHERE s.size > 200

This approach makes it simpler to adapt to changes in currencies or measurement units without altering your database schema.

In both scenarios, the Attribute Array design pattern in Azure Cosmos DB offers flexibility, scalability, and adaptability, making it a powerful choice for handling dynamic and evolving data structures.