1 of 44

10.0.0 Introduction

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.

Why Quick?

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:

Give relevant names to important collections of SQL code. (, , etc.)
Make queries easy to compose at runtime to get the exact data you want in the most efficient way (, , etc.)
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.

We can do better.

Contributing

Configuration

The following are the module settings for Quick:

settings = {
    "defaultGrammar"        : "AutoDiscover@qb",
    "defaultQueryOptions"   : {},
    "preventDuplicateJoins" : true,
    "metadataCache"         : {
        "name"       : "quickMeta",
	"provider"   : "coldbox.system.cache.providers.CacheBoxColdBoxProvider",
	"properties" : {
	    "objectDefaultTimeout"  : 0, // no timeout
	    "useLastAccessTimeouts" : false, // no last access timeout
	    "maxObjects"            : 300,
	    "objectStore"           : "ConcurrentStore"
	}
    }
};

Guide

Getting Started

qb is the engine that powers Quick. It is highly recommended that you become familiar with the qb documentation.

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 .

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

Quick can use , but it makes it easier to use when you don't have to deal with that.

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:

Valid options are any of the . 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 attributes to your entities.

Subclass Entities

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.

Working with Entities

isLoaded

Checks if the entity was loaded from the database.

Name

Type

Required

Default

Description

Deleting Entities

delete

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

var user = getInstance( "User" ).find( 1 );
user.delete();

The entity will still exist in any variables you have stored it in, even though it has been deleted from the database.

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

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 relationship types.

Relationship Types

hasOne

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.

hasMany

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

Name

Type

Required

Default

Description

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

Visualizer

belongsTo

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.

CBORM Compatibility Shim

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

Collections

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.

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.

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.

This is the same as if you had initially executed:

$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 chapter.

Custom Getters & Setters

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.

Custom getters and setters with

Cookbook

Introduction

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.

External Links

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" );
    }

}

UserProfile

userId

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

    function profile() {
       return hasOne( "UserProfile" ).withDefault( {
           "showHints": true
       } );
    }

}

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

    function posts() {
        return hasMany( "Post" );
    }

    function latestPost() {
        // remember, relationships are just queries!
        return hasOne( "Post" ).orderBy( "createdDate", "desc" );
    }

}

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

    function user() {
       return belongsTo( "User" ).withDefault( {
           "firstName": "Guest",
           "lastName": "Author"
       } );
    }

}

// 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" );
    }

}

component name="User" {

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

}

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

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

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:

Dynamic Datasource

Contributed by Wil de Bruin

Read about a real world usage of this pattern on Wil's blog.

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

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.

var post = getInstance( "Post" ).create( {
    "title" = "My Post",
    "body" = "Hello, world!"
} );

var user = getInstance( "User" ).findOrFail( 1 );

user.posts().save( post );
// OR use the keyValue
user.posts().save( post.keyValue() );

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

    property name="id";
    property name="uploadFileName";
    property name="fileLocation";
    property name="fileSizeBytes";

}

component
    extends="Media"
    table="book_media"
    joinColumn="FK_media"
    accessors="true"
{
    property name="displayOrder";
    property name="designation";

    function approvalStatus(){
        return belongsTo( "Book", "FK_book" );
    }

}

var smallCoverPhotos = getInstance( "BookMedia" )
                    .where( "designation", "cover" )
                    .where( "fileSizeBytes", "<", 40000 )
                    .orderBy( "displayOrder", "ASC" )
                    .orderBy( "uploadFileName", "ASC" );

// Media (parent entity)
component 
    extends="quick.models.BaseEntity" 
    accessors="true"
    table="media" 
    discriminatorColumn="type" // the database column that determines the subclass
{

    property name="id";
    property name="uploadFileName";
    property name="fileLocation";
    property name="fileSizeBytes";
    
    // Array of all possible subclass entities
    variables._discriminators = [
        "BookMedia"
    ];

}

// BookMedia (subclass)
component
    extends="Media"
    accessors="true"
    discriminatorValue="book" // column value unique to this subclass
{
    property name="displayOrder";
    property name="designation";

}

// Media (parent entity)
component 
    extends="quick.models.BaseEntity" 
    accessors="true"
    table="media" 
    discriminatorColumn="type" 
    singleTableInheritance="true" // Enable STI
{

get

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();

var user = getInstance( "User" )
	.withCount( [
	    "purchases.amount",
	    { "purchases.amount AS totalSingleQuantityPurchases": function( q ) {
	        q.where( "quantity", 1 );
	    } },
	    { "purchases.amount AS totalMultipleQuantityPurchases": function( q ) {
	        q.where( "quantity", ">", 1 );
	    } }
	] )
	.findOrFail( 1 );

post.getTotalPurchases();	
post.getTotalSingleQuantityPurchases();
post.getTotalMultipleQuantityPurchases();

component displayname="DynamicQuickBase" extends="quick.models.BaseEntity" {

	function instanceReady() {
		var thisDataSource = variables._wirebox.getInstance( "coldbox:requestContext" ).getPrivateValue( "mainDatasource","" );
		if ( len( thisDataSource) ){
			variables._queryoptions["datasource"] = thisDataSource;
			variables._builder.setDefaultOptions( variables._queryoptions );
		}
	}
}

component displayname="DynamicQuickBase" extends="quick.models.BaseEntity" {

	/**
	 * Configures a new query builder and returns it.
	 * We modify it to get a dynamic datasource
	 *
	 * @return  quick.models.QuickBuilder
	 */
	public any function newQuery() {
    var thisDataSource = variables._wirebox.getInstance( "coldbox:requestContext" ).getPrivateValue( "customerDatasource","" );
		if ( len( thisDataSource) ){
			variables._queryoptions["datasource"] = thisDataSource;
		}
		return super.newQuery();
	}
}

QBDynamicDataSourceInterceptor.cfc

component {

    function preQBExecute( event, data, buffer, rc, prc ){
        var thisDataSource = event.getPrivateValue( "mainDatasource", "" );
        if ( len( thisDataSource ) && !data.options.keyExists( "dataSource" ) ) {
            data.options["dataSource"] = thisDataSource;
        }
    }

}

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

    function posts() {
        return hasMany( "Post" );
    }
    
    function publishedPosts() {
        return this.posts().whereNotNull( "publishedDate" );
    }
    
}

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

    function posts() {
        return hasMany( "Post" );
    }
    
    function publishedPosts() {
        return this.posts().published();
    }
    
}

