ProjectDataHopper · mattcasters · Aug 27, 2026 · Aug 27, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,13 @@ All notable changes to Data Hopper EDW (formerly hop-datavault) are documented i
 
 ## Unreleased
 
+### Read-only existing Data Vault models
+
+- Data Vault configuration checkbox **Read-only existing vault** documents an already-built raw vault so Business Vault and dimensional models can sit on top
+- Data Vault Update, Generate DDL, and Debug are refused; Update resource definition group skips that `.hdv` and continues BV/DM
+- Model check keeps referential integrity only (hash keys, parent hubs/links, names, attributes) and does not require record sources or load settings
+- Use a dedicated configuration object; per-table **External read-only** remains the mixed-ownership mode
+
 ### BV SCD2 does not read omitted satellite record-source columns (issue #138)
 
 - Generated SCD2 satellite `TableInput` SQL omits the vault record-source / source-indicator column when **Store record source indicator** is off on that satellite

diff --git a/docs/ai-file-schemas/models/hdv.md b/docs/ai-file-schemas/models/hdv.md
@@ -25,7 +25,7 @@ Visual **raw Data Vault 2.0** model: hubs, links, satellites, physical **referen
 |---------|------|
 | `name_sync_with_filename` | Y/N — keep model name aligned with file basename |
 | `description` | Free text |
-| `configuration` | Target DB, hash algorithm/type, load/record-source fields, bulk options, PK/FK flags |
+| `configuration` | Target DB, hash algorithm/type, load/record-source fields, bulk options, PK/FK flags, optional `readOnlyExistingVault` |
 | `coaching` | Optional coach-panel sources |
 | `tables` / `table` | Polymorphic vault objects |
 | `notes` / `note` | Canvas documentation only |

diff --git a/docs/business-vault-overview.adoc b/docs/business-vault-overview.adoc
@@ -77,7 +77,9 @@ Business Vault **reads** hub and satellite history from the Data Vault target da
 
 When raw vault tables are loaded outside Hop (dbt, SQL, custom ETL), set **Integration mode** to **External read-only** on the DV table. Business Vault SCD2 generation still works as long as the `.hdv` metadata accurately describes the warehouse tables.
 
-See link:dv-integration-modes.adoc[Data Vault integration modes].
+To document a **whole** existing raw vault and only build Business Vault and dimensional layers in Hop, enable **Read-only existing vault** on a dedicated Data Vault configuration instead. Model the hubs, links, and satellites (hash keys, parents, attributes, table names) without record sources; Hop will not load or alter those tables.
+
+See link:dv-integration-modes.adoc[Data Vault integration modes] and link:datavault-configuration.adoc[Data Vault configuration].
 
 == Sample models
 

diff --git a/docs/datavault-configuration.adoc b/docs/datavault-configuration.adoc
@@ -39,7 +39,10 @@ Target database and hashing strategy.
 |Option |Description
 
 |Target database
-|The Hop database connection (DatabaseMeta) where Data Vault tables are created and loaded. Used for DDL generation, SQL quoting, and all generated pipelines that write to the vault.
+|The Hop database connection where Data Vault tables live. Hop-managed models create and load tables here. Read-only existing vaults only read from this connection (Business Vault and dimensional loads).
+
+|Read-only existing vault
+|When enabled, every `.hdv` that uses this configuration **documents** an already-built raw vault. Hop refuses Data Vault Update, Generate DDL, and Debug. Model check keeps referential integrity only (hash keys, parent hubs/links, names, attributes). Use a **dedicated** configuration object — do not share it with Hop-managed models. Mixed tables in one file still use per-table link:dv-integration-modes.adoc[External read-only].
 
 |Hash algorithm
 |Algorithm for surrogate hash keys (MD5, SHA-256, SHA-1, SHA-512). Affects computation and maximum key length.
@@ -285,8 +288,9 @@ There is no longer a separate per-table "configuration picker" metadata referenc
 
 == How the configuration affects daily work
 
