A CFML ORM Engine

Why?

Quick was built out of lessons learned and persistent challenges in developing complex RDBMS applications using built-in Hibernate ORM in CFML.

• Hibernate ORM error messages often obfuscate the actual cause of the error

  because they are provided directly by the Java classes.

• Complex CFML Hibernate ORM applications can consume significant memory and

  processing resources, making them cost-prohibitive and inefficient when used

  in microservices architecture.

• Hibernate ORM is tied to the engine releases. This means that updates come

  infrequently and may be costly for non-OSS engine users.

• Hibernate ORM is built in Java. This limits contributions from CFML

  developers who don't know Java or don't feel comfortable contributing to a

  Java project.

• Hibernate ORM doesn't take advantage of a lot of dynamic- and

  meta-programming available in CFML. (Tools like CBORM have helped to bridge

  this gap.)

We can do better.

What?

Quick is an ORM (Object Relational Mapper) written in CFML for CFML. It provides an ActiveRecord implementation for working with your database. With it you can map database tables to components, create relationships between components, query and manipulate data, and persist all your changes to your database.

Prerequisites

You need the following configured before using Quick:

• Configure a default datasource in your CFML engine

• ColdBox 4.3+

• Add a mapping for quick in your Application.cfc

• Configure your BaseGrammar in config/ColdBox.cfc

See Getting Started for more details.

Supported Databases

Quick supports all databases supported by qb.

Example

Here's a "quick" example to whet your appetite.

We'll show the database structure using a migrations file. This isn't required to use quick, but it is highly recommended.

// 2017_11_10_122835_create_users_table.cfc
component {

    function up() {
        schema.create( "users", function( table ) {
            table.increments( "id" );
            table.string( "username" ).unique();
            table.string( "email" ).unique();
            table.string( "password" );
            table.timestamp( "createdDate" );
            table.timestamp( "updatedDate" );
        } );
    }

}

// User
component extends="quick.models.BaseEntity" {

    // the name of the table is the pluralized version of the model
    // all fields in a table are mapped by default
    // both of these points can be configured on a per-entity basis

}

// handlers/Users.cfc
component {

    // /users/:id
    function show( event, rc, prc ) {
        // this finds the User with an id of 1 and retrieves it
        prc.user = getInstance( "User" ).findOrFail( rc.id );
        event.setView( "users/show" );
    }

}

<!-- views/users/show.cfm -->
<cfoutput>
    <h1>Hi, #prc.user.getUsername()#!</h1>
</cfoutput>

Now that you've seen an example, dig in to what you can do with Quick!

Prior Art, Acknowledgements, and Thanks

Quick is backed by qb. Without qb, there is no Quick.

Quick is inspired heavily by Eloquent in Laravel. Thank you Taylor Otwell and the Laravel community for a great library.

Development of Quick is sponsored by Ortus Solutions. Thank you Ortus Solutions for investing in the future of CFML.

Discussion & Help

The Box products community for further discussion and help can be found here: https://community.ortussolutions.com/c/communities/quick-orm/23

Configure a default datasource in your CFML engine

You can do this any way you'd like: through the web admin, in Application.cfc, or using cfconfig.

Make sure to set this.datasource in your Application.cfc so Quick knows which datasource to use.

Download Quick

The easiest way to download Quick is to use ForgeBox with CommandBox. Just run the following from the root of your application:

box install quick

Add a mapping for quick in your Application.cfc

For a default installation in a ColdBox template, the following line will do the trick.

this.mappings[ "/quick" ] = COLDBOX_APP_ROOT_PATH & "/modules/quick";

Configure your defaultGrammar in config/ColdBox.cfc

Quick will auto discover your grammar by default on startup. To avoid this check, set a BaseGrammar.

defaultGrammar is a module setting for Quick. Set it in your config/ColdBox.cfc like so:

moduleSettings = {
    quick = {
        defaultGrammar = "MySQLGrammar@qb"
    }
};

Valid options are any of the qb supported grammars. At the time of writing valid grammar options are: MySQLGrammar@qb, PostgresGrammar@qb, SqlServerGrammar@qb and OracleGrammar@qb. You can also have qb discover your grammar on application init using AutoDiscover@qb. Please check the qb docs for additional options.

If you want to use a different datasource and/or grammar for individual entitities you can do so by adding some metadata attributes to your entities.

Coming from <cfquery> or queryExecute?

You might be thinking, I don't need an ORM engine. I don't even know what ORM means! I know SQL backwards and forwards so there's nothing an ORM can offer me. Maybe you've had experience with other ORM engines, whether CFML-based or not, and the experience was less that ideal. Why should you consider Quick?

Quick's ORM philosophy comes down to three main points:

1. Give relevant names to important collections of SQL code. (scopes, relationships, etc.)

2. Make queries easy to compose at runtime to get the exact data you want in the most efficient way (subselects, eager loading, etc.)

3. Get out of your way when you need or want to write barebones SQL.

Coming from Hibernate?

Quick was built out of lessons learned and persistent challenges in developing complex RDBMS applications using built-in Hibernate ORM in CFML.

• Hibernate ORM error messages often obfuscate the actual cause of the error

  because they are provided directly by the Java classes.

• Complex CFML Hibernate ORM applications can consume significant memory and

  processing resources, making them cost-prohibitive and inefficient when used

  in microservices architecture.

• Hibernate ORM is tied to the engine releases. This means that updates come

  infrequently and may be costly for non-OSS engine users.

• Hibernate ORM is built in Java. This limits contributions from CFML

  developers who don't know Java or don't feel comfortable contributing to a

  Java project.

• Hibernate ORM doesn't take advantage of a lot of dynamic- and

  meta-programming available in CFML. (Tools like CBORM have helped to bridge

  this gap.)

We can do better.

isLoaded

Checks if the entity was loaded from the database.

A loaded entity has a tie to the database. It has either been loaded from the database or saved to the database. An unloaded entity is one created in code but not saved to the database yet.

delete

You can delete an entity by calling the delete method on it.

deleteAll

Just like updateAll, you can delete many records from the database by specifying a query with constraints and then calling the deleteAll method.

Deletes matching entities according to the configured query.

Additionally, you can pass in an array of ids to deleteAll to delete only those ids. Note that any previously configured constraints will still apply.

Relationships can be used in two ways.

The first is as a getter. Calling user.getPosts() will execute the relationship, cache the result, and return it.

The second is as a relationship. Calling user.posts() returns a Relationship instance to retrieve the posts that can be further constrained. A Relationship is backed by qb as well, so feel free to call any qb method to further constrain the relationship.