// User.cfc
component extends="quick.models.BaseEntity" {
    
    function preSave( event, eventData, buffer, rc, prc ) {
        if ( arguments.eventData.entityName == "User" ) {
            // this code will only execute once when interacting with Admin.cfc
        }
    }
    
}

// Admin.cfc
component extends="models.User" {

}

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

Eager Loading

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 N+1 problem 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 .

Retrieving Relationships

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.

var posts = user.getPosts();

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.

var newestPosts = user
    .posts()
    .orderBy( "publishedDate", "desc" )
    .get();

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

You can also use other Quick fetch methods that provide new entities if a related entity is not found, such as firstOrNew, firstOrCreate, findOrNew, and findOrCreate.

You can also get a new unloaded related entity by calling either the newEntity or the fill functions.

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

    function user() {
        belongsToMany( "User", "user_permission_map", "FK_PermissionID", "FK_UserId" );
    }

}

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

    function userPermissions() {
        return hasMany( "UserPermission" );
    }

    function permissions() {
        return hasManyThrough( [ "UserPermissions", "Permission" ] );
    }

}

var post = getInstance( "Post" ).findOrFail( 1 );
var tag = getInstance( "Tag" ).create( { "name": "miscellaneous" });

// pass an id
post.tags().attach( tag.getId() );
// or pass an entity
post.tags().attach( tag );

var post = getInstance( "Post" ).findOrFail( 1 );
var tag = getInstance("Tag").firstWhere( "name", "miscellaneous" );

// pass an id
post.tags().detach( tag.getId() );
// or pass an entity
post.tags().detach( tag );

<cfoutput>
    <h1>Posts</h1>
    <ul>
        <cfloop array="#prc.posts#" item="post">
            <li>#post.getTitle()# by #post.getAuthor().getUsername()#</li>
        </cfloop>
    </ul>
</cfoutput>

// User.cfc
component {

    function posts() {
        return hasMany( "Post" );
    }

    function publishedPosts() {
        return hasMany( "Post" ).published(); // published is a query scope on Post
    }

}

getInstance( "User" ).with( { "posts" = function( q1 ) {
    return q1
        .whereBetween( "published_date", rc.startDate, rc.endDate )
        .with( { "comments" = function( q2 ) {
            return q2.where( "body", "like", rc.search );
        } } );
} } ).latest().get();

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

    function activePosts() {
        return hasManyDeep(
            relationName = "Post",
            through = [ "User AS u" ],
            foreignKeys = [
                "teamId", // the key on User that refers to Team
                "authorId" // the key on Post that refers to User
            ],
            localKeys = [
                "id", // the key on Team that identifies Team
                "id" // the key on User that identifies User
            ]
        ).where( "u.active", 1 );
    }

}

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

    function activePosts() {
        return newHasManyDeepBuilder()
            .throughEntity( "User AS u", "teamId", "id" )
            .toRelated( "Post", "authorId", "id" )
            .where( "u.active", 1 );
    }

}

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

    function activePosts() {
        return hasManyDeep(
            relationName = "Post",
            through = [ () => newEntity( "User ).active() ],
            foreignKeys = [
                "teamId", // the key on User that refers to Team
                "authorId" // the key on Post that refers to User
            ],
            localKeys = [
                "id", // the key on Team that identifies Team
                "id" // the key on User that identifies User
            ]
        );
    }

}

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

    function activePosts() {
        return newHasManyDeepBuilder()
            .throughEntity(
                entityName = "User",
                foreignKey = "teamId",
                localKey = "id",
                callback = ( user ) => user.active()
            )
            .toRelated( "Post", "authorId", "id" )
    }

}

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

    function posts() {
        return hasManyDeep(
            relationName = "Post",
            through = [ "User" ],
            foreignKeys = [
                "teamId", // the key on User that refers to Team
                "authorId" // the key on Post that refers to User
            ],
            localKeys = [
                "id", // the key on Team that identifies Team
                "id" // the key on User that identifies User
            ]
        );
    }

}

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

    function posts() {
        return newHasManyDeepBuilder()
            .throughEntity( "User", "teamId", "id" )
            .toRelated( "Post", "authorId", "id" );
    }

}

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

    function permissions() {
        return hasManyDeep(
            relationName = "Role",
            through = [ "roles_users", "Role", "permissions_roles" ],
            foreignKeys = [ "userId", "id", "roleId", "id" ],
            localKeys = [ "id", "roleId", "id", "permissionId" ]
        );
    }

}

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

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

    function team() {
        return belongsToThrough( [ "author", "team" ] );
    }

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

}

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

    function posts() {
        return hasMany( "Post" );
    }

    function team() {
        return belongsTo( "Team" );
    }

}

belongsToThrough( [ "author", "team" ] );

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

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

    function office() {
        return belongsToThrough( [ "author", "team", "office" ] );
    }

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

}

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

    function posts() {
        return hasMany( "Post" );
    }

    function team() {
        return belongsTo( "Team" );
    }

}

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

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

    function office() {
        return belongsTo( "Office" );
    }

}

belongsToThrough( [ "author", "team", "office" ] );

+----------------+---------------------------+----------------+
| Current Entity | Relationship Method Names | Related Entity |
+================+===========================+================+
| Post           | author                    | User           |
+----------------+---------------------------+----------------+
| User           | team                      | Team           |
+----------------+---------------------------+----------------+
| Team           | office                    | Office         |
+----------------+---------------------------+----------------+

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

    function team() {
        return belongsToThrough( [ "author", "team" ] ).withDefault();
    }

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

}

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

    function team() {
        return belongsToThrough( [ "author", "team" ] ).withDefault( {
            "name": "No Team"
        } );
    }

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

}

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

    property name="id";
    property name="username";
    property name="email";
    property name="password";
    property name="createdDate";
    property name="modifiedDate";

}

{
    "id" = 1,
    "username" = "JaneDoe",
    "email" = "[email protected]",
    "password" = "$2a$04$2nVI5rPOfl6.hrflkhBWOObO5Z7lXGJpi1vlosY74NrL/CKdpWqZS"
    "createdDate" = "{ts '2018-03-12 16:14:10'}",
    "modifiedDate" = "{ts '2018-03-12 16:14:10'}"
}

