Hi, Jennifer. I’m sure you will hear differing opinions. More on that in a moment. But I’ll share a few of mine (from more of a troubleshooting perspective) that may perhaps help as you contemplate this feature.
1) The range of opinions
Let me say first that with orm being an abstraction layer, there’s always the chance that people will find it mysterious and make such pronouncements–even contradicting ones, as those in that doc do. (I’ll share in a moment how to better understand what’s really going on, rather than leave things such a mystery.)
It can also lead others to dismiss ORM in general as not worth the effort, while still others will regard it as THE way to go. Witness the site and resources of https://vladmihalcea.com/, who makes a living helping people make the most of orm (aka “persistence”) and hibernate in particular (which underlies most Java orm, as in ACF and Lucee).
The truth and typical experience of using it lies somewhere within that range.
2) The value of monitoring orm
But I can add second that good monitoring of what is really going on “under the covers” in orm can REALLY help you to know first WHAT sql is being generated. A tool like fusionreactor does this best in the context of a cfml web app, as it shows the top slow sql for every request (including those generated by orm), and it can even log those or log every one. But there are free and simplistic tools and logging features that some may consider/recommend instead.
Beyond knowing WHAT sql is being generated, note also that the sql then runs in your database just like any you’d craft by hand. And just as with those, we’d be helped tremendously with some sort of monitoring in the db server, to understand WHY it may be slow. That may lead to improvements in the db or in how the orm feature is configured to generate its sql.
3) Finding more documentation on orm, especially from CFML
And finally that’s another area where some are not aware: while we can “just use” the orm feature rather blindly, there is indeed a lot you can tweak about it, whether in your code, in your application.cfc/cfm, or in the underlying hibernate config.
And that takes us back to deeper discussions of the topic at sites like Vlad’s above, or even the acf docs (the Developing Applications manual rather than the cfml Reference).
You’ll also find more discussion of orm use within cfml in the context of various tools and projects of Ortus Solutions.
As I hinted at in the open, this is a topic like many in Lucee (and CF and IT in general) where “opinions are like noses”. More than that, it’s like discussions of frameworks, where often those writing about them speak more to those who DO already understand the motivation for them–such that they tend to leave that out of their discussions or documentation.
And the Lucee docs fall into that trap sometimes regarding cfml features, with a presumption that readers are coming from acf–such that the focus is on any differences (advantages or gotchas). They tend not to point to what even may be substantial additional documentation on a topic.
4) Improving the Lucee docs
That said, the Lucee team are always open to the docs being improved, whether to correct such a typo or to add more context, or (I assume) to ads links to more on a topic (though some doc folks prefer NOT to link out to such references, whose links may change and break over time).
Hope some of the above may help you. And let’s see what others will offer.