You can also call the other Quick fetch methods: first, firstOrFail, find, and findOrFail are all supported. This is especially useful to constrain the entities available to a user by using the user's relationships:

Sometimes you want to use a different value in your code than is stored in your database. Perhaps you want to enforce that setting a password always is hashed with BCrypt. Maybe you have a Date value object that you want wrapping each of your dates. You can accomplish this using custom getters and setters.

A custom getter or setter is simply a function in your entity.

To retrieve the attribute value fetched from the database, call retrieveAttribute passing in the name of the attribute.

To set an attribute for saving to the database, call assignAttribute passing in the name and the value.

component extends="quick.models.BaseEntity" accessors="true" {

    property name="bcrypt" inject="@BCrypt";

    function setPassword( value ) {
        return assignAttribute( "password", bcrypt.hashPassword( value ) );
    }

    function getCreatedDate( value ) {
        return dateFormat( retrieveAttribute( "createdDate" ), "DD MMM YYYY" );
    }

}

Collections are what are returned when calling get or all on an entity. By default, it returns an array. Every entity can override its newCollection method and return a custom collection. This method accepts an array of entities and should return your custom collection.

QuickCollection is a custom collection included in Quick as an extra component. It is a specialized version of CFCollection. It smooths over the various CFML engines to provide an extendible, reliable array wrapper with functional programming methods. You may be familiar with methods like map (ArrayMap), filter (ArrayFilter), or reduce (ArrayReduce). These methods work in every CFML engine with CFCollection.

To use collections you need to install cfcollection and configure it as your as your newCollection.

Here's how you would configure an entity to return a QuickCollection.

component name="User" {

    function newCollection( array entities = [] ) {
        return variables._wirebox.getInstance(
            name = "quick.extras.QuickCollection",
            initArguments = {
                "collection" = arguments.entities
            }
        );
    }

}

Collections are more powerful than plain arrays. There are many methods that can make your work easier. For instance, let's say you needed to group each active user by the first letter of their username in a list.

var users = getInstance("User").all();

users
    .filter(function(user) {
        return user.getActive();
    })
    .pluck("username")
    .groupBy(function(username) {
        return left(username, 1);
    });

So powerful! We think you'll love it.

load

Additionally, QuickCollection includes a load method. load lets you eager load a relationship after executing the initial query.

var posts = getInstance("Post").all();

if (someCondition) {
    posts.load("user");
}

This is the same as if you had initially executed:

getInstance("Post")
    .with("user")
    .all();

$renderData

QuickCollection includes a $renderData method that lets you return a QuickCollection directly from your handler and translates the results and the entities within to a serialized version. Check out more about it in the Serialization chapter.

The cookbook is a place to show examples of using Quick in practice. Each cookbook entry will include a short description of the problem to solve or use case and one or more code snippets showing the code.

The cookbook is not meant to teach you the basics of Quick or show you the method signatures. That is the purpose of the Guide and API Docs, respectively. The cookbook is meant to show you advanced and specific use cases.

Additionally, this is a great place to contribute to Quick! If you have solved a particular use case, send in a pull request and add it to the cookbook! We only ask that you take the time to simplify your example as much as you can. This usually means removing any custom naming convention for your attributes, tables, and entities.

To assist you in migrating from CBORM, Quick ships with a small compatibility shim. To use it, have your entity extend quick.models.CBORMCompatEntity. This will map common CBORM methods to their Quick counterparts as well as provide a partial CriteriaBuilder shim. The compatibility shim does not cover differences in properties or relationships.

Entity / Service Methods

• list

• countWhere

• deleteById

• deleteWhere

• exists

• findAllWhere

• findWhere

• get

• getAll

• new

• populate

• save

• saveAll

• newCriteria

Criteria Builder Methods

• getSQL

• between

• eqProperty

• isEQ

• isGT

• gtProperty

• isGE

• geProperty

• idEQ

• like

• ilike

• isIn

• isNull

• isNotNull

• isLT

• ltProperty

• neProperty

• isLE

• leProperty

• maxResults

• firstResult

• order

• list

• get

• count

• onMissingMethod

To order by a relationship field, you will use a dot-delimited syntax.

The last item in the dot-delimited string should be an attribute on the related entity.

Nested relationships are also supported. Continue to chain relationships in your dot-delimited string until arriving at the desired entity. Remember to end with the attribute to order by.

If you desire to be explicit, you can use the orderByRelated method, which is what is being called under the hood.

You might prefer the explicitness of this method, but it cannot handle normal orders like orderBy. Use whichever method you prefer.

One common type of subselect field is the count of related entites. For instance, you may want to load a Post or a list of Posts with the count of Comments on each Post. You can reuse your existing relationship definitions and add this count using the withCount method.

withCount

Adds a count of related entities as a subselect property. Relationships can be constrained at runtime by passing a struct where the key is the relationship name and the value is a function to constrain the query.

By default, you will access the returned count using the relationship name appended with Count, i.e. comments will be available under commentsCount.

var post = getInstance( "Post" )
	.withCount( "comments" )
	.findOrFail( 1 );
	
post.getCommentsCount();

You can alias the count attribute using the AS syntax as follows:

var post = getInstance( "Post" )
	.withCount( "comments AS myCommentsCount" )
	.findOrFail( 1 );
	
post.getMyCommentsCount();

This is especially useful as you can dynamically constrain counts at runtime using the same struct syntax as eager loading with the with function.

var post = getInstance( "Post" )
	.withCount( [
	    "comments AS allCommentsCount",
	    { "comments AS pendingCommentsCount": function( q ) {
	        q.where( "approved", 0 );
	    } },
	    { "comments AS approvedCommentsCount": function( q ) {
	        q.where( "approved", 1 );
	    } }
	] )
	.findOrFail( 1 );

post.getAllCommentsCount();	
post.getPendingCommentsCount();
post.getApprovedCommentsCount();

Usage

A hasOne relationship is a "one-to-one" relationship. For instance, a User entity might have an UserProfile entity attached to it.

The first value passed to hasOne is a WireBox mapping to the related entity.

Quick determines the foreign key of the relationship based on the entity name and key values. In this case, the UserProfile entity is assumed to have a userId foreign key. You can override this by passing a foreign key in as the second argument:

If your parent entity does not use id as its primary key, or you wish to join the child entity to a different column, you may pass a third argument to the hasOne method specifying your parent table's custom key.

The inverse of hasOne is . It is important to choose the right relationship for your database structure. hasOne assumes that the related model has the foreign key for the relationship.

withDefault

HasOne relationships can be configured to return a default entity if no entity is found. This is done by calling withDefault on the relationship object.

