Skip to content

Commit 6ff759e

Browse files
committed
fix(cube-model): spine review fixes (FR-044)
- A TPH subtype as the spine entity is exported through its own discriminator-scoped cube, so the view's rows are that subtype's only; pinned by a unit test and documented beside the TPH @from note (the view lowering refuses both reports). - Two listed dimensions over one field and path include one member twice under two aliases. Added to the report-spine corpus case (golden edited by hand); the cube lane's compile pass shows Cube 1.7.43 accepts it. - One exported JOIN_PATH_SEPARATOR, used by the build, both generator copies and the live lane. - One definition of the report scope and of the MySQL tuple count: reportScope and mysqlTupleCount in projection/report-sql.ts, called by the view lowering (extract-report-spec, report-ddl-emit) and the exporter (cube-members, cube-reports, build-cube-model). View SQL, the canonical schema, the report shapes and the projection goldens are unchanged. - ERR_CUBE_NAME_COLLISION says "cube or view" when one side is a view. - A facts or chain cube carries no title or description of its entity.
1 parent ba2ae64 commit 6ff759e

19 files changed

Lines changed: 233 additions & 73 deletions

File tree

‎docs/features/cube-export.md‎

Lines changed: 12 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -429,8 +429,18 @@ answer of the ordinary cubes is unchanged: on 1.7.43, `{ "measures": ["Week.week
429429
facts cubes in place. The measure definitions are copied into the facts cube, which is the cost of
430430
keeping the ordinary cubes as they are.
431431

432+
A TPH subtype is exported in either place. As the spine entity, its own cube, whose `sql` is the
433+
base table scoped by the subtype's discriminator, is the spine cube, so the view's rows are that
434+
subtype's rows only. As `@from`, the facts cube's `sql` puts the discriminator before the report's
435+
scope. Both are correct by construction, and the report view lowering refuses both reports (a TPH
436+
subtype has no table of its own), so there is no view to compare them with.
437+
438+
A facts or chain cube is private plumbing: it carries no `title` or `description`, while the view
439+
carries the report's.
440+
432441
Executed on Cube 1.7.43 before this was built, and checked by the `cube` lane since: a view
433-
includes a private primary key and a `public: false` member under an alias; the include-level
442+
includes a private primary key and a `public: false` member under an alias, and one member twice
443+
under two aliases (two dimensions over one field and path); the include-level
434444
`title`, `description` and `meta` reach `/v1/meta`; the roster view returns every program, with
435445
`weeks` `0`, its plain sum null and its defaulted measures `0` for the programs with no weeks; the
436446
scoped facts cube keeps the programs whose weeks are all short; and a two-hop chain returns the
@@ -440,7 +450,7 @@ view lowering's rows. A view is answered from the tables.
440450

441451
| Rule | Behaviour |
442452
|---|---|
443-
| cube name | the entity's name. Two entities of one name in two packages, or an alias, facts or chain cube or a `@spine` report's view named like a cube, is `ERR_CUBE_NAME_COLLISION`, naming both: Cube's cubes and views share one namespace. Rename one, or narrow the generator's `filter` to leave one out; the filter helps only when no `@via` reaches the entity it leaves out, since an entity a `@via` reaches is still written as a join-target cube, unless every hop onto it goes through an alias cube. |
453+
| cube name | the entity's name. Two entities of one name in two packages, or an alias, facts or chain cube or a `@spine` report's view named like a cube, is `ERR_CUBE_NAME_COLLISION`, naming both (the message says "cube or view" when one is a view): Cube's cubes and views share one namespace. Rename one, or narrow the generator's `filter` to leave one out; the filter helps only when no `@via` reaches the entity it leaves out, since an entity a `@via` reaches is still written as a join-target cube, unless every hop onto it goes through an alias cube. |
444454
| member name | the dimension, measure or segment name as written, so a report field and its Cube member share a name |
445455
| a name Cube refuses | Cube names start with a letter, hold only letters, digits and `_`, and are not a Python keyword (`from`, `class`, `in`, `is`, `not`, `and`, `or`, `if`, `else`, `for`, `while`, `with`, `as`, `def`, `return`, `yield`, `import`, `pass`, `global`, `nonlocal`, `lambda`, `del`, `assert`, `break`, `continue`, `try`, `except`, `finally`, `raise`, `async`, `await`, `True`, `False`, `None`, `elif`). That is `ERR_CUBE_INVALID_NAME`, naming the node. The exporter never renames: the name is the report field's. |
446456
| members the exporter adds | primary-key dimensions, reached-column dimensions, the `<m>Raw` measure of a defaulted measure, `<report>Scope` segments, rollups. A name that collides with another member of the cube is `ERR_CUBE_MEMBER_COLLISION`, naming both. The one exception is a declared dimension over a key field under its own name, which is that key dimension (see [Cubes and primary keys](#cubes-and-primary-keys)). |

‎docs/superpowers/plans/2026-10-09-fr-044-plan-4-cube-exporter.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -655,7 +655,7 @@ What execution changed or added, beyond the answers above. The contract tables a
655655
- **P. A dimension over a key field, under its own name (Table G, members the exporter adds).** A declared dimension without `@via` named after a key field and reading that field would collide with the key dimension the exporter adds. It is merged instead: one dimension, `primary_key: true` and `public: true`, carrying the declared dimension's `title`, `description` and `meta.grains`. A same-named dimension over another field, or with a `@via`, stays `ERR_CUBE_MEMBER_COLLISION`. Corpus case `dimension-over-key`.
656656
- **Q. `@default` (Task 9), as the task's table says.** #415's Table A (an integer `@default` on `measure.aggregate` and `measure.ratio`) and Table E (what an empty measure reads) agree with the task's table, so nothing in it changed. A defaulted `measure.aggregate` is `<m>Raw`, the Table D aggregate with its `filters`, `public: false`, then `<m>`, `type: number`, `COALESCE({<m>Raw}, n)`, carrying the measure's `title` and `description`; `<m>Raw` sits just before `<m>` and is an added member (`ERR_CUBE_MEMBER_COLLISION`). A defaulted ratio wraps its quotient (Postgres with the cast, MySQL without). An operand's own default reaches the ratio through its member reference; a unit test expands the Cube members of a ratio over a defaulted operand and requires the view's own SQL for it, character for character. A rollup lists `<m>`. The codegen-noop `with/` model now exports (its defaulted ratio is a measure of `WorkoutEvent`), and its cube-model row is pinned by hand. Corpus case `measure-default`.
657657
- **R. Review fixes before the gate.** A MySQL tuple distinct count is the view's own `COUNT(DISTINCT a, b)` as a `number` measure: a `count_distinct` over `JSON_ARRAY(a, b)` compares JSON bytes, and on mysql:8.4 (default `utf8mb4_0900_ai_ci`) it counted 6 tuples where the view counts 4 (case and accent variants; integer tuples agreed). SQL and free text share one Jinja-opener rule (`{{`, `{%`, `{#`), so a `{{x}}` literal is raw-wrapped too, and `endraw` is refused only in text that is wrapped. `ERR_CUBE_AMBIGUOUS_PATH` says when more routes exist than the eight it lists.
658-
- **S. `@spine` (Task 10), as a Cube view over a standalone facts cube.** The task's `<Report>Facts` that `extends` the fact cube would copy its rollups (item A), so the facts cube is standalone: `public: false`, `sql: 'SELECT * FROM <@from table> <alias>'` with the report's `@segment` filter and `@filter`, ANDed, as its `WHERE` (the alias is the view's own base alias, so it reads as the view's join condition; a TPH subtype's discriminator goes first), `@from`'s key, and `@from`'s definitions of the listed measures, a listed ratio's operands and a defaulted measure's `<m>Raw`, in `@from`'s order, unlisted ones `public: false`. It holds no foreign-key dimension: Cube's join reads the column (`{<Report>Facts}."programId"`), as every join does. The spine cube (the cube every listed dimension reaches after the spine's hops: the spine entity's own, its join-target cube, or the last hop's alias cube) gets one `one_to_many` join onto it, on the spine hop's columns, with the foreign key on whichever side the hop's reference puts it. No join is added to `@from`'s own cube or to any entity between, so the ordinary cubes' ad-hoc answers are unchanged (executed: `{ Week.weeks, Program.id }` stays rooted at `Week`). The view `model/views/<Report>.yml` shares the cube namespace (`ERR_CUBE_NAME_COLLISION`); its first `join_path` is the spine cube with the member each listed dimension reads under the dimension's name, the dimension's `title`, `description` and `meta.grains` on the include; a dimension past the spine is included from the cube its own joins end on; the last `join_path` is the facts cube with the listed measures. **A multi-hop spine is built, not refused:** each entity between `@from` and the spine entity gets a standalone `public: false` chain cube `<Report>_<hop>` (its table, key and one `one_to_many` join onward), because the chain is the same reverse join repeated and Cube walks a view's `join_path` through it exactly (executed on 1.7.43 by hand with a sessions table: the rows equal the view lowering's two-hop SQL); corpus case `report-spine-multi-hop` is compile-checked by the lane. Executed on 1.7.43 before building: a view includes a private key and a `public: false` member under an alias, include-level `title`, `description` and `meta` reach `/v1/meta`, and the roster and scoped views return every spine row. Every member of a `public: false` cube is private in `/v1/meta`, which the lane's member check now expects. The generator writes a view when every cube its join paths name is written, and its orphan cleanup owns `model/views/*.yml` as well. The guard module is deleted.
658+
- **S. `@spine` (Task 10), as a Cube view over a standalone facts cube.** The task's `<Report>Facts` that `extends` the fact cube would copy its rollups (item A), so the facts cube is standalone: `public: false`, `sql: 'SELECT * FROM <@from table> <alias>'` with the report's `@segment` filter and `@filter`, ANDed, as its `WHERE` (the alias is the view's own base alias, so it reads as the view's join condition; a TPH subtype's discriminator goes first), `@from`'s key, and `@from`'s definitions of the listed measures, a listed ratio's operands and a defaulted measure's `<m>Raw`, in `@from`'s order, unlisted ones `public: false`. It holds no foreign-key dimension: Cube's join reads the column (`{<Report>Facts}."programId"`), as every join does. The spine cube (the cube every listed dimension reaches after the spine's hops: the spine entity's own, its join-target cube, or the last hop's alias cube) gets one `one_to_many` join onto it, on the spine hop's columns, with the foreign key on whichever side the hop's reference puts it. No join is added to `@from`'s own cube or to any entity between, so the ordinary cubes' ad-hoc answers are unchanged (executed: `{ Week.weeks, Program.id }` stays rooted at `Week`). The view `model/views/<Report>.yml` shares the cube namespace (`ERR_CUBE_NAME_COLLISION`); its first `join_path` is the spine cube with the member each listed dimension reads under the dimension's name, the dimension's `title`, `description` and `meta.grains` on the include; a dimension past the spine is included from the cube its own joins end on; the last `join_path` is the facts cube with the listed measures. **A multi-hop spine is built, not refused:** each entity between `@from` and the spine entity gets a standalone `public: false` chain cube `<Report>_<hop>` (its table, key and one `one_to_many` join onward), because the chain is the same reverse join repeated and Cube walks a view's `join_path` through it exactly (executed on 1.7.43 by hand with a sessions table: the rows equal the view lowering's two-hop SQL); corpus case `report-spine-multi-hop` is compile-checked by the lane. Executed on 1.7.43 before building: a view includes a private key and a `public: false` member under an alias, include-level `title`, `description` and `meta` reach `/v1/meta`, and the roster and scoped views return every spine row. Every member of a `public: false` cube is private in `/v1/meta`, which the lane's member check now expects. The generator writes a view when every cube its join paths name is written, and its orphan cleanup owns `model/views/*.yml` as well. The guard module is deleted. Review fixes: a facts or chain cube carries no entity `title` or `description`; a TPH subtype as the spine entity is exported through its discriminator-scoped cube (unit-tested, documented; the view lowering refuses that report); two listed dimensions over one field and path include one member twice under two aliases, which the lane's corpus pass proves Cube accepts (`report-spine`); the report scope and the MySQL tuple count come from one helper each in `report-sql.ts` (`reportScope`, `mysqlTupleCount`), used by the view lowering and the exporter alike; `JOIN_PATH_SEPARATOR` is one exported constant; `ERR_CUBE_NAME_COLLISION` says "cube or view" when one side is a view.
659659
- **Requirements ledger.** Nothing moved. The `reporting` branch of `metaobjects/meta.requirements.yaml` (`dimensionAttribute`, `dimensionTime`, `measureAggregate`, `measureRatio` and `segmentFilter`) and the `objectReport` entry describe declaring the vocabulary, and the branch's description leaves lowering and serving out. No entry is about export.
660660

661661
## Open questions for the captain

‎fixtures/cube-model/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -61,7 +61,7 @@ never copied from it. A golden blessed from the implementation proves nothing.
6161
| `report-rollup` | B: served report; F | a `rollup` named after the report: dimensions and measures in listed order, `segments` with `@segment` then the scope segment `programsByMonthScope`, the one-time-dimension form; a report with no dimensions is a measures-only rollup; rollups are written coarsest first, so `ProgramTotals` precedes `ProgramsByMonth` |
6262
| `report-relative-no-rollup` | B; F (Review Focus 3) | a relative `@filter` gives the scope segment and no rollup; a relative condition on a listed measure gives no rollup and no segment |
6363
| `report-sourceless` | B: sourceless report; A | a sourceless, an abstract and a `materializedView` report add nothing to their `@from` cube |
64-
| `report-spine` | B: report `@spine`; the zero-rows / measure-defaults plan, Table D | a served `@spine` report is a Cube view `model/views/<Report>.yml`, no rollup and no scope segment: its first `join_path` is the spine cube (`Program`, a join-target cube here) with the members the listed dimensions read under the dimensions' names (`id` as `programKey`; `title` as `programTitle`, carrying the dimension's description), its last `Program.<Report>Facts` with the listed measures, and the report's description is the view's. `<Report>Facts` is a standalone `public: false` cube over the `@from` table with the report's scope in its own `sql` (`ProgramLongWeeks`: its `@segment` then its `@filter`, ANDed; `ProgramRoster`: none), its key, and `@from`'s definitions of the listed measures and what they read (a defaulted measure's `<m>Raw` included). The spine cube gets one `one_to_many` join onto each facts cube, on the spine hop's columns; `Week`, the ordinary fact cube, is what it would be without the reports |
64+
| `report-spine` | B: report `@spine`; the zero-rows / measure-defaults plan, Table D | a served `@spine` report is a Cube view `model/views/<Report>.yml`, no rollup and no scope segment: its first `join_path` is the spine cube (`Program`, a join-target cube here) with the members the listed dimensions read under the dimensions' names (`id` as `programKey`; `title` as `programTitle`, carrying the dimension's description, and the same `title` again as `programName`, a second dimension over the same field and path, which Cube accepts), its last `Program.<Report>Facts` with the listed measures, and the report's description is the view's. `<Report>Facts` is a standalone `public: false` cube over the `@from` table with the report's scope in its own `sql` (`ProgramLongWeeks`: its `@segment` then its `@filter`, ANDed; `ProgramRoster`: none), its key, and `@from`'s definitions of the listed measures and what they read (a defaulted measure's `<m>Raw` included). The spine cube gets one `one_to_many` join onto each facts cube, on the spine hop's columns; `Week`, the ordinary fact cube, is what it would be without the reports |
6565
| `report-spine-multi-hop` | B: report `@spine`, two hops | `Session.fkWeek.fkProgram`: the spine cube `Program` joins a standalone `public: false` chain cube `ProgramSessions_fkWeek` over `weeks`, which joins `ProgramSessionsFacts`, each `one_to_many` on its hop's columns; the view's last `join_path` is `Program.ProgramSessions_fkWeek.ProgramSessionsFacts`. The ordinary `Week` and `Session` cubes gain nothing |
6666
| `entity-tph-subtype` | K; A TPH row | a TPH subtype's cube is `sql: 'SELECT * FROM "auths" WHERE "type" = ''Bridge'''`, not `sql_table`; the base and a subtype with no vocabulary get none |
6767
| `escaping` | K; G literals and identifiers | `a{b}c` → `a\{b\}c`; a literal holding a Jinja opener (`{{`, `{%`, `{#`) has its braces escaped and is wrapped in `{% raw %}`; `'` doubled for SQL then for YAML; every backslash doubled before the braces are escaped, because Cube reads `sql` as a template literal (`a\b` → `a\\b`, a trailing `\` → `\\`, `a\{b}` → `a\\\{b\}`); a line break makes the scalar a JSON double-quoted string; an `@column` with braces escaped too. The lane reads each literal back from Cube's `/v1/sql` and requires the view's own SQL |

‎fixtures/cube-model/report-spine/expected/model/cubes/Week.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,9 @@ cubes:
1818
sql: '{Program.title}'
1919
type: string
2020
description: "The program's title."
21+
- name: programName
22+
sql: '{Program.title}'
23+
type: string
2124
measures:
2225
- name: weeks
2326
sql: '{CUBE}."id"'

‎fixtures/cube-model/report-spine/expected/model/views/ProgramRoster.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,8 @@ views:
1010
- name: title
1111
alias: programTitle
1212
description: "The program's title."
13+
- name: title
14+
alias: programName
1315
- join_path: Program.ProgramRosterFacts
1416
includes:
1517
- name: weeks

‎fixtures/cube-model/report-spine/meta.json‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -94,6 +94,13 @@
9494
"@description": "The program's title."
9595
}
9696
},
97+
{
98+
"dimension.attribute": {
99+
"name": "programName",
100+
"@of": "Program.title",
101+
"@via": "Week.fkProgram"
102+
}
103+
},
97104
{
98105
"measure.aggregate": {
99106
"name": "weeks",
@@ -126,7 +133,8 @@
126133
"@spine": "Week.fkProgram",
127134
"@dimensions": [
128135
"programKey",
129-
"programTitle"
136+
"programTitle",
137+
"programName"
130138
],
131139
"@measures": [
132140
"weeks",

0 commit comments

Comments
 (0)