Data Vault models use linked tables (tableType=LINKED_TABLE) for two related cases:

  1. Cross-model links — read-only canvas cards that point at hubs, links, satellites, or reference tables defined in another .hdv file (subject-area models around a shared core).

  2. Same-model hub aliases — role-playing names for the same physical hub so a link can participate that hub more than once with distinct source mappings and link columns (for example primary and secondary sales rep, or from/to location).

Both patterns mirror dimensional DIMENSION_ALIAS / referencedModelFilename.

Important
 A linked table is not a Reference table. Reference tables (tableType=REFERENCE) are physical code/catalog tables in the vault (natural keys, load, DDL). Linked tables are canvas pointers (no DDL or load of their own).

When to use

  • Enterprise core + subject areas — shared hubs live in shared-core.hdv; subject models link to them and define local links and satellites. For team ownership, git, catalog, and personas, see Organizing large Data Vault programs.

  • Avoid metadata duplication — hash keys, business keys, and source mappings stay authoritative on the physical hub.

  • Independent load workflows — each .hdv file runs its own Data Vault Update action; linked tables/aliases do not generate DDL or loads.

  • Same hub twice on one link (role-playing) — prefer the natural hub + one alias per extra role (not an orphan physical hub). See Data Vault Link and the role-playing section below.

Linked table metadata

A linked table is stored as tableType=LINKED_TABLE (legacy files may still say TABLE_REFERENCE; the plugin dual-reads both and re-saves as LINKED_TABLE):

<!-- Cross-model linked table (canvas name usually matches the physical hub) -->
<table>
  <referencedTableName>hub_customer</referencedTableName>
  <referencedModelFilename>${PROJECT_HOME}/models/shared-core.hdv</referencedModelFilename>
  <referencedTableType>HUB</referencedTableType>
  <tableName>hub_customer</tableName>
  <name>hub_customer</name>
  <tableType>LINKED_TABLE</tableType>
</table>

<!-- Same-model hub alias for an *extra* role (distinct name + role hash key column) -->
<table>
  <referencedTableName>hub_sales_rep</referencedTableName>
  <referencedTableType>HUB</referencedTableType>
  <hashKeyFieldName>secondary_rep_hk</hashKeyFieldName>
  <tableName>hub_sales_rep</tableName>
  <name>hub_secondary_rep</name>
  <tableType>LINKED_TABLE</tableType>
</table>

  • referencedModelFilename — optional; empty means same model.

  • name — unique canvas name (may differ from referencedTableName for aliases).

  • hashKeyFieldName — role column used when the alias participates in a link (must differ from the physical hub hash column and from other roles).

  • Physical tableName is synced from the target hub; aliases never create a second hub table.

Linked tables and aliases do not generate DDL or load pipelines.

Canvas workflow

From the Data Vault canvas context menu:

  • Add Linked Hub / Add Linked Link / Add Linked Satellite — browse an external .hdv and pick a table.

  • Add Hub alias — pick a physical hub in this model, enter a unique alias name and a role hash key column (for example secondary_rep_hk or to_party_hk).

  • Drag relationships from local links or satellites to linked tables/aliases (same rules as local tables).

Cards show (linked) for cross-model linked tables and (alias) for same-model role-playing aliases, plus the source model basename when external.

  • Click the table name on a linked/alias card to open the owning model (or select the physical hub in the same model) and select the linked table.

  • Or use the table context menu action Go to source table.

Data Vault 2.0 allows multiple foreign hash keys of the same hub domain on one link, distinguished by role-named columns (from/to location, employee/manager, primary/secondary rep).

Avoid leaving the physical hub as an orphan card that never participates in the link. Prefer:

  1. Create and load the physical hub once (hub_sales_rep).

  2. On the link, use the physical hub for the primary / natural role (column = the hub’s own hash key, e.g. sales_rep_hk, mapped from primary_rep_id).

  3. Add one hub alias per additional role only (hub_secondary_rep → secondary_rep_hk, mapped from secondary_rep_id).

  4. List participants as hub_sales_rep, hub_secondary_rep (and any other hubs), not the physical hub name twice.

Avoid

  • Two aliases of the same hub with no natural hub on the link (orphans the physical card and confuses ownership).

  • Reusing the same hash key column name for two roles.

Mapping and load

  • Link source mappings use the canvas name of the participant (alias name for extra roles).

  • DDL and load pipelines emit one column per role (sales_rep_hk, secondary_rep_hk, …).

  • Special records and optional FK constraints follow the same role columns.

  • Data Vault Update skips linked tables (no pipeline); only physical hubs/links/sats/reference tables load.

Validation and load order

  • Linked tables must resolve to a real non-linked table (local or external).

  • External models must not form circular linked-table chains.

  • Target database, hash algorithm, and hash key data type should match across models.

  • In a multi-file program, load core models before subject models that only hold linked tables to shared hubs.