SurrealQL FETCH clause depth and performance limits

Direct answer

SurrealDB does not publish a documented maximum depth for nested FETCH operations. The engine resolves record links recursively until no further references remain, but any internal recursion ceiling is not exposed in the public API. Treat deep nesting as unbounded only until you verify it on your target version.

Likely explanation versus confirmed facts

Statement	Status	Basis
No published hard depth limit for FETCH	Not documented	Public references do not specify a numeric ceiling
Implicit recursion ceiling exists to prevent stack overflow	Likely, unpublished	Exact value is not exposed
Multiple linked records resolve breadth-first	Likely	Immediate references are fetched before deeper levels
Cost grows roughly linearly with depth	Likely	Each level adds disk reads and object assembly
Circular references cause infinite recursion	Unconfirmed	May abort or timeout; test only in a disposable environment

Verification steps

1. Run a bounded read-only probe on non-production data:

SELECT * FROM my_table FETCH depth=5;

2. Record query latency, result size, and server memory before and after execution.
3. Increase depth incrementally, for example depth=10 then depth=20, until latency rises sharply or the server returns an error.
4. Inspect SurrealDB server logs for recursion, stack, or timeout warnings after each run.
5. If circular links exist, test in a sandbox first. Do not run unbounded FETCH against production graph data.

Recommendation

Cap FETCH depth at the shallowest level that satisfies the query, or denormalize frequently traversed edges. Avoid unbounded recursive resolution for large datasets because each additional level multiplies read amplification and memory pressure.

Missing diagnostic detail

Which SurrealDB version are you running? Internal limits and traversal behavior may vary across releases, and the version determines whether an explicit depth cap is available or safe to use.