Data Vault Hub

Table of Contents

How hub updates work
Options in the Hub dialog
Integration mode
Using the Check model feature with hubs
What gets created in the target database
Multi-source hubs
Composite hub business keys (single vault column)
Tips for hubs

A Hub represents a core business concept that you want to track over time, such as Customer, Product, Supplier, Order, or Account. In Data Vault terms, the hub stores the natural business key(s) that uniquely identify an instance of that concept, plus a surrogate hash key that is derived from those business keys.

Hubs are the foundation of the model. Links and Satellites refer back to them.

How hub updates work

When you load data into a hub (either from the visual model editor’s Debug button or from the Data Vault Update action), Hop generates a pipeline that:

Makes sure the target hub table exists (it can create or alter it for you).
Reads the business key values (and the record source indicator) from the source you attached to the hub.
For composite (single vault column) business keys, composes the stored BK string from ordered source parts using the model delimiter (see Composite hub business keys (single vault column)).
Compares the incoming keys against what is already in the hub (on vault column names).
Inserts only the rows that represent genuinely new business keys.
Calculates the hash key for those new rows (by default from ordered parts for composite keys, with optional hash suffix — not written into the stored BK column).
Writes the new rows together with the current load date and the record source value.

Only new keys are inserted. Existing keys are left untouched. This is the classic Data Vault 2.0 "insert-only" pattern for hubs.

Options in the Hub dialog

The Hub dialog is organized into three tabs: Options, Keys, and Record sources.

Option Description

Option	Description
Name	The name of this hub definition inside your Data Vault Model. It is also used as the default physical table name if you do not specify an explicit table name. The name must be unique within the model. Press CTRL-SHIFT-N or click N to apply a `dv-hub` naming scheme; see EDW naming schemes.
Physical table name	The actual name of the table that will be created or loaded in your target Data Vault database. Leave this empty to use the Name above. This is useful when your metadata name is more business-friendly while the physical table follows a different naming convention.
Description	A short business description of what this hub represents. Helpful for documentation and for anyone who later maintains the model.
Hash key field name (Options tab)	The name of the surrogate hash key column that will be stored in the hub table. Satellites and Links that attach to this hub will normally reference this column. If you leave it empty, the plugin will derive a name from the first business key (for example CUSTOMER_ID becomes CUSTOMER_ID_HK). Most teams prefer to set an explicit, consistent name such as CUSTOMER_HK.
Record source field name (Options tab)	Optional. Use this when you want the record source column in this particular hub to have a different name than the one defined in the Data Vault Configuration (for example you want HUB_CUSTOMER_SOURCE instead of the global RECORD_SOURCE). The field supports variables. If left empty, the value from the active Data Vault Configuration is used.
Business keys (Keys tab)	One or more business key definitions that together uniquely identify an instance of the hub. Two multi-part styles are supported — see Composite hub business keys (single vault column): * Multipartite vault columns (default): several rows with different Name values → several physical hub columns; hash uses those column names in order. * Composite (single vault column): Composite=Y on one row → one physical hub column; ordered source field name(s) supply the parts. For each business key you can specify: * The name of the column in the hub table (always the physical vault column name). * An optional description. * Data type and length (used when the source definition does not provide them). * Composite (Y/N) — single composed vault column from multiple source parts when Y. * Source field name(s) — one source column, or comma-separated ordered parts when Composite=Y. If the source column name matches the hub name for a non-composite key, a single value is enough. * Source system – the name of the Data Vault Source this business key mapping applies to. This column is the key to supporting multiple sources on one hub. When the same logical key (for example `CUSTOMER_ID` or composite `burger_bk`) comes from different source systems under different physical column names, you create separate rows in the business keys table and tag each with its Source system (same Name, same part count for composite keys). Use the Import keys from sources button on the Keys tab to populate business keys automatically. Before using it, make sure you have added at least one source in the Record sources tab. The button reads the primary key fields from unmapped sources, creates multipartite-style business key rows (Composite=N), and fills the Source system column. To model a VaultSpeed-style single composed column, set Composite=Y, set the vault Name to the hub BK column (for example `burger_bk`), and list ordered source parts in Source field name(s).
Record sources (Record sources tab)	A hub can be fed by one or more Data Vault Sources. List every source system or feed that will load this hub (insert business keys into the hub table). Do not list feeds that only load satellites of this hub. Satellite feeds are independent in Data Vault 2.0; each satellite has its own record source. Parent hash keys on satellites are computed from parent identity values on the satellite feed (hub vault key names, or ordered source parts for composite hub keys — not a stored composed BK column on the satellite). You can attach as many hub-load sources as you need. The generated load process will handle each source (typically producing one pipeline per source) but all of them write into the same physical hub table. This is the recommended way to handle a single business concept that receives identity from multiple upstream systems (for example a Customer hub that is populated from both a CRM system and an ERP system). It is also the cheapest way to prevent dangling hashes when a child feed (orders, invoices) arrives before the parent master: add that child feed as another hub record source (link dialog Also load parent hubs…, or the source-to-vault seed option). See Orphan handling.