-* The target database connection is required for **Generate DDL**, **Debug**, and the **Data Vault Update** action. Business Vault SCD2 generation also reads satellite history from this connection when a `.hbv` model links to the `.hdv` file.
-* Tables marked **External read-only** do not require Hop to load data, but the target database name must still be set so downstream features can resolve the connection. See link:dv-integration-modes.adoc[Data Vault integration modes].
+* The target database connection is required for **Generate DDL**, **Debug**, and the **Data Vault Update** action on Hop-managed models. Business Vault SCD2 generation also reads satellite history from this connection when a `.hbv` model links to the `.hdv` file.
+* **Read-only existing vault** refuses those load/DDL actions. The target database name must still be set so Business Vault and dimensional models can read the documented tables. See link:dv-integration-modes.adoc[Data Vault integration modes].
+* Tables marked **External read-only** do not require Hop to load data, but the target database name must still be set so downstream features can resolve the connection.
 * Hash algorithm and data type directly influence storage size and join performance.
 * Naming settings (LOAD_DATE, RECORD_SOURCE, etc.) should be agreed early with consumers of the Data Vault.
 * Unknown and invalid sentinel settings matter when downstream facts or links must reference "missing" or "bad" keys.

diff --git a/docs/datavault-update-action.adoc b/docs/datavault-update-action.adoc
@@ -8,6 +8,8 @@ toc::[]
 
 The **Data Vault Update** workflow action is the main way to load a complete Data Vault model in Apache Hop. You point it at a saved Data Vault Model (`.hdv` file), choose a pipeline run configuration, and the action takes care of the rest.
 
+If the model's Data Vault configuration has **Read-only existing vault** enabled, the action **fails immediately** after loading the model. Hop will not generate DDL, insert sentinels, or run load pipelines. Document the `.hdv` for Business Vault and dimensional layers instead; use **Update resource definition group** to skip that Data Vault job and continue BV/DM.
+
 At runtime the action:
 
 * Loads the model from the `.hdv` file.

diff --git a/docs/dv-integration-modes.adoc b/docs/dv-integration-modes.adoc
@@ -6,6 +6,8 @@ toc::[]
 
 Every hub, link, and satellite in a `.hdv` model has an **integration mode** that controls how Hop treats the physical table in the warehouse.
 
+To document an **entire** existing raw vault (Hop must not load or alter any table) use **Read-only existing vault** on the Data Vault configuration instead of setting External read-only on every card. See link:datavault-configuration.adoc[Data Vault configuration]. That flag refuses Data Vault Update, Generate DDL, and Debug, and model check keeps referential integrity only so Business Vault and dimensional models can sit on top. Per-table External read-only remains the mixed-ownership mode (Hop still runs Update and skips those tables).
+
 Integration mode is set on the **Options** tab of the hub, link, or satellite dialog (combo: *Hop managed*, *External read-only*, *Custom pipelines*).
 
 == Why integration modes exist

