You are viewing documentation for v1.0.x. Change


Through some simple configuration, Wheels allows you to unlock some powerful functionality to use your database tables' relationships in your code.

Associations in Wheels allow you to define the relationships between your database tables. After configuring these relationships, doing pesky table joins becomes a trivial task. And like all other ORM functions in Wheels, this is done without writing a single line of SQL.

3 Types of Associations

In order to set up associations, you only need to remember 3 simple methods. Considering that the human brain only reliably remembers up to 7 items, we've left you with a lot of extra space. You're welcome. :)

The association methods should always be called in the init() method of a model that relates to another model within your application.

The belongsTo Association

If your database table contains a field that is a foreign key to another table, then this is where to use the belongsTo() function.

If we had a comments table that contains a foreign key to the posts table called postid, then we would have this init() method within our comment model:

<cfcomponent extends="Model">

<cffunction name="init">
<cfset belongsTo("post")>


The hasOne and hasMany Associations

On the other side of the relationship are the "has" functions. As you may have astutely guessed, these functions should be used according to the nature of the model relationship.

At this time, you need to be a little eccentric and talk to yourself. Your association should make sense in plain English language.

An example of hasMany

So let's consider the post / comment relationship mentioned above for belongsTo(). If we were to talk to ourselves, we would say, "A post has many comments." And that's how you should construct your post model:

<cfcomponent extends="Model">

<cffunction name="init">
<cfset hasMany("comments")>


You may be a little concerned because our model is called comment and not comments. No need to worry: Wheels understands the need for the plural in conjunction with the hasMany() method.

And don't worry about those pesky words in the English language that aren't pluralized by just adding an "s" to the end. Wheels is smart enough to know that words like "deer" and "children" are the plurals of "deer" and "child," respectively.

An Example of hasOne

The hasOne() association is not used as often as the hasMany() association, but it has its use cases. The most common use case is when you have a large table that you have broken down into two or more smaller tables (a.k.a. denormalization) for performance reasons or otherwise.

Let's consider an association between user and profile. A lot of websites allow you to enter required info such as name and email but also allow you to add optional information such as age, salary, and so on. These can of course be stored in the same table. But given the fact that so much information is optional, it would make sense to have the required info in a users table and the optional info in a profiles table. This gives us a hasOne() relationship between these two models: "A user has one profile."

In this case, our profile model would look like this:

<cfcomponent extends="Model">

<cffunction name="init">
<cfset belongsTo("user")>


And our user model would look like this:

<cfcomponent extends="Model">

<cffunction name="init">
<cfset hasOne("profile")>


As you can see, you do not pluralize "profile" in this case because there is only one profile.

By the way, as you can see above, the association goes both ways, i.e. a user hasOne() profile, and a profile belongsTo() a user. Generally speaking, all associations should be set up this way. This will give you the fullest API to work with in terms of the methods and arguments that Wheels makes available for you.

However, this is not a definite requirement. Wheels associations are completely independent of one another, so it's perfectly OK to setup a hasMany() association without specifying the related belongsTo() association.

Database Table Setup

Like everything else in Wheels, we strongly recommend a default naming convention for foreign key columns in your database tables.

In this case, the convention is to use the singular name of the related table with id appended to the end. So to link up our table to the employees table, the foreign key column should be named employeeid.

Breaking the Convention

Wheels offers a way to configure your models to break this naming convention, however. This is done by using the foreignKey argument in your models' belongsTo() calls.