function instanceReady() {
    this.memento = {
        "defaultIncludes" : retrieveAttributeNames( withVirtualAttributes = true ),
          "defaultExcludes" : [],
          "neverInclude"    : [],
          "defaults"        : {},
          "mappers"         : {},
          "trustedGetters"  : true,
          "ormAutoIncludes" : false
    };
}

struct function getMemento(
    includes = "", // or []
    excludes = "", // or []
    struct mappers = {},
    struct defaults = {},
    boolean ignoreDefaults = false,
    boolean trustedGetters
)

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

    property name="id";
    property name="username";
    property name="email";
    property name="password";
    property name="createdDate";
    property name="modifiedDate";

    function getMemento() {
        return {
            id = getId(),
            username = getUsername(),
            email = getEmail(),
            createdDate = dateFormat( getCreatedDate(), "MM/DD/YYYY" ),
            // can also use getAttribute if you want to bypass a custom getter
            modifiedDate = dateFormat( retrieveAttribute( "modifiedDate" ), "MM/DD/YYYY" )
        };
    }

}

[
    {
        "id" = 1,
        "username" = "JaneDoe",
        "email" = "[email protected]",
        "createdDate" = "03/12/2018",
        "modifiedDate" = "03/12/2018"
    },
    {
        "id" = 2,
        "username" = "JohnDoe",
        "email" = "[email protected]",
        "createdDate" = "03/14/2018",
        "modifiedDate" = "03/15/2018"
    }
]

Query Scopes and Subselects

What are Scopes?

Query scopes are a way to encapsulate query constraints in your entities while giving them readable names .

A Practical Example

For instance, let's say that you need to write a report for subscribers to your site. Maybe you track subscribers in a users table with a boolean flag in a subscribed column. Additionally, you want to see the oldest subscribers first. You keep track of when a user subscribed in a subscribedDate column. Your query might look as follows:

Now nothing is wrong with this query. It retrieves the data correctly and you continue on with your day.

Later, you need to retrieve a list of subscribed users for a different part of the site. So, you write a query like this:

We've duplicated the logic for how to retrieve active users now. If the database representation changed, we'd have to change it in multiple places. For instance, what if instead of keeping track of a boolean flag in the database, we just checked that the subscribedDate column wasn't null?

Now we see the problem. Let's look at the solution.

The key here is that we are trying to retrieve subscribed users. Let's add a scope to our User entity for subscribed:

Now, we can use this scope in our query:

We can use this on our first example as well, for our report.

We've successfully encapsulated our concept of a subscribed user!

We can add as many scopes as we'd like. Let's add one for longestSubscribers.

Now our query is as follows:

Best of all, we can reuse those scopes anywhere we see fit without duplicating logic.

Usage

All query scopes are methods on an entity that begin with the scope keyword. You call these functions without the scope keyword (as shown above).

Each scope is passed the query, a reference to the current QuickBuilder instance, as the first argument. Any other arguments passed to the scope will be passed in order after that.

Scopes that Return Values

All of the examples so far either returned the QuickBuilder object or nothing. Doing so lets you continue to chain methods on your Quick entity. If you instead return a value, Quick will pass on that value to your code. This lets you use scopes as shortcut methods that work on a query.

For example, maybe you have a domain method to reset passwords for a group of users, and you want the count of users updated returned.

Global Scopes

Occasionally, you want to apply a scope to each retrieval of an entity. An example of this is an Admin entity which is just a User entity with a type of admin. Global Scopes can be registered in the applyGlobalScopes method on an entity. Inside this entity you can call any number of scopes:

These scopes will be applied to the query without needing to call the scope again.

To temporarily disable global scopes that have been applied to an entity, you have the option to disable them individually or all at once by utilizing the withoutGlobalScope method.

Subselects

Subselects are a useful way to grab data from related tables without having to execute the full relationship. Sometimes you just want a small piece of information like the lastLoginDate of a user, not the entire Login relationship. Subselects are perfect for this use case. You can even use subselects to provide the correct key for dynamic subselect relationships. We'll show how both work here.

Quick handles subselect properties (or computed or formula properties) through query scopes. This allows you to dynamically include a subselect. If you would like to always include a subselect, add it to your entity's

Here's an example of grabbing the lastLoginDate for a User:

We'd add this subselect by calling our scope:

We can even constrain our User entity based on the value of the subselect, so long as we've called the scope adding the subselect first (or made it a global scope).

Or add a new scope to User based on the subselect:

In this example, we are using the addSubselect helper method. Here is that function signature:

Argument

Type

Required

Default

Description

You might be wondering why not use the logins relationship? Or even logins().latest().limit( 1 ).get()? Because that executes a second query. Using a subselect we get all the information we need in one query, no matter how many entities we are pulling back.

Using Relationships in Subselects

In most cases the values you want as subselects are values from your entity's relationships. In these cases, you can use a shortcut to define your subselect in terms of your entity's relationships represented as a dot-delimited string.

Let's re-write the above subselect for lastLoginDate for a User using the existing relationship:

Much simpler! In addition to be much simpler this code is also more dynamic and reusable. We have a relationship defined for logins if we need to fetch them. If we change how the logins relationship is structured, we only have one place we need to change.

With the query cleaned up using existing relationships, you might find yourself adding subselects directly in your handlers instead of behind scopes. This is fine in most cases. Keep an eye on how many places you use the subselect in case you need to re-evaluate and move it behind a scope.

Dynamic Subselect Relationships

Subselects can be used in conjunction with relationships to provide a dynamic, constrained relationship. In this example we will pull the latest post for a user.

This can be executed as follows:

As you can see, we are loading the id of the latest post in a subquery and then using that value to eager load the latestPost relationship. This sequence will only execute two queries, no matter how many records are loaded.

Virtual Attributes

Virtual attributes are attributes that are not present on the table backing the Quick entity. A Subselect is an example of a virtual attribute. Other examples could include calculated counts or CASE statement results.

By default, if you add a virtual column to a Quick query, you won't see anything in the entity. This is because Quick needs to have an attribute defined to map the result to. You can create a virtual attribute in these cases.

This step is unnecessary when using the addSubselect helper method.

Here's an example including the result of a CASE statement as a field:

With this code, we could now access the publishedStatus just like any other attribute. It will not be updated, inserted, or saved though, as it is just a virtual column.

The appendVirtualAttribute method adds the given name as an attribute available in the entity.

appendVirtualAttribute

Argument

Type

Required

Default

Description

Creates a virtual attribute for the given name.

It is likely that Quick will introduce more helper methods in the future making these calls simpler.

hasManyThrough

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 .

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

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.

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.

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:

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

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

    function scopeLongestSubscribers( query ) {
        return query.orderBy( "subscribedDate" );
    }

    function scopeSubscribed( query ) {
        return query.where( "subscribed", true );
    }

}

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

    property name="id";
    property name="username";
    property name="password";
    property name="type";

    function scopeOfType( query, type = "limited" ) {
        return query.where( "type", type );
    }

    function scopeResetPasswords( query ) {
        return query.updateAll( { "password" = "" } ).result.recordcount;
    }

}


// disable all global scopes
var admins = getInstance( "Admin" ).withoutGlobalScope().all();

// selectively disable global scopes
var admins = getInstance( "Admin" ).withoutGlobalScope( [ "ofType" ] ).all();

// SELECT * FROM users

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

    /* properties */

    function logins() {
        return hasMany( "Login" ).latest();
    }

    function scopeAddLastLoginDate( qb ) {
        qb.addSubselect( "lastLoginDate", newEntity( "Login" )
            .select( "timestamp" )
            .whereColumn( "users.id", "user_id" )
        );
    }

}

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

    /* properties */

    function logins() {
        return hasMany( "Login" );
    }

    function scopeAddLastLoginDate( qb ) {
        qb.addSubselect( "lastLoginDate", "logins.timestamp" );
    }

}

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

    /* properties */

    function scopeWithLatestPost( qb ) {
        return qb.addSubselect( "latestPostId", newEntity( "Post" )
            .select( "id" )
            .whereColumn( "user_id", "users.id" )
            .orderBy( "created_date", "desc" )
        ).with( "latestPost" );
    }

    function latestPost() {
        return belongsTo( "Post", "latestPostId" );
    }

}

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

    function scopeAddType( qb ) {
        qb.selectRaw( "
                CASE
                    WHEN publishedDate IS NULL THEN 'unpublished'
                    ELSE 'published'
                END AS publishedStatus
            " );
        appendVirtualAttribute( "publishedStatus" );
    }

}

// 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" );
    }

}

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

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

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

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

}

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

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

// 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" );
    }

}

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

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

// 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           |
    +----------------+---------------------------+----------------+

interface displayname="KeyType" {

    /**
    * Called to handle any tasks before inserting into the database.
    * Recieves the entity as the only argument.
    */
    public void function preInsert( required entity );

    /**
    * Called to handle any tasks after inserting into the database.
    * Recieves the entity and the queryExecute result as arguments.
    */
    public void function postInsert( required entity, required struct result );

}

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

    property name="fieldID";
    property name="clientID";
    property name="fieldName";

    variables._key = [ "fieldID", "clientID" ];
    
    function keyType() {
        return variables._wirebox.getInstance( "NullKeyType@quick" );
    }

}

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

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

    property name="id";
    property name="username";
    property name="email";

}

// BooleanCast.cfc
component implements="CastsAttribute" {

    /**
     * Casts the given value from the database to the target cast type.
     *
     * @entity      The entity with the attribute being casted.
     * @key         The attribute alias name.
     * @value       The value of the attribute.
     *
     * @return      The casted attribute.
     */
    public any function get(
        required any entity,
        required string key,
        any value
    ) {
        return isNull( arguments.value ) ? false : booleanFormat( arguments.value );
    }

    /**
     * Returns the value to assign to the key before saving to the database.
     *
     * @entity      The entity with the attribute being casted.
     * @key         The attribute alias name.
     * @value       The value of the attribute.
     *
     * @return      The value to save to the database. A struct of values
     *              can be returned if the cast value affects multiple attributes.
     */
    public any function set(
        required any entity,
        required string key,
        any value
    ) {
        return arguments.value ? 1 : 0;
    }

}

// Address.cfc
component accessors="true" {

    property name="streetOne";
    property name="streetTwo";
    property name="city";
    property name="state";
    property name="zip";

    function fullStreet() {
        var street = [ getStreetOne(), getStreetTwo() ];
        return street.filter( function( part ) {
            return !isNull( part ) && part != "";
        } ).toList( chr( 10 ) );
    }

    function formatted() {
        return fullStreet() & chr( 10 ) & "#getCity()#, #getState()# #getZip()#";
    }

}

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

    property name="id";
    property name="username";
    property name="firstName" column="first_name";
    property name="lastName" column="last_name";
    property name="password";

    property name="address"
        casts="AddressCast"
        virtual="true"
        getter="false"
        setter="false";
    property name="streetOne";
    property name="streetTwo";
    property name="city";
    property name="state";
    property name="zip";

}

component implements="quick.models.Casts.CastsAttribute" {

    property name="wirebox" inject="wirebox";

    /**
     * Casts the given value from the database to the target cast type.
     *
     * @entity      The entity with the attribute being casted.
     * @key         The attribute alias name.
     * @value       The value of the attribute.
     * @attributes  The struct of attributes for the entity.
     *
     * @return      The casted attribute.
     */
    public any function get(
        required any entity,
        required string key,
        any value
    ) {
        return wirebox.getInstance( dsl = "Address" )
            .setStreetOne( entity.retrieveAttribute( "streetOne" ) )
            .setStreetTwo( entity.retrieveAttribute( "streetTwo" ) )
            .setCity( entity.retrieveAttribute( "city" ) )
            .setState( entity.retrieveAttribute( "state" ) )
            .setZip( entity.retrieveAttribute( "zip" ) );
    }

    /**
     * Returns the value to assign to the key before saving to the database.
     *
     * @entity      The entity with the attribute being casted.
     * @key         The attribute alias name.
     * @value       The value of the attribute.
     * @attributes  The struct of attributes for the entity.
     *
     * @return      The value to save to the database. A struct of values
     *              can be returned if the cast value affects multiple attributes.
     */
    public any function set(
        required any entity,
        required string key,
        any value
    ) {
        return {
            "streetOne": arguments.value.getStreetOne(),
            "streetTwo": arguments.value.getStreetTwo(),
            "city": arguments.value.getCity(),
            "state": arguments.value.getState(),
            "zip": arguments.value.getZip()
        };
    }

}