Called this way will return a new unloaded entity with no data. You can also specify any default attributes data by passing in a struct of data to withDefault.

Signature

Returns a HasOne relationship between this entity and the entity defined by relationName.

Visualizer

Usage

A belongsTo relationship is a many-to-one relationship. For instance, a Post may belong to a User.

The first value passed to belongsTo is a WireBox mapping to the related entity.

Quick determines the foreign key of the relationship based on the entity name and key values. In this case, the Post entity is assumed to have a userId foreign key. You can override this by passing a foreign key in as the second argument:

If your parent entity does not use id as its primary key, or you wish to join the child entity to a different column, you may pass a third argument to the belongsTo method specifying your parent table's custom key.

The inverse of belongsTo is or .

Updating

To update a belongsTo relationship, use the associate method. associate takes the entity to associate as the only argument.

Removing

To remove a belongsTo relationship, use the dissociate method.

Relationship Setter

You can also influence the associated entities by calling "set" & relationshipName and passing in an entity or key value.

After executing this code, the post would be updated in the database to be associated with the user with an id of 1.

withDefault

BelongsTo relationships can be configured to return a default entity if no entity is found. This is done by calling withDefault on the relationship object.

Called this way will return a new unloaded entity with no data. You can also specify any default attributes data by passing in a struct of data to withDefault.

Signature

Returns a BelongsTo relationship between this entity and the entity defined by relationName.

Visualizer

Usage

A polymorphicBelongsTo relationship is a many-to-one relationship. This relationship is used when an entity can belong to multiple types of entities. The classic example for this type of relationship is Posts, Videos, and Comments. For instance, a Comment may belong to a Post or a Video.

The only value passed to polymorphicBelongsTo is a prefix for the polymorphic type. A common convention where is to add able to the end of the entity name, though this is not automatically done. In our example, this prefix is commentable. This tells quick to look for a commentable_type and a commentable_id column in our Comment entity. It stores our entity's mapping as the _type and our entity's primary key value as the _id.

When retrieving a polymorphicBelongsTo relationship the _id is used to retrieve a _type from the database.

The inverse of polymorphicBelongsTo is also polymorphicHasMany. It is important to choose the right relationship for your database structure. hasOne assumes that the related model has the foreign key for the relationship.

Signature

Returns a polymorphicBelongsTo relationship between this entity and the entity defined by relationName.

Visualizer

What's the difference between `posts()` and `getPosts()`?

Answered by

When you define a relationship you name the function without a get in front of it. When calling a relationship with get preceding it, Quick loads the relationship and executes the query. You are returned either a single entity (or null) or an array of entities.

When you call the relationship function you get back an instance of a Quick Relationship component. This component is configured based on the entity that created it and the attributes configured in the relationship call. You can think of a relationship component as a super-charged query. In fact, you can call other Quick and qb methods on the relationship object. This is one way to restrict the results you get back.

For instance, perhaps you want to retrieve a specific Post by its id. In this case, you want the Post to be found only if it belongs to the User. You could add a constraint to a Post query on the foreign key userId like so:

Another way to write this is by leveraging existing relationships:

Let's disect this. At first glance it may look like it is just a matter of style and preference. But the power behind the relationship approach is that it encapsulates the logic to define the relationship. Remember that relationships don't have to only define foreign keys. They can define any custom query logic and give a name to it. They can even build on each other:

You see here that we have now named an important concept to our domain - a published post. Let's take this one step further and name the query logic on the Post entity itself.

When do I use a scope method and when do I use a normal method?

I keep getting a `QuickEntityNotLoaded` exception. What is the difference between a loaded entity and an unloaded entity?

How can I add a subselect field to my entity?

How can I add a computed field to my entity, like from a SQL CASE statement?

How can I always add a subselect or computed field to my queries?

Debugging a Single Query

toSQL

Returns the SQL that would be executed for the current query.

var userQuery = getInstance( "User" )
    .where( "active", "=", 1 );

writeOutput( userQuery.toSQL() );

SELECT `users`.`id`, `users`.`username` /* etc */
FROM "users"
WHERE "active" = ?

The bindings for the query are represented by question marks (?) just as when using queryExecute. qb can replace each question mark with the corresponding cfqueryparam-compatible struct by passing showBindings = true to the method.

var userQuery = getInstance( "User" )
    .where( "active", "=", 1 );

writeOutput( userQuery.toSQL( showBindings = true ) );

SELECT `users`.`id`, `users`.`username` /* etc */
FROM "users"
WHERE "active" = {"value":1,"cfsqltype":"CF_SQL_NUMERIC","null":false}

tap

Executes a callback with the current entity passed to it. The return value from tap is ignored and the current entity is returned.

While not strictly a debugging method, tap makes it easy to see the changes to an entity after each call without introducing temporary variables.

getInstance( "User" )
    .tap( function( e ) {
        writeOutput( e.toSQL() & "<br>" );
    } )
    .where( "active", "=", 1 )
    .tap( function( e ) {
        writeOutput( e.toSQL() & "<br>" );
    } );

SELECT `users`.`id`, `users`.`username` /* etc */ FROM "users"
SELECT `users`.`id`, `users`.`username` /* etc */ FROM "users" WHERE "active" = ?

Debugging All Queries

cbDebugger

Starting in cbDebugger 2.0.0 you can view all your Quick and qb queries for a request. This is the same output as using qb standalone. This is enabled by default if you have qb installed. Make sure your debug output is configured correctly and scroll to the bottom of the page to find the debug output.

Additionally, with Quick installed you will see number of loaded entities for the request. This can help identify places that are missing pagination or relationships that could be tuned or converted to a subselect.

LogBox Appender

Quick is set to log all queries to a debug log out of the box via qb. To enable this behavior, configure LogBox to allow debug logging from qb's grammar classes.

logbox = {
    debug = [ "qb.models.Grammars" ]
};

Interception Points

ColdBox Interception Points can also be used for logging, though you may find it easier to use LogBox. See the documentation for qb's Interception Points or Quick's own interception points for more information.

The Problem

Let's imagine a scenario where you are displaying a list of posts. You fetch the posts:

And start looping through them:

When you visit the page, though, you notice it takes a while to load. You take a look at your SQL console and you've executed 26 queries for this one page! What?!?

Turns out that each time you loop through a post to display its author's username you are executing a SQL query to retreive that author. With 25 posts this becomes 25 SQL queries plus one initial query to get the posts. This is where the gets its name.

So what is the solution? Eager Loading.

Eager Loading means to load all the needed users for the posts in one query rather than separate queries and then stitch the relationships together. With Quick you can do this with one method call.

