DV Modeling Specification v1.0.9

here are the rules for specification version 1.0.9 of data vault modeling.
(please feel free to comment on them by replying to this post).
the new pieces are marked in red as usual.

operational data vaults carry slightly modified rule sets from these, there will be a new specification started shortly for the operational data vault. what is an operational data vault? read the postings to find out.

section 1.0 – entity types
1.1 hub entity = unique list of business keys
1.2 link entity = list of relationships between business keys (composite keys), a link is also known as: transaction, granularity change, hierarchical relationship, recursive relationship, aggregate store.
1.3 satellites = descriptive information (data that changes over time).
1.4 stand-alone = tables like calendar/time or code/description. any table that is used in 60% or 80% of the model, where the business user has stated: i do not wish to store “history” on this section of data, and the keys are proliferated throughout the model. hubs, links, and satellites should never stand-alone. a stand-alone table may also be an intermediate join table (very much like a materialized view) existing for performance reasons. if the table is a “reporting table” (denormalized) then it belongs in a “report collection” area – (a different data mart/data distribution data base). there is now such a thing as stand-alone hub/satellites for history of codes and descriptions, but where denormalization of the data into other satellites causes too much data explosion, so lookups on the way out are a good thing to do.  also known as: cross-reference, or lookup tables, they may or may not contain history – and if they contain history, they are to be modeled in their own hub/link/sat structures.

section 2.0 – common field elements
common field elements are system driven, and system managed – they do *not* fall under the scrutiny of an audit.  they are generated fields on the way in to the target (stage, data vault, or star schema) and are necessary for assisting in the traceability of individual fields, but in and of themselves cannot be audited.
2.1 sequence id (required) – if surrogate keys are used, is the primary key of all tables
2.2 load date time stamp (required) – an attribute in the hub, and link – part of the primary key in a satellite. this is the date stamp of the date/time that the data was loaded into the database. this is stamped this way for consistency of information across the database. ** in a real time solution, or in a solution where the data is coming in from a cdc component (that stamps it with a time of change), it may be replacd with the extract date or date of change. as long as that date is mechanical from a trusted process **
2.3 record source (required) – this is the source system that generated the information, it is mechanically stamped when the information is loaded to the database. used when there is no meta-data project in place to trace information back to the source. it is provides tracability of every record at a granular level back to the source system. while optional, it is implemented by 98% of the customers today.
2.4 update user (optional) – this is there to track dba level modifications to the data. it is optional, and should be in another metrics tracking area.
2.5 update timestamp (optional). this is another dba tracking field. it also is optional and should be in another metrics tracking area.
2.6 last seen date (optional) – allows current tracking on hubs and links of the last time the key was seen on the source feed. this is a system generated, system defined date time stamp. since this is a data warehouse system generated field, controlled for a system view of the data, it is eligible for updating in place.
2.7 load end-dates (required) – this is the best practice today. represents the data warehouse system stamping of the life of the record in a satellite. since it is systematic, and it is maintained by the system for query purposes – it is not eligable for direct updating. load end-dates are now required in order to avert a historical data problem in a satellite that does not appear until load end dates are visible and in use.
2.8 extract date (optional) – this has proven to be beneficial if included in the module. there are times at which knowing what the extract date is, helps. however only in real-time systems does the extract date actually become the load date. in batch oriented loads, the extract date is attached as an extra information field (metadata).

