ScalefreeCOM/datavault4dbt-agent-skills

# Configuring datavault4dbt

Set up the [datavault4dbt](https://github.com/ScalefreeCOM/datavault4dbt) package and its global
variables before building any Data Vault models. Configuration is the prerequisite to every other
datavault4dbt task — get the hashing and naming standardized once, project-wide.

## 1. Install the package

`packages.yml`:

```yaml
packages:
  - package: ScalefreeCOM/datavault4dbt
    version: [">=1.9.0", "<2.0.0"]   # 1.9+ allows passing yaml_metadata directly (recommended)

# Rehashing datavault4dbt entities

When you change anything that affects hash output — the algorithm (`MD5`→`SHA2`), `hash_datatype`,
`hashdiff_use_trim`, or case-sensitivity vars — every hashkey and hashdiff in the Raw Data Vault must
change too, or referential integrity breaks. You have two options:

1. **Full refresh** the RDV (only if the full source history is still available to reload), or
2. **Rehash** existing entities in place with the package's rehashing macros (when history is *not*
   reloadable).

This skill is about option 2.

> **v1 → v2.0.0 upgrade.** v2.0.0 unifies/corrects hash standardization: with default settings,
> hashkeys are now `UPPER`-normalized and hashdiffs are no longer `UPPER`-normalized, plus

# Testing a datavault4dbt project

Turn the Primary-Key and Foreign-Key assumptions of Data Vault 2 into dbt tests. In DV2 these are
**soft constraints** — implemented as dbt tests that warn (and let you investigate) rather than
hard database constraints that would silently drop "bad and ugly" raw data you still want to capture.

**Default to soft constraints (dbt tests).** Only use hard database constraints if you accept the risk
of losing non-conforming raw data and have an Error Mart to catch it.

## Where these tests live

Add `data_tests` in the model's YAML file (colocated with the `.sql`). Generic tests `unique` and
`not_null` are built in; `relationships` covers FK integrity. For multi-column uniqueness (satellites)
use `dbt_utils.unique_combination_of_columns` (add the `dbt_utils` package) or an equivalent.

# Troubleshooting datavault4dbt

Diagnose datavault4dbt models by symptom. The package generates the SQL, so most issues trace back to
the **staging metadata** (hashkeys/hashdiffs), the **YAML parameters**, or **incremental/HWM** behavior.

## First moves

1. `dbt compile --select <model>` and read the generated SQL in `target/` — it shows exactly what the
   macro produced.
2. Enable verbose package logs: set `datavault4dbt.show_debug_logs: true` in `vars:` and re-run, then
   read the dbt `.log` file.
3. Inspect the staging output (`dbt show --select <stage_model> --limit 20`) — most raw-vault problems
   originate one layer up, in staging.

# Using datavault4dbt

[datavault4dbt](https://github.com/ScalefreeCOM/datavault4dbt) is a dbt package that generates Data
Vault 2.0 SQL from compact YAML metadata. You write a `{%- set yaml_metadata -%}` block and call a
macro; the package generates the insert-only loading logic, hashing, and high-water-mark optimization.

**Core principle:** every model is *staging-driven*. The `stage` macro computes the hashkeys and
hashdiffs once; hubs, links, and satellites then just reference those pre-computed columns. Get staging
right and the raw vault falls into place.

## When to use

- Building or editing datavault4dbt models: staging, hubs, links, satellites, PITs, snapshot control.
- Setting up a raw vault from flat source tables.