The Solution

with

You can eager load a relationship with the with method call.

with takes one parameter, the name of the relationship to load. Note that this is the name of the function, not the entity name. For example:

To eager load the User in the snippet above you would call pass author to the with method.

For this operation, only two queries will be executed:

Quick will then stitch these relationships together so when you call post.getAuthor() it will use the fetched relationship value instead of going to the database.

Nested Relationships

You can eager load nested relationships using dot notation. Each segment must be a valid relationship name.

You can eager load multiple relationships by passing an array of relation names to with or by calling with multiple times.

Constraining Eager Loaded Relationships

In most cases when you want to constrain an eager loaded relationship, the better approach is to create a new relationship.

You can eager load either option.

Occassionally that decision needs to be dynamic. For example, maybe you only want to eager load the posts created within a timeframe defined by a user. To do this, pass a struct instead of a string to the with function. The key should be the name of the relationship and the value should be a function. This function will accept the related entity as its only argument. Here is an example:

If you need to load nested relationships with constraints you can call with in your constraint callback to continue eager loading relationships.

load

Finally, you can postpone eager loading until needed by using the load method on QuickCollection. load has the same function signature as with. QuickCollection is the object returned for all Quick queries that return more than one record. Read more about it in .

Problem

Often you will configure Quick with a default datasource, but in some cases you might need a dynamic datasource. For example, your killer app is multi-tenant, each customer has it's own database but the codebase is exactly the same for each customer. In this case you have two options:

• Deploy the same app over and over again for each customer, which is only feasible for a small customer count.

• or create some central authentication mechanisms, and after authentication each user gets his own

  • userId

  • customerId

  • customerDatasource

  In this scenario you know from your user authentication info which datasource you should use for each customer. The problem: this datasource name is dynamic, while Quick knows about default datasources or . So how can we make this datasource dynamic?

Solution

Actually there are multiple solutions available - you just have to pick one which suits you best. After login you know which datasource you need. Since Quick needs to know where to get the value of your datasource you need to store it somewhere. We will store it in the private request collection (prc), but other options like session storage or user-specific caching might be preferable in your use case. So let's assume we have a variable called mainDatasource in our private request collection which has the datasource name we should use. We should be able to change the default datasource in every quick object just before it sends a query to the database.

Option 1: instanceReady()

Quick fires an instanceReady event internally and as an interceptor. We will hook in to this lifecycle event by creating a base component for our entities.

In this case, I use the instanceReady() lifecycle method which fires AFTER an object is created, but before data is loaded from the database. We get the datasource from the private request collection, and only take action if it is set. If there is a value, we change the _queryoptions on the builder object. Unfortunately this is not enough, because the _queryoptions will not be read again after instanceReadyfires, so we explicitly have to set the default options on the _builder object again. Once that's done, your Quick entity is ready to query using your dynamic datasource. So every Quick entity which inherits from our custom base component will use dynamic datasources

Option 2: overriding the newQuery() method

The newQuery method reads the default _queryOptions, and prepares a query object. We create a base component again and this time override the newQuery method.

In this scenario we read the dynamic datasource value from the prc again, and modify the _queryoptions to use that datasource. Once this is ready we can call the newQuery() method of the parent object to finish setting up. Again, if your Quick entity inherits from this base, your quick object will now be using dynamic datasources.

Option 3: Intercepting qb execution

The third option might look simpler, but offers you less control. Quick uses qb to query the database, and just before it does this it announces a preQBExecute interception point. By creating and registering an interceptor, you can change your datasource just in time. The interceptor can look like this:

In this case you don't need your own base component. Be aware that this interceptor changes your datasource for ALL qb requests, no matter if you use custom base component or even if it is a regular qb query. So if qb already had some default datasource that will also be changed. We added an extra check, so this interceptor is not touching your qb query if a datasource was already explicitly defined. You can register your interceptor in the coldbox config like this

Option 2 is the most specific option you can use, and makes most sense if you see what happens in the newQuery method of quick.models.BaseEntity. Option 3 is less specific and might change your datasource in unwanted places. But if you know what you are doing it can be a very powerful way to add this dynamic datasource capability to Quick.

Usage

A hasOneThrough relationship is either a many-to-one or a one-to-one relationship. It is used when you want to access a related entity through one or more intermediate entities. For instance, a Team may have one latest Post through a User.

// Team.cfc
component extends="quick.models.BaseEntity" accessors="true" {

    function latestPost() {
        return hasOneThrough( [ "members", "posts" ] )
            .orderByDesc( "publishedDate" );
    }
    
    function members() {
        return hasMany( "User" );
    }

}

// User.cfc
component extends="quick.models.BaseEntity" accessors="true" {

    function posts() {
        return hasMany( "Post" );
    }
    
    function team() {
        return belongsTo( "Team" );
    }

}

// Post.cfc
component extends="quick.models.BaseEntity" accessors="true" {

    function author() {
        return belongsTo( "Post" );
    }

}

The only value needed for hasOneThrough is an array of relationship function names to walk through to get to the related entity. The first relationship function name in the array must exist on the current entity. Each subsequent function name must exist on the related entity of the previous relationship result. For our previous example, members must be a relationship function on Team. posts must then be a relationship function on the related entity resulting from calling Team.members(). This returns a hasMany relationship where the related entity is User. So, User must have a posts relationship function. That is the end of the relationship function names array, so the related entity resulting from calling User.posts() is our final entity which is Post.

hasOneThrough( [ "members", "posts" ] );

+----------------+---------------------------+----------------+
| Current Entity | Relationship Method Names | Related Entity |
+================+===========================+================+
| Team           | members                   | User           |
+----------------+---------------------------+----------------+
| User           | posts                     | Post           |
+----------------+---------------------------+----------------+

This approach can scale to as many related entities as you need. For instance, let's expand the previous example to include an Office that houses many Teams.

// Office.cfc
component extends="quick.models.BaseEntity" accessors="true" {

    function latestPost() {
        return hasOneThrough( [ "teams", "members", "posts" ] )
            .orderByDesc( "publishedDate" );
    }
    
    function teams() {
        return hasMany( "Team" );
    }

}

// Team.cfc
component extends="quick.models.BaseEntity" accessors="true" {

    function members() {
        return hasMany( "User" );
    }
    
    function office() {
        return belongsTo( "Office" );
    }

}

// User.cfc
component extends="quick.models.BaseEntity" accessors="true" {

    function team() {
        return belongsTo( "Team" );
    }
    
    function posts() {
        return hasMany( "Post" );
    }

}

