Caching

Module 15 was about not doing the wrong thing. Module 16 starts with doing the right thing faster: the cheapest performance win in any application is skipping work you've already done once. ColdFusion gives you three different layers to do that at, query results, arbitrary objects, and whole rendered pages, and each one fits a different situation.

Learning Objectives

After completing this lesson, you'll be able to:

• Cache a query's results with cachedwithin and cachedafter.
• Cache an arbitrary value with cachePut(), cacheGet(), and cacheRemove().
• Cache a whole page or page fragment with cfcache.
• Use cacheRegionNew(), cacheIdExists(), cacheRemoveAll(), and cacheGetAllIds() to manage cache regions beyond basic put/get.
• Know that ORM has its own separate caching layer, distinct from cfcache and cachePut().
• Know a real naming difference between Adobe ColdFusion and Lucee for the same caching feature.

How Caching Fits Together

Four Layers of Caching

Query Caching

cachedwithin and cachedafter both reuse a previous result instead of re-running the query, they just measure differently. A cached result is only reused if the SQL statement, datasource, query name, and credentials all match exactly, change any of those and it's a fresh query.

<cfquery name="news" datasource="myDSN" cachedwithin="#createTimeSpan(0, 1, 0, 0)#">
    SELECT id, title FROM news
</cfquery>

Object Caching

cachePut()/cacheGet()/cacheRemove() cache anything, not just query results, a struct, an expensive computed value, a parsed API response.

// store, with a 30-minute expiry
cachePut("homepage_stats", statsStruct, createTimeSpan(0, 0, 30, 0));

// retrieve, checking for a miss
cachedStats = cacheGet("homepage_stats");
if (isNull(cachedStats)) {
    cachedStats = buildStatsStruct();
    cachePut("homepage_stats", cachedStats, createTimeSpan(0, 0, 30, 0));
}

// remove early, e.g. after the underlying data changes
cacheRemove("homepage_stats");

More Cache Functions Worth Knowing

cachePut()/cacheGet()/cacheRemove() cover the common case, but the full cache-functions reference has more, including the one that actually creates a named region in the first place.

ORM Has Its Own Separate Caching Layer

If an application loads data through ColdFusion's ORM (covered back in Module 8), that's a fourth caching layer entirely, separate from cfcache and cachePut(). ORM caching works at two levels: a session-level cache that holds entities only for the current ORM session (EntityReload() forces a fresh database hit), and a secondary-level cache that persists across sessions, the one actually worth configuring deliberately.

// cache this query's results at the secondary level
availableArts = ORMExecuteQuery(
    "from CArt where issold = 0",
    {},
    false,
    { cacheable: true, cachename: "availableArtsQuery" }
);

// evict explicitly once the underlying data changes
ORMEvictEntity("CArt");
ORMEvictQueries("availableArtsQuery");

A Real Detail: Same Feature, Different Parameter Name

Both engines support named cache regions, separate pools so unrelated cached data doesn't collide or get flushed together, but the parameter is named differently. Adobe ColdFusion's cachePut() calls it region, Lucee's calls the equivalent parameter cacheName (with region accepted as an alias). Writing cross-engine code that uses named regions is one more place worth double-checking against the target engine's own docs.

Page-Level Caching with cfcache

cfcache caches rendered output instead of data, an entire page, or just the content between its tags.

<cfcache action="cache" timespan="#createTimeSpan(1, 0, 0, 0)#" idletime="#createTimeSpan(0, 12, 0, 0)#">
    <div id="daily-deals"><!--- expensive content to render --></div>
</cfcache>

Common Beginner Mistakes

Best Practices

• Match the caching layer to the problem: query results with cachedwithin, arbitrary values with cachePut(), whole rendered output with cfcache.
• Always check isNull() on a cacheGet() result before using it.
• Use named cache regions to keep unrelated cached data from being flushed together, checking the correct parameter name (region vs cacheName) for the target engine.
• Call cacheRemove() explicitly when the underlying data changes, rather than waiting out a long timespan.

Interview Questions

Summary

In this lesson, you cached a query's result with cachedwithin/cachedafter, cached an arbitrary value with cachePut()/cacheGet()/cacheRemove(), managed cache regions with cacheRegionNew()/cacheIdExists()/cacheRemoveAll(), cached rendered page output with cfcache, saw that ORM has its own separate caching layer entirely, and saw a real naming difference between Adobe ColdFusion and Lucee for named cache regions.

What's Next?

The next lesson covers broader performance tips: where else to look once caching alone isn't enough.