What's New?

10.0.1

Better matching of only "as" in relationship strings.

10.0.0

Upgrade to qb v10

9.0.3

Child Entities: Ensure single table inheritance columns are not duplicated.

9.0.2

HasOneThrough: Added the missing matchOnemethod.

Child Entities: Fixed qualifying columns on discriminated joined entities.

9.0.1

Fixed an issue with NULLvalues being inserted into identify columns for SQL Server

9.0.0

BREAKING CHANGES

When a relationship, if there is a defined, it will return the default entity instead of null.
The function no longer accepts a ignoreNonExistentAttributes flag. This is because assignAttributesData always skips non-existent attributes.

Features

Get a new filled instance of a relationship by calling the fill method on the relationship object.
Add newAttributes and originalAttributes to the event.
Add methods to Relationship classes.

Bug Fixes

Clear the relationship cache for a relationship when using the relationship setter.
Only compute the attributes hash from persistent attributes.
Handle null values when assigning to attributes
Fixed an issue where virtual attributes were not being applied to discriminated child entities when loading through the parent.

8.0.3

Respect qb's support options.

8.0.2

Handle skipping constraints when a relationship is defined with other relationships

8.0.1

Make the withoutRelationshipConstraints check more resilient by checking against a set of relationship method names.

8.0.0

BREAKING CHANGE

The withoutRelationshipConstraints method now requires the relationship method name as the first parameter.

This is used to ensure only the desired relationship has its constraints skipped. This is especially important in asynchronous contexts.

7.4.4

Fix for thread safety when loading multiple relationships off of a single entity

7.4.3

Fix qualifying column issue when using HasManyDeep relationships.

7.4.2

Remove duplicate join from addCompareConstraints when using HasManyDeep relationships.

7.4.1

Upgrade to latest str dependency

7.4.0

HasManyDeep

Introduced a new alternative relationship to the old hasManyThrough — hasManyDeep. It produces more readable, parsable SQL and is the basis for the new version of hasManyThrough.

HasManyDeepBuilder

If you prefer the hasManyDeep syntax over the hasManyThrough syntax, you might enjoy the HasManyDeepBuilder, a builder object to create the hasManyDeep relationship. It is generally more readable, especially when using additional constraints on related or through entities, at the cost of verbosity.

Revamped HasManyThrough relationships

All hasManyThrough relationships are now hasManyDeep relationships under the hood. No code changes should be necessary for you to enjoy more readable SQL, less bugs, and greater performance. 🏎️

7.3.2

Use the interceptor approach instead of wirebox:targetId to support CommandBox 5.

7.3.1

Fix where discriminated entities could use the wrong qualified column name in the join with the parent entity.

7.3.0

New Features

Return optional QuickBuilder instances for withCount and withSum to allow for further chaining.

Bug Fixes

Fix clearAttribute when not setting to null.
Fix using a QueryBuilder instance to define a subselect.

Additional Test Cases

Add test case for checking null attributes on newly created entities.
Add test case for deleteAll off of a hasMany relationship.
Add test case for belongsToMany withCount.

7.2.0

Allow setting for the underlying qb instance backing Quick.

7.1.1

Pin to version 3.

7.1.0

Add a method, similar to for quickly adding a subselect based on the sum of a relationship's attribute.

7.0.1

Correctly handle null values with casted attributes.

7.0.0

QuickBuilder now has its own clone method that behaves as you would expect. Previously, it only cloned the enclosed QueryBuilder which was not that useful.

Making this fix required the newQuery method of QuickBuilder to return an instance of QuickBuilder instead of QueryBuilder as it previously was. If you need a new QueryBuilder instance from a QuickBuilder, use the newQuickQB method.

6.2.1

Allow a QuickBuilder to be used wherever a QueryBuilder can be used.

6.2.0

Add the ability to .

6.1.0

Introducing the `asQuery` method

This method is similar to asMemento. You use it when the return format you want is an array of structs. asQuery will skip creating entities at all, instead returning the values straight from qb. This can result in a large performance boost depending on the number of records being returned. Additionally, asQuery supports returning the columns using the alias names and returning eager loaded entities.

6.0.0

Add compatibility with ColdBox 7.
Fixed a bug where once a virtual attribute was added to an entity it was added to all future entities of that same type.
Dropped support for ColdBox 5.

5.3.3

Use correct nesting for where statements

5.3.2

Fixed retrieving null values from fields and relationships

5.3.1

Special handling for Lucee generated keys
Workaround for adobe@2021 not supporting null values in param statements
Upgrade to latest cfmigrations (v4.0.0)

5.3.0

Add a way to not fire events inside a callback using withoutFiringEvents.

5.2.11

Upgrade to qb 9

5.2.10

HasOneOrManyThrough: Fix too many joins for has and whereHas

5.2.9

HasOneOrManyThrough: Fixed applying of through constraints BaseEntity: Use wirebox to get the util to work in CommandBox

5.2.8

Fix bad link to Getting Started guide

5.2.7

Use existing builder when adding subselects

5.2.6

Update to latest mementifier (v3.0.0)

5.2.5

CommandBox compatibility

5.2.4

Force generated key to be an integer.

5.2.3

CommandBox-friendly injections using the box namespace.

5.2.2

Fixed regression where eager loading inside a relationship was broken.

5.2.1

Fixed accessing QuickBuilder from entities and relationships.

5.2.0

Add include and exclude arguments to method.

5.1.3

Always return numeric value for .

5.1.2

Add the builder to the preInsert method for .

5.1.1

Set the table when creating new queries.

5.1.0

Added support for with discriminated subclass entities.

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:

Engine

4.2.0

5.0.0

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

Other Changes

for memento transformations.
Use to automatically convert queries to mementos.
Automatically-generated .
Add error message for defaulting key values.

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.

2.3.0

2.2.0

(first and find methods)

2.1.0

Mapping foreign keys for relationships is now optional

accessors="true"

// 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" );
    }

}

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

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

// 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" );
    }

}

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

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

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

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

}

// 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" );
    }

}

var user = getInstance( "User" ).findOrCreate(
    9999,
      {
        "username"  : "doesntexist",
              "firstName" : "doesnt",
              "lastName"  : "exist",
              "password"  : "secret"
      }
);