// Post.cfc
component extends="quick.models.BaseEntity" accessors="true" {

    function author() {
        return belongsTo( "User" );
    }

}

hasOneThrough( [ "teams", "members", "posts" ] )

+----------------+---------------------------+----------------+
| Current Entity | Relationship Method Names | Related Entity |
+================+===========================+================+
| Office         | teams                     | Team           |
+----------------+---------------------------+----------------+
| Team           | members                   | User           |
+----------------+---------------------------+----------------+
| User           | posts                     | Post           |
+----------------+---------------------------+----------------+

withDefault

HasOneThrough relationships can be configured to return a default entity if no entity is found. This is done by calling withDefault on the relationship object.

// Team.cfc
component extends="quick.models.BaseEntity" accessors="true" {

    function latestPost() {
        return hasOneThrough( [ "members", "posts" ] )
            .orderByDesc( "publishedDate" )
            .withDefault();
    }
    
    function members() {
        return hasMany( "User" );
    }

}

Called this way will return a new unloaded entity with no data. You can also specify any default attributes data by passing in a struct of data to withDefault.

// Team.cfc
component extends="quick.models.BaseEntity" accessors="true" {

    function latestPost() {
        return hasOneThrough( [ "members", "posts" ] )
            .orderByDesc( "publishedDate" )
            .withDefault( {
                "title": "Your next great post!"
            } );
    }
    
    function members() {
        return hasMany( "User" );
    }

}

Signature

save

Updates are handled identically to inserts when using the save method. The only difference is that instead of starting with a new entity, we start with an existing entity.

update

You can update multiple fields at once using the update method. This is similar to the create method for creating new entities.

There is no need to call save when using the update method.

By default, if you have a key in the struct that doesn't match a property in the entity the update method will fail. If you add the optional argument ignoreNonExistentAttributes set to true, those missing keys are ignored. Now you can pass the rc scope from your submitted form directly into the update method and not worry about any other keys in the rc like event that would cause the method to fail.

updateOrCreate

Updates an existing record or creates a new record with the given attributes.

updateAll

Updates matching entities with the given attributes according to the configured query. This is analagous to

fresh

Retrieves a new entity from the database with the same key value as the current entity. Useful for seeing any changes made to the record in the database. This function executes a query.

refresh

Refreshes the attributes data for the entity with data from the database. This differs from fresh in that it operates on the current entity instead of returning a new one. This function executes a query.

Usage

A belongsToMany relationship is a many-to-many relationship. For instance, a User may have multiple Permissions while a Permission can belong to multiple Users.

The first value passed to belongsToMany is a WireBox mapping to the related entity.

belongsToMany makes some assumptions about your table structure. To support a many-to-many relationship, you need a pivot table. This is, at its simplest, a table with each of the foreign keys as columns.

As you can see, Quick uses a convention of combining the entity table names in alphabetical order with an underscore (_) to create the new pivot table name. If you want to override this convention, you can do so by passing the desired table name as the second parameter or the table parameter.

Quick determines the foreign key of the relationship based on the entity name and key values. In this case, the User entity is assumed to have a userId foreign key and the Permission entity a permissionId foreign key. You can override this by passing a foreignKey in as the third argument and a relatedKey as the fourth argument:

Finally, if you are not joining on the primary keys of the current entity or the related entity, you can specify those keys using the last two parameters:

The inverse of belongsToMany is also belongsToMany. The foreignKey and relatedKey arguments are swapped on the inverse side of the relationship.

If you find yourself needing to interact with the pivot table (permissions_users) in the example above, you can create an intermediate entity, like UserPermission. You will still be able to access the end of the relationship chain using the hasManyThrough relationship type.

attach

Use the attach method to relate two belongsToMany entities together. attach can take a single id, a single entity, or an array of ids or entities (even mixed and matched) to associate.

detach

Use the detach method to remove an existing entity from a belongsToMany relationship. detatch can also take a single id, a single entity, or an array of ids or entities (even mixed and matched) to remove.

sync

Sometimes you just want the related entities to be a list you give it. For these situations, use the sync method.

Now, no matter what relationships existed before, this Post will only have three tags associated with it.

Relationship Setter

You can also influence the associated entities by calling "set" & relationshipName and passing in an entity or key value.

This code calls sync on the relationship. After executing this code, the post would be updated in the database to be associated with the tags passed in (4, 12, and 2). Any tags that were previously associated with this post would no longer be and only the tags passed in would be associated now.

Signature

Returns a BelongsToMany relationship between this entity and the entity defined by relationName.

Visualizer

Usage

A belongsToThrough relationship is the one side of a many-to-one relationship with an intermediate entity. It is used when you want to access a related, owning entity through one or more intermediate entities. For instance, a Post may belong to a Team via a User.

The only value needed for belongsToThrough is an array of relationship function names to walk through to get to the related entity. The first relationship function name in the array must exist on the current entity. Each subsequent function name must exist on the related entity of the previous relationship result. For our previous example, author must be a relationship function on Post. team must then be a relationship function on the related entity resulting from calling Post.author(). This returns a belongsTo relationship where the related entity is User. So, User must have a team relationship function. That is the end of the relationship function names array, so the related entity resulting from calling User.team() is our final entity which is Team.

This approach can scale to as many related entities as you need. For instance, let's expand the previous example to include an Office that houses many Teams.

withDefault

HasOneThrough relationships can be configured to return a default entity if no entity is found. This is done by calling withDefault on the relationship object.

Called this way will return a new unloaded entity with no data. You can also specify any default attributes data by passing in a struct of data to withDefault.

Signature

getMemento

The memento pattern is an established pattern in ColdBox apps. A memento in this case is a simple representation of your entity using arrays, structs, and simple values.

For instance, the following example shows a User entity and its corresponding memento:

Quick bundles in the excellent library to handle converting entities to mementos. This gives you excellent control over serialization using a this.memento struct on the entity and passing in arguments to the getMemento function.

this.memento

By default, Quick includes all defined attributes as includes. You can change this or add other Mementifier options by defining your own this.memento struct on your entity. Your custom this.memento struct will be merged with Quick's default, so you can only define what changes you need.

Here is the default Quick memento struct. It is inside the instanceReady() lifecycle method in this example because retrieveAttributeNames() relies on the entity being wired (though not loaded); it is not otherwise necessary to put this.memento inside instanceReady().

getMemento Arguments

You can also control the serialization of a memento at call time using Mementifier's getMemento arguments.

Custom getMemento

If this does not give you the control you need, you can further modify the memento by overriding the getMemento function on your entity. In this case, a $getMemento function will be available which is the Mementifier function.

