Storing ordered lists

[lavish fern]

The documentation contains this recommendation:

"While it's useful that Convex supports nested objects and arrays, you should keep documents relatively small in size. In practice, we recommend limiting Arrays to no more than 5-10 elements and avoiding deeply nested Objects.

Instead, leverage separate tables, documents, and references to structure your data. This will lead to better maintainability and performance as your project grows."

Does this apply to use cases where I want to store ordered lists too?

[jaunty roost]

Hi @lavish fern. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:

---

Yes, this recommendation applies to ordered lists as well. The Convex documentation suggests limiting arrays within documents to about 5–10 elements and avoiding deeply nested objects, regardless of whether the array is ordered or not. This is due to performance, maintainability, and scalability concerns as your project grows. For larger or more complex ordered lists, it's recommended to use separate tables, documents, and references to represent the list items and their order, rather than storing large arrays directly within a single document. This approach will help you avoid hitting array size limits (such as the 8192 element maximum) and will make your data model more flexible and performant as your application scales Document IDs.

If you need to maintain order, you can add an explicit ordering field (like an index or position) to each item in the separate table. This pattern is common and recommended for handling ordered collections in Convex.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

@lavish fern Kapa.ai is still learning and improving, please let me know how I did by reacting below.

[lavish fern]

Why is it more flexible and performant that way? Aren't queries faster if I only need to load one document instead of many?

@jaunty roost Why is it more flexible and performant that way? Aren't queries faster if I only need to load one document instead of many?

[jaunty roost]

Let me check the knowledge base for you again. One moment! :books:

---

Great question! While loading a single document can be fast for small arrays, Convex recommends splitting large or ordered lists into separate tables for several reasons:

1. Performance at Scale: Convex recommends limiting arrays in documents to about 5–10 elements. Larger arrays can lead to performance issues, especially as your data grows. Queries that require scanning or updating large arrays become slower and less efficient. Convex is optimized for queries that use indexes and references between documents, which scale much better than large, nested arrays Document IDs.

2. Maintainability: Using separate tables and references makes your data model easier to manage and extend. For example, you can add, remove, or reorder items in a list without rewriting the entire array field in a document. This is especially important for collaborative or frequently updated data.

3. Query Flexibility: With separate tables, you can efficiently query, filter, and paginate list items using indexes. This is not possible with large arrays inside a single document, since you can't index into arrays and would need to load and process the entire array in memory Other Recommendations.

4. Limits and Best Practices: Convex enforces a hard limit of 8192 entries per array and recommends much smaller arrays in practice. Storing large lists in arrays risks hitting these limits and can make your application brittle Document IDs.

So, while loading a single document is simple and fast for small lists, using separate tables and references is more flexible and performant for larger or ordered lists, especially as your application and data grow.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: