Module 5 — Business Vault

A Business Vault model is an .hbv file that references a linked Data Vault model (.hdv). It reads hub and satellite history from the Data Vault target database and writes its tables to the Business Vault target database. The two connections are configured separately (the DV one on the .hdv, the BV one on the .hbv) and may or may not be the same; both must resolve in the Hop project, and Check model validates that before any pipeline is generated.

Data Vault hubs, links and satellites are referenced on a .hbv canvas as Linked Hub, Linked Link and Linked Satellite cards, so a table names the vault objects it reads.

An SCD2 table merges satellite history into version rows. Every functional change opens a version with validity bounds (valid_from / valid_to by default; the retail project’s configuration uses x_from_ts / x_to_ts). The functional timestamp decides where a version starts — the moment the source system said the value became true. It resolves in this order: per-satellite override, then the per-table field, then the model default, then the load-date fallback. The retail 360 model sets it to x_load_ts on the table.

An SCD2 table is pure Type 2: a value change becomes a new version row and the older rows stay queryable. There is deliberately no per-column Type 1 switch that would rewrite historical versions when a "current" value changes — mixing the two would make some columns look historical while they are not. When users need a value as it is now (say, the current sales rep on old facts), resolve it downstream: join the open SCD2 row, read the latest satellite row, use a separate current-state view or table, or use hybrid Type 1 + Type 2 in the dimensional model.

Field mappings are required when two or more inputs feed one table, and Suggest mappings fills the unmapped attributes of the satellites and source queries you select. On Satellite settings, each satellite can override the functional timestamp, carry a source indicator value (the merge tag used when several satellites are merged), and name the calendar system it belongs to when a source calendar is selected.

A PIT table materializes the as-of lookup once, so consumers join instead of re-deriving it: one row per (hub hash key, snapshot date), plus one pointer column per satellite (default suffix _ldts) holding the load timestamp of the satellite row that was effective at that snapshot. A query then joins sat.x_load_ts = pit.sat_customer_ldts for the snapshot it wants.

PIT reads raw hub and satellite history — not SCD2 output. SCD2 and PIT are independent siblings in the same run, and SCD2 tables run first. The snapshot spine is a schedule: Snapshot cadence (daily only today; the other cadences validate but cannot be generated yet), Snapshot anchor (end of period by default), Horizon days (default 1 — skips the most recent days as a late-arriving-data buffer), and Range start / Range end (default: the earliest participating satellite load to now minus the horizon). A PIT table that already exists only receives snapshot dates newer than its highest snapshot_date.

An identity map resolves many raw hub hashes to one durable hash. Add it with Add identity map (a parent hub and a same-as link are what it needs), and an SCD2 table opts in with Identity map; leave that blank and the timeline keeps the raw hub hash as its grain. The generated map upserts and never truncates: a raw key that already has a durable key keeps it, so hk_durable is frozen on first assignment and survives the next run. Rows that predate the mapping follow the unmapped policy — self keeps the raw hash, quarantine and drop leave the row out of the timeline.

Survivorship decides values when several sources feed the same target column. Give each of those mapping rows a Rank — 1 wins over 2 — and the merge keeps the best-ranked value at every timestamp. Null policies decide what a null does (inherit skips to the next rank, apply writes it). A table with no ranks keeps the normal merge behaviour.

A source calendar is shared metadata — not a warehouse table — that says when each source system may contribute rows. Each entry is a half-open window: a calendar system name you choose (ORACLE, KAFKA, …), an effective-from and an effective-to, where an empty effective-to means the source is still in use. An SCD2 table opts in with Source calendar and then names the calendar system per satellite on Satellite settings; leave it blank and every satellite row is kept. The documented example: Oracle rows count through 2024-02-29, Kafka rows from 2024-03-01.

Business Vault Update (BUSINESS_VAULT_UPDATE) mirrors Data Vault Update: model check, optional DDL on the target, pipeline generation, staging, parallel execution, and optional catalog publish. Within one run the order is fixed: SCD2 tables, then PIT, then bridges, then SQL business tables. Inside a full warehouse wave, Update resource definition group runs all Data Vault models first, then all Business Vault models, then all dimensional models — each layer in list order.

Debug (toolbar) and Show build pipeline (table context menu) generate a build pipeline and open it without writing any data. That is the fastest way to read what a table will actually do before a load touches the warehouse.