var users = getInstance( "User" ).hydrateAll( [
    {
        "id": 3,
        "username": "JohnDoe",
        "email": "[email protected]",
        "password": "mypass4321"
    },
    {
        "id": 4,
        "username": "JaneDoe",
        "email": "[email protected]",
        "password": "mypass1234"
    }
] );

Upgrade Guide

10.0.0

qb v10 is now the minimum version required to use Quick.

9.0.0

Relationships with a default entity but no match used to return null (or an empty struct when in asQuery mode). It will now return the default entity attributes or memento. (Relationships without default entities have no change.)
hydrate no longer accepts a ignoreNonExistentAttributes flag. This is because assignAttributesData always skips non-existent attributes.

8.0.0

The `withoutRelationshipConstraints` method now requires the relationship method name as the first parameter.

This is used to ensure only the desired relationship has its constraints skipped. This is especially important in asynchronous contexts.

7.0.0

QuickBuilder.newQuery() now returns QuickBuilder instances

Calling newQuery on a QuickBuilder now returns a new QuickBuilder instance instead of a new QueryBuilder instance. If you needed a QueryBuilder instance, use the newQuickQB method instead.

6.0.0

Dropped support for ColdBox 5

It's very likely that Quick v6 will still work on ColdBox 5, but it is no longer an officially supported platform.

5.1.0

KeyType now accepts the builder as a second argument to `preInsert`

This is only a breaking change if you have built your own key types. This is being released as a bug fix since the ReturningKeyType has not worked correctly since 5.0.0

5.0.0

Dropped support for Adobe ColdFusion 2016

Please upgrade to a supported engine.

`addSubselect` calls must be accessed on the QuickBuilder

This means for scopes, you must call addSubselect off of the passed in builder object.

`applyGlobalScopes` functions now receive a Builder instance that should be used to call scopes

Instead of this:

the scopes should be called on the passed in Builder instance:

4.0.0

Scopes, whereHas, and whereDoesntHave are now automatically grouped when using an OR combinator

This isn't a breaking change that will affect most people. In fact, it will most likely improve your code.

Previously, when using , , or , you were fully responsible for the wrapping of your where statements. For example, the following query:

with the following scopes defined:

would generate the following SQL:

The problem with this statement is that the OR can short circuit the active check.

The fix is to wrap the LIKE statements in parenthesis. This is done in qb using a function callback to where. Adding this nesting inside our scope will fix this problem.

But this was easy to miss this. This is because you are in a completely different file than the built query. It also breaks the mental model of a scope as an encapsulated piece of SQL code.

In Quick 4.0.0, scopes, whereHas, and whereDoesntHave will automatically group added where clauses when needed. That means our original example now produces the SQL we probably expected.

Grouping is not needed if there is no OR combinator. In these cases no grouping is added.

If you had already wrapped your expression in a group inside the scope, whereHas, or whereDoesntHave call, nothing changes. Your code works as before. The OR combinator check only works on the top most level of added where clauses. Additionally, if you do not add any where clauses inside your scope, nothing changes.

The breaking change part is if you were relying on these statements residing at the same level without grouping. If so, you will need to group your changes into a single scope where you control the grouping or do the querying at the builder level outside of scopes.

3.0.0

Adobe ColdFusion 11 and Lucee 4.5 are no longer supported

Please migrate to a supported engine.

Virtual Inheritance support removed

Virtual Inheritance allowed you to use a quick annotation on your entity instead of extending quick.models.BaseEntity. This was hardly used and didn't offer any benefit to extending using traditional inheritance. Additionally, removing the support allows us to clean up the code base by removing duplicate code paths.

If any of your entities are using the quick annotation, instead have them extends="quick.models.BaseEntity".

`accessors="true"` required for all entities

From the early days of Quick, developers have wanted to have accessors="true" on their entities. Because of this, Quick supported defining entities both with and without accessors. However, just as with virtual inheritance, it created two code paths that could hide bugs and make it hard to follow the code. In Quick 3.0.0, accessors="true" is required on all entities. If it is omitted, a helpful error message is thrown to remind you. This will help immensely in simplifying the code base. (In fact, just introducing this requirement helped find two bugs that were only present when using accessors.)

Ensure all entities have accessors="true" in their component metadata.

AssignedKey removed

Use NullKeyType instead.

Boolean casts updates to hook in to new Cast system

Previously, the only valid cast type was casts="boolean". In introducing the new Casts system, the boolean cast was refactored to use the same system. For this reason, any casts="boolean" needs to be changed to casts="BooleanCast@quick"

defaultGrammar updated to be the full WireBox mapping

In previous versions, the value passed to defaultGrammar was used to look up a mapping in the @qb namespace. This made it difficult to add or use grammars that weren't part of qb. (You could get around this be registering your custom grammar in the @qb namespace, but doing so seemed strange.)

To migrate this code, change your defaultGrammar to be the full WireBox mapping in your moduleSettings:

re-tooled to be based on relationships

It no longer accepts any entities or columns. Rather, it accepts an array of relationships to walk "through" to end up at the desired entity.

Here's how the old syntax would be used to define the relationship between Country and Post.

This same relationship now needs to be defined in terms of other relationships, like so.

This approach does require a relationship defined for each level, but it works up and down any number of relationships to get to your desired entity.

`` cannot be called on unloaded entities

To update the foreign key of a belongsTo relationship you use the associate method. In the past, it was possible to associate a new, unsaved child entity to its parent using this method.

In an attempt to provide more helpful error messages, this behavior is no longer possible. You can achieve the same effect in one of two ways.

The first is to manually assign the foreign keys:

While this works, it breaks the encapsulation provided by the relationship.

The second approach is to use the hasOne or hasMany side of the relationship to create the new child entity:

If you have all the data handy in a struct, you can use the create method for a more concise syntax.

This is the recommended way of creating these components.

assignAttributesData argument renamed to `attributes`

This brings the API in line with the other methods referencing attributes.

Method changes due to compound key support

Compound key support required some method and parameter name changes. Although the list seems extensive, you will likely not need to change anything in your code unless you have extended built-in Quick components. (You will see many relationship parameter name changes. Note that the function you call to define a relationship is a function on the BaseEntity and has not changed its signature.)

