Associations Deep-Dive: hasMany, belongsTo, Nested Properties, and Eager Loading

[bpamiri]

Read: https://blog.wheels.dev/posts/associations-deep-dive-wheels-4

You build the blog, and then the requests start coming. The author page needs every post that author wrote. The post page needs every comment, but only the ones belonging to that post. Deleting an author shouldn't orphan a hundred posts pointing at a dead foreign key. The admin form edits a post and adds three comments in one submit. The index renders 50 posts with their author's name — and you don't want 51 queries to do it.

Every one of those is a join, a foreign key, and a lifecycle rule. Associations are the part of the ORM that turns all of it into declarations you write once in config(). This post is the comprehensive 4.0 walkthrough.

What's in it

The three types. belongsTo (this model holds the FK), hasMany (FK on the other table, many rows), and hasOne (FK on the other table, exactly one) — plus how Wheels deduces modelName, foreignKey, and joinKey from a single name argument, and the named-argument syntax for overriding them.

The exact dynamic methods each generates. This is the part people guess at. A belongsTo gives you two methods; a hasOne, seven; a hasMany, eleven. The post has a table per type — author.posts(), author.postCount(), author.hasPosts(), author.addPost(), author.removeAllPosts(), author.deleteAllPosts() — with the naming rule that decides singular vs. plural verbs.

Cascading deletes with dependent=. The five legal values are delete, deleteAll, remove, removeAll, and false. Two things worth flagging up front for anyone coming from another ORM:

• There is no nullify value. FK-nulling is remove (instantiated, runs callbacks) or removeAll (bulk, no callbacks). Anything outside the five throws Wheels.InvalidArgument when the parent is deleted and the cascade runs.
• belongsTo takes no dependent argument — it doesn't own the related records.

Nested properties. Save a parent and its children from one params struct with one .save(). autoSave defaults to true (children save automatically); allowDelete defaults to false (opt in before _delete works). Must be declared after the association it names, or you get Wheels.AssociationNotFound.

Eager loading with include=. Collapse the N+1 into a single JOIN. Comma-list direct associations; use parentheses for nested includes (include="artist(genre)") — but those are query-only. findOne optimizes to maxRows=1 unless you include a hasMany.

has-many-through for many-to-many via shortcut (+ through when names diverge), and polymorphic associations (as= on the parent, polymorphic=true on the child) — including the hard rule that a polymorphic belongsTo cannot be eager-loaded (Wheels.PolymorphicIncludeNotSupported); you resolve it per row through the dynamic getter.

The sharp edges (the part worth arguing about)

The post closes with a Sharp Edges section built from real, cited behavior:

• Getters return query objects, not arrays — loop with <cfloop query="posts">, not array=.
• Join-type defaults differ by association: belongsTo uses INNER JOIN, hasMany/hasOne use LEFT OUTER JOIN. Including a belongsTo with the default join silently drops parent rows that have no matching child. Pass joinType="outer" if a post might have no author and you still want the post.
• Mixing positional and named arguments errors every time — the instant you pass one option, name them all.

Discussion

A few things I'd genuinely like to hear from people on:

• Polymorphic + eager loading. The per-row resolution is correct but it's the one place the N+1 sneaks back in. Has anyone built a clean batching pattern around polymorphic parents — group by type, one finder per type — that's worth documenting?
• The query-vs-array default. Do you mostly take the query and loop it, or do you reach for returnAs="objects" in associations enough that the default feels wrong?
• dependent= defaults. It defaults to false (do nothing) — which is the safe-but-surprising choice. Do you wish a generated model wired dependent="delete" by convention, or is silent-no-cascade the right default?

If the post is missing a scenario you hit in production, drop it below — happy to fold real cases into a follow-up.