Configure a default datasource in your CFML engine

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

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

Download Quick

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

box install quick

Add a mapping for quick in your Application.cfc

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

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

Configure your defaultGrammar in config/ColdBox.cfc

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

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

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

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

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

Coming from <cfquery> or queryExecute?

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

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

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

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

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

Coming from Hibernate?

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

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

  because they are provided directly by the Java classes.

• Complex CFML Hibernate ORM applications can consume significant memory and

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

  in microservices architecture.

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

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

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

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

  Java project.

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

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

  this gap.)

We can do better.

isLoaded

Checks if the entity was loaded from the database.

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

var user = getInstance( "User" );
user.isLoaded(); // false
user.save();
user.isLoaded(); // true

save

New Quick entities can be created and persisted to the database by creating a new entity instance, setting the attributes on the entity, and then calling the save method.

When we call save, the record is persisted from the database and the primary key is set to the auto-generated value (if any).

We can shortcut the setters above using a fill method.

fill

Finds the first matching record or creates a new entity.

Sets attributes data from a struct of key / value pairs. This method does the following, in order:

1. Guard against read-only attributes.

2. Attempt to call a relationship setter.

3. Calls custom attribute setters for attributes that exist.

4. Throws an error if an attribute does not exist (if ignoreNonExistentAttributes is false which is the default).

populate

Populate is simply an alias for fill. Use whichever one suits you best.

create

Creates a new entity with the given attributes and then saves the entity.

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

firstOrNew

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

firstOrCreate

Finds the first matching record or creates a new entity.

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.

updateOrCreate

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

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.

save

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

update

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

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

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

updateOrCreate

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

updateAll

fresh

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

refresh

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

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:

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.

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 -> keyColumns : [String]