BaseEntity.cfc:

retrieveQualifiedKeyName : String -> retrieveQualifiedKeyNames : [String]
keyName : String -> keyNames : [String]
keyColumn : String

AutoIncrementingKeyType.cfc

This cannot be used with composite primary keys

BaseRelationship.cfc

getKeys now takes an array of keys as the second argument
getQualifiedLocalKey : String -> getQualifiedLocalKeys : [String]
getExistenceCompareKey : String

BelongsTo.cfc

init arguments have changed
- foreignKey : String -> foreignKeys : [String]
- localKey : String

BelongsToMany.cfc

init arguments have changed
- foreignPivotKey : String -> foreignPivotKeys : [String]
- relatedPivotKey : String

HasManyThrough.cfc

This component now extends quick.models.Relationships.HasOneOrManyThrough
init arguments are now as follows:
- related: The related entity instance.

HasOneOrMany.cfc

init arguments have changed
- foreignKey : String -> foreignKeys : [String]
- localKey : String

PolymorphicBelongsTo.cfc

init arguments have changed
- foreignKey : String -> foreignKeys : [String]
- localKey : String

PolymorphicHasOneOrMany.cfc

init arguments have changed
- id : String -> ids : [String]
- localKey : String

2.0.0

Quick 2.0 brings with it a lot of changes to make things more flexible and more performant. This shouldn't take too long — maybe 2-5 minutes per entity.

Internal properties renamed

There were some common name clashes between internal Quick properties and custom attributes of your entities (the most common being fullName). All Quick internals have been obfuscated to avoid this situation. If you relied on these properties, please consult the following table below for the new property names.

If you are renaming your primary keys in your entities, you will have to change your key definition from variables.key = "user_id"; to variables._key = "user_id"; See for details.

Old Property Name

New Property Name

Additionally, some method names have also changed to avoid clashing with automatically generated getters and setters. Please consult the table below for method changes.

Old Method Name

New Method Name

Lastly, the following properties and methods have been removed:

Removed Property or Method

Key Types

Defining Key Types

Key Types are the way to define setting and retrieving a primary key in Quick. In Quick 1.0 these were injected in to the component. This made reusability hard for simple things like sequence names. In order to allow for more flexible key types, key types are no longer injected. Instead, they should be returned from a keyType method.

The keyType is lazily created and cached on the component, so this is both a more flexible approach as well as being more performant. If you are injecting custom key types in your entities you will need to move them to the method syntax.

Changed Key Types

A few key types have been renamed and will need to be updated in your codebase:

Old Key Type Name

New Key Type Name

New Key Types

In additional to the changes to defining key types, there is a few new key types introduced in Quick 2.0.

ReturningKeyType

Used with grammars that return their primary key in the query response when inserting to the database. An example of this is NEWSEQUENTIALID in Microsoft SQL Server.

Scopes

The way arguments are passed to scopes have been updated to allow for default arguments. query is still the first argument. Other arguments will be passed in order after that. The args struct is no longer passed.

Relationships

The relationship methods are still named the same but some of the arguments have been changed to fix bugs and support better eager loading performance. Please for more details.

Additionally, the alternative syntax for defining relationships on a relationships struct has been removed. It created an unnecessary code path that had it's own share of bugs. All relationships should be defined as methods on the entity.

Removing CFCollection

CFCollection was included in Quick 1.0 as both a way to lazily eager load a relationship and as a compatibility layer for older CF versions. The compatibility that CFCollection provides, however, comes with a performance cost. Additionally, the majority of users wanted to use plain arrays as the return format. For those reasons, arrays are now the default return format for collections. CFCollections can still be used by specifying a different return format in the module settings.

Converting to Null

Null is a tricky thing in CFML. The same goes for interacting with nulls in a database. By default, we will support the CFML convention of using an empty string to represent null. When interacting with the database empty strings will be converted to nulls. You can adjust this behavior on the property level with two new annotations:

convertToNull - Determines if the property will be automatically checked to convert to null at all. Defaults to true.
nullValue - This is the value that is equivalent to null for this property. Defaults to an empty string.

Returning Null instead of Unloaded Entities

In an effort to avoid dealing with CFML's version of null, Quick originally returned unloaded entities. You could check if an entity was loaded using the isLoaded method. This doesn't make as much sense as null however and even made it more difficult to interact with other libraries. Now Quick will return null when it encounters an empty query result either from a retrieval or from a belongsTo or hasOne relationship. Any instances that you were checking isLoaded should be updated. isLoaded will continue to exist for when you are creating a new entity not from the database.

AutoDiscover Grammar

The default grammar for Quick is now AutoDiscover. This provides a better first run experience. The grammar can still be set in the moduleSettings.

BaseService

As a new way to interact with Quick, you can use Quick Services to interact with your entities in a service-oriented fashion. These are equivalent to VirtualEntityServices in cborm.

The easiest way to use a Quick Service is to use the quickService: injection dsl.

All methods available on the Quick entity are available on the service.

Eager Loading

Eager loading is now supported for nested relationships using a dot-separated syntax. Additionally, constraints can be added to an eager loaded relationship. See the for more information.

Column Aliases in Queries

Column aliases can now be used in queries. They will be transformed to columns before executing the query.

Quick entities in Setters

If you pass a Quick entity to a setter method the entity's keyValue value will be passed.

Update and Insert Guards

Columns can be prevented from being inserted or updated using property attributes — insert="false" and update="false".

cbvalidation removed as a default dependency

Quick no longer automatically validates entities before saving them. Having cbvalidation baked in made it hard to extend it. If desired, validation can be added back in using Quick's lifecycle hooks.

`instanceReady` Lifecycle Method

Quick now announces an instanceReady event after the entity has gone through dependency injected and had its metadata inspected. This can be used to hook in other libraries, like cbvalidation and mementifier.

Automatic Attribute Casting

You can automatically cast a property to a boolean value while retrieving it from the database and back to a bit value when serializing to the database by setting casts="boolean" on the property.

keyColumns : [String]

getExistenceCompareKeys : [String]

localKeys : [String]

relatedPivotKeys : [String]

localKeys : [String]

/**
 * Called to handle any tasks before inserting into the database.
 * Receives the entity as the only argument.
 *
 * @entity   The entity that is being inserted.
 * @builder  The builder that is doing the inserting.
 *
 * @return   void
 */