Name

The name of this hub definition inside your Data Vault Model. It is also used as the default physical table name if you do not specify an explicit table name. The name must be unique within the model. Press CTRL-SHIFT-N or click N to apply a dv-hub naming scheme; see EDW naming schemes.

Physical table name

The actual name of the table that will be created or loaded in your target Data Vault database. Leave this empty to use the Name above. This is useful when your metadata name is more business-friendly while the physical table follows a different naming convention.

Description

A short business description of what this hub represents. Helpful for documentation and for anyone who later maintains the model.

Hash key field name (Options tab)

The name of the surrogate hash key column that will be stored in the hub table. Satellites and Links that attach to this hub will normally reference this column.

If you leave it empty, the plugin will derive a name from the first business key (for example CUSTOMER_ID becomes CUSTOMER_ID_HK). Most teams prefer to set an explicit, consistent name such as CUSTOMER_HK.

Record source field name (Options tab)

Optional. Use this when you want the record source column in this particular hub to have a different name than the one defined in the Data Vault Configuration (for example you want HUB_CUSTOMER_SOURCE instead of the global RECORD_SOURCE).

The field supports variables. If left empty, the value from the active Data Vault Configuration is used.

Business keys (Keys tab)

One or more business key definitions that together uniquely identify an instance of the hub. Two multi-part styles are supported — see Composite hub business keys (single vault column):

* Multipartite vault columns (default): several rows with different Name values → several physical hub columns; hash uses those column names in order. * Composite (single vault column): Composite=Y on one row → one physical hub column; ordered source field name(s) supply the parts.

For each business key you can specify: * The name of the column in the hub table (always the physical vault column name). * An optional description. * Data type and length (used when the source definition does not provide them). * Composite (Y/N) — single composed vault column from multiple source parts when Y. * Source field name(s) — one source column, or comma-separated ordered parts when Composite=Y. If the source column name matches the hub name for a non-composite key, a single value is enough. * Source system – the name of the Data Vault Source this business key mapping applies to. This column is the key to supporting multiple sources on one hub. When the same logical key (for example CUSTOMER_ID or composite burger_bk) comes from different source systems under different physical column names, you create separate rows in the business keys table and tag each with its Source system (same Name, same part count for composite keys).

Use the Import keys from sources button on the Keys tab to populate business keys automatically. Before using it, make sure you have added at least one source in the Record sources tab. The button reads the primary key fields from unmapped sources, creates multipartite-style business key rows (Composite=N), and fills the Source system column. To model a VaultSpeed-style single composed column, set Composite=Y, set the vault Name to the hub BK column (for example burger_bk), and list ordered source parts in Source field name(s).

Record sources (Record sources tab)

A hub can be fed by one or more Data Vault Sources. List every source system or feed that will load this hub (insert business keys into the hub table).

Do not list feeds that only load satellites of this hub. Satellite feeds are independent in Data Vault 2.0; each satellite has its own record source. Parent hash keys on satellites are computed from parent identity values on the satellite feed (hub vault key names, or ordered source parts for composite hub keys — not a stored composed BK column on the satellite).

You can attach as many hub-load sources as you need. The generated load process will handle each source (typically producing one pipeline per source) but all of them write into the same physical hub table. This is the recommended way to handle a single business concept that receives identity from multiple upstream systems (for example a Customer hub that is populated from both a CRM system and an ERP system). It is also the cheapest way to prevent dangling hashes when a child feed (orders, invoices) arrives before the parent master: add that child feed as another hub record source (link dialog Also load parent hubs…, or the source-to-vault seed option). See Orphan handling.

Integration mode

On the Options tab, Integration mode controls how Hop loads this hub:

Hop managed (default) — Hop generates DDL, sentinel rows, and update pipelines.
External read-only — the hub table exists elsewhere; Hop documents it for Business Vault and catalog only. Canvas shows (ext).
Custom pipelines — Hop runs .hpl files from customUpdatePipelinePaths instead of generating pipelines. Canvas shows (custom).

See Data Vault integration modes for Data Vault Update behavior and validation differences.

Using the Check model feature with hubs

When you click Check model on the model editor toolbar, the plugin validates every hub. Common issues it will report include:

No business keys have been defined.
One or more business keys have no name.
The hub has no record sources listed in the Record sources tab.
One or more of the listed record sources do not exist in the project.
Business keys that reference a Source system that is not present in the Record sources list.
Missing source part columns for composite business keys (or different part counts for the same vault BK name across multi-source mappings).
Source-to-target type mismatches for each business key mapping (per record source / part): incompatible Hop types, or source column length/precision larger than the hub business key definition.
Warning when Hash composed business key is enabled together with a non-empty hash content suffix on a hub that uses composite BKs (confirm the recipe intentionally hashes the composed string rather than ordered parts).

