Allow opt-in inclusion of non-default-selected computed SQL properties in find*()

[bpamiri]

Requested by Ben Nadel in discussion #1634. A contributor signalled intent to implement in Jan 2026 but no tracking issue was ever filed — opening one so the idea isn't lost.

The gap

Wheels already supports excluding a computed property from the default SELECT:

property(name="fullName", sql="firstName || ' ' || lastName", select=false);

…honored at vendor/wheels/model/sql.cfc (if (local.classData.calculatedProperties[local.key].select)). But there is currently no per-call way to pull that property back in on a specific finder short of spelling out the entire select clause by hand. include= is association-only (vendor/wheels/model/read.cfc — "Associations that should be included in the query using INNER or LEFT OUTER joins"); there is no sql:/sqlProperties path (grep confirms neither exists).

So a property defined as select=false (to keep it off the hot path) can only be retrieved by manually listing every column you want — which defeats the convenience the property(sql=...) helper otherwise gives you.

Suggested API (from the discussion)

// Ben's suggestion — opt a single computed property into one finder:
model("User").findAll(include="sql:fullName");
// or a dedicated argument:
model("User").findAll(sqlProperties="fullName,ageInYears");

Scope notes

• This is a convenience over the existing select= workaround, not a defect — low priority.
• The complementary half (property(..., select=false)) already exists; this is the inverse, per-call opt-in.
• Old issue Attribute to define whether a calculated property is used by default in a select statement with findAll()  #122 (the select=true/false default flag) is closed/implemented and does not cover this.

[wheels-bot]

Wheels Bot — Triage

Classified as framework-design (API/feature design question).
Cross-framework research will follow shortly — Rails, Laravel, Django,
and other modern frameworks will be consulted before any path forward
is proposed.

<!-- wheels-bot:triage:3252 -->
<!-- wheels-bot:triage-class:framework-design -->

[wheels-bot]

Wheels Bot — Cross-Framework Research

Question

A model can declare a computed SQL property and keep it off the default SELECT with property(name="fullName", sql="firstName || ' ' || lastName", select=false) — honored at vendor/wheels/model/sql.cfc:499. The gap is the inverse: there is no per-finder way to pull that one property back in without hand-listing every other column. Passing select="fullName" works but is replacing, not additive — it drops the base columns and yields a partial record. The issue asks for an opt-in-by-name mechanism (include="sql:fullName" or sqlProperties="fullName").

How other frameworks handle this

