Skip to content

Commit ba2ae64

Browse files
committed
feat(cube-model): a @spine report as a Cube view (FR-044)
A served report with @spine is a Cube view, model/views/<Report>.yml, with no rollup and no scope segment (a rollup on the spine cube is built from the fact cube and loses the zero rows). Its first join_path is the spine cube (the cube every listed dimension reaches after the spine's hops), including the member each dimension reads under the dimension's name, with the dimension's title, description and grains; its last is <Report>Facts with the listed measures. <Report>Facts is a standalone public: false cube (no `extends`, which would copy the fact cube's rollups): `SELECT * FROM <@from table> <alias>` with the report's @segment and @filter, ANDed, as its WHERE, so the scope stays inside the join and a spine row whose facts are all filtered out keeps its row. It holds @from's key and @from's own definitions of the listed measures, ratio operands and <m>Raw members. The spine cube gets one one_to_many join onto it; no reverse join is added to an ordinary cube, so ad-hoc answers are unchanged. A multi-hop spine is built with standalone chain cubes <Report>_<hop>, one per entity between @from and the spine entity. Executed on Cube 1.7.43 before building: a view includes a private key and a public: false member under an alias, include-level docs and meta reach /v1/meta, the roster view returns every program (weeks 0, sums null, defaults 0), the scoped facts cube keeps the programs whose weeks are all short, a two-hop chain equals the view lowering's SQL, and {Week.weeks, Program.id} stays rooted at Week. The guard is deleted: cube-pending.ts, ERR_CUBE_UNMAPPED_VOCABULARY and the error-unmapped-vocabulary case. renderCubeViewYaml and the view types are exported; the generator writes a view when every cube it reads is written and cleans up model/views/*.yml. Corpus cases report-spine and report-spine-multi-hop (hand-written goldens); the canonical golden gains the two facts cubes and views. The cube lane compares ProgramRoster and ProgramLongWeeks through their views (7 rows each), FitnessTotalsFilled through its rollup, and reads a defaulted operand's COALESCE inside a ratio from /v1/sql. Docs, spec section 5, roadmap and skills say both attributes are mapped.
1 parent adc8971 commit ba2ae64

58 files changed

Lines changed: 2320 additions & 408 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎CHANGELOG.md‎

Lines changed: 13 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,11 @@ it until 1.1 ships._
2424
reference between cubes, dimensions (a time dimension carries its `@grains` as
2525
`meta.grains`), measures, segments, and a `rollup` pre-aggregation for each served report. A
2626
report with a relative date (in its `@filter`, its `@segment` or a listed measure's condition)
27-
gets no rollup, and a `<report>Scope` segment when it has a `@filter`. It is opt-in
27+
gets no rollup, and a `<report>Scope` segment when it has a `@filter`. A served report that
28+
declares `@spine` is a Cube view, `model/views/<Report>.yml`, rooted at the spine cube over a
29+
`public: false` `<Report>Facts` cube whose own `sql` holds the report's scope (so a spine row
30+
whose facts are all filtered out keeps its row), with no rollup; the ordinary cubes gain no
31+
reverse join. It is opt-in
2832
(`meta init` wires nothing), listed by `meta gen --list` in the `capability` layer, ejectable
2933
(`meta eject cube-model`) and drift-checked by `meta verify --codegen`. It writes Postgres
3034
and MySQL SQL and refuses `sqlite` and `d1`. What Cube cannot hold is an `ERR_CUBE_*`
@@ -33,19 +37,19 @@ it until 1.1 ships._
3337
view lowering and the exporter now share one SQL module, moved without changing a byte of
3438
any view. A measure's `@default` is a `public: false` `<m>Raw` aggregate and the measure as
3539
`COALESCE({<m>Raw}, n)` (a ratio's default wraps its quotient, and an operand's own default
36-
reaches the ratio), so Cube reads the default where the view does. A served report's `@spine`
37-
is not mapped yet: it is refused with `ERR_CUBE_UNMAPPED_VOCABULARY` rather than written
38-
without the spine's rows. A MySQL tuple distinct count is the view's own
39-
`COUNT(DISTINCT a, b)`. Gated by the new `fixtures/cube-model/` corpus (43 cases and a
40-
canonical golden; the 29th shared corpus in `docs/CONFORMANCE.md`, run by TypeScript only).
40+
reaches the ratio), so Cube reads the default where the view does. A MySQL tuple distinct
41+
count is the view's own `COUNT(DISTINCT a, b)`. Gated by the new `fixtures/cube-model/` corpus
42+
(44 cases and a canonical golden; the 29th shared corpus in `docs/CONFORMANCE.md`, run by
43+
TypeScript only).
4144
See [docs/features/cube-export.md](docs/features/cube-export.md).
4245
- **A `cube` lane checks the exporter against a real Cube.** `scripts/ci-local.sh --only cube`
4346
(also `scripts/integration-test.sh cube`, `bun run test:cube` in `integration-tests`, and a
4447
`cube` entry in `integration-tests.yml`) loads the canonical model's output into
4548
`cubejs/cube:v1.7.43` over a private `postgres:16-alpine`, requires the Cube query for each
46-
served report to return the rows of its view, requires each of the 32 corpus cases that hold
47-
a tree to compile (the two MySQL ones included), and reads the escaping case's literals back
48-
from Cube's `/v1/sql`. It owns a private Docker network and an ephemeral `127.0.0.1` port and
49+
served report to return the rows of its view (a `@spine` report through its Cube view, its
50+
empty spine rows included), requires each of the 34 corpus cases that hold a tree to compile
51+
(the two MySQL ones included), and reads the escaping case's literals and a ratio over a
52+
defaulted operand back from Cube's `/v1/sql`. It owns a private Docker network and an ephemeral `127.0.0.1` port and
4953
never uses the shared Postgres sidecar. Without Docker it is a SKIP behind a banner (a failure
5054
under `--strict-toolchains`). The full `scripts/ci-local.sh` runs it; `--quick` and
5155
`--no-integration` do not.

‎agent-context/skills/metaobjects-authoring/references/reporting.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -165,7 +165,9 @@ letter first, then letters, digits and `_`, and not a Python keyword such as `fr
165165
otherwise the export fails with `ERR_CUBE_INVALID_NAME` and renames nothing. It also refuses a
166166
dimension over an array, object or map field. A report with a relative date in its `@filter`,
167167
its `@segment`'s filter or a listed measure's condition gets no rollup. Its `<report>Scope`
168-
segment is written only when it has a `@filter`. A report that is not served contributes nothing. Reference: `docs/features/cube-export.md`.
168+
segment is written only when it has a `@filter`. A served report with `@spine` becomes a Cube view
169+
with its scope inside a facts cube and no rollup, so the spine's empty rows survive, and a measure's
170+
`@default` is a `COALESCE`, as in the view. A report that is not served contributes nothing. Reference: `docs/features/cube-export.md`.
169171

170172
## What a report does not have
171173

‎agent-context/skills/metaobjects-codegen/references/typescript.md‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -202,8 +202,11 @@ target (`targets: { cube: { outDir: "cube" } }`, `cubeModel({ target: "cube" })`
202202
`dialect` (`"postgres"` or `"mysql"`, default the config's; `sqlite` and `d1` raise
203203
`ERR_CUBE_UNSUPPORTED_DIALECT`), `filter` and `target`. What Cube cannot take is an `ERR_CUBE_*`
204204
error naming the node (an array or object dimension, a name that is a Python keyword, two members
205-
of one name); the exporter never renames or drops. `@spine` and `@default` are not mapped. The
206-
mapping, wiring and the `cube` lane that checks it against a real Cube are in
205+
of one name); the exporter never renames or drops. A measure's `@default` is a `COALESCE` over it
206+
(a `measure.aggregate` keeps its aggregate as a `public: false` `<m>Raw` member), and a served
207+
report with `@spine` is a Cube view, `model/views/<Report>.yml`, rooted at the spine cube over a
208+
`public: false` `<Report>Facts` cube that holds the report's scope, with no rollup. The mapping,
209+
wiring and the `cube` lane that checks it against a real Cube are in
207210
`docs/features/cube-export.md`.
208211

209212
The `CREATE VIEW` DDL is generated by `meta migrate`

‎docs/CONFORMANCE.md‎

Lines changed: 11 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,7 @@ regenerate with `ls -d fixtures/<corpus>/*/ | wc -l` for directory-shaped corpor
5454
| [`fixtures/requirement-test-identity-conformance/`](../fixtures/requirement-test-identity-conformance/) (the identity, skip state and digest of each generated requirement test, and the filter seam, ADR-0057) | 26 cases | ✓ (reference) | ✓ | identity function inherits via Java; emitted names asserted by its own generator test | ✓ | ✓ |
5555
| [`fixtures/naming-conformance/`](../fixtures/naming-conformance/) | 8 cases | ✓ | ✓ | inherits via Java (`RouteNaming.pluralize`) | ✓ | ✓ |
5656
| [`fixtures/codegen-noop/`](../fixtures/codegen-noop/) (FR-044 — reporting vocabulary: what is lowered, what stays inert) | 1 model pair (`reporting/with` vs `reporting/without`) | ✓ (codegen + migrate) | ✓ | ✓ | ✓ | ✓ |
57-
| [`fixtures/cube-model/`](../fixtures/cube-model/) (FR-044 Plan 4 — the `cube-model` generator's golden Cube files, plus the canonical model's golden) | 43 cases (32 trees + 11 errors) + 1 canonical golden | ✓ (the exporter is TypeScript-only, spec R6; its `cube` lane also loads the files into a real Cube) | — | — | — | — |
57+
| [`fixtures/cube-model/`](../fixtures/cube-model/) (FR-044 Plan 4 — the `cube-model` generator's golden Cube files, plus the canonical model's golden) | 44 cases (34 trees + 10 errors) + 1 canonical golden | ✓ (the exporter is TypeScript-only, spec R6; its `cube` lane also loads the files into a real Cube) | — | — | — | — |
5858

5959
A ✓ means the port runs the corpus green; an explicit `n / m` is used where a port
6060
carries a ledgered divergence. The two ledgered YAML fixtures are documented
@@ -127,17 +127,18 @@ manifest contains without moving these boundaries.
127127

128128
**The Cube exporter** ([features/cube-export.md](features/cube-export.md)):
129129

130-
- *Mapping — gated in TypeScript only, by decision.* `fixtures/cube-model/` holds 43 cases, 32
131-
with the exact tree the generator writes and 11 with the exact error message, plus the
130+
- *Mapping — gated in TypeScript only, by decision.* `fixtures/cube-model/` holds 44 cases, 34
131+
with the exact tree the generator writes and 10 with the exact error message, plus the
132132
canonical model's golden. `codegen-ts/test/cube/cube-model-corpus.test.ts` and
133133
`cube-model-canonical.test.ts` run them. No other port has an exporter (spec R6), so no other
134134
port makes a claim the corpus would have to check.
135135
- *Cube accepts the output — queried on Postgres, compiled in both dialects.* The `cube` lane
136-
(`scripts/ci-local.sh --only cube`, which needs Docker) loads the canonical golden and the 31
136+
(`scripts/ci-local.sh --only cube`, which needs Docker) loads the canonical golden and the 34
137137
cases that hold a tree into a pinned Cube (`cubejs/cube:v1.7.43`) and requires each to
138138
compile, the two MySQL cases included: compiling a model runs no SQL, so the lane's Postgres
139-
data source serves them too. For the six canonical reports it compares the Cube query with the
140-
report view, and for the `escaping` case it reads each literal back from Cube's `/v1/sql`. No
139+
data source serves them too. For the nine canonical reports it compares the Cube query with the
140+
report view (a `@spine` report through its Cube view, its empty spine rows included), and for
141+
the `escaping` and `measure-default` cases it reads the SQL back from Cube's `/v1/sql`. No
141142
SQL of a MySQL case is executed; the goldens hold it. The lane runs Cube in development mode,
142143
so Cube's production mode with a separate Cube Store is not gated.
143144
- *The lane is a gate, not a second corpus.* Like the codegen-compile gate, it reuses
@@ -480,11 +481,12 @@ outside ASCII. The case list is in the
480481
Kotlin's identity function is the Java one; the names its generator emits are asserted by
481482
`server/java/codegen-kotlin/src/test/kotlin/com/metaobjects/generator/kotlin/KotlinRequirementTestsGeneratorTest.kt`.
482483

483-
### `fixtures/cube-model/` (43 cases)
484+
### `fixtures/cube-model/` (44 cases)
484485

485-
All 43 cases and the canonical golden → [features/cube-export.md](features/cube-export.md).
486+
All 44 cases and the canonical golden → [features/cube-export.md](features/cube-export.md).
486487
Each case is the smallest model for one mapping rule (an entity's cube, a join, an alias cube, a
487-
dimension type, a measure, a segment, a relative date, a rollup, the escaping rules) or for one
488+
dimension type, a measure, a measure's `@default`, a segment, a relative date, a rollup, a
489+
`@spine` report's Cube view, the escaping rules) or for one
488490
`ERR_CUBE_*` refusal, and holds exactly one of an expected file tree and an expected error
489491
message. The case list, with the rule each pins, is the
490492
[corpus README](../fixtures/cube-model/README.md).

0 commit comments

Comments
 (0)