asMemento

Sometimes when retrieving entities or executing a Quick query, you already know you want mementos back. You can skip the step of calling getMemento yourself or mapping over the array of results returned by calling asMemento before executing the query. asMemento takes the same arguments that getMemento does. It will pass those arguments on and convert your entities to mementos after executing the query. This works for all the query execution methods - find, first, get, paginate, etc.

$renderData

The $renderData method is a special method for ColdBox. When returning a model from a handler, this method will be called and the value returned will be used as the serialized response. This let's you simply return an entity from a handler for your API. By default this will call getMemento().

QuickCollection also defines a $renderData method, which will delegate the call to each entity in the collection and return the array of serialized entities.

Relationships are the heart of any ORM engine. They let you interact with relational database tables in an object-oriented way.

Quick's relationship engine provides readable relationship types, extendible relations at runtime, eager loading, and much more.

Start by checking out the different .

Usage

A hasManyThrough relationship is either a one-to-many or a many-to-many relationship. It is used when you want to access related entities through one or more intermediate entities. The most common example for this is through a pivot table. For instance, a User may have multiple Permissions via a UserPermission entity. This allows you to store additional data on the UserPermission entity, like a createdDate .

// User.cfc
component extends="quick.models.BaseEntity" accessors="true" {

    function permissions() {
        return hasManyThrough( [ "userPermissions", "permission" ] );
    }
    
    function userPermissions() {
        return hasMany( "UserPermission" );
    }

}

// Permission.cfc
component extends="quick.models.BaseEntity" accessors="true" {

    function users() {
       return hasManyThrough( [ "userPermissions", "user" ] );
    }
    
    function userPermissions() {
        return hasMany( "UserPermission" );
    }

}

// UserPermission.cfc
component extends="quick.models.BaseEntity" accessors="true" {

    function user() {
        return belongsTo( "User" );
    }

    function permission() {
        return belongsTo( "Permission" );
    }

}

The only value needed for hasManyThrough is an array of relationship function names to walk through to get to the related entity. The first relationship function name in the array must exist on the current entity. Each subsequent function name must exist on the related entity of the previous relationship result. For our previous example, userPermissions must be a relationship function on User. permission must then be a relationship function on the related entity resulting from calling User.userPermissions(). This returns a hasMany relationship where the related entity is UserPermission. So, UserPermission must have a permission relationship function. That is the end of the relationship function names array, so the related entity resulting from calling UserPermission.permission() is our final entity which is Permission.

hasManyThrough( [ "userPermissions", "permission" ] );

+----------------+---------------------------+----------------+
| Current Entity | Relationship Method Names | Related Entity |
+================+===========================+================+
| User           | userPermissions           | UserPermission |
+----------------+---------------------------+----------------+
| UserPermission | permission                | Permission     |
+----------------+---------------------------+----------------+

Let's take a look at another example. HasManyThrough relationships can go up and down the relationship chain. Here's an example of finding a User's teammates

The inverse of hasManyThrough is either a belongsToThrough or a hasManyThrough relationship.

// User.cfc
component extends="quick.models.BaseEntity" accessors="true" {

    function team() {
        return belongsTo( "Team" );
    }
    
    function teammates() {
        return hasManyThrough( [ "team", "members" ] );
    }

}

// Team.cfc
component extends="quick.models.BaseEntity" accessors="true" {

    function members() {
       return hasMany( "User" );
    }

}

hasManyThrough( [ "team", "members" ] );

+----------------+---------------------------+----------------+
| Current Entity | Relationship Method Names | Related Entity |
+================+===========================+================+
| User           | team                      | Team           |
+----------------+---------------------------+----------------+
| Team           | members                   | User           |
+----------------+---------------------------+----------------+

This approach can scale to as many related entities as you need. For instance, let's expand the previous example to include an Office that houses many Teams.

// User.cfc
component extends="quick.models.BaseEntity" accessors="true" {

    function team() {
        return belongsTo( "Team" );
    }
    
    function teammates() {
        return hasManyThrough( [ "team", "members" ] );
    }
    
    function officemates() {
        return hasManyThrough( [ "team", "office", "teams", "members" ] );
    }

}

// Team.cfc
component extends="quick.models.BaseEntity" accessors="true" {

    function members() {
       return hasMany( "User" );
    }
    
    function office() {
       return belongsTo( "Office" );
    }

}

// Office.cfc
component extends="quick.models.BaseEntity" accessors="true" {

    function teams() {
       return hasMany( "Team" );
    }

}

hasManyThrough( [ "team", "office", "teams", "members" ] );

+----------------+---------------------------+----------------+
| Current Entity | Relationship Method Names | Related Entity |
+================+===========================+================+
| User           | team                      | Team           |
+----------------+---------------------------+----------------+
| Team           | office                    | Office         |
+----------------+---------------------------+----------------+
| Office         | teams                     | Team           |
+----------------+---------------------------+----------------+
| Team           | members                   | User           |
+----------------+---------------------------+----------------+

This next example can get a little gnarly - you can include other hasManyThrough relationships in a hasManyThrough relationship function names array. You can rewrite the officemates relationship like so:

// User.cfc
component extends="quick.models.BaseEntity" accessors="true" {

    function team() {
        return belongsTo( "Team" );
    }
    
    function teammates() {
        return hasManyThrough( [ "team", "members" ] );
    }
    
    function officemates() {
        return hasManyThrough( [ "team", "office", "members" ] );
    }

}

// Team.cfc
component extends="quick.models.BaseEntity" accessors="true" {

    function members() {
        return hasMany( "User" );
    }
    
    function office() {
       return belongsTo( "Office" );
    }

}

// Office.cfc
component extends="quick.models.BaseEntity" accessors="true" {

    function teams() {
        return hasMany( "Team" );
    }
    
    function members() {
        return hasManyThrough( [ "teams", "members" ] );
    }

}

hasManyThrough( [ "team", "office", "members" ] );

+----------------+---------------------------+----------------+
| Current Entity | Relationship Method Names | Related Entity |
+================+===========================+================+
| User           | team                      | Team           |
+----------------+---------------------------+----------------+
| Team           | office                    | Office         |
+----------------+---------------------------+----------------+
| Office         | members                   | (below)        |
+----------------+---------------------------+----------------+---+
    | Office         | teams                     | Team           |
    +----------------+---------------------------+----------------+
    | Team           | members                   | User           |
    +----------------+---------------------------+----------------+

As you can see, this is a very powerful relationship type that can save you many unnecessary queries to get the data you need.

Signature