• keyValue : String -> keyValues : [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 -> getExistenceCompareKeys : [String]

BelongsTo.cfc

• init arguments have changed

  • foreignKey : String -> foreignKeys : [String]

  • localKey : String -> localKeys : [String]

• getQualifiedLocalKey : String -> getQualifiedLocalKeys : [String]

• getExistenceCompareKey : String -> getExistenceCompareKeys : [String]

BelongsToMany.cfc

• init arguments have changed

  • foreignPivotKey : String -> foreignPivotKeys : [String]

  • relatedPivotKey : String -> relatedPivotKeys : [String]

  • parentKey : String -> parentKeys : [String]

  • relatedKey : String -> relatedKeys : [String]

• getQualifiedRelatedPivotKeyName : String -> getQualifiedRelatedPivotKeyNames : [String]

• getQualifiedForeignPivotKeyName : String -> getQualifiedForeignPivotKeyNames : [String]

• getQualifiedForeignKeyName : String -> getQualifiedForeignKeyNames : [String]`

HasManyThrough.cfc

• This component now extends quick.models.Relationships.HasOneOrManyThrough

• init arguments are now as follows:

  • related: The related entity instance.

  • relationName: The WireBox mapping for the related entity.

  • relationMethodName: The method name called to retrieve this relationship.

  • parent: The parent entity instance for the relationship.

  • relationships: An array of relationships between the parent entity and the related entity.

  • relationshipsMap: A dictionary of relationship name to relationship component.

• The following methods no longer exist:

  • getQualifiedFarKeyName

  • getQualifiedForeignKeyName

  • getQualifiedFirstKeyName

  • getQualifiedParentKeyName

HasOneOrMany.cfc

• init arguments have changed

  • foreignKey : String -> foreignKeys : [String]

  • localKey : String -> localKeys : [String]

• getParentKey : any -> getParentKeys : [any]

• getQualifiedLocalKey : String -> getQualifiedLocalKeys : [String]

• getQualifiedForeignKeyName : String -> getQualifiedForeignKeyNames : [String]

PolymorphicBelongsTo.cfc

• init arguments have changed

  • foreignKey : String -> foreignKeys : [String]

  • localKey : String -> localKeys : [String]

PolymorphicHasOneOrMany.cfc

• init arguments have changed

  • id : String -> ids : [String]

  • localKey : String -> localKeys : [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.

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

Lastly, the following properties and methods have been removed:

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:

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

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

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.

delete

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

deleteAll

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

Deletes matching entities according to the configured query.

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

A CFML ORM Engine

Why?

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

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

  because they are provided directly by the Java classes.

• Complex CFML Hibernate ORM applications can consume significant memory and

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

  in microservices architecture.

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

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

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

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

  Java project.

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

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

  this gap.)

We can do better.

What?

Prerequisites

You need the following configured before using Quick:

• Configure a default datasource in your CFML engine

• ColdBox 4.3+

• Add a mapping for quick in your Application.cfc

• Configure your BaseGrammar in config/ColdBox.cfc

Supported Databases

Example

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

Prior Art, Acknowledgements, and Thanks

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

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

3.1.0

3.0.4

• Compatibility updates for ColdBox 6

3.0.3

3.0.2

3.0.1

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

3.0.0

BREAKING CHANGES

• Drop support for Lucee 4.5 and Adobe ColdFusion 11.

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

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

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

  • For instance, MSSQLGrammar would become MSSQLGrammar@qb.

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

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

Other Changes

• Add error message for defaulting key values.

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

• Ensure loadRelationship doesn't reload existing relationships.

• Split reset into reset and resetToNew methods.

• Store the original attributes for later resetting.

• Use parameterLimits to eager load.

• Use a new entity each time on BaseService.

• Apply sql types for columns to wheres.

• Apply global scopes more consistently

• Correctly ignore key column when updating.

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

• Better handling of constrained relationships when eager loading.

• Convert aliases when qualifying columns.

• Add a better error message if onMissingMethod fails.

• Only retrieve columns for defined attributes.

• Cache entity metadata in CacheBox.

• Use attribute hash for checking isDirty.

2.5.0

2.4.0

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

• Improve error messages for not loaded entities.

• Return the correct memento with accessors on.

2.3.0

2.2.0

2.1.0

• Mapping foreign keys for relationships is now optional

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

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

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

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:

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:

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.

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.

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.

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.

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.

If you have a global scope applied to an entity that you need to temporarily disable, you can disable them individually using 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.

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:

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.

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

Creates a virtual attribute for the given name.

To get started with Quick, you need an entity. You start by extending quick.models.BaseEntity.

That's all that is needed to get started with Quick. There are a few defaults of Quick worth mentioning here.

Tables

We don't need to tell Quick what table name to use for our entity. By default, Quick uses the pluralized name of the component for the table name. That means for our User entity Quick will assume the table name is users. You can override this by specifying a table metadata attribute on the component.

Primary Key

By default, Quick assumes a primary key of id. The name of this key can be configured by setting variables._key in your component.

Quick also assumes a key type that is auto-incrementing. If you would like a different key type, override thekeyType function and return the desired key type from that function.

Quick ships with the following key types:

• AutoIncrementingKeyType

• NullKeyType

• ReturningKeyType

• UUIDKeyType

keyType can be any component that adheres to the keyType interface, so feel free to create your own and distribute them via ForgeBox.

Attributes

You specify what attributes are retrieved by adding properties to your component.

Now, only the id, username, and email attributes will be retrieved.

Persistent

To prevent Quick from mapping a property to a database column add the persistent="false" attribute to the property. This is needed mostly when using dependency injection.

Column

If the column name in your table is not the column name you wish to use in Quick, you can specify the column name using the column metadata attribute. The attribute will be available using the name of the attribute.

Null Values

To work around CFML's lack of null, you can use the nullValue and convertToNull attributes.

nullValue defines the value that is considered null for a attribute. By default it is an empty string. ("")

convertToNull is a flag that, when false, will not try to insert null in to the database. By default this flag is true.

Read Only

The readOnly attribute will prevent setters, updates, and inserts to a attribute when set to true.

SQL Type

In some cases you will need to specify an exact SQL type for your attribute. Any value set for the sqltype attribute will be used when inserting or updating the attribute in the database. It will also be used when you use the attribute in a where constraint.

Casts

The casts attribute allows you to use a value in your CFML code as a certain type while being a different type in the database. A common example of this is a boolean which is usually represented as a BIT in the database.

Two casters ship with Quick: BooleanCast@quick and JsonCast@quick. You can add them using those mappings to any applicable columns.

Custom Casts

The casts attribute must point to a WireBox mapping that resolves to a component that implements the quick.models.Casts.CastsAttribute interface. (The implements keyword is optional.) This component defines how to get a value from the database in to the casted value and how to set a casted value back to the database. Below is an example of the built-in BooleanCast, which comes bundled with Quick.

Casted values are lazily loaded and cached for the lifecycle of the component. Only cast values that have been loaded will have set called on them when persisting to the database.

Casts can be composed of multiple fields as well. Take this Address value object, for example:

This component is not a Quick entity. Instead it represents a combination of fields stored on our User entity:

Noticed that the casted address is neither persistent nor does it have a getter or setter created for it.

The last piece of the puzzle is our AddressCast component that handles casting the value to and from the native database values:

You can see that returning a struct of values from the set function assigns multiple attributes from a single cast.

Insert & Update

You can prevent inserting and updating a property by setting the insert or update attribute to false.

Formula, Computed, or Subselect properties

Multiple datasource support

Comparing Entities

You can compare entities using the isSameAs and isNotSameAs methods. Each method takes another entity and returns true if the two objects represent the same entity.