Type validation uses the live database schema when detailed data type checking is active (always in the GUI; configurable on the Data Vault Update action). A warning is raised when stored source field metadata in the Data Vault Source differs from the live schema.

These checks run before any pipelines are generated, so you catch problems early.

What gets created in the target database

The plugin builds a target table layout that typically contains (in this order):

The hash key column (its type and length depend on the hash algorithm and hash key data type chosen in the configuration: HEX is the default; STRING is human-readable; BINARY is the most compact and is supported on the required Hop 2.19.0+ runtime — see Hop issue 7346).
The business key columns: one physical column per distinct business key name, in definition order. Composite keys still contribute a single vault column (the composed string). Multipartite keys contribute one column per name. Length and precision come from the business key definition.
The record source column (name and length come from the configuration or the per-hub override; variables are supported).
The load date column (usually a timestamp, named LOAD_DATE or whatever you configured).

If the table does not exist yet, the generated pipeline will first run the necessary DDL to create it (or alter it if columns are missing). The final load step only writes the fields that belong in the hub (the internal "flag" column used during comparison is excluded).

Multi-source hubs

A powerful feature of the plugin is that a single hub definition can receive data from multiple independent sources. All sources contribute rows to the same hub table.

To use this: 1. On the Record sources tab, add every Data Vault Source that will feed the hub. 2. On the Keys tab, define your business keys. Use the Source system column (last column in the business keys table) to indicate which source a particular mapping belongs to. 3. Use Load from source once per source (after ensuring the desired source appears in the Record sources list) to pull the correct source column names for that system.

This approach keeps your hub modeling clean: one logical hub table, many places it can be populated from, with explicit control over which source columns map to which business keys.

For composite business keys, every source that maps the same vault Name must use the same number of source parts (only the field names may differ per source).

Composite hub business keys (single vault column)

Many warehouses (including VaultSpeed-style models) store a single hub business-key column built by concatenating several source fields, while still hashing from those parts under fixed rules.

Multipartite vs composite

Style Hub table Hash inputs (default)

Style	Hub table	Hash inputs (default)
Multipartite vault columns	One physical column per business key Name (for example `order_id`, `line_no`)	Those vault column names / stream fields, in order
Composite (this feature)	One physical column (for example `burger_bk = IKL#12278170`)	Ordered source parts (for example `num_seq_bkcc_bk`, `num_seq_bk`); optional trailing hash content suffix applies to the hash input only

Multipartite vault columns

One physical column per business key Name (for example order_id, line_no)

Those vault column names / stream fields, in order

Composite (this feature)

One physical column (for example burger_bk = IKL#12278170)

Ordered source parts (for example num_seq_bkcc_bk, num_seq_bk); optional trailing hash content suffix applies to the hash input only

Do not confuse this with composite catalog feeds (multi-table .hsm queries): those describe sources, not hub BK composition.

Storage vs hash

Stored BK = ordered parts joined with the model business key delimiter, with trim / null placeholder from configuration. The hash content suffix is not stored in the column (so you can match VaultSpeed: stored IKL#12278170, hash input IKL#12278170# when delimiter and suffix are both #).
Hash (default): DvHashKey over ordered part fields, using delimiter, casing, prefix/suffix, trim, and null placeholder from configuration.
Optional configuration flag Hash composed business key: hash the composed vault field only (simpler; may not match trailing-suffix recipes).

Satellites and links do not store the composed hub BK column. They map ordered source part columns on their feeds and compute the parent/hub hash using the hub definition and the same model hash settings.

Modeling example

Source parts:  num_seq_bkcc_bk = IKL ,  num_seq_bk = 12278170
Delimiter:     #
Hash suffix:   #
Stored BK:     burger_bk = IKL#12278170
Hash input:    IKL#12278170#   (parts + delimiter + suffix)

In the hub Keys tab: Name burger_bk, Composite Y, Source field name(s) num_seq_bkcc_bk, num_seq_bk, plus the Source system for that feed.

Tips for hubs

Start with good source definitions (Data Vault Database Source) that accurately declare primary keys and column lengths. This makes Import keys from sources work well and produces better target tables.
When a hub has multiple sources, add them all on the Record sources tab first, then use Import keys from sources for each source in turn so the Source system column is populated correctly.
Prefer composite single-column BKs when you need DDL/hash parity with existing VaultSpeed-style hubs; keep multipartite vault columns when each part is a true natural key column of equal stature.
Be consistent with hash key naming across the model (either rely on the default suffix or set explicit names on every hub).
Use the per-hub record source field name override sparingly; most of the time the model configuration’s record source field name is sufficient.
Hashing rules are defined once per model in the embedded configuration (Edit model dialog). Use consistent hash key naming across hubs rather than expecting per-table hashing overrides.