When querying an entity, you may want to restrict the query based on the existence or absence of a related entity. You can do that using the following four methods:

has

Checks for the existence of a relationship when executing the query.

By default, a has constraint will only return entities that have one or more of the related entity.

getInstance( "User" ).has( "posts" ).get();

An optional operator and count can be added to the call.

getInstance( "User" ).has( "posts", ">", 2 ).get();

Nested relationships can be checked by passing a dot-delimited string of relationships.

getInstance( "User" ).has( "posts.comments" ).get();

doesntHave

Checks for the absence of a relationship when executing the query.

By default, a doesntHave constraint will only return entities that have zero of the related entity.

getInstance( "User" ).doesntHave( "posts" ).get();

An optional operator and count can be added to the call.

getInstance( "User" ).doesntHave( "posts", "<=", 1 ).get();

Nested relationships can be checked by passing a dot-delimited string of relationships.

getInstance( "User" ).doesntHave( "posts.comments" ).get();

whereHas

When you need to have more control over the relationship constraint, you can use whereHas. This method operates similarly to has but also accepts a callback to configure the relationship constraint.

The whereHas callback is passed a builder instance configured according to the relationship. You may call any entity or query builder methods on it as usual.

getInstance( "User" )
    .whereHas( "posts", function( q ) {
	      q.where( "body", "like", "%different%" );
    } )
		.get();

When you specify a nested relationship, the builder instance is configured for the last relationship specified.

getInstance( "User" )
    .whereHas( "posts.comments", function( q ) {
	      q.where( "body", "like", "%great%" );
	  } )
	  .get();

An optional operator and count can be added to the call, as well.

getInstance( "User" )
    .whereHas( "posts.comments", function( q ) {
	      q.where( "body", "like", "%great%" );
	  }, ">", 2 )
	  .get();

whereDoesntHave

The whereDoesntHave callback is passed a builder instance configured according to the relationship. You may call any entity or query builder methods on it as usual.

getInstance( "User" )
    .whereDoesntHave( "posts", function( q ) {
	      q.where( "body", "like", "%different%" );
    } )
		.get();

When you specify a nested relationship, the builder instance is configured for the last relationship specified.

getInstance( "User" )
    .whereDoesntHave( "posts.comments", function( q ) {
	      q.where( "body", "like", "%great%" );
	  } )
	  .get();

An optional operator and count can be added to the call, as well.

getInstance( "User" )
    .whereDoesntHave( "posts.comments", function( q ) {
	      q.where( "body", "like", "%great%" );
	  }, ">", 2 )
	  .get();

Usage

A polymorphicHasMany relationship is a one-to-many relationship. This relationship is used when an entity can belong to multiple types of entities. The classic example for this type of relationship is Posts, Videos, and Comments.

// Post.cfc
component extends="quick.models.BaseEntity" accessors="true" {

    function comments() {
       return polymorphicHasMany( "Comment", "commentable" );
    }

}

// Video.cfc
component extends="quick.models.BaseEntity" accessors="true" {

    function comments() {
        return polymorphicHasMany( "Comment", "commentable" );
    }

}

The first value passed to polymophicHasMany is a WireBox mapping to the related entity.

The second value is a prefix for the polymorphic type. A common convention where is to add able to the end of the entity name, though this is not automatically done. In our example, this prefix is commentable. This tells quick to look for a commentable_type and a commentable_id column in our Comment entity. It stores our entity's mapping as the _type and our entity's primary key value as the _id.

The inverse of polymophicHasMany is polymorphicBelongsTo.

// Comment.cfc
component extends="quick.models.BaseEntity" accessors="true" {

    function post() {
        return polymorphicBelongsTo( "commentable" );
    }

}

Signature

Returns a polymorphicHasMany relationship between this entity and the entity defined by relationName.

Visualizer

5.0.0

In 5.0.0, we stepped up the performance of Quick in a major way. Entity creation is now over twice as fast as before.

Performance Improvements

Average duration to create one entity:

While the times may seem small, this is compounded for each entity you create. So, if you are retrieving 1000 entities, multiply each of these numbers by 1000 and you'll start to see why this matters.

This did introduce one breaking change from v4. See the for more information.

New Features

• Added a new that will correctly set your primary key if your database only returns ROWID in the queryExecute response.

Bug Fixes

• Fixed a null check in isNullValue.

• Fixed nulls coming back as strings in JsonCast.

4.2.0

• Add a pagination method for quicker performance when total records or total pages are not needed or too slow.

4.1.6

• Configure columns are no longer cleared when setting up a BelongsToMany relationship.

4.1.5

• Provide initialThroughConstraints for hasOne relationships (used in *Through relationships).

4.1.4

• Ignore orders when retrieving a relationship count.

4.1.1, 4.1.2

• Preserve casted value after saving an entity.

4.1.0

• Allow for including

• Look up returning values by column name not by alias in the ReturningKeyType.

4.0.2

• Skip eager loading database call when no keys are found.

• Only apply CONCAT when needed in *Through relationships.

4.0.1

• Use WHERE EXISTS over DISTINCT when fetching relationships. DISTINCT restricts some of the queries that can be run.

4.0.0

BREAKING CHANGES

• , , and callbacks now automatically group where clauses when an OR combinator is detected.

Other Changes

• Dynamically add to a parent entity without loading all of the relationship.

• Give a helpful error message when trying to set relationship values before saving an entity, where applicable.

• Multiple bug fixes related to and when using belongsToThrough, hasOneThrough, or hasManyThrough.

3.1.7

• Correct jQuery link in test runner.

3.1.6

• Allow expressions in basic where clauses.

• Fix delete naming collision.

3.1.5

• Add an alias to with to QuickBuilder.

3.1.4

• Fix a stack overflow on nested relationship checks.

3.1.3

• Configured tables (.from) are now used for qualifying columns.

3.1.2

• Remove unnecessary nesting in compare queries.

3.1.1

• Fix when using "OR" combinators.

3.1.0

• Add support for JSON using a new JsonCast@quick component.

3.0.4

• Compatibility updates for ColdBox 6

3.0.3

• Optimize caching

3.0.2

• Apply during .

3.0.1

• Account for null values in .

• Swap structAppend order for a Lucee bug in mementifier integration.

3.0.0

BREAKING CHANGES

Please see the for more information on these changes.

• Drop support for Lucee 4.5 and Adobe ColdFusion 11.

• Virtual Inheritance (using a quick annotation instead of extending quick.models.BaseEntity) has been removed. It was hardly used, and removing it allows us to simplify some of the code paths.

