Make JSON DEPTH unlimited – new feature in MariaDB 12.1
At some point, nearly every developer encounters a common challenge: working with deeply nested JSON only to run into an arbitrary depth limit imposed by the database. In our case, that hard cap was set at 32 levels — sufficient for many scenarios but too restrictive for more complex or dynamic data structures. To address this, we decided to remove the limitation entirely.
The database now supports JSON documents and JSON paths with virtually unlimited nesting! This change unlocks the ability to work with more flexible and expressive data models without forcing developers to restructure or flatten their data.
What’s even better is that this enhancement requires no changes to syntax or application logic. From the user’s perspective, everything continues to work exactly the same, with all improvements happening transparently behind the scenes.
This update also improves query diagnostics. The optimizer trace, which shows how the database executes queries, can now fully represent execution plans deeper than 32 levels. This is particularly valuable for complex queries involving multiple nested subqueries or join trees, providing developers with detailed and complete visibility into query planning and optimization.
High-Level Implementation Details
Previously, the system used a fixed-size array to track values associated with each JSON nesting level, capped at 32 — directly enforcing the depth limit. To support unlimited nesting, we replaced this with a dynamic array that grows as needed. It starts with a default size of 32 and grows by 3200 whenever the current capacity is exceeded. This allows the system to safely handle arbitrarily deep JSON structures without crashing or requiring predefined limits.
Example:
SELECT JSON_QUERY('{"key1":123, "key1": [1,2,3]}', concat('$', repeat('.k', 1000))) AS exp;This query is now valid and no longer errors out with “Limit of 32 on JSON nested structures depth is reached.”
Why This Matters to You
Rich Data Modeling: Real-world data often comes in deeply nested forms. Unlimited depth lets developers store these naturally, without flattening or splitting data across multiple tables.
Simpler Application Logic:Developers can avoid complex transformations or pre-processing to work around artificial limits, reducing development time and minimizing bugs.
Better API Integration:Modern APIs and data interchange formats frequently use nested JSON structures. Unlimited depth support means the database can natively handle these complex payloads effectively.
Improved Schema Evolution:As applications grow, JSON schemas tend to evolve and deepen. Removing depth restrictions lets developers extend and modify schemas without worrying about hitting hard limits.
Enhanced Compatibility with Document Stores:As the boundaries between relational and document databases blur, unlimited depth strengthens JSON support, making it easier to build.
In short, ditching the JSON depth limit means more freedom for your data, less fuss in your code, and clearer insight into query performance — all without changing how you work.
Dropping the depth ceiling is more than a technical milestone—it’s a commitment to letting your data stay as rich as the real-world problems you’re solving. You can start benefiting immediately: no code changes, no new syntax, just deeper insights and simpler pipelines. Spin up the 12.1 preview, throw your most nested payloads at it, and let us know what you build next. Questions or feedback? Join the conversation in our community forum or check out the release notes for all the details.
Freedom for your data starts now!
MariaDB 12.1 release is coming soon — your feedback directly shapes its future. Try the preview, test it, and help us make 12.1 better.
