Data dependency

dbml-homepage/docs/docs.md

@@ -25,6 +25,7 @@ This part covers all constructs that define database structure and map directly
 - [TablePartial](#tablepartial)
 - [Data Sample](#data-sample)
   - [Data Types](#data-types)
+- [Data Lineage](#data-lineage)
 
 ## Project Definition
 
@@ -534,3 +535,68 @@ records users(id, name, age, status, created_at) {
   3, 'Charlie', , Status.pending, '2024-01-15'
 }
 ```
+
+## Data Lineage
+
+`Dep` lets you describe **data dependency** among tables and their columns. It allows you to model: Which tables (or columns) this table (or column) is computed from? Think of it like a SQL view where the view is computed from one or more source tables (or other views).
+
+A **dependency** syntax consists of 3 parts:
+- The **upstream** endpoint: The source table (or column) that data come from
+- The **downstream** endpoint: The destination table (or column) where the source data are processed and computed to derive a new value
+- An arrow (`<-` or `->`) pointing from the **upstream** endpoint to the **downstream** endpoint
+
+A **dependency** can be categorized into one of the two types:
+- Table-level dependency: Both the upstream endpoint and the downstream endpoint are tables.
+- Column-level dependency: Both the upstream endpoint and the downstream endpoint are columns.
+
+Note that both sides of an edge must be at the same level (table-to-table or column-to-column).
+
+```text
+/* Short form — separate from the table or column*/
+
+// `raw_orders` is the upstream table endpoint
+// `stg_orders` is the downstream table endpoint
+// `->` and `<-` always point from the upstream to the downstream
+Dep: raw_orders -> stg_orders
+Dep: stg_orders <- raw_orders
+
+// Column-level dependency
+Dep: raw_orders.amount -> stg_orders.revenue   // column-level
+
+/* Short form — on a table header or column */
+Table fct_orders [dep: <- stg_orders] {
+  id int
+  revenue decimal [dep: <- stg_orders.amount]
+}
+```
+
+### Dependency Block
+
+When a table is produced by a specific transformation step (e.g. a dbt model, a SQL view, or an ETL job), you can express this transformation using a dependency block:
+
+```
+/* Block form — group edges for a transformation step */
+Dep order_staging [color: #79AD51] {
+  raw_orders -> stg_orders
+  raw_payments -> stg_orders
+  raw_orders.amount -> stg_orders.revenue
+
+  note: 'Join orders with payments, compute revenue'
+  materialized: table
+  query: '''
+     Transformation query
+  '''
+  owner: 'data-team'
+}
+```
+
+Block settings:
+
+- `note`: description of the transformation. Supports [multi-line strings](./syntax/language-basics.md#multi-line-string).
+- `color`: lineage line color. See [Colors](./syntax/enrichment-visualization.md#colors).
+- Custom keys (e.g. `materialized`, `owner`) are preserved in the output.
+
+:::note
+- All edges in a block must target the **same downstream table**.
+- Each directed edge must be unique. Reversed pairs and different levels are considered distinct.
+:::

dbml-homepage/static/llms.txt

@@ -7,7 +7,7 @@ For the dbdiagram.io web app (diagrams, collaboration, API), see [dbdiagram docs
 ## Language and reference
 
 - [Home](https://dbml.dbdiagram.io/home): Overview, ecosystem, and links to tools.
-- [Core database markup](https://dbml.dbdiagram.io/docs): Tables, columns, relationships, indexes, enums, and other core syntax.
+- [Core database markup](https://dbml.dbdiagram.io/docs): Tables, columns, relationships (including optional and inactive refs), indexes, enums, records (sample data), data dependencies (Dep), and other core syntax.
 - [Enrichment and visualization](https://dbml.dbdiagram.io/syntax/enrichment-visualization): Notes, labels, colors, and display-oriented syntax like table groups, diagram views.
 - [Language basics](https://dbml.dbdiagram.io/syntax/language-basics): Core language constructs (strings, comments, and syntax conventions).
 

dbml-playground/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dbml/playground",
-  "version": "8.4.0-alpha.1",
+  "version": "9.0.0-alpha.21",
   "description": "Interactive playground for debugging and visualizing the DBML parser pipeline",
   "author": "Holistics <dev@holistics.io>",
   "license": "Apache-2.0",
@@ -25,8 +25,8 @@
     "format": "prettier --write src/"
   },
   "dependencies": {
-    "@dbml/core": "^8.4.0-alpha.1",
-    "@dbml/parse": "^8.4.0-alpha.1",
+    "@dbml/core": "^9.0.0-alpha.21",
+    "@dbml/parse": "^9.0.0-alpha.21",
     "@phosphor-icons/vue": "^2.2.0",
     "floating-vue": "^5.2.2",
     "lodash-es": "^4.17.21",

dbml-playground/src/components/panes/output/tabs/DatabaseTab.vue

@@ -234,6 +234,39 @@
           </div>
         </DbSection>
 
+        <!-- Deps -->
+        <DbSection
+          label="Deps"
+          :count="database.deps.length ?? 0"
+          :icon="PhArrowRight"
+          icon-color="text-orange-500"
+        >
+          <template
+            v-for="(dep, di) in database.deps"
+            :key="di"
+          >
+            <div
+              v-for="(edge, ei) in dep.edges"
+              :key="`${di}-${ei}`"
+              class="flex items-center gap-2 py-1 border-b border-gray-50 hover:bg-blue-50"
+              :style="{ paddingLeft: '20px', paddingRight: '12px' }"
+            >
+              <VTooltip
+                placement="right"
+                :distance="6"
+              >
+                <PhArrowRight class="w-3.5 h-3.5 text-orange-500 flex-shrink-0" />
+                <template #popper>
+                  <span class="text-xs">Dep</span>
+                </template>
+              </VTooltip>
+              <span class="text-blue-500">{{ depEndpointLabel(edge.upstream) }}</span>
+              <span class="text-gray-400">→</span>
+              <span class="text-blue-500">{{ depEndpointLabel(edge.downstream) }}</span>
+            </div>
+          </template>
+        </DbSection>
+
         <!-- Enums -->
         <DbSection
           label="Enums"
@@ -541,6 +574,7 @@ import {
   PhListBullets,
   PhArrowsLeftRight,
   PhArrowsDownUp,
+  PhArrowRight,
   PhTextAa,
   PhNumberSquareOne,
   PhFolder,
@@ -557,6 +591,7 @@ import TabSettingsButton from './common/TabSettingsButton.vue';
 import type { Database } from '@dbml/parse';
 
 type RefEndpoint = Database['refs'][number]['endpoints'][number];
+type DepEndpoint = NonNullable<Database['deps']>[number]['edges'][number]['upstream'];
 type IndexEntry = Database['tables'][number]['indexes'][number];
 
 import DbSection from './common/DbSection.vue';
@@ -594,7 +629,7 @@ const totalCount = computed(() => {
   const db = database;
   if (!db) return 0;
   const indexCount = db.tables.reduce((n, t) => n + t.indexes.length, 0);
-  return db.tables.length + indexCount + db.refs.length + db.enums.length
+  return db.tables.length + indexCount + db.refs.length + (db.deps?.length ?? 0) + db.enums.length
     + db.tableGroups.length + (db.records?.length ?? 0) + (db.tablePartials?.length ?? 0)
     + (db.notes?.length ?? 0) + (db.diagramViews?.length ?? 0) + externalsCount.value;
 });
@@ -720,4 +755,11 @@ function endpointLabel (ep: RefEndpoint): string {
   const fields = ep.fieldNames.length === 1 ? ep.fieldNames[0] : `(${ep.fieldNames.join(', ')})`;
   return ep.schemaName ? `${ep.schemaName}.${ep.tableName}.${fields}` : `${ep.tableName}.${fields}`;
 }
+
+function depEndpointLabel (ep: DepEndpoint): string {
+  const base = ep.schemaName ? `${ep.schemaName}.${ep.tableName}` : ep.tableName;
+  if (ep.fieldNames.length === 0) return base;
+  const fields = ep.fieldNames.length === 1 ? ep.fieldNames[0] : `(${ep.fieldNames.join(', ')})`;
+  return `${base}.${fields}`;
+}
 </script>

dbml-playground/src/services/sample-content.ts

@@ -30,12 +30,62 @@ export interface SampleCategory {
   readonly content: string;
 }
 
+export const DATA_LINEAGE_SAMPLE_CONTENT = `Table raw_orders {
+  id int [pk]
+  user_id int
+  amount decimal
+  created_at timestamp
+}
+
+Table stg_orders {
+  id int [pk]
+  user_id int
+  amount decimal
+}
+
+Table fct_orders {
+  id int [pk]
+  user_id int
+  revenue decimal
+}
+
+// Short form
+Dep: raw_orders -> stg_orders
+
+// Long form with custom attrs
+Dep {
+  stg_orders -> fct_orders
+
+  note: 'Aggregate staging orders into facts'
+  materialized: table
+  owner: 'data-team'
+}
+
+// Reverse direction (sugar — same edge as stg_orders -> fct_orders)
+Dep: fct_orders <- stg_orders
+
+// Column-level
+Dep {
+  stg_orders.amount -> fct_orders.revenue
+}
+
+// Inline on table header
+Table mart_orders [dep: <- fct_orders] {
+  id int [pk]
+  total decimal
+}`;
+
 export const SAMPLE_CATEGORIES: readonly SampleCategory[] = [
   {
     name: 'Basic Example',
     description: 'Simple tables with relationships',
     content: DEFAULT_SAMPLE_CONTENT,
   },
+  {
+    name: 'Data Lineage',
+    description: 'Dep blocks (data flow) — short, long, reverse, column-level, inline',
+    content: DATA_LINEAGE_SAMPLE_CONTENT,
+  },
   {
     name: 'E-commerce Schema',
     description: 'Complete e-commerce database with users, products, and orders',

lerna.json

@@ -1,5 +1,5 @@
 {
-  "version": "8.4.0-alpha.1",
+  "version": "9.0.0-alpha.21",
   "npmClient": "yarn",
   "$schema": "node_modules/lerna/schemas/lerna-schema.json"
 }

packages/dbml-cli/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@dbml/cli",
-  "version": "8.4.0-alpha.1",
+  "version": "9.0.0-alpha.21",
   "description": "",
   "main": "lib/index.js",
   "license": "Apache-2.0",
@@ -32,9 +32,9 @@
   ],
   "dependencies": {
     "@babel/cli": "^7.21.0",
-    "@dbml/connector": "^8.4.0-alpha.1",
-    "@dbml/core": "^8.4.0-alpha.1",
-    "@dbml/parse": "^8.4.0-alpha.1",
+    "@dbml/connector": "^9.0.0-alpha.21",
+    "@dbml/core": "^9.0.0-alpha.21",
+    "@dbml/parse": "^9.0.0-alpha.21",
     "bluebird": "^3.5.5",
     "chalk": "^2.4.2",
     "commander": "^2.20.0",

packages/dbml-connector/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@dbml/connector",
-  "version": "8.4.0-alpha.1",
+  "version": "9.0.0-alpha.21",
   "description": "This package was created to fetch the schema JSON from many kind of databases.",
   "author": "huy.phung.sw@gmail.com",
   "license": "MIT",

packages/dbml-core/__tests__/examples/model_exporter/dbml_exporter/input/dep.in.json

@@ -0,0 +1,46 @@
+{
+  "tables": [
+    {
+      "name": "raw_orders",
+      "fields": [
+        { "name": "id", "type": { "type_name": "int" }, "pk": true }
+      ]
+    },
+    {
+      "name": "stg_orders",
+      "fields": [
+        { "name": "id", "type": { "type_name": "int" }, "pk": true }
+      ]
+    },
+    {
+      "name": "fct_orders",
+      "fields": [
+        { "name": "id", "type": { "type_name": "int" }, "pk": true },
+        { "name": "amount", "type": { "type_name": "decimal" } }
+      ]
+    }
+  ],
+  "refs": [],
+  "enums": [],
+  "tableGroups": [],
+  "notes": [],
+  "records": [],
+  "tablePartials": [],
+  "deps": [
+    {
+      "schemaName": "public",
+      "edges": [
+        { "upstream": { "tableName": "raw_orders", "fieldNames": [] }, "downstream": { "tableName": "stg_orders", "fieldNames": [] } }
+      ]
+    },
+    {
+      "schemaName": "public",
+      "note": { "value": "Aggregate staging into facts" },
+      "metadata": { "materialized": "table", "owner": "data-team", "priority": 1 },
+      "edges": [
+        { "upstream": { "tableName": "stg_orders", "fieldNames": [] }, "downstream": { "tableName": "fct_orders", "fieldNames": [] } },
+        { "upstream": { "tableName": "stg_orders", "fieldNames": ["id"] }, "downstream": { "tableName": "fct_orders", "fieldNames": ["amount"] } }
+      ]
+    }
+  ]
+}

packages/dbml-core/__tests__/examples/model_exporter/dbml_exporter/output/dep.out.dbml

@@ -0,0 +1,24 @@
+Table "raw_orders" {
+  "id" int [pk]
+}
+
+Table "stg_orders" {
+  "id" int [pk]
+}
+
+Table "fct_orders" {
+  "id" int [pk]
+  "amount" decimal
+}
+
+Dep: "raw_orders" -> "stg_orders"
+
+Dep {
+  "stg_orders" -> "fct_orders"
+  "stg_orders"."id" -> "fct_orders"."amount"
+
+  note: 'Aggregate staging into facts'
+  materialized: 'table'
+  owner: 'data-team'
+  priority: 1
+}

packages/dbml-core/__tests__/examples/model_structure/dep.json

@@ -0,0 +1,43 @@
+{
+  "schemas": [],
+  "aliases": [],
+  "project": { "database_type": "Lineage", "name": "lineage_test" },
+  "tables": [
+    { "name": "raw_orders", "schemaName": "public", "fields": [{ "name": "id", "type": { "type_name": "int" }, "pk": true }] },
+    { "name": "stg_orders", "schemaName": "public", "fields": [{ "name": "id", "type": { "type_name": "int" }, "pk": true }] },
+    { "name": "fct_orders", "schemaName": "public", "fields": [{ "name": "id", "type": { "type_name": "int" }, "pk": true }, { "name": "amount", "type": { "type_name": "decimal" } }] },
+    { "name": "events", "schemaName": "analytics", "fields": [{ "name": "id", "type": { "type_name": "int" }, "pk": true }, { "name": "ts", "type": { "type_name": "timestamp" } }] }
+  ],
+  "refs": [],
+  "enums": [],
+  "tableGroups": [],
+  "notes": [],
+  "records": [],
+  "tablePartials": [],
+  "deps": [
+    {
+      "name": null,
+      "schemaName": "public",
+      "edges": [
+        { "upstream": { "schemaName": null, "tableName": "raw_orders", "fieldNames": [] }, "downstream": { "schemaName": null, "tableName": "stg_orders", "fieldNames": [] } }
+      ]
+    },
+    {
+      "name": null,
+      "schemaName": "public",
+      "note": { "value": "Aggregate staging into facts" },
+      "metadata": { "materialized": "table", "owner": "data-team" },
+      "edges": [
+        { "upstream": { "schemaName": null, "tableName": "stg_orders", "fieldNames": [] }, "downstream": { "schemaName": null, "tableName": "fct_orders", "fieldNames": [] } },
+        { "upstream": { "schemaName": null, "tableName": "stg_orders", "fieldNames": ["id"] }, "downstream": { "schemaName": null, "tableName": "fct_orders", "fieldNames": ["amount"] } }
+      ]
+    },
+    {
+      "name": null,
+      "schemaName": "public",
+      "edges": [
+        { "upstream": { "schemaName": "analytics", "tableName": "events", "fieldNames": ["ts"] }, "downstream": { "schemaName": "public", "tableName": "fct_orders", "fieldNames": ["id"] } }
+      ]
+    }
+  ]
+}