Relation Paths And Scopes

Relation Paths And Scopes

Relation-aware features depend on the resolved registry that ToolBuilder builds from every registered model config.

Direct And Nested Relations

Direct relations come from relations([...]) on the current model.

Nested relations are derived from those direct relations plus the related models' own registered configs. That means a nested path such as author.company only exists when:

• author is configured on the root model
• the related Author model is also registered in the same ToolBuilder
• company is configured on Author

If a related model is not registered, the relation is dropped from the resolved schema.

Relation Path Depth

relationPathMaxDepth() limits dotted relation paths.

• 1 means no nested relation hops
• values below 2 effectively limit you to direct relations only for nested features
• the default is 5

Which Relation Kinds Support Dotted Column Paths

Dotted column references such as author.name work only for relation kinds that the join planner can translate into SQL join hops:

• belongsTo
• hasOne
• hasMany
• belongsToMany

That support is used by:

• where
• expressions
• select
• groupBy
• orderBy

Relation kinds such as morphOne, morphMany, morphTo, hasOneThrough, and hasManyThrough are not available as dotted column references.

These joins are derived from the requested relation-path columns. The current request shape does not let the agent declare arbitrary joins itself.

Expressions Across Relations

Named expressions can use relation-path columns too, with two important limits:

• expression columns must be numeric
• all columns inside one named expression must come from the root model or one single relation path

That means an expression can use price and discount, or lineItems.amount plus a literal, but not mix unrelated relation paths in one expression tree.

Eager Loading vs Column Paths

with and withAggregate are not exactly the same as dotted column references:

• with works with configured relation paths and applies related scopes
• withAggregate works on configured direct relations only
• dotted column references need a resolvable join path, which is a stricter requirement

This is why a relation can be valid for eager loading but still be invalid as a dotted where or select column.

Scope Propagation

Scopes are reused across relation-aware features:

• root scopes are applied to the root query
• related scopes are applied when eager loading relations
• related scopes are applied when running withAggregate
• relation-path joins carry the related model's scopes into the query planning context

That keeps AI-facing queries aligned with the same visibility and tenancy rules your application already uses elsewhere.