Understanding Depth

In Dyrected, relationship fields (such as collections referencing other collections) are stored in the database as document IDs. When you query your data, you can control how many levels of these relationships are automatically resolved (hydrated) using the depth parameter.

What is Depth?

The depth parameter is an integer that defines the recursive limit of relationship traversal:

• depth: 0: No relationships are populated. You receive only the ID strings of the related documents.
• depth: 1 (Default): Traverses one level deep. Direct relationships are hydrated with their full document data, but any relationships within those documents remain as ID strings.
• depth: 2: Traverses two levels deep. Nested relationships (e.g., product $\rightarrow$ category $\rightarrow$ parent category) are hydrated.

Worked Example

Consider a posts collection that has a relationship field named author pointing to a users collection, and the users collection has a relationship field named role pointing to a roles collection.

Here is how the returned JSON looks for the same document at different depths:

Querying at depth: 0

Only the reference IDs are returned:

{
  "id": "post_101",
  "title": "Introduction to Dyrected",
  "author": "user_abc" // Only the reference ID
}

Querying at depth: 1 (Default)

The author document is resolved, but the author's role remains an ID:

{
  "id": "post_101",
  "title": "Introduction to Dyrected",
  "author": {
    "id": "user_abc",
    "name": "Jane Doe",
    "email": "[email protected]",
    "role": "role_admin" // Direct relationship inside author remains an ID
  }
}

Querying at depth: 2

Both the author document and their associated role are fully hydrated:

{
  "id": "post_101",
  "title": "Introduction to Dyrected",
  "author": {
    "id": "user_abc",
    "name": "Jane Doe",
    "email": "[email protected]",
    "role": {
      "id": "role_admin",
      "name": "Administrator",
      "permissions": ["all"]
    }
  }
}

Recommendations & Best Practices

• Use depth: 1 by default when querying collections containing relationship fields. This populates direct relationship properties (like names and labels) automatically, eliminating the need to write extra round-trip queries manually.
• Use depth: 0 for list pages where you only need high-level fields (e.g. title, slug) and do not need to display details about related documents. This reduces payload size and database fetch times.
• Avoid setting extremely high depth values (e.g. depth: 5) unless absolutely necessary, as it can cause large payloads and complex database query overhead.