Framework	Naming	Surface	Trade-offs	Edge cases
Rails	select / reselect, "SQL-fragment select"	Model.select("expr AS alias") — additive raw fragment; reselect/unscope(:select) to override a scope	Dead simple, no schema; but SQL restated at call site, read-only attr	select("expr AS x") alone drops base cols -> partial record + MissingAttributeError; no declared-once computed column
Laravel	"accessor" + addSelect / selectRaw	addSelect(['*','full_name'=>DB::raw(...)]); PHP accessor + $appends/append() for serialization	Clean compute-vs-expose split; addSelect purpose-built to append	Two unrelated layers (SQL addSelect vs PHP accessor); select() clobbers *, addSelect doesn't
Django	defer() / only(), annotate(), GeneratedField	defer("full_name") excludes; only("full_name") / annotate(full_name=Concat(...)) opts in	defer accumulates, only replaces — asymmetric; GeneratedField declares once	Deferred access = extra query per field (N+1); only() semantics trip people up
Phoenix/Ecto	field …, virtual: true + select_merge	`select_merge: %{full_name: fragment("?		' '
Spring/JPA	@Formula, lazy basic, DTO/dynamic projection	@Formula("…") (always on); <T> find…(…, Class<T>) projection per call	@Formula declarative one-liner; dynamic projection picks shape per call	@Formula can't be per-query toggled; lazy column needs bytecode enhancement; projection != managed entity
Doctrine (+1)	DQL SELECT … AS [HIDDEN] alias, NEW DTO	SELECT u, CONCAT(...) AS fullName opts in; AS HIDDEN for sort-only	Fully explicit per query; HIDDEN separates compute-for-sort vs compute-for-output	No entity-level declaration — expression duplicated everywhere; aliased scalar -> mixed result array

+1 justification: Doctrine is the canonical "computed-as-DQL-SELECT-expression" ORM (deliberately no @Formula), so it stress-tests the exact tension here — derived columns hidden from the hot path but selectively re-includable.

Dominant pattern

Strong convergence on additive, per-query opt-in: Rails addSelect-style fragment, Laravel addSelect, Django only/annotate, Ecto select_merge, Doctrine AS alias, JPA dynamic projection. The universal failure mode they warn about is the replacing select (select(...) clobbers * -> partial record) — which is exactly the trap a bare Wheels select="fullName" falls into today. Where they diverge is the declaration half: Ecto/Doctrine/Rails make you restate the SQL at every call site; Django GeneratedField and Hibernate @Formula declare once. Wheels already has the declare-once half (property(sql=…, select=false)) — so the only missing piece is an additive, by-name opt-in that references the existing declaration. That puts Wheels ergonomically ahead of most of these once the gap is closed.

Recommended path for Wheels

Add a dedicated additive finder argument that takes already-declared calculated-property names and merges them on top of the default selection (never replacing base columns). Name it includeCalculated — it reuses Wheels' existing include verb ("pull more into this finder") without overloading the association-only include argument, and calculated matches the framework-internal calculatedProperties term. This avoids the author's include="sql:fullName" overload (which would muddy association vs. SQL semantics in one arg).

// Declare once — kept off the default SELECT (existing behavior, unchanged)
property(name="fullName", sql="firstName || ' ' || lastName", select=false);

// Opt it back into a single finder — ADDITIVE: all default columns still selected
model("User").findAll(includeCalculated="fullName");
model("User").findOne(where="id = ##params.key##", includeCalculated="fullName,ageInYears");

// Composes with scopes, association include, and pagination
model("User").active().findAll(
    include="role",                 // associations (unchanged)
    includeCalculated="fullName",   // declared-once SQL property, opted in
    page=params.page, perPage=25
);

Lives in: vendor/wheels/model/read.cfc (new optional string includeCalculated="" on findAll / findOne / findByKey, threaded into the finder-args struct) and vendor/wheels/model/sql.cfc (consumed in $selectClause — see the !Len(arguments.list) default-build branch at lines 491-505 and the calculated-property handling at 616-623).

Implementation shape (pure list manipulation — no closures, no struct member fns):

• In $selectClause, after the default property list is assembled, append each includeCalculated name (even when its .select flag is false). When the caller also passed an explicit select, append to that list instead so it stays additive.
• Validate each name against local.classData.calculatedProperties; throw Wheels.CalculatedPropertyNotFound in development/testing for unknown names (a no-op in production), mirroring the existing dev-only validation pattern (e.g. paginationNav's Wheels.PaginationNav.InvalidArgument).

Composes with: query scopes, the chainable query builder (select/get), the association include path, and pagination — all of which already flow through $selectClause.

Cross-engine notes

None. The change is string/list manipulation inside $selectClause — no closures, no struct.map(), no obj["key"](), no application-scope members, no array-by-value reliance. The calculated-property SQL itself is author-supplied and already runs across all engines today (the select=false declaration path is unchanged). The only author-side caveat is the usual one: the sql= expression must use DB-portable syntax (e.g. prefer CONCAT/|| per the app's target DBs) — but that predates and is orthogonal to this feature.

Open questions

• Argument name. includeCalculated (recommended) vs. the author's sqlProperties vs. selectCalculated. Worth a maintainer call — should it also accept an alias for discoverability?
• Unknown-name behavior. Throw in dev / no-op in prod (recommended, matches existing patterns), or silently ignore everywhere?
• select=true props. Should includeCalculated be a strict no-op when naming a property that's already in the default select, or an error? (Recommend: no-op, dedup is already handled in $selectClause.)

Confidence: high

The dominant pattern (additive per-query opt-in) is unambiguous across all six frameworks, Wheels already owns the declare-once half, and the CFML sketch threads one optional named argument through the existing $selectClause builder with no new infrastructure, no anti-patterns, and no cross-engine traps.

Sources

• https://guides.rubyonrails.org/active_record_querying.html
• https://api.rubyonrails.org/classes/ActiveRecord/QueryMethods.html
• https://laravel.com/docs/11.x/eloquent-mutators
• https://laravel.com/docs/11.x/queries
• https://docs.djangoproject.com/en/5.2/ref/models/querysets/
• https://docs.djangoproject.com/en/5.2/ref/models/fields/
• https://ecto.hexdocs.pm/Ecto.Query.html
• https://ecto.hexdocs.pm/Ecto.Schema.html
• https://docs.spring.io/spring-data/jpa/reference/repositories/projections.html
• https://docs.hibernate.org/stable/orm/javadocs/org/hibernate/annotations/Formula.html
• https://www.doctrine-project.org/projects/doctrine-orm/en/3.6/reference/dql-doctrine-query-language.html

[wheels-bot]

Wheels Bot — Fix proposed

Draft PR: #3254

Spec: vendor/wheels/tests/specs/model/includeCalculatedSpec.cfc — failing → passing (5 passed / 0 failed / 0 errors)
Implementation: vendor/wheels/model/sql.cfc, vendor/wheels/model/read.cfc

The fix follows the cross-framework research recommendation verbatim: a new additive, by-name finder argument includeCalculated that opts an already-declared select=false calculated SQL property back into a single finder without replacing the default column list.

A human review is required before merge. The Reviewer will weigh in shortly. Doc updates (MDX guides, .ai/wheels/, CLAUDE.md) are handled separately by bot-update-docs.yml.