{"id":6622,"date":"2023-09-05T07:00:59","date_gmt":"2023-09-05T14:00:59","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/cosmosdb\/?p=6622"},"modified":"2025-01-31T09:34:50","modified_gmt":"2025-01-31T17:34:50","slug":"4-design-patterns-to-deal-with-large-item-sizes","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/cosmosdb\/4-design-patterns-to-deal-with-large-item-sizes\/","title":{"rendered":"4 Design Patterns to Deal with Large Item Sizes in Azure Cosmos DB for NoSQL"},"content":{"rendered":"

Introduction<\/span><\/b>\u00a0<\/span><\/h2>\n

A recommended best practice in Azure Cosmos DB for NoSQL is to avoid overly large item sizes. An Azure Cosmos DB item can represent either a document in a container, a row in a table, or a node or edge in a graph, depending on which API you use. Though the maximum size of an item allowed in Azure Cosmos DB for NoSQL is 2 MB<\/a>, it is strongly recommended to restrict item sizes to 1 – 5 KB. This blog post covers multiple approaches that you can use to model large objects within your Azure Cosmos DB-backed application. <\/span>\u00a0<\/span><\/p>\n

This post draws from our experiences of collaborating with different Software Engineering and Line-Of-Business (LOB) Application teams at Walmart.<\/span><\/p>\n

Why should I avoid large items?<\/span><\/b>\u00a0<\/span><\/h2>\n

Serialization is the process by virtue of which Azure Cosmos DB SDKs convert a Java POJO or .NET object into JSON. The SDKs require more time and high CPU utilization on the client-side to serialize large item sizes (e.g., 500 KB, 700 KB) for sending the JSON across the wire during a CRUD call. In high volume scenarios, this could result in users experiencing higher than normal write latency with <\/span>a high percentage of create item requests getting HTTP Status code 408 (time out)<\/a> eventually<\/span>. Your success with Azure Cosmos DB depends on how well you define and model for access patterns during data modeling.<\/span>\n\u00a0<\/span><\/p>\n

Short summary of the design patterns covered in this blog post.<\/span><\/b><\/p>\n\n\n\n\n\n\n\n
#<\/span><\/b>\u00a0<\/span><\/td>\n\n

Design Pattern<\/span><\/b><\/p>\n<\/td>\n

\n

User-end experience<\/span><\/b><\/p>\n<\/td>\n<\/tr>\n

1<\/span>\u00a0<\/span><\/td>\nDefault behavior<\/span><\/td>\nYou receive \u201cError 413: Entity too large\u201d.<\/span><\/td>\n<\/tr>\n
2<\/span>\u00a0<\/span><\/td>\nCQRS: Store large item in Azure Blob Storage with a pointer in Azure Cosmos DB<\/span><\/td>\nYou should use this for applications needing high durability and low-cost.<\/span><\/td>\n<\/tr>\n
3<\/span>\u00a0<\/span><\/td>\nSplit large item<\/span><\/td>\nRequires re-modeling at container level.<\/span><\/td>\n<\/tr>\n
4<\/span>\u00a0<\/span><\/td>\nCompress large item<\/span><\/td>\nOnly applicable for scenarios wherein additional compute time for uncompressing is OK.<\/span><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

\u00a0<\/span><\/p>\n

Design Patterns<\/span><\/b>\u00a0<\/span><\/h2>\n

Pattern #1: Default Behavior<\/span><\/b><\/h3>\n

The default behavior for Azure Cosmos DB for NoSQL is to reject items which are over the maximum permissible size limit. The limit is 2 MB. In such a situation, you are returned an error message indicating the item size is larger than the permissible limit. It is the responsibility of the developer to handle the exception, and implement the correct behavior, which could be based on one or more of the following design patterns mentioned below.<\/span>\u00a0<\/span><\/p>\n

The error encountered is similar to:<\/span>\u00a0<\/span><\/p>\n

2019-10-01T00:34:11.057681415Z {Error: Message: {\"Errors\":[\"Request size is too large\"]}<\/span>\u00a0<\/span>\r\n\r\n2019-10-01T00:34:14.057755320Z RequestStartTime: 2019-10-01T00:34:13.9695930Z, RequestEndTime: 2019-10-01T00:34:13.99955676Z, Number of regions attempted:1<\/span>\u00a0<\/span>\r\n\r\n2019-10-01T00:34:14.057768921Z ResponseTime: 2019-11-01T00:43:13.9995776Z, StoreResult: StorePhysicalAddress: rntbd:<<>>p\/, LSN: -1, GlobalCommittedLsn: -1, PartitionKeyRangeId: , IsValid: True, StatusCode: 413, SubStatusCode: 0, RequestCharge: 0, ItemLSN: -1, SessionToken: , UsingLocalLSN: False, TransportException: null, ResourceType: Document, OperationType: Create<\/span>\u00a0<\/span><\/pre>\n
This error is flagged off with HTTP Status Code 413. This refers to the fact that the item size in the request exceeded the allowable item size for a request. In<\/span>\u00a0such a scenario, it is recommended that you try and know the exact item size that you want to process. You can use the Azure Cosmos DB SDK to determine the size of the item size before sending it. Use <\/span>JsonConvert.SerializeObject<\/span><\/a> which serializes the specified object to a JSON string. You can then find the size sent over the wire using Encoding.UTF8.GetBytes.<\/span><\/p>\n
public static int GetTakeCount(IEnumerable<object> docs, int maxSizeKb = 500)<\/span>\u00a0<\/span>\r\n{<\/span>\u00a0<\/span>\r\n    var takeCount = docs.Count();<\/span>\r\n    while(takeCount > 1)<\/span>\u00a0<\/span>\r\n    {\r\n<\/span>         var bytes = Encoding.UTF8.GetBytes(JsonConvert.SerializeObject(docs.Take(takeCount)));\r\n<\/span>         if((bytes.Length \/ 1000) <= maxSizeKb)\r\n<\/span>         {\r\n             \/\/ array is small\r\n             break;\r\n<\/span>         }\r\n<\/span>         takeCount = Convert.ToInt32(Math.Ceiling((double)takeCount \/ 2));\r\n<\/span>    }\r\n<\/span>    return takeCount;<\/span> \r\n}<\/span><\/pre>\n
Pattern #2: CQRS: Store large item in Azure Blob Storage with a pointer in Azure Cosmos DB<\/span><\/b><\/h3>\n
If you have a use-case scenario wherein you need to be able to store a large item (usually in the form of a Binary Large Object (or, Blob)), it is recommended that you store the item in Azure Blob storage. Azure Blob storage is purpose-built storage for providing high durability and low-cost. You can store the meta-data related to the large item along with reference URI links as item properties in Azure Cosmos DB. As a developer, you need to refactor your application code to read and write blobs from the Azure Blob storage container.<\/span>\u00a0<\/span><\/p>\n
Command and Query Responsibility Segregation (CQRS)<\/strong><\/a> pattern ensures that you separate write (or, update) and read operations for the Azure Cosmos DB data store using a queue for asynchronous processing. This will ensure high performance, scalability, and security of your user-end application.<\/span><\/p>\n
Three practical design decisions for this pattern include:<\/span><\/p>\n
    \n
  1. You need to ensure data object mapping does not get overly complicated. This will affect latency for writes and reads while writing and reading large items from the Azure Blob storage container respectively.<\/span><\/span><\/span><\/li>\n
  2. You need to handle data contention on the client-end wherein two or more write operations performed in parallel could be accessing (updating and subsequently reading) the same set of data. Azure Cosmos DB has support for multiple types of CRUD operation conflict resolution policies including Last Write Wins (LWW) and custom conflict resolution via a merge stored procedure. Read here<\/a> for further information.<\/span><\/span><\/span><\/li>\n
  3. You need to encapsulate any business logic-related customization in your application code. This should not be part of the Azure Cosmos DB data model.<\/span>\u00a0<\/span><\/li>\n<\/ol>\n
    This pattern is illustrated using the architecture below:<\/span><\/p>\n