diff --git a/docs/feature-overview.adoc b/docs/feature-overview.adoc
@@ -302,7 +302,7 @@ image::images/search-panel-model-results.png[Search panel — Data Vault model m
 
 === Raw Data Vault (`.hdv`)
 
-Visual modeler for hubs, links, and satellites with embedded configuration (target database, hashing, sentinels, column names, pipeline options). Toolbar actions: **Edit model**, **Import sources**, **Check model**, **Generate DDL**, **Debug**, optional **AI Help**.
+Visual modeler for hubs, links, and satellites with embedded configuration (target database, hashing, sentinels, column names, pipeline options). Toolbar actions: **Edit model**, **Import sources**, **Check model**, **Generate DDL**, **Debug**, optional **AI Help**. A configuration **Read-only existing vault** checkbox documents an already-built vault so Business Vault and dimensional models can sit on top without Hop loading or altering those tables.
 
 **Data Vault Update** workflow action validates (optionally), generates DDL, stages update pipelines, and runs them in parallel with a shared load timestamp.
 

diff --git a/docs/help/dv-model-dialog.adoc b/docs/help/dv-model-dialog.adoc
@@ -20,7 +20,8 @@ There is one target database per configuration. Table dialogs can still override
 
 Target database and hashing strategy.
 
-- **Target database** — Hop connection where vault tables are created and loaded (DDL, quoting, generated pipelines). Required for Generate DDL, Debug, and Data Vault Update.
+- **Target database** — Hop connection where vault tables live. Hop-managed models create and load here; read-only existing vaults only read from it (Business Vault and dimensional loads). Required for Generate DDL, Debug, and Data Vault Update on Hop-managed models.
+- **Read-only existing vault** — Documents an already-built raw vault. Hop refuses Data Vault Update, Generate DDL, and Debug. Model check keeps referential integrity only. Use a dedicated configuration; do not share it with Hop-managed models.
 - **Data catalog connection** — Optional catalog used when resolving `DV_SOURCE` feeds for this model.
 - **Hash algorithm** — Surrogate key algorithm (MD5, SHA-256, SHA-1, SHA-512).
 - **Hash key data type** — Physical storage: HEX (default), STRING, or BINARY. BINARY needs Hop 2.19.0+ for correct sort order.

diff --git a/docs/update-resource-definition-group-action.adoc b/docs/update-resource-definition-group-action.adoc
@@ -16,6 +16,8 @@ The **Update resource definition group** workflow action loads every Data Vault
 
 Each model runs through the same update path as the dedicated **Data Vault Update** / **Business Vault Update** / **Dimensional Update** actions (model check options, DDL policy, parallel pipeline copies, optional catalog publish).
 
+If a listed `.hdv` uses a **read-only existing vault** configuration, that Data Vault job is **skipped** (logged) so Business Vault and dimensional updates still run. A standalone Data Vault Update action pointed at the same file still errors.
+
 Optionally the action **manages vault update metrics** for the whole wave: it assigns `DV_WORKFLOW_EXECUTION_ID` at the start (Begin-style) and publishes a workflow load overview at the end (End-style). You do not need separate Begin/End Vault Update actions or hand-wired per-model hops for a standard multi-layer load.
 
 Retail example workflows `run-retail-update.hwf` and `run-retail-update-models.hwf` use this action with group **`retail-sources`**.

diff --git a/src/main/java/org/hopper/edw/catalog/ddl/CatalogTableDdlSupport.java b/src/main/java/org/hopper/edw/catalog/ddl/CatalogTableDdlSupport.java
@@ -16,8 +16,6 @@
 package org.hopper.edw.catalog.ddl;
 
 import java.util.List;
-import org.hopper.edw.catalog.model.PhysicalTableRef;
-import org.hopper.edw.catalog.model.RecordDefinition;
 import org.apache.hop.core.Const;
 import org.apache.hop.core.database.Database;
 import org.apache.hop.core.database.DatabaseMeta;
@@ -27,6 +25,8 @@
 import org.apache.hop.core.row.IRowMeta;
 import org.apache.hop.core.util.Utils;
 import org.apache.hop.core.variables.IVariables;
+import org.hopper.edw.catalog.model.PhysicalTableRef;
+import org.hopper.edw.catalog.model.RecordDefinition;
 import org.hopper.edw.datavault.catalog.DvSourceFieldSupport;
 import org.hopper.edw.datavault.metadata.DvDdlSupport;
 import org.hopper.edw.datavault.metadata.SourceField;

diff --git a/src/main/java/org/hopper/edw/catalog/discovery/PhysicalSourceRef.java b/src/main/java/org/hopper/edw/catalog/discovery/PhysicalSourceRef.java
@@ -17,13 +17,13 @@
 
 import java.util.regex.Pattern;
 import org.apache.commons.vfs2.FileObject;
-import org.hopper.edw.catalog.model.PhysicalIcebergTableRef;
 import org.apache.hop.core.Const;
 import org.apache.hop.core.exception.HopException;
 import org.apache.hop.core.util.Utils;
 import org.apache.hop.core.variables.IVariables;
 import org.apache.hop.core.vfs.HopVfs;
 import org.apache.hop.i18n.BaseMessages;
+import org.hopper.edw.catalog.model.PhysicalIcebergTableRef;
 
 /** Resolved physical location used for record-definition schema discovery. */
 public final class PhysicalSourceRef {

diff --git a/src/main/java/org/hopper/edw/catalog/discovery/RecordDefinitionCatalogRefreshSupport.java b/src/main/java/org/hopper/edw/catalog/discovery/RecordDefinitionCatalogRefreshSupport.java
@@ -17,18 +17,18 @@
 
 import java.util.Date;
 import java.util.List;
+import org.apache.hop.core.exception.HopException;
+import org.apache.hop.core.variables.IVariables;
+import org.apache.hop.i18n.BaseMessages;
+import org.apache.hop.metadata.api.IHopMetadataProvider;
 import org.hopper.edw.catalog.model.CatalogCustomProperty;
 import org.hopper.edw.catalog.model.RecordDefinition;
 import org.hopper.edw.catalog.model.RecordOrigin;
-import org.apache.hop.core.exception.HopException;
-import org.apache.hop.core.variables.IVariables;
 import org.hopper.edw.datavault.catalog.DvSourceFieldSupport;
 import org.hopper.edw.datavault.metadata.DvSourceType;
 import org.hopper.edw.datavault.metadata.SourceField;
 import org.hopper.edw.datavault.metadata.iceberg.IcebergConnectionSettings;
 import org.hopper.edw.datavault.metadata.iceberg.IcebergTableMetadataDiscovery;
-import org.apache.hop.i18n.BaseMessages;
-import org.apache.hop.metadata.api.IHopMetadataProvider;
 
 /** Re-discovers physical source schemas and refreshes catalog record-definition contracts. */
 public final class RecordDefinitionCatalogRefreshSupport {

diff --git a/src/main/java/org/hopper/edw/catalog/discovery/RecordDefinitionCatalogWriter.java b/src/main/java/org/hopper/edw/catalog/discovery/RecordDefinitionCatalogWriter.java
@@ -17,17 +17,19 @@
 
 import java.util.Date;
 import org.apache.commons.vfs2.FileObject;
+import org.apache.hop.core.exception.HopException;
+import org.apache.hop.core.util.Utils;
+import org.apache.hop.core.variables.IVariables;
+import org.apache.hop.core.vfs.HopVfs;
+import org.apache.hop.i18n.BaseMessages;
+import org.apache.hop.metadata.api.IHopMetadataProvider;
 import org.hopper.edw.catalog.model.DvCsvFormatRecord;
 import org.hopper.edw.catalog.model.PhysicalTableRef;
 import org.hopper.edw.catalog.model.RecordDefinition;
 import org.hopper.edw.catalog.model.RecordDefinitionKey;
 import org.hopper.edw.catalog.model.RecordDefinitionType;
 import org.hopper.edw.catalog.model.RecordOrigin;
 import org.hopper.edw.catalog.registry.RecordDefinitionRegistry;
-import org.apache.hop.core.exception.HopException;
-import org.apache.hop.core.util.Utils;
-import org.apache.hop.core.variables.IVariables;
-import org.apache.hop.core.vfs.HopVfs;
 import org.hopper.edw.datavault.catalog.CatalogModelRegistrySupport;
 import org.hopper.edw.datavault.catalog.DvSourceCatalogMapper;
 import org.hopper.edw.datavault.catalog.DvSourceFieldSupport;
@@ -44,8 +46,6 @@
 import org.hopper.edw.datavault.metadata.file.DvParquetSource;
 import org.hopper.edw.datavault.metadata.file.IDvFileBasedSource;
 import org.hopper.edw.datavault.metadata.iceberg.DvIcebergSource;
-import org.apache.hop.i18n.BaseMessages;
-import org.apache.hop.metadata.api.IHopMetadataProvider;
 
 /** Persists discovered record definitions to a data catalog connection. */
 public final class RecordDefinitionCatalogWriter {

diff --git a/src/main/java/org/hopper/edw/catalog/discovery/RecordDefinitionDiscoveryService.java b/src/main/java/org/hopper/edw/catalog/discovery/RecordDefinitionDiscoveryService.java
@@ -28,6 +28,8 @@
 import org.apache.hop.core.row.IValueMeta;
 import org.apache.hop.core.util.Utils;
 import org.apache.hop.core.variables.IVariables;
+import org.apache.hop.i18n.BaseMessages;
+import org.apache.hop.metadata.api.IHopMetadataProvider;
 import org.hopper.edw.datavault.metadata.DvSourceType;
 import org.hopper.edw.datavault.metadata.SourceField;
 import org.hopper.edw.datavault.metadata.database.DvDatabaseSourceImportSupport;
@@ -41,8 +43,6 @@
 import org.hopper.edw.datavault.metadata.sourcemodel.SourceQuery;
 import org.hopper.edw.datavault.metadata.sourcemodel.publish.SourcePipelineCatalogPublisher;
 import org.hopper.edw.datavault.metadata.sourcemodel.publish.SourceQueryCatalogPublisher;
-import org.apache.hop.i18n.BaseMessages;
-import org.apache.hop.metadata.api.IHopMetadataProvider;
 
 /** Discovers field layouts from physical database tables and file sources. */
 public final class RecordDefinitionDiscoveryService {

diff --git a/src/main/java/org/hopper/edw/catalog/discovery/RecordDefinitionPhysicalRefSupport.java b/src/main/java/org/hopper/edw/catalog/discovery/RecordDefinitionPhysicalRefSupport.java
@@ -15,16 +15,16 @@
  */
 package org.hopper.edw.catalog.discovery;
 
+import org.apache.hop.core.exception.HopException;
+import org.apache.hop.core.util.Utils;
+import org.apache.hop.i18n.BaseMessages;
 import org.hopper.edw.catalog.model.DvSourceRecord;
 import org.hopper.edw.catalog.model.PhysicalFileRef;
 import org.hopper.edw.catalog.model.PhysicalIcebergTableRef;
 import org.hopper.edw.catalog.model.PhysicalTableRef;
 import org.hopper.edw.catalog.model.RecordDefinition;
 import org.hopper.edw.catalog.model.RecordDefinitionType;
-import org.apache.hop.core.exception.HopException;
-import org.apache.hop.core.util.Utils;
 import org.hopper.edw.datavault.metadata.DvSourceType;
-import org.apache.hop.i18n.BaseMessages;
 
 /** Builds physical discovery references from catalog record definitions. */
 public final class RecordDefinitionPhysicalRefSupport {

diff --git a/src/main/java/org/hopper/edw/catalog/discovery/RecordDefinitionSchemaDiffSupport.java b/src/main/java/org/hopper/edw/catalog/discovery/RecordDefinitionSchemaDiffSupport.java
@@ -22,9 +22,9 @@
 import java.util.Map;
 import org.apache.hop.core.Const;
 import org.apache.hop.core.util.Utils;
+import org.apache.hop.i18n.BaseMessages;
 import org.hopper.edw.datavault.metadata.SourceField;
 import org.hopper.edw.datavault.metadata.SourceFieldPrimaryKeySupport;
-import org.apache.hop.i18n.BaseMessages;
 
 /** Compares stored catalog field contracts against freshly discovered source fields. */
 public final class RecordDefinitionSchemaDiffSupport {

diff --git a/src/main/java/org/hopper/edw/catalog/discovery/SourceFieldMetadataEquivalenceSupport.java b/src/main/java/org/hopper/edw/catalog/discovery/SourceFieldMetadataEquivalenceSupport.java
@@ -20,10 +20,10 @@
 import org.apache.hop.core.Const;
 import org.apache.hop.core.row.IValueMeta;
 import org.apache.hop.core.util.Utils;
+import org.apache.hop.i18n.BaseMessages;
 import org.hopper.edw.datavault.metadata.DvDataTypeSupport;
 import org.hopper.edw.datavault.metadata.DvSqlStringTypeSupport;
 import org.hopper.edw.datavault.metadata.SourceField;
-import org.apache.hop.i18n.BaseMessages;
 
 /**
  * Compares {@link SourceField} length/precision using Hop value-meta semantics.

diff --git a/src/main/java/org/hopper/edw/catalog/harvest/SchemaHarvestApplyGuiSupport.java b/src/main/java/org/hopper/edw/catalog/harvest/SchemaHarvestApplyGuiSupport.java
@@ -15,22 +15,11 @@
  */
 package org.hopper.edw.catalog.harvest;
 
-import org.hopper.edw.catalog.harvest.SchemaHarvestCatalogApplySupport.ApplyOptions;
-import org.hopper.edw.catalog.harvest.SchemaHarvestCatalogApplySupport.ApplyResult;
-import org.hopper.edw.catalog.harvest.SchemaHarvestModels.HarvestResult;
-import org.hopper.edw.catalog.harvest.SchemaHarvestSourceModelGenerator.GenerateOptions;
-import org.hopper.edw.catalog.harvest.SchemaHarvestSourceModelGenerator.GenerateResult;
-import org.hopper.edw.catalog.harvest.history.SchemaHarvestHistoryPublisher;
-import org.hopper.edw.catalog.harvest.history.SchemaHarvestHistoryReader;
-import org.hopper.edw.catalog.harvest.history.SchemaHarvestHistoryReader.HistoryConnection;
-import org.hopper.edw.catalog.metadata.ResourceDefinitionGroupMeta;
 import org.apache.hop.core.Const;
 import org.apache.hop.core.database.DatabaseMeta;
 import org.apache.hop.core.exception.HopException;
 import org.apache.hop.core.util.Utils;
 import org.apache.hop.core.variables.IVariables;
-import org.hopper.edw.datavault.metadata.sourcemodel.SourceModel;
-import org.hopper.edw.datavault.metadata.sourcemodel.SourceModelLoadSupport;
 import org.apache.hop.i18n.BaseMessages;
 import org.apache.hop.metadata.api.IHopMetadataProvider;
 import org.apache.hop.ui.core.dialog.EnterSelectionDialog;
@@ -40,6 +29,17 @@
 import org.eclipse.swt.SWT;
 import org.eclipse.swt.widgets.MessageBox;
 import org.eclipse.swt.widgets.Shell;
+import org.hopper.edw.catalog.harvest.SchemaHarvestCatalogApplySupport.ApplyOptions;
+import org.hopper.edw.catalog.harvest.SchemaHarvestCatalogApplySupport.ApplyResult;
+import org.hopper.edw.catalog.harvest.SchemaHarvestModels.HarvestResult;
+import org.hopper.edw.catalog.harvest.SchemaHarvestSourceModelGenerator.GenerateOptions;
+import org.hopper.edw.catalog.harvest.SchemaHarvestSourceModelGenerator.GenerateResult;
+import org.hopper.edw.catalog.harvest.history.SchemaHarvestHistoryPublisher;
+import org.hopper.edw.catalog.harvest.history.SchemaHarvestHistoryReader;
+import org.hopper.edw.catalog.harvest.history.SchemaHarvestHistoryReader.HistoryConnection;
+import org.hopper.edw.catalog.metadata.ResourceDefinitionGroupMeta;
+import org.hopper.edw.datavault.metadata.sourcemodel.SourceModel;
+import org.hopper.edw.datavault.metadata.sourcemodel.SourceModelLoadSupport;
 
 /**
  * GUI entry points for applying harvest results to catalog contracts and generating .hsm models.