Secondary Level Caching in ColdFusion ORM

I've been doing some performance improvements to a site by making use of the ORM Secondary Level Caching that is built into ColdFusion 9. Interacting with databases is a common bottleneck in applications so you want to reduce the amount of queries you need to run. ColdFusion has had the ability to cache queries for a long time by simply adding the cachedWithin attribute to cfquery. When you're using ORM, then there are similar in-built caching capabilites.

Firstly you need to enable the secondary level cache in your Application.cfc

this.ormSettings.secondaryCacheEnabled = true;

Once you've done that they you need to add the cacheuse attribute to the persistent CFCs (your entities) that you want to be cached. There are several values you could use, but the one I'm using is transactional.

component persistent="true" table="contents" cacheuse="transactional" cachename="content"
{
  property name="id" column="content_id" generator="native";
}

The cachename attribute is optional, by default it will use the name of your entity.

Now when you use EntityLoadByPk to load a Content entity, then ColdFusion will automatically look in the cache first. If it finds it, it will use it, if it doesn't then it will query the database. As I've set the cacheuse value to "transactional" in my CFC, when I update (and persist) the entity, then the cache is updated for you so you don't need to worry about stale entries in the cache.

One of the great things about the ORM caching is the fine grained control is gives. One of the worst things about the ORM caching is the fine grained control is gives you! What do I mean? Well, consider the following:

a = EntityLoadByPK( "Content", 1 );
b = EntityLoad( "Content", 1, true );
c = EntityLoad( "Content", {id=1}, true );
d = EntityLoad( "Content", {id=1} ); // returns an array
e = ORMExecuteQuery( "from Content where id = :id", {id=1}, true );
f = ORMExecuteQuery( "from Content where id = :id", {id=1} ); // returns an array

They all get the content entity with an id of 1, but which ones would you expect to be pulled from the cache? The answer is that ORMExecuteQuery will not use the cache. This is not surprising as you could be using custom HQL but it does mean we have to do some extra work if we want to cache results from HQL:

e = ORMExecuteQuery( 
    "from Content where id = :id", 
    {id=1}, 
    true,
    {cacheable=true, cachename='content', timeout=60}
);

The above will cache the result with a key name of "content" for 60 seconds. If you update the entity within those 60 seconds, then you won't get the updated entity. This is similar to how it works with cached queries, but you need to be aware of it.

If you prefer to write your HQL in cfquery blocks (ColdFusion 9.0.1) then you'll need to use the new ormoptions attribute:

<cfset options = {cacheable=true, cachename='content', timeout=60}>
<cfquery name="q" dbtype="hql" ormoptions="#options#">
    from Content where id = <cfqueryparam value="1">
</cfquery>

<cfset e = q[1]>