• accessors="true" is now required on every entity. This is similar to above where requiring it allows us to simplify the codebase immensely. A helpful error message will be thrown if accessors="true" is not present on your entity.

• The defaultGrammar mapping needs to be the full WireBox mapping, including the @qb, if needed.

  • For instance, MSSQLGrammar would become MSSQLGrammar@qb.

  • This will allow for other grammars to be more easily contributed via third party modules.

• now only accept a relationships parameter of relationship methods to walk to get to the intended entity.

• Attributes using casts="boolean" need to be updated to .

• Some method and parameter names have been changed to support composite keys. The majority of changes will only affect you if you have extended base Quick components. The full list can be found in the Upgrade Guide.

Other Changes

• for memento transformations.

• Use to automatically convert queries to mementos.

• Automatically-generated .

• Add error message for defaulting key values.

• Update to .

• Add a .

• Add a .

• - using custom components to represent one or more attributes.

• .

• .

• Add a new QuickBuilder to better handle interop with qb.

• .

• Allow for orFail methods.

• Ensure loadRelationship doesn't reload existing relationships.

• Add multiple retrieve or new/create methods - , , , , and .

• Add to Quick.

• Add to compare entities.

• Allow from serialized data.

• Allow returning default entities for null relations on , , , and relationships.

• Query relations using , , , and .

• Split reset into reset and resetToNew methods.

• Store the original attributes for later resetting.

• Use parameterLimits to eager load.

• Use a new entity each time on BaseService.

• Apply sql types for columns to wheres.

• Apply global scopes more consistently

• Correctly ignore key column when updating.

• Fix hasRelationship method to only return true for exact matches.

• Better handling of constrained relationships when eager loading.

• Convert aliases when qualifying columns.

• Add a better error message if onMissingMethod fails.

• Only retrieve columns for defined attributes.

• Cache entity metadata in CacheBox.

• Use attribute hash for checking isDirty.

2.5.0

• Define per entity.

2.4.0

• Apply custom setters when hydrating from the database. (Reverted in 2.5.3 for unintended consequences with things like password hashing.)

• This allows you to use scopes to perform query functions and return values. (If you do not want to return a custom value, return the QueryBuilder instance or nothing.)

• Improve error messages for not loaded entities.

• Return the correct memento with accessors on.

2.3.0

2.2.0

• (first and find methods)

2.1.0

• Mapping foreign keys for relationships is now optional

• Either entities or primary key values can be passed to relationship persistance methods

• Relationships can also be saved by calling "set" & relationshipName

• works on ColdBox 5.2+

By default, Quick supports basic component-level inheritance of entities, meaning that a child component inherits the properties ( and ability to overload ) its parent. A common, object-oriented relational database pattern, however is to provide additional definition on parent tables ( and classes ) within child tables which contain a foreign key.

Quick supports two types of child classes: Discriminated and Subclassed child entities. In both cases, loading any child class will also deliver the data of its parent class.

Subclass Entities

Let's say, for example, that I have a Media entity, which is used to catalog and organize all media items loaded in to my application.

My Media entity contains all of the properties which are common to every media item uploaded in to my application. Let's say, however, that I need to have specific attributes that are available on only media for my Book entity ( e.g. whether the image is the cover photo, for example ). I can create a child class of BookMedia which extends my Media entity. When loaded, all of the properties of Media will be loaded along with the custom attributes which apply to my BookMedia object:

Note the additional component attribute joincolumn. The presence of this attribute on a child class signifies that it is a child entity of the parent and that the parent's properties should be loaded whenever the BookMedia entity is loaded. In addition, the primary key of the entity is that of the parent.

Child entities can be retrieved by queries specific to their own properties:

Or properties on the parent class can be used as first-class properties within the query:

Child entities can be retrieved, individually, using the value of the joinColumn, which should be a foreign key to the parent identifier column:

Now my Book entity can use its extended media class to retrieve media items which are specific to its own purpose:

Discriminated Entities

A discriminated child class functions, basically, in the same way as a subclassed entity, with one exception: The parent entity is aware of the discriminated child, due to a discriminatorValue attribute and will return that specific class when a retrieval is performed through the parent Entity. Let's take our BookMedia class, again, but this time defining it as a discriminated entity.

The first step is to add the discriminatorColumn attribute to the Media entity:

Then we set a discriminatorValue property on the child class, the value of which is stored in the parent entity table:

Finally, we define an array of possible discriminated entities for the parent. This is so we don't have to scan all Quick components just to determine if there are any discriminated entities.

Once this is defined, any new BookMedia entity will be saved with a type value of book in the media table. As such, the following query will result in only entities of BookMedia being returned:

If our Media table contains a combination of non-book and book media, then the collection returned when querying all records will contain a mix of BookMedia and Media entities.

Loading a collection of BookMedia entities, however, will always return a collection of BookMedia entities, because the type column value on the media must be equal to book.

Summary

Discriminated and child class entities, allow for a more Object oriented approach to entity-specific relationships by allowing you to eliminate pivot/join tables and extend the attributes of the base class.

Usage

A hasMany relationship is a one-to-many relationship. For instance, a User may have multiple Posts.

The first value passed to hasMany is a WireBox mapping to the related entity.

Quick determines the foreign key of the relationship based on the entity name and key values. In this case, the Post entity is assumed to have a userId foreign key. You can override this by passing a foreign key in as the second argument:

If your parent entity does not use id as its primary key, or you wish to join the child entity to a different column, you may pass a third argument to the hasMany method specifying your parent table's custom key.

The inverse of hasMany is .

Inserting & Updating

There are two ways to add an entity to a hasMany relationship. Both mirror the for entities.

save

You can call the save method on the relationship passing in an entity to relate.

This will add the User entity's id as a foreign key in the Post and save the Post to the database.

Note: the save method is called on the posts relationship, not the getPosts collection.

saveMany

You can also add many entities in a hasMany relationship by calling saveMany. This method takes an array of key values or entities and will associate each of them with the base entity.

create

Use the create method to create and save a related entity directly through the relationship.

This example will have the same effect as the previous example.

Removing

Removing a hasMany relationship is handled in two ways: either by using the dissociate method on the side of the relationship or by deleting the side of the relationship.

Relationship Setter

You can also influence the associated entities by calling "set" & relationshipName and passing in an array of entities or key values.

After running this code, this user would only have two posts, the posts with ids 2 and 4. Any other posts would now be disassociated with this user. Likely your database will be guarding against creating these orphan records. Admittedly, this method is not as likely to be used as the others, but it does exist if it solves your use case.

Signature

Returns a HasMany relationship between this entity and the entity defined by relationName.

Visualizer