Depth

When a document points at another document — a post with an author, a page with a category — Dyrected stores that link as the related document's ID. depth decides whether a read hands you back that raw ID or follows the link and returns the whole related document. It's the difference between author: "author-123" and author: { id: "author-123", name: "Alice" }.

How depth reads

depth is a number. Each level tells Dyrected to follow relationships one step further:

• depth: 0 — relationships stay as IDs. You get author: "author-123".
• depth: 1 — relationships are populated one level deep. You get the full author document.
• depth: 2 and up — relationships inside those populated documents are followed too, one more level per number.

// Just the IDs — no related documents fetched
const shallow = await client.collection('posts').find({ depth: 0 })
// shallow.docs[0].author === 'author-123'

// One level — each post arrives with its author document attached
const populated = await client.collection('posts').find({ depth: 1 })
// populated.docs[0].author.name === 'Alice'

If you don't pass depth, Dyrected uses 1 — enough to populate the immediate relationships you usually want to render, without pulling in the whole graph.

Only relationships cost depth

Plain fields — text, numbers, groups, arrays, rich text — are always returned in full, at every depth. Depth only governs how far Dyrected walks relationship links. So depth: 0 still gives you a post's title and body; it just leaves author as an ID.

This is why raising depth is something you do deliberately. Each extra level can fan out into many more database reads as relationships branch, so ask for the depth a given view actually needs rather than reaching for a large number by default.

Setting depth per read

depth is a per-call option on both list and single-document reads:

// A list read
await client.collection('posts').find({ depth: 1 })

// A single document — findOne takes depth too
await client.collection('posts').findOne('post-1', { depth: 2 })

// The chained builder form
await client.collection('posts').find().depth(1)

Pick the depth at the call site, matched to what you're about to render: 0 when you only need IDs or scalar fields, 1 to show a related document's fields directly, higher only when you're rendering relationships-of-relationships.

Changing the default for every read

If most of your reads want the same depth, set defaultDepth once when you create the client instead of repeating it on every call. Dyrected applies it to any document read — find, findOne, global().get(), and media listing — that doesn't pass its own depth:

const client = createClient<Schema>({
  baseUrl: 'https://example.com',
  defaultDepth: 0, // reads return relationship IDs unless a call asks for more
})

A per-call depth always wins over the client default — including depth: 0, so you can still ask for shallow results even when the default is higher. If you set neither, the default is 1.

Depth pairs naturally with filter and sort — you can narrow, order, and populate in the same call, and the populated documents respect your where and sort.