Key takeaways
- Gold retains unmatched rows; unknown members are first-class.
- Business-key parse rules live in gold with fixture tests.
- Grain, bridge keys, and semantic relationships release together.
- Captions, descriptions, and query folders are required for publish.
- Acceptance includes every source row visible regardless of dim match.
- Matching logic is shared across fact tables.
A gold table that looks clean in Spark can still fail as a platform asset. Optional links to a dim table drop unmatched rows. Free-text fields hide business keys behind tribal regex. Captions and folders are treated as polish. Stakeholders open a report and part of the data is missing without an error.
Gold becomes useful when unmatched keys, captions, and relationships ship as one semantic contract with the table. "Every source row visible regardless of match" is an acceptance test, not a slogan.
Named model: gold as a semantic contract
- Curated Delta: the gold write that passes Spark and row counts.
- Unknown members: every source row survives optional dim linkage; unmatched is first-class, not deleted.
- Bridges + TMDL: grain statement, typed bridge keys, parse fixtures, and model relationships in the same change set.
- Captions / folders: culture-aware names, descriptions, and query folders so analysts can find fields without tribal knowledge.
- Contract: Delta alone is a source copy. The four parts together are the platform asset. "Later" is a future blank-visual ticket.
Figure 1. Gold as a semantic contract. Curated Delta is necessary. Unknown members, bridges, relationships, and human-facing names make it a platform asset.
Context and constraint
A common failure: lakehouse row counts pass and report pages still look empty for whole slices of the data. The fact exists. The contract for unmatched members and relationship behavior does not.
Optional linkage to a dim table must surface unknowns, not silently filter. Parsed business keys from free-text are modeling decisions with tests. Culture captions and query folders are usability infrastructure. Treat them as part of the same release as the gold write.
Figure 2 is the Learn surface for model relationships. Keys and relationship behavior are the contract the model can trust, not a follow-up polish item.
Figure 2. Gold only becomes a platform asset when keys and relationships behave as a semantic contract the model can trust. Source: Microsoft Learn: understand relationships.
Figure 3 is why SQL endpoint health is not acceptance. Row counts can look fine while reports hide unmatched keys.
Figure 3. Row counts on the SQL endpoint can look healthy while reports hide unmatched keys. Test the contract, not only Spark success. Source: Microsoft Learn: lakehouse SQL analytics endpoint.
Design
1. Unknown members beat silent drops
Left joins that filter away non-matches make dashboards look authoritative and incomplete. Keep every source row. Attach unknown or unmatched members on the dim and bridge tables so totals reconcile to the source count people believe. Document what "unknown" means so nobody cleans it away in a follow-up PR. Figure 4 is the fork between silent drop and first-class unknowns.
Figure 4. Unknown members beat silent drops. Matched-only is an explicit report filter, not the default grain of gold.
2. Parsed business keys are a modeling decision
If business identifiers live in free-text fields, the parse rules belong in gold with fixtures, not in a report author's DAX or a one-off notebook cell. Version the rules. When the upstream text format changes, you want one place to fix and retest, not five visuals that each guessed differently.
3. Grain, bridge keys, and TMDL relationships ship together
Publish the grain statement (one row per key per what?), the bridge keys to the dim tables, and the TMDL or model relationships in the same change set. A gold table without updated relationships is a landmine for the next semantic refresh. Role-playing dims need matching key types or you get blank visuals that look like DAX bugs. Figure 5 is that single change-set handoff.
Figure 5. Grain, bridges, and captions ship together. If any answer is later, the PR is a table drop, not a platform asset.
4. Captions and query folders are part of the handoff
Field names that make sense to engineers fail field lists for analysts. Culture-aware captions, descriptions, and folder groupings reduce "where is the key?" support. This is not decoration. It is how the semantic contract is consumed.
5. Stakeholder acceptance: every row visible regardless of match
Write the test: source row count in gold equals the count reachable in the model under the default path, including unmatched. Spot-check known orphans. If product owners care that every row appears, automate that check before you argue about color on the dashboard.
6. Keep enrichment logic shared
If fact table A and fact table B both resolve keys to the same dim table, share the matching module. Divergent match logic produces two truths that both claim gold status.
Unknown members in the wild
Expect pushback the first time unknown members appear on a slicer. That pushback is useful. It forces a conversation about data quality versus silent exclusion. Teach filters for matched only as an explicit report choice, not as the default grain of gold. Gold tells the truth about coverage. Reports may narrow. They must not pretend the lake never saw the orphans.
How I review a gold PR
I ask four questions before merge. Does every source row survive optional dim linkage? Are parse rules for business keys covered by fixtures? Do TMDL relationships and key types match the gold grain in the same change set? Are captions and folders present for the fields analysts will hunt first? If any answer is later, the PR is a table drop, not a platform asset. Later rarely arrives before the first blank visual ticket.
Failure modes
Inner-join comfort. Unmatched rows disappear. Leadership thinks coverage is complete.
Regex as hobby craft. each notebook invents a slightly different key parse.
Gold merged, model relationships stale. Refresh succeeds. Visuals blank.
English-only technical names in the field list. Adoption dies quietly.
Accepting report screenshots as proof. Screenshots hide missing members.
Different match rules per fact. Row counts disagree by page.
What to copy / what not to copy
Copy
- Gold retains unmatched rows; unknown members are first-class.
- Business-key parse rules live in gold with fixture tests.
- Grain, bridge keys, and semantic relationships release together.
- Captions, descriptions, and query folders are required for publish.
- Acceptance includes every source row visible regardless of dim match.
- Matching logic is shared across fact tables.
Do not copy blindly
Unknown members inflate some visuals until filters are taught. That teaching is cheaper than silent undercount. Explicit parse rules mean change management when upstream text shifts; hidden parse rules mean silent drift. Shipping captions and TMDL with gold slows the data PR slightly and saves a week of semantic thrash. Shared enrichment modules require package discipline across notebooks. Worth it when two facts must agree.
Primary references: Microsoft Learn on semantic models in Fabric, understand relationships, and TMDL workflows your team already uses for model-as-code.
When you review a pull request that only adds a gold table, ask for the semantic companion: unknown-member behavior, relationship diff, and caption coverage. If those are follow-ups, the table is not a platform asset yet. It is a source copy waiting for a future incident.
If unmatched rows vanish, keys are tribal, and captions are later, you shipped a table. Ship the contract: unknowns, bridges, relationships, and human-facing names in the same breath as gold.