public void function preInsert( required any entity, required any builder );

component extends="quick.models.BaseEntity" {

    function posts() {
        return hasManyThrough( [ "users", "posts" ] );
    }

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

}

Retrieving Entities

Once you have an entity and its associated database table you can start retrieving data from your database.

You can configure your query to retrieve entities using any qb method. It is highly recommended you become familiar with the qb documentation.

Active Record

You start every interaction with Quick with an instance of an entity. The easiest way to do this is using WireBox. getInstance is available in all handlers by default. WireBox can easily be injected in to any other class you need using inject="wirebox".

Quick is backed by qb, a CFML Query Builder. With this in mind, think of retrieving records for your entities like interacting with qb. For example:

In addition to using for you can utilize the each function on arrays. For example:

You can add constraints to the query just the same as you would using qb directly:

For more information on what is possible with qb, check out the .

Quick Service

A second way to retrieve results is to use a Quick Service. It is similar to a VirtualEntityService from cborm.

The easiest way to create a Quick Service is to inject it using the quickService: dsl:

If you have a existing Service, and you would like to extend the quickService, you can extend the quikc.models.BaseService and then call super.init inside of the service init function passing the name of the entity (for example your User Entity) shown below:

Any method you can call on an entity can be called on the service. A new entity will be used for all calls to a Quick Service.

If you need a new unsaved entity from your service, you can call myService.newEntity()

Aggregates

Calling qb's aggregate methods (count, max, etc.) will return the appropriate value instead of an entity or collection of entities.

existsOrFail

Returns true if any entities exist with the configured query. If no entities exist, it throws an EntityNotFound exception.

Retrieval Methods

all

Retrieves all the records for an entity. Calling all will ignore any non-global constraints on the query.

get

Executes the configured query, eager loads any relations, and returns the entities in a new collection.

paginate

Executes the configured query, eager loads any relations, and returns the entities in the configured qb pagination struct.

simplePaginate

Executes the configured query, eager loads any relations, and returns the entities in the configured qb simple pagination struct.

first

Executes the configured query and returns the first entity found. If no entity is found, returns null.

firstWhere

Adds a basic where clause to the query and returns the first result.

firstOrFail

Executes the configured query and returns the first entity found. If no entity is found, then an EntityNotFound exception is thrown with the given or default error message.

firstOrNew

Finds the first matching record or returns an unloaded new entity.

firstOrCreate

Finds the first matching record or creates a new entity.

find

Returns the entity with the id value as the primary key. If no record is found, it returns null instead.

findOrFail

Returns the entity with the id value as the primary key. If no record is found, it throws an EntityNotFound exception.

findOrNew

Returns the entity with the id value as the primary key. If no record is found, it returns a new unloaded entity.

findOrCreate

Returns the entity with the id value as the primary key. If no record is found, it returns a newly created entity.

newEntity

You will probably not use newEntity very often if you use wirebox getinstance("someQuickEntity") to retrieve an entity, because that will already give you a new entity. If you are using a QuickService you will need this method for creating a new entity

Hydration Methods

Hydration is a term to describe filling an entity with a struct of data and then marking it as loaded, without doing any database queries. For example, this might be useful when hydrating a user from session data instead of doing a query every request.

hydrate

Hyrdates an entity from a struct of data. Hydrating an entity fills the entity and then marks it as loaded.

If the entity's keys are not included in the struct of data, a MissingHydrationKey is thrown.

hydrateAll

Hydrates a new collection of entities from an array of structs.

Custom Collections

If you would like collections of entities to be returned as something besides an array, you can override the newCollection method. It receives the array of entities. You can return any custom collection you desire.

newCollection

Returns a new collection of the given entities. It is expected to override this method in your entity if you need to specify a different collection to return. You can also call this method with no arguments to get an empty collection.

// default response example
{
    "results": [ User#1, User#2, ... ],
    "pagination": {
        "totalPages": 2,
        "maxRows": 25,
        "offset": 0,
        "page": 1,
        "totalRecords": 40
    }
}

var user = getInstance( "User" ).findOrCreate(
    9999,
      {
        "username"  : "doesntexist",
              "firstName" : "doesnt",
              "lastName"  : "exist",
              "password"  : "secret"
      }
);

var users = getInstance( "User" ).hydrateAll( [
    {
        "id": 3,
        "username": "JohnDoe",
        "email": "[email protected]",
        "password": "mypass4321"
    },
    {
        "id": 4,
        "username": "JaneDoe",
        "email": "[email protected]",
        "password": "mypass1234"
    }
] );

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

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

}

10.0.0

Introduction

A CFML ORM Engine

Why?

Why Quick?

Coming from <cfquery> or queryExecute?

Coming from Hibernate?

Contributing

Configuration

Guide

Getting Started

Configure a default datasource in your CFML engine

Download Quick

Add a mapping for quick in your Application.cfc

Configure your defaultGrammar in config/ColdBox.cfc

Subclass Entities

Subclass Entities

Working with Entities

isLoaded

Deleting Entities

delete

deleteAll

Relationships

Relationship Types

hasOne

Usage

hasMany

Usage

Inserting & Updating

save

saveMany

create

Removing

Relationship Setter

Signature

Visualizer

belongsTo

Usage

CBORM Compatibility Shim

Entity / Service Methods

Collections

load

$renderData

Custom Getters & Setters

Cookbook

Introduction

External Links

Contributing

Relationships

Working with Entities

isLoaded

Configuration

clone

Why Quick?

Coming from <cfquery> or queryExecute?

Coming from Hibernate?

Relationship Types

Deleting Entities

delete

deleteAll

Getting Started

Configure a default datasource in your CFML engine

Download Quick

Add a mapping for quick in your Application.cfc

Configure your defaultGrammar in config/ColdBox.cfc

hasOne

Usage

Custom Getters & Setters

Introduction

withDefault

Signature

Visualizer

belongsTo

Usage

Introduction

A CFML ORM Engine

Why?

CBORM Compatibility Shim

Entity / Service Methods

Criteria Builder Methods

Add a mapping for `quick` in your `Application.cfc`

Configure your `defaultGrammar` in `config/ColdBox.cfc`

Add a mapping for `quick` in your `Application.cfc`

Configure your `defaultGrammar` in `config/ColdBox.cfc`