Skip to content

Commit 04a269a

Browse files
youngsofunyoungsofun
committed
docs: add data lineage documentation (databend#20417)
1 parent e24d13c commit 04a269a

15 files changed

Lines changed: 659 additions & 3 deletions

File tree

‎docs/cn/guides/20-self-hosted/04-references/node-config/query-config.md‎

Lines changed: 20 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ import FunctionDescription from '@site/src/components/FunctionDescription';
66
import LanguageDocs from '@site/src/components/LanguageDocs';
77
import DetailsWrap from '@site/src/components/DetailsWrap';
88

9-
<FunctionDescription description="引入或更新：v1.2.901"/>
9+
<FunctionDescription description="引入或更新：v1.2.935"/>
1010

1111
本页介绍 [databend-query.toml](https://github.com/databendlabs/databend/blob/main/scripts/distribution/configs/databend-query.toml) 配置文件中可用的 Query 节点配置。
1212

@@ -77,6 +77,25 @@ on = true
7777
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
7878
| on | 是否在 Databend Query 节点上启用私有化 Task 调度与执行，默认为 `false`。 |
7979

80+
## [lineage] 部分
81+
82+
使用 `[lineage]` 配置捕获并持久化对象级和列级数据血缘：
83+
84+
```toml
85+
[lineage]
86+
on = true
87+
# retention = 720
88+
```
89+
90+
请在所有 Query 节点上使用相同配置，并在修改配置后重启节点。启用数据血缘后，Databend 会自动配置内部历史存储；不要将 `lineage_history` 添加到 `[log.history.tables]`。
91+
92+
| 参数 | 描述 |
93+
|------|------|
94+
| on | 是否启用血缘捕获和持久化，默认为 `false`。 |
95+
| retention | 可选的 DML 血缘保留时长，单位为小时。省略时永久保留血缘。 |
96+
97+
有关使用方法，请参见[数据血缘](/guides/data-management/data-lineage)。
98+
8099
## [log] 部分
81100

82101
该部分可包含以下子部分：[log.file]、[log.stderr]、[log.query] 和 [log.tracing]。

‎docs/cn/guides/57-data-management/05-data-lineage.md‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
---
2+
title: 数据血缘
3+
---
4+
5+
import FunctionDescription from '@site/src/components/FunctionDescription';
6+
7+
<FunctionDescription description="引入或更新：v1.2.935"/>
8+
9+
数据血缘用于展示数据如何从源对象流向目标对象。你可以使用数据血缘了解对象依赖关系、评估变更影响、排查数据管道问题，以及将派生列追溯到其源列。
10+
11+
Databend 会记录对象级和列级关系：
12+
13+
- **上游血缘（Upstream Lineage）**：标识为当前对象提供数据的表、视图或 Stage。
14+
- **下游血缘（Downstream Lineage）**：标识使用当前对象数据的其他对象。
15+
- **列级血缘（Column Lineage）**：展示源列到派生目标列的映射关系。
16+
17+
![Databend Cloud 中的表级和列级血缘](/img/guides/data-lineage.png)
18+
19+
## 启用数据血缘
20+
21+
对于提供 **Lineage** 页签的 Databend Cloud Warehouse，血缘配置由服务管理。私有化部署需要在每个 Query 节点的 `databend-query.toml` 中添加以下配置，然后重启节点：
22+
23+
```toml title="databend-query.toml"
24+
[lineage]
25+
on = true
26+
```
27+
28+
默认情况下，血缘历史会永久保留。如需设置固定的保留时长，可通过 `retention` 指定小时数，例如：
29+
30+
```toml title="databend-query.toml"
31+
[lineage]
32+
on = true
33+
retention = 720
34+
```
35+
36+
请仅使用专用的 `[lineage]` 配置，不要将内部表 `lineage_history` 添加到 `[log.history.tables]`。完整配置说明请参见 [Query 节点配置](/guides/self-hosted/references/node-config/query-config#lineage-部分)。
37+
38+
## 生成血缘关系
39+
40+
启用数据血缘后，Databend 会自动记录由 `CREATE TABLE ... AS SELECT`、`CREATE VIEW`、`INSERT ... SELECT`、多表 `INSERT`、`REPLACE`、`MERGE` 和 `COPY` 等操作产生的关系。通过 Stream 读取数据时，血缘会解析到其底层表。
41+
42+
以下示例创建了一条包含两跳关系的血缘链路：
43+
44+
```sql
45+
CREATE OR REPLACE DATABASE lineage_demo;
46+
47+
CREATE OR REPLACE TABLE lineage_demo.fact_orders (
48+
order_id BIGINT,
49+
customer_id BIGINT,
50+
amount DECIMAL(12, 2),
51+
order_time TIMESTAMP
52+
);
53+
54+
CREATE OR REPLACE TABLE lineage_demo.agg_customer_sales AS
55+
SELECT
56+
customer_id,
57+
sum(amount) AS total_amount,
58+
count(*) AS order_count,
59+
max(order_time) AS last_order_time
60+
FROM lineage_demo.fact_orders
61+
GROUP BY customer_id;
62+
63+
CREATE OR REPLACE TABLE lineage_demo.customer_segments AS
64+
SELECT
65+
customer_id,
66+
total_amount,
67+
order_count,
68+
if(total_amount >= 1000, 'high_value', 'standard') AS segment,
69+
now() AS updated_at
70+
FROM lineage_demo.agg_customer_sales;
71+
```
72+
73+
## 查看血缘关系
74+
75+
在 Databend Cloud 中，通过 Database Explorer 打开一个表或视图，然后选择 **Lineage** 页签。血缘图会显示上下游对象；如果存在列级血缘，还会显示列之间的连接关系。
76+
77+
如需通过 SQL 查询血缘，请使用 [`GET_LINEAGE`](/sql/sql-functions/table-functions/get-lineage) 表函数：
78+
79+
```sql
80+
SELECT
81+
distance,
82+
source_object_database,
83+
source_object_name,
84+
target_object_database,
85+
target_object_name
86+
FROM GET_LINEAGE(
87+
'lineage_demo.agg_customer_sales',
88+
'TABLE',
89+
'UPSTREAM',
90+
2
91+
)
92+
ORDER BY distance;
93+
```
94+
95+
查询列级血缘时，请使用带限定符的列名，并将对象域指定为 `COLUMN`：
96+
97+
```sql
98+
SELECT
99+
distance,
100+
source_object_name,
101+
source_column_name,
102+
target_object_name,
103+
target_column_name
104+
FROM GET_LINEAGE(
105+
'lineage_demo.customer_segments.segment',
106+
'COLUMN',
107+
'UPSTREAM',
108+
2
109+
)
110+
ORDER BY distance;
111+
```
112+
113+
## 刷新现有视图的血缘
114+
115+
启用数据血缘后创建的视图会被自动追踪。如果部署中已存在视图，请先预览缺失或过期的关系，然后再进行刷新：
116+
117+
```sql
118+
REFRESH LINEAGE FOR ALL VIEWS DRY RUN;
119+
REFRESH LINEAGE FOR ALL VIEWS;
120+
```
121+
122+
该命令会校准 `default` Catalog 中所有视图的血缘关系。结果只显示需要变更或无法处理的视图，不显示未发生变化的视图。执行命令需要全局 `SUPER` 权限。有关输出列的详细说明，请参见 [`REFRESH LINEAGE`](/sql/sql-commands/ddl/view/refresh-lineage)。
123+
124+
## 使用限制
125+
126+
- `GET_LINEAGE` 最多可遍历五跳关系。
127+
- `system` 和 `information_schema` 中的对象不会作为血缘源记录。
128+
- Stage 支持对象级血缘，但 Stage 文件字段无法提供稳定的列级映射。
129+
- 外部 Catalog 对象可作为血缘端点显示，但不会继续跨越外部 Catalog 边界遍历。
130+
- 查询结果仅包含当前角色可见的对象。

‎docs/cn/guides/57-data-management/index.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,4 +9,5 @@ title: 数据管理
99
| **[数据生命周期](./01-data-lifecycle.md)** | 创建和管理对象 | • 数据库和表 <br/>• 外部表<br/>• Stream 和视图<br/>• 索引和 Stage | • CREATE/DROP/ALTER<br/>• SHOW TABLES<br/>• DESCRIBE TABLE |
1010
| **[数据恢复](./02-data-recovery.md)** | 访问和恢复历史数据 | • 时间回溯<br/>• 闪回表<br/>• 备份和恢复<br/>• AT 和 UNDROP | • SELECT ... AT<br/>• FLASHBACK TABLE<br/>• BENDSAVE BACKUP |
1111
| **[数据保护](./03-data-protection.md)** | 安全访问和防止数据丢失 | • 网络策略<br/>• 访问控制<br/>• 时间回溯和故障安全<br/>• 数据加密 | • NETWORK POLICY<br/>• GRANT/REVOKE<br/>• USER/ROLE |
12-
| **[数据回收](./04-data-recycle.md)** | 释放存储空间 | • VACUUM 命令<br/>• 保留策略<br/>• 孤立文件清理<br/>• 临时文件管理 | • VACUUM TABLE<br/>• VACUUM DROP TABLE<br/>• DATA_RETENTION_TIME |
12+
| **[数据回收](./04-data-recycle.md)** | 释放存储空间 | • VACUUM 命令<br/>• 保留策略<br/>• 孤立文件清理<br/>• 临时文件管理 | • VACUUM TABLE<br/>• VACUUM DROP TABLE<br/>• DATA_RETENTION_TIME |
13+
| **[数据血缘](./05-data-lineage.md)** | 追踪数据流和依赖关系 | • 上游和下游<br/>• 对象级和列级血缘<br/>• 影响分析 | • GET_LINEAGE<br/>• REFRESH LINEAGE<br/>• 血缘图 |

‎docs/cn/sql-reference/10-sql-commands/00-ddl/05-view/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ title: 视图（View）
1212
| [ALTER VIEW](ddl-alter-view.md) | 为现有视图分配或移除 Tag |
1313
| [DROP VIEW](ddl-drop-view.md) | 删除视图 |
1414
| [物化视图](materialized-view.md) | 创建并维护由物理存储支持的物化视图 |
15+
| [REFRESH LINEAGE](refresh-lineage.md) | 回填或校准现有视图的血缘关系 |
1516

1617
## 视图信息
1718

‎docs/cn/sql-reference/10-sql-commands/00-ddl/05-view/refresh-lineage.md‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
---
2+
title: REFRESH LINEAGE
3+
sidebar_position: 7
4+
---
5+
6+
import FunctionDescription from '@site/src/components/FunctionDescription';
7+
8+
<FunctionDescription description="引入或更新：v1.2.935"/>
9+
10+
回填或校准 `default` Catalog 中现有视图的血缘关系。在已有视图的部署中启用数据血缘后，请使用此命令进行回填。启用数据血缘后创建的视图会被自动追踪。
11+
12+
执行此命令需要全局 `SUPER` 权限，并且必须已启用数据血缘。请参见[数据血缘](/guides/data-management/data-lineage#启用数据血缘)。
13+
14+
## 语法
15+
16+
```sql
17+
REFRESH LINEAGE FOR ALL VIEWS [ DRY RUN ]
18+
```
19+
20+
`DRY RUN` 只计算并报告变更，不会写入数据。建议先使用该选项检查刷新将执行的操作。
21+
22+
## 输出列
23+
24+
| 列 | 描述 |
25+
|----|------|
26+
| `object_domain` | 对象域，当前为 `VIEW`。 |
27+
| `catalog` | 视图所属的 Catalog，当前为 `default`。 |
28+
| `database` | 视图所属的数据库。 |
29+
| `object_name` | 视图名称。 |
30+
| `status` | `DRY_RUN`、`REFRESHED` 或 `ERROR`。 |
31+
| `edge_count` | 当前视图定义中发现的血缘边数量。 |
32+
| `upsert_count` | 需要新增或更新的缺失或已变更血缘边数量。 |
33+
| `delete_count` | 需要删除的过期血缘边数量。 |
34+
| `error` | `status` 为 `ERROR` 时的错误信息；其他情况为 `NULL`。 |
35+
36+
没有变更且处理成功的视图不会出现在结果中。
37+
38+
## 示例
39+
40+
预览现有视图需要执行的变更：
41+
42+
```sql
43+
REFRESH LINEAGE FOR ALL VIEWS DRY RUN;
44+
```
45+
46+
应用变更：
47+
48+
```sql
49+
REFRESH LINEAGE FOR ALL VIEWS;
50+
```
51+
52+
命令完成后，可通过 [`GET_LINEAGE`](/sql/sql-functions/table-functions/get-lineage) 查询视图的上游血缘：
53+
54+
```sql
55+
SELECT
56+
distance,
57+
source_object_database,
58+
source_object_name,
59+
target_object_database,
60+
target_object_name
61+
FROM GET_LINEAGE(
62+
'lineage_demo.sales_view',
63+
'VIEW',
64+
'UPSTREAM',
65+
1
66+
);
67+
```
68+
69+
:::note
70+
如需修改逻辑视图定义，请使用 [`CREATE OR REPLACE VIEW`](ddl-create-view.md)。不支持 `ALTER VIEW ... AS ...`，因为不重新创建视图就修改定义可能导致已持久化的血缘关系不一致。
71+
:::

‎docs/cn/sql-reference/20-sql-functions/17-table-functions/get-lineage.md‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
---
2+
title: GET_LINEAGE
3+
---
4+
5+
import FunctionDescription from '@site/src/components/FunctionDescription';
6+
7+
<FunctionDescription description="引入或更新：v1.2.935"/>
8+
9+
返回表、视图、Stage 或列的上游或下游血缘。结果中的每一行表示血缘路径中的一条源对象到目标对象的关系。
10+
11+
在私有化部署中使用该函数之前，需要先在 `databend-query.toml` 中启用数据血缘。请参见[数据血缘](/guides/data-management/data-lineage#启用数据血缘)。
12+
13+
## 语法
14+
15+
```sql
16+
GET_LINEAGE(
17+
'<object_name>',
18+
'<object_domain>',
19+
'<direction>'
20+
[, <distance> ]
21+
)
22+
```
23+
24+
## 参数
25+
26+
| 参数 | 描述 |
27+
|------|------|
28+
| `object_name` | 查询起点。表或视图使用 `[catalog.]database.object`，Stage 使用 `stage_name`，列使用 `[catalog.]database.object.column`。省略 Catalog 或数据库时，将使用当前会话中的值。 |
29+
| `object_domain` | 对象类型：`TABLE`、`VIEW`、`STAGE` 或 `COLUMN`。 |
30+
| `direction` | `UPSTREAM` 表示向数据源方向追溯；`DOWNSTREAM` 表示向数据使用方方向追溯。 |
31+
| `distance` | 可选的最大遍历跳数，取值范围为 `1` 到 `5`，默认为 `5`。 |
32+
33+
所有参数均为位置参数。
34+
35+
## 输出列
36+
37+
| 列 | 类型 | 描述 |
38+
|----|------|------|
39+
| `source_object_catalog` | Nullable(String) | 源对象所属的 Catalog；Stage 为 `NULL`。 |
40+
| `source_object_database` | Nullable(String) | 源对象所属的数据库；Stage 为 `NULL`。 |
41+
| `source_object_name` | Nullable(String) | 源对象名称。 |
42+
| `source_object_domain` | Nullable(String) | 源对象域：`TABLE`、`VIEW` 或 `STAGE`。 |
43+
| `source_column_name` | Nullable(String) | 列级血缘中的源列；非列级血缘为 `NULL`。 |
44+
| `source_status` | String | `ACTIVE`；如果源列应用了 Masking Policy，则为 `MASKED`。 |
45+
| `target_object_catalog` | Nullable(String) | 目标对象所属的 Catalog；Stage 为 `NULL`。 |
46+
| `target_object_database` | Nullable(String) | 目标对象所属的数据库；Stage 为 `NULL`。 |
47+
| `target_object_name` | Nullable(String) | 目标对象名称。 |
48+
| `target_object_domain` | Nullable(String) | 目标对象域：`TABLE`、`VIEW` 或 `STAGE`。 |
49+
| `target_column_name` | Nullable(String) | 列级血缘中的目标列；非列级血缘为 `NULL`。 |
50+
| `target_status` | String | `ACTIVE`；如果目标列应用了 Masking Policy，则为 `MASKED`。 |
51+
| `distance` | Int32 | 相对于查询起点的跳数。直接关系的距离为 `1`。 |
52+
| `process` | Nullable(String) | 创建该关系的操作元数据，采用 JSON 字符串格式，例如 Query ID、查询文本、用户、时间和血缘类型。 |
53+
54+
## 示例
55+
56+
### 查询上游表
57+
58+
以下查询返回 `agg_customer_sales` 两跳以内的上游关系：
59+
60+
```sql
61+
SELECT
62+
distance,
63+
source_object_catalog,
64+
source_object_database,
65+
source_object_name,
66+
source_object_domain,
67+
target_object_database,
68+
target_object_name
69+
FROM GET_LINEAGE(
70+
'lineage_demo.agg_customer_sales',
71+
'TABLE',
72+
'UPSTREAM',
73+
2
74+
)
75+
ORDER BY distance;
76+
```
77+
78+
### 查询下游列
79+
80+
以下查询追踪 `fact_orders.amount` 被哪些列使用：
81+
82+
```sql
83+
SELECT
84+
distance,
85+
source_object_name,
86+
source_column_name,
87+
target_object_name,
88+
target_column_name
89+
FROM GET_LINEAGE(
90+
'lineage_demo.fact_orders.amount',
91+
'COLUMN',
92+
'DOWNSTREAM',
93+
5
94+
)
95+
ORDER BY distance, target_object_name, target_column_name;
96+
```
97+
98+
## 使用说明
99+
100+
- 如果对象存在但没有已记录的血缘，函数将返回空结果。
101+
- 查询结果会根据当前角色的对象可见性进行过滤。
102+
- Stage 仅支持对象级关系；Stage 文件字段不会作为稳定列返回。
103+
- `system` 和 `information_schema` 中的对象不会被记录为血缘源。
104+
- 外部 Catalog 对象会作为终止端点返回，不会继续向外部 Catalog 内部遍历。
105+
- 对于启用数据血缘之前已存在的视图，请使用 [`REFRESH LINEAGE`](/sql/sql-commands/ddl/view/refresh-lineage) 回填血缘关系。

‎docs/cn/sql-reference/20-sql-functions/17-table-functions/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@ title: 表函数 (Table Functions)
3131
| [FUSE_VACUUM_TEMPORARY_TABLE](./fuse-vacuum-temporary-table.md) | 清理临时表 | `SELECT * FROM FUSE_VACUUM_TEMPORARY_TABLE()` |
3232
| [FUSE_AMEND](./fuse-amend.md) | 执行数据修正操作 | `SELECT * FROM FUSE_AMEND()` |
3333
| [TAG_REFERENCES](./tag-references.md) | 返回指定对象上分配的所有 Tag | `SELECT * FROM TAG_REFERENCES('default.users', 'TABLE')` |
34+
| [GET_LINEAGE](./get-lineage.md) | 返回对象和列的上游或下游血缘 | `SELECT * FROM GET_LINEAGE('mydb.mytable', 'TABLE', 'UPSTREAM')` |
3435

3536
## Iceberg 集成函数
3637

0 commit comments

Comments
 (0)