feat: add YML and MD documentation for all macros (#374)

macros/hooks/clean_up_pit.md

@@ -0,0 +1,29 @@
+{% docs clean_up_pit %}
+
+## Clean Up PIT (Post-Hook)
+
+This macro should be used as a post-hook for each PIT table whenever a logarithmic snapshot logic is used.
+The macro deletes all records in a PIT table that are no longer active according to the snapshot view.
+Deletion is safe here because no actual data is deleted — only pointers to satellite entries.
+
+### Usage as a post-hook
+
+```jinja
+{{ config(
+    post_hook="{{ datavault4dbt.clean_up_pit('control_snap_v1') }}"
+) }}
+```
+
+### With custom column names
+
+```jinja
+{{ config(
+    post_hook="{{ datavault4dbt.clean_up_pit(
+        snapshot_relation='control_snap_v1',
+        snapshot_trigger_column='is_active',
+        sdts='sdts'
+    ) }}"
+) }}
+```
+
+{% enddocs %}

macros/hooks/clean_up_pit.yml

@@ -0,0 +1,21 @@
+version: 2
+
+macros:
+  - name: clean_up_pit
+    description: '{{ doc("clean_up_pit") }}'
+    arguments:
+      - name: snapshot_relation
+        type: string
+        description: >
+          The name of the dbt model that creates the snapshot table / view that has the logarithmic snapshot
+          logic applied.
+      - name: snapshot_trigger_column
+        type: string
+        description: >
+          The name of the boolean column inside the snapshot tables that activates/deactivates single snapshots.
+          If not set, the name defined inside the global variable 'datavault4dbt.snapshot_trigger_column' is used.
+      - name: sdts
+        type: string
+        description: >
+          The name of the snapshot date timestamp column inside the snapshot table. If not set, the name defined
+          inside the global variable 'datavault4dbt.sdts_alias' is used.

macros/staging/stage.md

@@ -0,0 +1,57 @@
+{% docs stage %}
+
+## Stage
+
+Creates the staging layer for the Data Vault model. This layer is mainly for hashing, and additionally gives the
+option to create derived columns, conduct prejoins and add NULL values for missing columns. Always create one stage
+per source table that you want to add to the Data Vault model. The staging layer is not to harmonize data — that
+will be done in the later layers.
+
+### Usage
+
+```jinja
+{{ datavault4dbt.stage(
+    source_model='source_account',
+    ldts='edwLoadDate',
+    rsrc='!SAP.Accounts',
+    hashed_columns={
+        'hk_account_h': ['account_number', 'account_key'],
+        'hd_account_s': {
+            'is_hashdiff': true,
+            'columns': ['name', 'address', 'country', 'phone', 'email']
+        }
+    },
+    derived_columns={
+        'country_isocode': {'value': '!GER', 'datatype': 'STRING'}
+    }
+) }}
+```
+
+### Multi-active stage
+
+```jinja
+{{ datavault4dbt.stage(
+    source_model='source_contact_phones',
+    ldts='edwLoadDate',
+    rsrc='!CRM.ContactPhones',
+    hashed_columns={
+        'hk_contact_h': ['contact_id'],
+        'hd_contact_phonenumber_s': {
+            'is_hashdiff': true,
+            'columns': ['phone_type', 'phone_number']
+        }
+    },
+    multi_active_config={
+        'multi_active_key': 'phone_type',
+        'main_hashkey_column': 'hk_contact_h'
+    }
+) }}
+```
+
+### Metadata block usage
+
+```jinja
+{{ datavault4dbt.stage(yaml_metadata=meta) }}
+```
+
+{% enddocs %}

macros/staging/stage.yml

@@ -0,0 +1,82 @@
+version: 2
+
+macros:
+  - name: stage
+    description: '{{ doc("stage") }}'
+    arguments:
+      - name: yaml_metadata
+        type: dictionary
+        description: >
+          Optional. A YAML metadata block that passes all parameters as a single dictionary instead
+          of specifying each one directly in the macro call.
+      - name: ldts
+        type: string
+        description: >
+          Name of the column inside the source data, that holds information about the Load Date Timestamp.
+          Can also be a SQL expression.
+          Examples: 'edwLoadDate' (column name as-is),
+          'PARSE_TIMESTAMP('%Y-%m-%dT%H-%M-%S', edwLoadDate)' (applying a SQL function).
+      - name: rsrc
+        type: string
+        description: >
+          Name of the column inside the source data, that holds information about the Record Source. Can also
+          be a SQL expression or a static string. A static string must begin with a '!'.
+          Examples: 'edwRecordSource' (column), '!SAP.Accounts' (static string),
+          'CONCAT(source_system, '||', source_object)' (expression).
+      - name: source_model
+        type: string | dictionary
+        description: >
+          Can be just a string holding the name of the referred dbt model to use as a source. But if the 'source'
+          functionality inside the .yml file is used, it must be a dictionary with 'source_name': 'source_table'.
+          Examples: 'source_account' (model name), {'source_data': 'source_account'} (dbt source reference).
+      - name: include_source_columns
+        type: boolean
+        description: >
+          Defines if all columns from the referred source table should be included in the result table, or if only
+          the added columns should be part of the result table. By default the source columns should be included.
+      - name: hashed_columns
+        type: dictionary
+        description: >
+          Defines the names and input for all hashkeys and hashdiffs to create. The key of each hash column is
+          the name of the hash column. The value for Hashkeys is a list of input Business Keys; for Hashdiffs
+          another dictionary with the pairs 'is_hashdiff:true' and 'columns: <list of columns>'.
+          Example: {'hk_account_h': ['account_number', 'account_key'], 'hd_account_s': {'is_hashdiff': true, 'columns': ['name', 'address']}}.
+      - name: derived_columns
+        type: dictionary
+        description: >
+          Defines values and datatypes for derived ('added' or 'calculated') columns. The values of this dictionary
+          are the desired column names; the value is another dictionary with the keys 'value' (holding a column name,
+          a SQL expression, or a static string beginning with '!') and 'datatype' (holding a valid SQL datatype).
+          Example: {'country_isocode': {'value': '!GER', 'datatype': 'STRING'}}.
+      - name: sequence
+        type: string
+        description: >
+          Name of the column inside the source data, that holds a sequence number generated during data source
+          extraction. Optional and not required.
+          Example: 'edwSequence'.
+      - name: prejoined_columns
+        type: dictionary
+        description: >
+          Defines information about columns that need to be prejoined. Most commonly used to create links when
+          the source data does not hold the Business Key but the technical key of the referred object. For each
+          prejoined column define: 'src_name', 'src_table' (or 'ref_model'), 'bk', 'this_column_name',
+          'ref_column_name'.
+      - name: missing_columns
+        type: dictionary
+        description: >
+          If the schema of the source changes over time and columns are disappearing, this parameter gives you
+          the option to create additional columns holding NULL values. The dictionary holds the column names as
+          keys and the SQL datatypes as values.
+          Example: {'legacy_account_uuid': 'INT64', 'shipping_address': 'STRING'}.
+      - name: multi_active_config
+        type: dictionary
+        description: >
+          If the source data holds multi-active data, define here the column(s) holding the multi-active key and
+          the main hashkey column. The combination of multi-active key(s), the main hashkey and the ldts column
+          should be unique in the final result satellite. If not set, the stage will be treated as a single-active stage.
+          Example: {'multi_active_key': 'phonetype', 'main_hashkey_column': 'hk_contact_h'}.
+      - name: enable_ghost_records
+        type: boolean
+        description: >
+          If set to true, the stage will be created with ghost records. By default, ghost records are enabled.
+          Optional Parameter.

macros/tables/bigquery/control_snap_v0.yml

@@ -0,0 +1,21 @@
+version: 2
+
+macros:
+  - name: default__control_snap_v0
+    description: >
+      Default implementation of the control_snap_v0 macro, co-located in the bigquery adapter folder as BigQuery
+      uses this fallback via adapter.dispatch(). See the parent control_snap_v0 macro for full parameter
+      documentation.
+    arguments:
+      - name: start_date
+        type: timestamp
+        description: Earliest timestamp for the snapshot table. Time part must be '00:00:00'.
+      - name: daily_snapshot_time
+        type: time
+        description: Time that daily snapshots should have (e.g. '07:00:00').
+      - name: sdts_alias
+        type: string
+        description: Name of the snapshot date timestamp column. Optional, defaults to 'datavault4dbt.sdts_alias'.
+      - name: end_date
+        type: timestamp
+        description: Latest timestamp for the snapshot table. Optional.

macros/tables/bigquery/control_snap_v1.yml

@@ -0,0 +1,20 @@
+version: 2
+
+macros:
+  - name: bigquery__control_snap_v1
+    description: >
+      BigQuery-specific adapter implementation of the control_snap_v1 macro. Called automatically via
+      adapter.dispatch() when running on BigQuery. See the parent control_snap_v1 macro for full parameter
+      documentation.
+    arguments:
+      - name: control_snap_v0
+        type: string
+        description: The name of the underlying version 0 control snapshot table.
+      - name: log_logic
+        type: dictionary
+        description: >
+          Defining the desired durations of each granularity ('daily', 'weekly', 'monthly', 'yearly').
+          Optional — if not set, all snapshots remain active.
+      - name: sdts_alias
+        type: string
+        description: Name of the snapshot date timestamp column. Optional, defaults to 'datavault4dbt.sdts_alias'.

macros/tables/bigquery/eff_sat_v0.yml

@@ -0,0 +1,32 @@
+version: 2
+
+macros:
+  - name: default__eff_sat_v0
+    description: >
+      Default implementation of the eff_sat_v0 macro, co-located in the bigquery adapter folder as BigQuery uses
+      this fallback via adapter.dispatch(). See the parent eff_sat_v0 macro for full parameter documentation.
+    arguments:
+      - name: tracked_hashkey
+        type: string
+        description: Name of the hashkey column to be tracked.
+      - name: src_ldts
+        type: string
+        description: Name of the ldts column. Optional, defaults to 'datavault4dbt.ldts_alias'.
+      - name: src_rsrc
+        type: string
+        description: Name of the rsrc column. Optional, defaults to 'datavault4dbt.rsrc_alias'.
+      - name: is_active_alias
+        type: string
+        description: Name of the active flag column. Optional, defaults to 'datavault4dbt.is_active_alias'.
+      - name: source_model
+        type: string
+        description: Name of the source model.
+      - name: source_is_single_batch
+        type: boolean
+        description: REQUIRED. Whether the source contains only one batch. Must be explicitly set.
+      - name: disable_hwm
+        type: boolean
+        description: Whether the High Water Mark should be disabled. Optional.
+      - name: additional_columns
+        type: list | string
+        description: Additional columns to include. Optional, defaults to empty list.

macros/tables/bigquery/hub.yml

@@ -0,0 +1,29 @@
+version: 2
+
+macros:
+  - name: default__hub
+    description: >
+      Default implementation of the hub macro, co-located in the bigquery adapter folder as BigQuery uses
+      this fallback via adapter.dispatch(). See the parent hub macro for full parameter documentation.
+    arguments:
+      - name: hashkey
+        type: string
+        description: Name of the hashkey column inside the stage, used as PK of the Hub.
+      - name: business_keys
+        type: string | list of strings
+        description: Name(s) of the business key columns loaded into the hub.
+      - name: source_models
+        type: dictionary
+        description: Dictionary with information about the source models.
+      - name: src_ldts
+        type: string
+        description: Name of the ldts column. Optional, defaults to 'datavault4dbt.ldts_alias'.
+      - name: src_rsrc
+        type: string
+        description: Name of the rsrc column. Optional, defaults to 'datavault4dbt.rsrc_alias'.
+      - name: disable_hwm
+        type: boolean
+        description: Whether the High Water Mark should be turned off. Optional, default False.
+      - name: additional_columns
+        type: list | string
+        description: Additional columns to include in the Hub. Optional, defaults to empty list.

macros/tables/bigquery/link.yml

@@ -0,0 +1,29 @@
+version: 2
+
+macros:
+  - name: default__link
+    description: >
+      Default implementation of the link macro, co-located in the bigquery adapter folder as BigQuery uses
+      this fallback via adapter.dispatch(). See the parent link macro for full parameter documentation.
+    arguments:
+      - name: link_hashkey
+        type: string
+        description: Name of the link hashkey column inside the stage.
+      - name: foreign_hashkeys
+        type: list of strings
+        description: List of all hashkey columns inside the link that refer to other hub entities.
+      - name: source_models
+        type: dictionary
+        description: Dictionary with information about the source models.
+      - name: src_ldts
+        type: string
+        description: Name of the ldts column. Optional, defaults to 'datavault4dbt.ldts_alias'.
+      - name: src_rsrc
+        type: string
+        description: Name of the rsrc column. Optional, defaults to 'datavault4dbt.rsrc_alias'.
+      - name: disable_hwm
+        type: boolean
+        description: Whether the High Water Mark should be turned off. Optional, default False.
+      - name: additional_columns
+        type: list | string
+        description: Additional columns to include in the Link. Optional, defaults to empty list.

macros/tables/bigquery/ma_sat_v0.yml

@@ -0,0 +1,39 @@
+version: 2
+
+macros:
+  - name: default__ma_sat_v0
+    description: >
+      Default implementation of the ma_sat_v0 macro, co-located in the bigquery adapter folder as BigQuery uses
+      this fallback via adapter.dispatch(). Uses QUALIFY for intra-batch deduplication.
+      See the parent ma_sat_v0 macro for full parameter documentation.
+    arguments:
+      - name: parent_hashkey
+        type: string
+        description: Name of the hashkey column of the parent hub or link.
+      - name: src_hashdiff
+        type: string
+        description: Name of the hashdiff column for this satellite.
+      - name: src_ma_key
+        type: string | list of strings
+        description: Name(s) of the multi-active key column(s).
+      - name: src_payload
+        type: list of strings
+        description: List of descriptive attribute columns (excluding the multi-active key).
+      - name: src_ldts
+        type: string
+        description: Name of the ldts column. Optional, defaults to 'datavault4dbt.ldts_alias'.
+      - name: src_rsrc
+        type: string
+        description: Name of the rsrc column. Optional, defaults to 'datavault4dbt.rsrc_alias'.
+      - name: source_model
+        type: string
+        description: Name of the underlying staging model.
+      - name: additional_columns
+        type: list | string
+        description: Additional columns to include. Optional, defaults to empty list.
+      - name: disable_hwm
+        type: boolean
+        description: Whether the High Water Mark should be turned off. Optional, default False.
+      - name: source_is_single_batch
+        type: boolean
+        description: Whether the source contains only one batch. Skips QUALIFY deduplication. Optional, default False.