Skip to content

Emit primary-key markers and join keys in OKF export#1

Merged
vladflaks merged 2 commits into
mainfrom
fix/okf-export-emit-join-keys
Jul 19, 2026
Merged

Emit primary-key markers and join keys in OKF export#1
vladflaks merged 2 commits into
mainfrom
fix/okf-export-emit-join-keys

Conversation

@Obolrus

@Obolrus Obolrus commented Jul 19, 2026

Copy link
Copy Markdown
Contributor

Why

The OKF exporter emits relationships without concrete join keys and never marks a mart's primary key, even though it already reads isPrimaryKey from the OWOX schema and emits FK to [Target] notes. As a result any OKF consumer that renders the model — e.g. the Model Canvas ERD — draws every relationship as a bare line with no join columns. The picture of the model is incomplete: you can see that two marts are related, but not on what.

Measured on the current example bundle, parsed by the Model Canvas OKF parser:

NODES: withPK  = 0
EDGES: withKeys = 0   → every relationship is a keyless line

What this PR changes

1. Exporter (tools/odm-to-okf-export/export.py)

  • Primary-key markers. render_schema_section now prefixes the PK column's description with PK. (cell order: PK. → description → FK to […], matching what the canvas serializer produces). The data was already available via isPrimaryKey; it just wasn't written out.
  • Join keys in ## Joins. _render_joins_section now emits - [Target](./target.md) — left = right`` when the key is derivable — i.e. this mart has a column named the same as the target mart's primary key. OWOX's blendedFieldsConfig carries no explicit join columns, so a link with no matching column is left bare (unchanged behaviour for those).
  • --folder flag. Optional override for the bundle subfolder name (defaults to the slugified project title, as before).

No cardinality is emitted — OWOX Data Marts has no such concept, and the canvas treats its absence gracefully.

2. Example bundle (bundles/…)

Regenerated with the fix so it renders join keys on the canvas, and cleaned up:

  • Scoped to a single storage (BigQuery [Common]) so it is a coherent e-commerce model — 24 marts. The previous 27-mart example silently mixed marts from several storages (some same-named ad marts actually lived in Snowflake / other storages); those 3 out-of-storage marts are dropped and a few ad marts now resolve to their BigQuery counterparts.
  • Renamed demo-projecte-commerce, so adding further example models later doesn't leave a generic demo-project sitting next to them.

After the fix, the same parser reports:

NODES: withPK  = 18 / 24
EDGES: withKeys = 9 / 20   (remaining keyless targets have no PK — connector/aggregate marts)

Keyed relationships now include e.g. orders → sessions: session_id = session_id, orders → customers: customer_id = customer_id, purchases → products: product_id = product_id, sessions → visitors: visitor_id = visitor_id.

How to verify

Import https://model.owox.com/?okf=https://github.com/OWOX/models/tree/<this-branch>/bundles/e-commerce and confirm the ERD shows join-key fields on the related marts instead of bare lines.

Obolrus and others added 2 commits July 19, 2026 06:55
The exporter already knew each mart's primary key (isPrimaryKey) and
emitted "FK to [Target]" notes, but it never marked the PK column or put
the join key on the relationship line. Downstream OKF consumers (e.g. the
Model Canvas ERD) therefore rendered every relationship as a bare line
with no join columns, making the model picture incomplete.

- render_schema_section: prefix the PK column's description with "PK."
  (cell order: PK. -> description -> FK note).
- _render_joins_section: emit "- [Target](./t.md) — `left = right`" when
  the key is derivable (this mart's column == the target mart's PK of the
  same name); OWOX's blend config carries no explicit join columns, so a
  link with no matching column stays bare.
- add --folder and --title to override the bundle subfolder name and
  display title (default to the slugified / raw project title as before).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…commerce

Regenerate the example bundle with the exporter fix so it renders join
keys on the canvas. Scope it to a single storage (BigQuery [Common]) so it
is a coherent e-commerce model, and rename the folder/title to E-Commerce
to leave room for future example models.

- 24 marts from one storage instead of a 27-mart mix across storages;
  drops 3 marts that actually lived in other storages.
- every mart now declares its PK; relationships carry join keys.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@Obolrus
Obolrus force-pushed the fix/okf-export-emit-join-keys branch from e37dbfe to 0611a57 Compare July 19, 2026 03:56
@Obolrus
Obolrus requested a review from vladflaks July 19, 2026 03:56
@vladflaks
vladflaks merged commit 516ffee into main Jul 19, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

2 participants