[zantvoort]

Summary

A query may name a column that the entity record does not hold: a stored generated column such as a folded title, or a trigger-filled column that serves a search or a sort. Entities now declare such a column with @QueryColumn, which gives the metamodel a field for it while keeping it out of every SELECT, INSERT and row mapping.

@QueryColumn(field = "titleFolded", type = String.class)
public record Movie(@PK Integer id, String title) implements Entity<Integer> {}

movies.select().where(Movie_.titleFolded, LIKE, folded + "%").getResultList();

• @QueryColumn (repeatable, field, type, optional column, nullable) in storm-foundation.
• Model.queryColumns() lists them apart from columns(); a query column has index 0 and never reaches the row mapper.
• The APT and KSP metamodel processors emit a field per declaration, with the same component type as a regular field, so Owner_.lastNameFolded works in search, where, orderBy and keyset sorting (nullable feeds the sort check).
• A record holds no value for a query column; reading it through the metamodel throws with a message that says so.
• Schema validation checks the column exists with the declared type and nullability, as for a field. For an insert a query column is a column the entity does not map, so a NOT NULL query column the database does not fill (not generated, no identity, no default) falls under the existing UNMAPPED_COLUMN warning rather than a kind of its own. Unmapped generated columns no longer trigger UNMAPPED_COLUMN.
• DatabaseSchema reads IS_GENERATEDCOLUMN defensively since not every driver reports it.
• Sealed hierarchies ignore the annotation.

Docs: the entities page gains a Query Columns section, the validation table lists the new error, the metamodel page mentions the generated field, and the search page describes the stored folded column as the optional step for a search the expression index leaves slow, folding the input in the database so the recheck stays gone. Skills (entity, entity-from-schema, validate, query, Java and Kotlin) carry the same guidance.

Dependency gate

The dependency-check job has not completed since #740 merged: the NVD API throttles GitHub-hosted runners to a page every few minutes, the first pull needs the whole feed, and the job ran into its 40-minute timeout on every run (shown as cancelled) while the Maven cache, already saved by the build job, kept none of the data. The gate now writes a CycloneDX bill of materials of compile and runtime scope with cyclonedx-maven-plugin and scans it with Trivy, failing on High or Critical. Trivy carries its own advisory database, so there is no key, the scan also runs on Dependabot pull requests, and it finishes in seconds after the build. The NVD_API_KEY secret is no longer read.

The first scan found two High advisories in the shipped graph: storm-ktor-test carries httpcore5 5.3.6 through ktor-server-test-host and the Apache HTTP client (CVE-2026-54399, CVE-2026-54428). The module now declares httpcore5 and httpcore5-h2 5.4.4 directly, so the fixed line also wins in an application's test classpath, where a managed version would not reach. The storm-ktor-test suite passes on 5.4.4 and the BOM scans clean.

Test plan

• storm-core suite (3104 tests) incl. new QueryColumnIntegrationTest, SchemaValidatorTest and DatabaseSchemaTest cases
• APT and KSP processor tests render the generated field
• storm-java21 and storm-kotlin QueryBuilderTest, each with a query column test over its own test model
• Diff coverage checked with JaCoCo locally; the lines left are the declaration guards for an empty or duplicate field name, which the annotation processors refuse at compile time, so a processed record cannot reach them
• Schema validator conformance test for a generated column on H2, PostgreSQL, MySQL, MariaDB, SQLite, Oracle and SQL Server via Testcontainers
• spotless clean on every touched module
• CycloneDX BOM built locally, Trivy reports 2 Highs on the current graph and 0 after the httpcore5 pin; storm-ktor-test suite green on 5.4.4

Fixes #743

[codecov]

Codecov Report

❌ Patch coverage is 87.57764% with 20 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...va/st/orm/core/template/impl/MetamodelFactory.java	77.58%	8 Missing and 5 partials ⚠️
...n/java/st/orm/core/template/impl/ModelFactory.java	86.95%	3 Missing and 3 partials ⚠️
...ava/st/orm/core/template/impl/SchemaValidator.java	96.15%	0 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!