section 3.0 hub rules
3.0 definition of a hub: a list of uniquely identified business keys that have a very low propensity to change.
3.1 a hub must have at least 1 business key.
3.2 a hub cannot contain a composite set of business keys. ** exception below
3.2.1 a hub should support at least one satellite to be in existence, hubs without satellites usually indicate “bad source data”, or poorly defined source data, or business keys that are missing valuable metadata
3.2.2 a hub key can be composite when: two of the same operational systems are using the same keys to mean different things and these keys collide when integrated back together again. please be aware: bad data causes breaks in these rules – these are guiding principles. exceptions to this rule should not happen (but do), also be aware, bad architecture in source systems causes breaks in these rules too.
3.3 a hub’s business key must stand-alone in the environment – either be a system created key, or a true business key that is the single basis for “finding” information in the source system. a true business key is often referred to as a natural key
3.4 a hub can contain a surrogate sequence key (if the database doesn’t work well with natural keys).
3.5 a hub’s load-date-time stamp or observation start date must be an attribute in the hub, and not a part of the hub’s primary key structure.
3.6 a hub’s primary key cannot contain a record source.
3.7 a hub may contain a last-seen-date if desired grain of tracking is needed.

section 4.0 link rules
4.0 definition of a link:
a ) a list of uniquely identified composite relationships between hub keys – must have 2 or more hubs or link keys combined.
b ) a hierarchical representation of a relationship or aggregation across a single hub’s key, migrated in exactly two times. any further hierarchy is broken down into two migrations, this way no limitation is placed upon the hierarchy, and the link is not playing a role-game which is dangerous. also, a hierarchical link must contain at least one satellite to indicate effectivity of the relationship (start and end dating of the hierarchical relationship.
4.1 a link must contain at least two imported hub or link primary keys
4.2 a link can contain two keys imported from the same hub for a hierarchical relationship, or rolled up relationship.
4.3 a link’s load-date-time stamp or observation start date must be an attribute in the link, and not a part of the links’ primary key structure.
4.4 a links composite key must be unique (a unique business key).
4.5 a link may contain a surrogate sequence key (if the composite is too large, or the database doesn’t work well with natural keys).
4.6 a link may contain 2 or more hub keys.
4.7 a links’ granularity is determined by the number of imported hub or link parent keys.
4.8 a link is a transaction, or a hierarchy, or a relationship.
4.9 a link may have zero or more satellites attached. except a hierarchical link as denoted above.
4.10 a link must be at the lowest level of granularity for tracking purposes.
4.11 a link must represent at most, 1 instance of a relationship component at any given time.
4.12 a link may have a last seen date for tracking purposes if desired.
4.13 in a hierarchical link, the child key is the primary driver for the relationship. this is the only instance in which a role-playing (half or part of the relationship) key is utilized. the child key will determine which effectivity satellite record to end-date. this is a defined and repeatable rule/pattern, and for hierarchical relationships is necessary. however, this rule does not hold for any other type of link, because it _is_ a role-playing rule based on one side of the composite key.
4.14 a same-as link takes the same form as a hierarchical link, but provides different context for usage, in that it allows differently named business keys to be “merged together” to a single master key – ie: this key is really the same-as this other key.

section 5.0 – satellite rules
5.0 definition of a satellite: any data with a propensity to change, any descriptive data about a business key – the data in the satellite must be separated by type (grouping) and rates of change (removal of redundancy).
5.1 a satellite must have at least one hub or link primary key imported.
5.2 a satellite cannot be attached to more than one hub – if it needs a composite key, then it must be attached to a link entity.
5.3 a satellite must have a load-date-time stamp (observation start date) as a part of it’s primary key.
5.4 a satellite may contain a sequence identifier or and ordering identifier as part of the primary key for uniqueness.
5.5 a satellite must contain a record source attribute for data tracability.
5.6 a satellite must contain at least one descriptive element about the hub or link to which it’s attached in order to be valid.
5.7 a satellite may contain system generated or aggregated attributes.
5.8 a satellite’s purpose is to store data over time.
5.9 a satellite may contain a code to a stand-alone code/description table, however if the code is tracked for history purposes, the code must be linked through to the hub on a link table.  foreign keys are what is being referenced here. fk’s to reference tables are allowed, fk’s to a reference structure which is a single hub with satellite (code / description history) is allowed. indirect references to date time calendar table, or geography is acceptable. these fk’s are not to be represented within the data model, if the data architect wishes to represent these, then the requirement to use a link table is necessary – but there can be no link’s associated to a satellite structure, this will break the architecture.
5.10 a satellite must-have a load-end-date for efficient sql queries. this is considered best practice for 99% of the rdbms engines, as they do not yet handle time inherantly within the query sides.
5.11 a satellite may be split or merged at any time, as long as no historical value is lost, and no historical audit trail is lost.

section 6.0 – naming conventions
6.0 naming conventsions are enforced in order to meet the needs of very large data models. without naming conventions, the models will get out of hand and become unmanagable. there are field naming conventions required for the fields in the data vault – there’s a different section for suggested naming conventions for generic data vault models, the wizards here will work with the required naming conventions (suggested will be picked up and used if available).
naming conventions are required to help handle large models, as long as the naming conventions for each component are labeled and followed, then the model will be compliant. what the tables are named (prefix or suffix) won’t matter – as long as they follow a standard and documented naming convention.

the naming conventions below are suggestive, the elements below require a specific standard naming convention.
6.1 entity naming conventions
6.1.1 hubs – either prefix with hub_ or suffix with _hub or the letter “h”
6.1.2 links – either prefix with lnk_ or suffix with _lnk or the letter “l”
6.1.3 satellites – either prefix with sat_ or suffix with _sat or the letter “s”
6.1.4 hierarchical links – prefix or suffix with hlnk or hier or hl, please note: hierarchical link is a form of a link with specific rules (see above), it is not a true entity class of its’ own.
6.1.5 same-as links – prefix or suffix with slnk, or sal, or sa. please note: same-as link is a form of a link with specific rules (see above), it is not a true entity class of its’ own.

6.2 field naming conventions
6.2.1 record source – rec_src or record_source or prefix/suffix with rcsrc or rsrc
6.2.2 sequence id’s – seq_id or sequence_id or prefix or suffix with sqn
6.2.3 date time stamps – prefix or suffix dts
6.2.4 date stamps – prefix or suffix with dt
6.2.5 time stamps – prefix or suffix with tm
6.2.6 load date time stamps – prefix or suffix with lddts
6.2.7 user (dbo/trigger) watch fields – prefix or suffix with usr
6.2.8 occurrence number – prefix or suffix with ocnum
6.2.9 end date time stamps – prefix or suffix with ledts

section 7.0 end dating styles
all styles may choose to use point in time satellites – can be used for end-date indicators, or load-date indicators – basically providing a snapshot of freshness when the information needs to be rolled together. this is a good technique when feeding the tables in a near-real-time (eai) fashion.
7.2 style 2: you may use a load_end_date or observation end date as an attribute in your satellites. the time between the load date and load end date is the time span indicating the life of the data.

section 8.0 avoiding outer joins
in all these styles the queries can get complex if outer-joins are required. to simplify, there are two styles of avoiding outer joins. the preference of most users is style 1.
8.1 style 1: insert an empty satellite record (null’s or default values for everything except the primary key, and record source) for every new hub key (if the satellite data is not available during that load window). this allows the queries to equi-join and avoid outer joins.
8.2 style 2: insert one empty satellite record with a pk surrogate key of zero. this requires some tricky logic in the query to join to because the keys no longer match, but provides a single “empty” satellite structure rather than replicating empty records for every hub key. this is not a preferred method.

depricated rules – do not use
end-dating styles
style 1: no end-dates, the time between consecutively keyed records’ load date time stamps is the time span for the life of the row, there is a problem with the satellites that doesn’t show until style 2 is utilized.
7.3 style 3: occurrence number in the primary key of a satellite. always keeping the occurrence number of the current record equal to zero. older records are numbered accordingly (most recent=1, further back=2 etc..)
***this requires updates to the satellites after loading, so that older rows get re-ordered. this notion is not typically utilized, as it causes severe hemmoraging at volume levels of data, or near zero latency of data, in fact, in the next revision of standards, this rule may is now phased out completely.

a link may not contain the same hub key more than once, unless used as a hierarchical definition. it may contain the same hub key twice if role based pk’s are setup (for instance, shipper_id is hub_customer_id and customer_id is also hub_customer_id)
*** this rule is wrong. role based keys cause problems with historical tracking or end-dating of satellites on the links. denormalizing the same key multiple times in a single link causes too many problems. please extract the links into multiple granularity.
** do not use going forward

Tags: , , ,

14 Responses to “DV Modeling Specification v1.0.9”

  1. ovidiu_t 2010/06/15 at 4:31 am #

    Hi Dan,

    When modeling good architecture in source systems, things pretty much fall into place.
    When hitting bad architecture, exceptions to DV rules come along.

    Suppose we have the following definition in a source system:

    Order (
    OrderId (PK),
    Client (
    ClientId (PK),
    Product (
    ProductId (PK),

    Everything is clear until the OrderLine is defined:
    OrderLine (
    OrderLineId (PK),
    There is no Unique Constraint on OrderId, ProductId. This means the system allows the same product to be placed more than once on an Order.
    Would this be an example of “bad architecture”?

    Modeling this into a Data Vault would result in something like:

    HUB_Client (SQN_Client)
    HUB_Product (SQN_Product)
    HUB_Order (SQN_Order)
    LNK_Order_Client (SQN_Order, SQN_Client)

    And now regarding OrderLine:
    1. Try to build the uniqueness of the link by adding the OrderLineId alongside the Order and Product

    LNK_Order_OrderLine (SQN_Order, SQN_Product, OrderLineId)

    Because we have here OrderLineId, in my opinion we break the guideline rule that a Link is a list of uniquely identified composite relationships between hub keys and must have 2 or more hubs or link keys combined.


    HUB_OrderLine (SQN_OrderLine)
    LNK_OrderLine_Order_Product (SQN_Order_Line, SQN_Order, SQN_Product)

    Here the order line is not a real standalone business entity and that breaks the rule regarding hub definition which states that in the hubs we need to have only business entities.

    I wonder what is the best approach. Are there other approaches you might consider?

    Thanks very much,

  2. dlinstedt 2010/06/17 at 6:26 am #

    Hi Ovidiu,

    This is generally reserved for coaching/training. These rules and concepts can be found in the Data Vault basics section, but they take quite a bit of explanation to understand. I call this a dependent child, and the line-item-number does belong in the Link table.

    Check out my coaching section for more information.

    Dan L

  3. Mandy 2010/08/18 at 5:00 pm #

    Hi Dan,

    How can we maintain history in Links? What if there are some relationships between the hubs that can change over period of time, can we use Load-End-Date to maintain history?

    Thank you in advance.


  4. dlinstedt 2010/08/18 at 7:10 pm #

    Hi Mandy,

    History directly in the Link violates the rules. No, we do not allow history to be maintained in the Link structures. I have a full lesson on this in the coaching area that explains why, what happens when you break the rules, and how to overcome this type of need. I also describe it in my technical modeling book (still in draft format inside the coaching area).

    The short answer to making this work is: use a Satellite called an Effectivity Satellite that allows you to set a status flag for a particular date combination.

    Never change the structure of the Link, if you do, you run the risk of re-engineering the model whenever a change comes down from the business.

    Hope this helps,
    Dan L
    PS: Check out coaching at: http://danLinstedt.com/my-coach

  5. rogierwerschkull 2010/10/14 at 5:04 am #

    Hi Dan, I have a question about the Satellite Rules:
    Is it required that every Hub record has at least 1 record in the corresponding sattelite or is it allowed that there are 0 records?

    I ask this question in relation with late arriving business keys / dimensional data:
    -One only knows the business key from a fact table, so the fact table to is the provider of the hub key
    -And then: do you insert a dummy record in the sattelite for the added hub key, or not?


  6. dlinstedt 2010/10/14 at 5:39 am #

    Hi Rogier,

    Thanks for registering, I appreciate it.

    I think it’s time for me to update the rules. No, it’s not required. In fact, Hubs are no longer required to have at least 1 Satellite either… That’s an optional guideline, a suggested guideline. And no, we do not require any dummy records for this reason.

    On the other hand, a “starter” dummy record in the Satellite generally makes the queries work with equi-joins. (especially if you already have other Sats on the Hub). If you have late-arriving data, then NO, I would not recommend using a dummy record at all. The dummy record is there as a “stop-gap” measure for joins, and for purposes of identifying keys that never seem to get any descriptive data, but when you think about it… they should appear in the queries anyhow with NULLS for the Sat info.

    Great question, thanks for the feedback. By the way, I will cover this in detail in the Coaching section as well. (more depth with examples of why/why not, and how to..)

    Dan L
    Check out my coaching site: http://danLinstedt.com/my-coach

  7. rogierwerschkull 2010/10/14 at 6:55 am #

    Hi Dan, thanks for the quick reply!

    While we’re onto it, I have another question about Link rules:
    In the datavault definition on wikipedia there is a sentence (I know, it’s wikipedia, but still):

    “Links sometimes link to only one Hub, a construct called ‘peg-legged Link’ by Dan Linstedt. This occurs when one of the business keys associated by the Link is not a real business key”

    Doen’t this contradict the “Link must have 2 or more hubs or link keys combined” rule?


  8. dlinstedt 2010/10/14 at 7:14 am #

    Yes it does, and if the Wikipedia entry was corrected, it would continue to read: Peg-Legged Links are not allowed! I think there are 2 situations (only 2 Data Vaults) that I’m aware of where this impossibility exists, and the reason is: because the data was simply TOO awful to create a clear business key. The end-user could even change the surrogate/pk in the source! just horrible…

    Dan Linstedt

  9. rogierwerschkull 2010/10/14 at 7:53 am #

    Ok, that’s clear…

    But, how then would you model the following scenario:

    I have a Trade (Hub and Satelite) that records multiple Fees per Trade (Unique key: Trade / Fee number). The Fee number is meaningless: it starts with number one for each trade. There is no other potential real Business key that would make the Fee records unique.

    Does ik make sense to make a Hub based on Fee Number? (It is not a real business key)
    If I indeed would model Fee number as an Hub I could make a Fee link table (with links to Hub Trade and Hub Fee number)

    But isn’t it better to make a Link that only Links to the Trade Hub and add the Fee Number to the Link to make it Unique? But that would create the not allowed Peg-legged Link…


  10. dlinstedt 2010/10/14 at 8:03 am #


    Thank-you kindly for your replies and questions, in order to fully answer your questions, please subscribe to the coaching area. This is typically the type of one-on-one service that I provide within the coaching area. it allows me to spend time, answering your questions with diagrams, downloads, best practices, and how-to’s. I appreciate the questions, they are very good questions – and require more time invested on my part to answer them accurately than I can give for free. If Centennium wishes to sign a corprate deal for access to my coaching site, I would be happy to work something out.

    Thank-you kindly,
    Dan Linstedt

  11. rogierwerschkull 2010/10/14 at 8:23 am #

    Ok Dan, thanks for your support so far.

    I’m going to look into that!

    Rogier Werschkull

  12. Alex 2014/09/23 at 5:47 am #

    “3.6 A Hub’s PRIMARY KEY cannot contain a record source.”
    >> What to do if an hub have several sources simultaneously, and business key is unique within each of them?

  13. Dan Linstedt 2014/09/23 at 8:12 am #

    I teach this in my DV2 boot camp and private certification classes. Soon, you’ll be able to get this information on-line in my class at http://LearnDataVault.com – sign up for the newsletters today, and get an early bird discount code when we do launch the class.

    By the way, the answer takes about 30 minutes or more to explain, it is not simple enough to post in a reply here.

    Dan L


  1. Data Vault Modeling | DWH-Consult - 2016/02/10

    […] English: DV-Modeling specification (DanLinstedt) […]

Leave a Reply