Let's pretend that you have a relationship between author and post, but you didn't use the naming convention and instead called the column post_id. (You just can't seem to let go of the underscores, can you?)

Your post's init() method would then need to look like this:

<cfcomponent extends="Model">

<cffunction name="init">
<cfset belongsTo(name="author", foreignKey="post_id")>


You can keep your underscores if it's your preference or if it's required of your application.

Leveraging Model Associations in Your Application

Now that we have our associations set up, let's use them to get some data into our applications.

There are a couple ways to join data via associations, which we'll go over now.

Using the include Argument in findAll()

To join data from related tables in our findAll() calls, we simply need to use the include argument. Let's say that we wanted to include data about the author in our findAll() call for posts.

Here's what that call would look like:

<cfset posts = model("post").findAll(include="author")>

It's that simple. Wheels will then join the authors table automatically so that you can use that data along with the data from posts.

Note that if you switch the above statement around like this:

<cfset authors = model("author").findAll(include="posts")>

Then you would need to specify "post" in its plural form, "posts." If you're thinking about when to use the singular form and when to use the plural form, just use the one that seems most natural.

If you look at the two examples above, you'll see that in example #1, you're asking for all posts including each post's author (hence the singular "author"). In example #2, you're asking for all authors and all of the posts written by each author (hence the plural "posts").

You're not limited to specifying just one association in the include argument. You can for example return data for authors, posts, and bios in one call like this:

<cfset authorsPostsAndComments = model("author").findAll(include="posts,bio")>

To include several tables, simply delimit the names of the models with a comma. All models should contain related associations, or else you'll get a mountain of repeated data back.

Joining Tables Through a Chain of Associations

When you need to include tables more than one step away in a chain of joins, you will need to start using parenthesis. Look at the following example:

<cfset commentsPostsAndAuthors = model("comment").findAll(include="post(author)")>

The use of parentheses above tells Wheels to look for an association named author on the post model instead of on the comment model. (Looking at the comment model is the default behavior when not using parenthesis.)

Handling Column Naming Collisions

There is a minor caveat to this approach. If you have a column in both associated tables with the same name, Wheels will pick just one to represent that column.

In order to include both columns, you can override this behavior with the select argument in the finder functions.

For example, if we had a column named name in both your posts and authors tables, then you could use the select argument like so:

    post = model("post").findAll(
        select=",, authors.post_id, AS authorname",

You would need to hard-code all column names that you need in that case, which does remove some of the simplicity. There are always trade-offs!

Using Dynamic Shortcut Methods

A cool feature of Wheels is the ability to use dynamic shortcut methods to work with the models you have set up associations for. By dynamic, we mean that the name of the method depends on what name you have given the association when you set it up. By shortcut, we mean that the method usually delegates the actual processing to another Wheels method but gives you, the developer, an easier way to achieve the task (and makes your code more readable in the process).

As usual, this will make more sense when put into the context of an example. So let's do that right now.

Example: Dynamic Shortcut Methods for Posts and Comments

Let's say that you tell Wheels through a hasMany() call that a post has many comments. What happens then is that Wheels will enrich the post model by adding a bunch of useful methods related to this association.

If you wanted to get all comments that have been submitted for a post, you can now call post.comments(). In the background, Wheels will delegate this to a findAll() call with the where argument set to

Listing of Dynamic Shortcut Methods

Here are all the methods that are added for the three possible association types.

Methods Added by hasMany

Given that you have told Wheels that a post has many comments through a hasMany() call, here are the methods that will be made available to you on the post model.

Replace XXX below with the name of the associated model (i.e. comments in the case of the example that we're using here).

Method Example Description
XXX() post.comments() Returns all comments where the foreign key matches the post's primary key value. Similar to calling model("comment").findAll(where="").
addXXX() post.addComment(comment) Adds a comment to the post association by setting its foreign key to the post's primary key value. Similar to calling comment.updateByKey(,
removeXXX() post.removeComment(comment) Removes a comment from the post association by setting its foreign key value to NULL. Similar to calling comment.updateByKey(, postid="").
deleteXXX() post.deleteComment(comment) Deletes the associated comment from the database table. Similar to calling model("comment").deleteByKey(
removeAllXXX() post.removeAllComments() Removes all comments from the post association by setting their foreign key values to NULL. Similar to calling model("comment").updateAll(postid="", where="").
deleteAllXXX() post.deleteAllComments() Deletes the associated comments from the database table. Similar to calling model("comment").deleteAll(where="").
XXXCount() post.commentCount() Returns the number of associated comments. Similar to calling model("comment").count(where="").
newXXX() post.newComment() Creates a new comment object. Similar to calling model("comment").new(
createXXX() post.createComment() Creates a new comment object and saves it to the database. Similar to calling model("comment").create(
hasXXX() post.hasComments() Returns true if the post has any comments associated with it. Similar to calling model("comment").exists(where="").
findOneXXX() post.findOneComment() Returns one of the associated comments. Similar to calling model("comment").findOne(where="").
Methods Added by hasOne

The hasOne() association adds a few methods as well. Most of them are very similar to the ones added by hasMany().

Given that you have told Wheels that an author has one profile through a hasOne() call, here are the methods that will be made available to you on the author model.

Method Example Description
XXX() author.profile() Returns the profile where the foreign key matches the author's primary key value. Similar to calling model("profile").findOne(where="").
setXXX() author.setProfile(profile) Sets the profile to be associated with the author by setting its foreign key to the author's primary key value. You can pass in either a profile object or the primary key value of a profile object to this method. Similar to calling model("profile").updateByKey(,
removeXXX() author.removeProfile() Removes the profile from the author association by setting its foreign key to NULL. Similar to calling model("profile").updateOne(where="", authorid="").
deleteXXX() author.deleteProfile() Deletes the associated profile from the database table. Similar to calling model("profile").deleteOne(where="").
newXXX() author.newProfile() Creates a new profile object. Similar to calling model("profile").new(
createXXX() author.createProfile() Creates a new profile object and saves it to the database. Similar to calling model("profile").create(
hasXXX() author.hasProfile() Returns true if the author has an associated profile. Similar to calling model("profile").exists(where="").
Methods Added by belongsTo

The belongsTo() association adds a couple of methods to your model as well.

Given that you have told Wheels that a comment belongs to a post through a belongsTo() call, here are the methods that will be made available to you on the comment model.

Method Example Description
XXX() Returns the post where the primary key matches the comment's foreign key value. Similar to calling model("post").findByKey(comment.postid).
hasXXX() comment.hasPost() Returns true if the comment has a post associated with it. Similar to calling model("post").exists(comment.postid).

One general rule for all of the methods above is that you can always supply any argument that is accepted by the method that the processing is delegated to. This means that you can, for example, call post.comments(order="createdAt DESC"), and the order argument will be passed along to findAll().

Another rule is that whenever a method accepts an object as its first argument, you also have the option of supplying the primary key value instead. This means that author.setProfile(profile) will perform the same task as author.setProfile(1). (Of course, we're assuming that the profile object in this example has a primary key value of 1.)

Performance of Dynamic Association Finders

You may be concerned that using a dynamic finder adds yet another database call to your application.

If it makes you feel any better, all calls in your Wheels request that generate the same SQL queries will be cached for that request. No need to worry about the performance implications of making multiple calls to the same author.posts() call in the scenario above, for example.

Passing Arguments to Dynamic Shortcut Methods

You can also pass arguments to dynamic shortcut methods where applicable. For example, with the XXX() method, perhaps we'd want to limit a post's comment listing to just ones created today. We can pass a where argument similar to what is passed to the findAll() function that powers XXX() behind the scenes.

<cfset today = DateFormat(Now(), "yyyy-mm-dd")>
<cfset comments = post.comments(where="createdAt >= '#today# 00:00:00'")>

Many-to-Many Relationships

We can use the same 3 association functions to set up many-to-many table relationships in our models. It follows the same logic as the descriptions mentioned earlier in this chapter, so let's jump right into an example.

Let's say that we wanted to set up a relationship between customers and publications. A customer can be subscribed to many publications, and publications can be subscribed to by many customers. In our database, this relationship is linked together by a third table called subscriptions (sometimes called a bridge entity by ERD snobs).

Setting up the Models

Here are the representative models:

<!--- Customer.cfc --->
<cfcomponent extends="Model">

<cffunction name="init">
<cfset hasMany("subscriptions")>

<!--- Publication.cfc --->
<cfcomponent extends="Model">

<cffunction name="init">
<cfset hasMany("subscriptions")>

<!--- Subscription.cfc --->
<cfcomponent extends="Model">

<cffunction name="init">
<cfset belongsTo("customer")>
<cfset belongsTo("publication")>


This assumes that there are foreign key columns in subscriptions called customerid and publicationid.

Using Finders with a Many-to-Many Relationship

At this point, it's still fairly easy to get data from the many-to-many association that we have set up above.

We can include the related tables from the subscription bridge entity to get the same effect:

<cfset data = model("subscription").findAll(include="customer,publication")>

Creating a Shortcut for a Many-to-Many Relationship

With the shortcut argument to hasMany(), you can have Wheels create a dynamic method that lets you bypass the join model and instead reference the model on the other end of the many-to-many relationship directly.

For our example above, you can alter the hasMany() call on the customer model to look like this instead:

<cfset hasMany(name="subscriptions", shortcut="publications")>

Now you can get a customer's publications directly by using code like this:

<cfset cust = model("customer").findByKey(params.key)>
<cfset pubs = cust.publications()>

This functionality relies on having set up all the appropriate hasMany() and belongsTo() associations in all 3 models (like we have in our example in this chapter).

It also relies on the association names being consistent, but if you have customized your association names, you can specify exactly which associations the shortcut method should use with the through argument.

The through argument accepts a list of 2 association names. The first argument is the name of the belongsTo() association (set in the subscription model in this case), and the second argument is the hasMany() association going back the other way (set in the publication model).

Sound complicated? That's another reason to stick to the conventions whenever possible: it keeps things simple.

Are You Still with Us?

As you just read, Wheels offers a ton of functionality to make your life easier in working with relational databases. Be sure to give some of these techniques a try in your next Wheels application, and you'll be amazed at how little code that you'll need to write to interact with your database.

^ Top
Table of Contents


Read and submit questions, clarifications, and corrections about this chapter.

[Add Comment]

  1. I was testing the associations using a simple database schema, which includes two tables, Genres and Movies.  They have a foreign key relationship defined in SQL Server on the genreid.

    Since I am following the conventions, the models are thus defined.


    <cfcomponent extends="Model" output="false">
        <cffunction name="init">
            <cfset hasMany("movies") />;


    <cfcomponent extends="Model" output="false">
        <cffunction name="init">
            <cfset belongsTo("genre") />;

    Here are the table columns:

    Genres                                  Movies
    genreid                                 movieid
    genrename                          title

    Whenever I do this in my Movies controller:
    <cfset movies = model("movie").findAll(include="genre", order="title") />;

    It throws:
    "Element genre is undefined in a CFML structure referenced as part of an expression.

    The error occurred in C:\ColdFusion8\wwwroot\victorwheels\wheels\model\crud.cfm: line 1018"

    I know the associations are not getting set when I step through it in the debugger.  What am I doing wrong?

  2. Per Djurner's Gravatar Per Djurner says:

    Hi Richard, try naming your models Genre.cfc and Movie.cfc instead.
    Also name the primary key "id" in both tables.

  3. Yes, that worked.  I don't recall why I thought one must pluralize the cfc names.  It did not give me a problem when I accessed the models without table joins, so I had assumed i was in the clear.

    Thank you for the quick reply.

  4. Dave's Gravatar Dave says:

    does anyone have a working example of "Joining Tables Through a Chain of Associations" that involves at least 3-4 chained tables in CFWheels?  

  5. JohnB's Gravatar JohnB says:

    In the hasmany association above it shows that  post.comments() is a valid function added as a result of the assocation, however when i try this i get an error:

    Entity has incorrect type for being called as a function.

    however the equivalent of post.comments works for me - is this a typo in the docs?

  6. Jeremy's Gravatar Jeremy says:

    Just curious as I've been unsuccessful in my there a way to model self joins in CFWheels?

  7. Per Djurner's Gravatar Per Djurner says:

    Jeremy, that is not supported yet unfortunately but we hope to have it in the next release (1.1).

  8. Emmanuel's Gravatar Emmanuel says:


    I am ready to embark on Wheels, I use Flex for client, I'm hoping to find enough Flash Remoting, to be able to get on Wheels. It already sounds great to me, I can't wait. Well, I'll let you know.

  9. Robert's Gravatar Robert says:

    I am new to wheels and am having a problem with associations.  I am working off of a legacy database, so I have to use the table() function in every model.  I have three tables:

    products (product information)
    categoriesChild (categories)
    product_categories_2 (joining table linking products and categories)

    I have 3 models:


    In my controller in I am calling the following in order to get all products in a category:

    The error I am getting is:
    The productcategoryproductcategoryls table could not be found in the database.

    Can anyone help?

  10. Mohamad's Gravatar Mohamad says:


    This is a bit late, but the information may still be helpful to others: This issue happens when one of the properties you have in the table has the same name as a method within that Model. So for example, you would get this error in the following setup:

    <!--- Post.cfc --->

    And it also happens that the posts table has a tags column.

  11. Wondering why associations have to be set up manually, rather than being introspected from the foreign key relationships in the database? Obviously if those exist, the associations are not optional in the application.

  12. Chris Peters's Gravatar Chris Peters says:


    It would be impossible for Wheels to guess the "nature" of the association. For example, is it hasMany or hasOne? A foreign key doesn't really indicate that information.

  13. Ah good point, I haven't used hasOne type associations much but I think I'm going to try them out on the e-commerce site I'm building, to associate images with products. In the past I've added image name columns to the products table, but this client wants to post up to a dozen images for each product and adding twelve columns to the products table for that seems ridiculous, not to mention hard to change if he later wants more or fewer images.

    One other question, is there a naming convention for cross reference tables i.e. a table for joining products and categories would be productcategories? I seem to remember reading about this somewhere but can't track it down....

Add Comment