@clickzetta/cz-cli-darwin-x64 0.3.1

package/bin/skills/lakehouse-doc/references/SlowlyChangingDimensionsInLakehouseUsingStreamsandTasks.md

@@ -0,0 +1,616 @@
+# 通过流、管道和SQL任务在 Lakehouse 上实现数仓缓慢变化维SCD
+
+## 关于SCD
+
+缓慢变化维 (Slowly Changing Dimensions, SCD) 是数据仓库设计中的一个关键概念，用于处理维度表中的数据在随时间变化时的管理。维度表包含描述性数据，例如客户信息、产品信息等，而这些信息可能会随时间发生变化。SCD提供了一种方法来处理和记录这些变化，以便数据仓库中的历史数据和当前数据都能保持一致和准确。
+
+SCD通常分为几种类型：
+
+### SCD 类型 1
+
+SCD 类型 1 通过覆盖旧数据来处理变化。这意味着当维度数据发生变化时，旧的数据将被新数据覆盖，因此不会保留历史记录。这种方法简单且快速，但会丢失历史数据。
+
+**示例**：假设客户的地址发生了变化，SCD 类型 1 将直接更新客户地址字段，旧的地址信息将被新地址覆盖。
+
+### SCD 类型 2
+
+SCD 类型 2 通过创建新行来处理变化，以保留历史记录。这种方法在维度表中添加一个新的记录，并且用新数据更新它，同时保留旧数据行，并可能使用有效日期列或版本列来跟踪不同版本的数据。
+
+**示例**：当客户的地址发生变化时，SCD 类型 2 将在维度表中插入一条新的记录，包含新地址，并可能添加一个有效日期范围来表示该地址的有效期。
+
+### SCD 类型 3
+
+SCD 类型 3 通过在表中添加额外的列来处理变化，以保留有限的历史记录。这种方法在维度表中添加一个新列来存储旧数据，当变化发生时，旧数据移到新列，新数据覆盖原来的位置。
+
+**示例**：如果客户的地址变化，SCD 类型 3 会在表中添加一个“旧地址”列，将旧地址存储到该列中，新地址存储在原始列中。
+
+### 需要什么
+
+* [云器Lakehouse](https://www.yunqi.tech/)账户
+* 本指南的[Github代码库](https://github.com/yunqiqiliang/clickzetta_quickstart/tree/main/Slowly_Changing_Dimensions_In_Lakehouse_Using_Streams_and_Tasks)
+* 访问阿里云OSS的AK信息
+
+## 在Lakehouse上实现SCD方案介绍
+
+在 Lakehouse 中实现缓慢变化维度 (SCD) 的现代方法，利用自动化数据管道和原生 Lakehouse 功能实现高效的变化跟踪和历史数据管理。
+
+^
+
+:-: ![](.topwrite/assets/image_1736735808312.png =823)
+
+^
+
+### 管道概述
+
+自动捕获和处理数据变化的端到端数据管道：
+
+1. **数据源**（Jupyter 调用 Fake 生成测试数据）**→** 使用 Python 创建数据来模拟现实世界事件。
+2. [Zettapark](ZettaparkQuickStart.md) **PUT**→ 使用Zettapark将数据拉取并加载到 数据湖Volume上。
+3. [数据湖Volume](datalake_volume.md) → 基于阿里云OSS的数据湖存储。
+4. [Lakehouse Pipe](pipe-summary.md)**捕捉数据湖文件变化**→ Lakehouse Pipe 高效地将数据从数据湖Volume流式传输到 Lakehouse。
+5. [Lakehouse Table Stream](table_stream.md)**捕捉Table数据变化**→ 捕捉基表里的变化数据供增量消费。
+6. **SQL**[任务](ide.md)**进行SCD处理 →** 通过开发SQL任务实现SCD的处理逻辑，并通过云器Lakehouse Studio实现任务调度。
+7. **Lakehouse数据管理**，Lakehouse 通过三个表管理数据：
+
+   * `customer_raw`：存储原始摄取数据。
+   * `customer`：反映流管道的最新更新。
+   * `customer_history`：保留所有更新的记录以供分析和审计变化历史。
+
+## 关键组件
+
+### 数据生成
+
+* **使用的工具**： Python
+* Python 脚本动态生成模拟客户数据以模拟实时数据源。
+
+### 数据采集​​层
+
+* **数据湖 Volume**：源文件的存储区，Lakehouse 的数据湖存储，本案例采用阿里云 OSS。通过创建外部 Volume 实现和 Table 的统一管理。
+
+* **Zettapark**：将生成的模拟数据 PUT 到数据湖 Volume 上
+
+* **Pipe**：Lakehouse内置的实时数据提取服务，使用 Pipe 进行实时流式传输
+
+  * 自动检测 数据湖Volume 中的新文件
+  * 无需人工干预即可将数据加载到临时表customer\_raw中
+
+### 变化检测层
+
+* **Lakehouse 流（Table Stream）**：
+
+  * 捕获 INSERT、UPDATE、DELETE 等操作
+  * 维护变更跟踪元数据
+  * 能够高效处理增量变更
+  * 将从customer中检测到的变化数据存储到中customer\_table\_changes
+
+### 处理层
+
+* **Lakehouse SQL任务**：
+
+  * SCD 处理的计划作业
+  * 处理类型 1（覆盖）和类型 2（历史）更改
+  * 维护参照完整性
+  * 任务
+    * 将新的或更新的记录插入`customer`表（SCD 类型1）中。
+    * 将更新记录到`customer_history`表（SCD 类型2）中以保留审计跟踪。
+
+### 存储层
+
+* **临时表**：原始数据的临时存储区
+
+* **维度表**：具有历史跟踪的最终表
+
+  * 包括生效日期
+  * 维护当前和历史记录
+  * 支持时间点分析
+
+### 应用场景
+
+* 客户维度管理
+* 产品目录版本控制
+* 员工数据追踪
+* 任何需要历史变更跟踪的维度
+
+### 技术堆栈
+
+所需组件：
+
+* 云器Lakehouse
+* 阿里云OSS（数据湖存储）
+* [Jupyter Notebook](https://jupyter.org/install)（用于测试数据生成并将文件PUT到数据湖Volume上），或其它Python环境
+
+## 实现步骤
+
+### 任务开发
+
+导航到 [Lakehouse Studio](studio_overview.md) 的 开发 -> 任务，
+
+^
+
+:-: ![](.topwrite/assets/image_1736424981726.png =537)
+
+^
+
+单击“+”新建如下目录：
+
+* 01\_DEMO\_SCD\_In\_Lakehouse
+
+单击“+”新建如下SQL任务：
+
+* 01\_setup\_env
+* 10\_table\_creation\_for\_data\_storage
+* 11\_stream\_creation\_for\_change\_detect
+* 12\_volume\_creation\_for\_datalake
+* 13\_pipe\_creation\_for\_data\_ingestion
+* 14\_scd\_type\_1
+* 15\_scd\_type\_2\_1
+* 16\_scd\_type\_2\_2
+* 20\_clean\_env
+
+将如下代码复制到对应的任务里，也可以从[GitHub下载文件](https://github.com/yunqiqiliang/clickzetta_quickstart/tree/main/Slowly_Changing_Dimensions_In_Lakehouse_Using_Streams_and_Tasks)后将内容复制到对应的任务里。
+
+^
+
+#### Lakehouse环境设置
+
+SQL任务：01\_setup\_env
+
+```SQL
+-- Create required virtual cluster and schemas
+-- SCD virtual cluster
+CREATE VCLUSTER IF NOT EXISTS SCD_VC
+   VCLUSTER_SIZE = XSMALL
+   VCLUSTER_TYPE = ANALYTICS
+   AUTO_SUSPEND_IN_SECOND = 60
+   AUTO_RESUME = TRUE
+   COMMENT  'SCD VCLUSTER for test';
+
+-- Use our VCLUSTER
+USE VCLUSTER SCD_VC;
+
+-- Create and Use SCHEMA
+CREATE SCHEMA IF NOT EXISTS  SCD_SCH;
+USE SCHEMA SCD_SCH;
+```
+
+> 注：计算集群的vcluster\_size参数同时支持以T-shirt size（XSMALL、SMALL、Large等）和以数字（1,2,4,16等）表达的方式，以提供更丰富的计算集群规格，满足不同场景的需要。更多信息详见：[计算集群规格代码变更说明](vcluster_size_description.md)
+
+#### 创建表
+
+SQL任务：10\_table\_creation\_for\_data\_storage
+
+```SQL
+USE VCLUSTER SCD_VC;
+USE SCHEMA SCD_SCH;
+
+create  table if not exists customer (
+     customer_id string,
+     first_name varchar,
+     last_name varchar,
+     email varchar,
+     street varchar,
+     city varchar,
+     state varchar,
+     country varchar,
+     update_timestamp timestamp_ntz default current_timestamp());
+
+create  table if not exists customer_history (
+     customer_id string,
+     first_name varchar,
+     last_name varchar,
+     email varchar,
+     street varchar,
+     city varchar,
+     state varchar,
+     country varchar,
+     start_time timestamp_ntz default current_timestamp(),
+     end_time timestamp_ntz default current_timestamp(),
+     is_current boolean
+     );
+     
+create  table if not exists customer_raw (
+     customer_id string,
+     first_name varchar,
+     last_name varchar,
+     email varchar,
+     street varchar,
+     city varchar,
+     state varchar,
+     country varchar);
+```
+
+#### 创建流（Stream）
+
+SQL任务：11\_stream\_creation\_for\_change\_detect
+
+```SQL
+USE VCLUSTER SCD_VC;
+USE SCHEMA SCD_SCH;
+     
+create table stream if not exists customer_table_changes 
+on table customer 
+WITH PROPERTIES('TABLE_STREAM_MODE' = 'STANDARD');
+```
+
+#### 创建数据湖Volume
+
+SQL任务：12\_volume\_creation\_for\_datalake
+
+创建 Volume 需要一个到阿里云 OSS 的 Connection，请参考 [创建Connection](connection-guide.md)。
+
+```SQL
+--external data lake
+--创建数据湖Connection,到数据湖的连接
+CREATE STORAGE CONNECTION if not exists hz_ingestion_demo
+    TYPE oss
+    ENDPOINT = 'oss-cn-hangzhou-internal.aliyuncs.com'
+    access_id = '请输入您的access_id'
+    access_key = '请输入您的access_key'
+    comments = 'hangzhou oss private endpoint for ingest demo'
+```
+
+```SQL
+USE VCLUSTER SCD_VC;
+USE SCHEMA SCD_SCH;
+
+--创建Volume,数据湖存储文件的位置
+CREATE EXTERNAL VOLUME  if not exists scd_demo
+  LOCATION 'oss://yourbucketname/scd_demo' 
+  USING connection hz_ingestion_demo  -- storage Connection
+  DIRECTORY = (
+    enable = TRUE
+  ) 
+  recursive = TRUE;
+
+--同步数据湖Volume的目录到Lakehouse
+ALTER volume scd_demo refresh;
+
+--查看云器Lakehouse数据湖Volume上的文件
+SELECT * from directory(volume scd_demo);
+  
+show volumes;
+```
+
+#### 创建Pipe
+
+SQL任务：13\_pipe\_creation\_for\_data\_ingestion
+
+```SQL
+USE VCLUSTER SCD_VC;
+USE SCHEMA SCD_SCH;
+
+create pipe volume_pipe_cdc_demo
+  VIRTUAL_CLUSTER = 'scd_vc'
+  --执行获取最新文件使用扫描文件模式
+  INGEST_MODE = 'LIST_PURGE'
+  as
+copy into customer_raw from volume scd_demo(customer_id string,
+     first_name varchar,
+     last_name varchar,
+     email varchar,
+     street varchar,
+     city varchar,
+     state varchar,
+     country varchar) 
+using csv OPTIONS(
+  'header'='true'
+)
+--必须添加purge参数导入成功后删除数据 
+purge=true
+;
+
+show pipes;
+DESC PIPE volume_pipe_cdc_demo;
+```
+
+#### SCD Type 1
+
+SQL任务：14\_scd\_type\_1
+
+```SQL
+USE VCLUSTER SCD_VC;
+USE SCHEMA SCD_SCH;
+
+MERGE INTO customer AS c 
+USING customer_raw AS cr
+   ON c.customer_id = cr.customer_id
+WHEN MATCHED AND (c.first_name  <> cr.first_name  OR
+                  c.last_name   <> cr.last_name   OR
+                  c.email       <> cr.email       OR
+                  c.street      <> cr.street      OR
+                  c.city        <> cr.city        OR
+                  c.state       <> cr.state       OR
+                  c.country     <> cr.country) THEN 
+    UPDATE SET 
+        c.first_name = cr.first_name,
+        c.last_name = cr.last_name,
+        c.email = cr.email,
+        c.street = cr.street,
+        c.city = cr.city,
+        c.state = cr.state,
+        c.country = cr.country,
+        c.update_timestamp = current_timestamp()
+WHEN NOT MATCHED THEN 
+    INSERT (customer_id, first_name, last_name, email, street, city, state, country)
+    VALUES (cr.customer_id, cr.first_name, cr.last_name, cr.email, cr.street, cr.city, cr.state, cr.country);
+
+select count(*) from customer;
+```
+
+#### SCD Type 2-1
+
+SQL任务：15\_scd\_type\_2\_1
+
+```SQL
+USE VCLUSTER SCD_VC;
+USE SCHEMA SCD_SCH;
+
+-- 创建视图 v_customer_change_data
+CREATE VIEW IF NOT EXISTS v_customer_change_data AS
+-- 这个子查询用于处理插入到 customer 表的数据
+-- 插入到 customer 表的数据会在 customer_HISTORY 表中产生一条新的插入记录
+SELECT CUSTOMER_ID, FIRST_NAME, LAST_NAME, EMAIL, STREET, CITY, STATE, COUNTRY,
+       start_time, end_time, is_current, 'I' AS dml_type
+FROM (
+    SELECT CUSTOMER_ID, FIRST_NAME, LAST_NAME, EMAIL, STREET, CITY, STATE, COUNTRY,
+           update_timestamp AS start_time,
+           LAG(update_timestamp) OVER (PARTITION BY customer_id ORDER BY update_timestamp DESC) AS end_time_raw,
+           CASE WHEN end_time_raw IS NULL THEN '9999-12-31' ELSE end_time_raw END AS end_time,
+           CASE WHEN end_time_raw IS NULL THEN TRUE ELSE FALSE END AS is_current
+    FROM (
+        SELECT CUSTOMER_ID, FIRST_NAME, LAST_NAME, EMAIL, STREET, CITY, STATE, COUNTRY, UPDATE_TIMESTAMP
+        FROM customer_table_changes
+        WHERE __change_type = 'INSERT'
+    )
+)
+UNION
+-- 这个子查询用于处理更新到 customer 表的数据
+-- 更新到 customer 表的数据会在 customer_HISTORY 表中产生一条更新记录和一条插入记录
+-- 下面的子查询会生成两条记录，每条记录有不同的 dml_type
+SELECT CUSTOMER_ID, FIRST_NAME, LAST_NAME, EMAIL, STREET, CITY, STATE, COUNTRY, start_time, end_time, is_current, dml_type
+FROM (
+    SELECT CUSTOMER_ID, FIRST_NAME, LAST_NAME, EMAIL, STREET, CITY, STATE, COUNTRY,
+           update_timestamp AS start_time,
+           LAG(update_timestamp) OVER (PARTITION BY customer_id ORDER BY update_timestamp DESC) AS end_time_raw,
+           CASE WHEN end_time_raw IS NULL THEN '9999-12-31' ELSE end_time_raw END AS end_time,
+           CASE WHEN end_time_raw IS NULL THEN TRUE ELSE FALSE END AS is_current, 
+           dml_type
+    FROM (
+        -- 识别需要插入到 customer_history 表的数据
+        SELECT CUSTOMER_ID, FIRST_NAME, LAST_NAME, EMAIL, STREET, CITY, STATE, COUNTRY, update_timestamp, 'I' AS dml_type
+        FROM customer_table_changes
+        WHERE __change_type = 'INSERT'
+        UNION
+        -- 识别 customer_HISTORY 表中需要更新的数据
+        SELECT CUSTOMER_ID, null AS FIRST_NAME, null AS LAST_NAME, null AS EMAIL, null AS STREET, null AS CITY, null AS STATE, null AS COUNTRY, start_time, 'U' AS dml_type
+        FROM customer_history
+        WHERE customer_id IN (
+            SELECT DISTINCT customer_id 
+            FROM customer_table_changes
+            WHERE __change_type = 'DELETE'
+        )
+        AND is_current = TRUE
+    )
+)
+UNION
+-- 这个子查询用于处理从 customer 表中删除的数据
+-- 从 customer 表中删除的数据会在 customer_HISTORY 表中产生一条更新记录
+SELECT ctc.CUSTOMER_ID, null AS FIRST_NAME, null AS LAST_NAME, null AS EMAIL, null AS STREET, null AS CITY, null AS STATE, null AS COUNTRY, ch.start_time, current_timestamp() AS end_time, NULL AS is_current, 'D' AS dml_type
+FROM customer_history ch
+INNER JOIN customer_table_changes ctc
+ON ch.customer_id = ctc.customer_id
+WHERE ctc.__change_type = 'DELETE'
+AND ch.is_current = TRUE;
+```
+
+#### SCD Type 2-2
+
+SQL任务：16\_scd\_type\_2\_2
+
+```SQL
+USE VCLUSTER SCD_VC;
+USE SCHEMA SCD_SCH;
+
+merge into customer_history ch -- 目标表，将 NATION 中的变化合并到此表中
+using v_customer_change_data ccd -- v_customer_change_data 是一个视图，包含插入/更新到 customer_history 表的逻辑。
+   on ch.CUSTOMER_ID = ccd.CUSTOMER_ID -- CUSTOMER_ID 和 start_time 确定 customer_history 表中是否存在唯一记录
+   and ch.start_time = ccd.start_time
+when matched and ccd.dml_type = 'U' then update -- 表示记录已被更新且不再是当前记录，需要标记 end_time
+    set ch.end_time = ccd.end_time,
+        ch.is_current = FALSE
+when matched and ccd.dml_type = 'D' then update -- 删除实际上是逻辑删除。记录会被标记且不会插入新版本
+   set ch.end_time = ccd.end_time,
+       ch.is_current = FALSE
+when not matched and ccd.dml_type = 'I' then insert -- 插入一个新的 CUSTOMER_ID 或更新现有 CUSTOMER_ID 都会产生一个插入操作
+          (CUSTOMER_ID, FIRST_NAME, LAST_NAME, EMAIL, STREET, CITY, STATE, COUNTRY, start_time, end_time, is_current)
+    values (ccd.CUSTOMER_ID, ccd.FIRST_NAME, ccd.LAST_NAME, ccd.EMAIL, ccd.STREET, ccd.CITY, ccd.STATE, ccd.COUNTRY, ccd.start_time, ccd.end_time, ccd.is_current);
+```
+
+### 构建环境
+
+运行开发好的任务，构建Lakehouse运行环境。
+导航到开发->任务页面，打开如下任务并逐一运行：
+
+* 01\_setup\_env
+* 10\_table\_creation\_for\_data\_storage
+* 11\_stream\_creation\_for\_change\_detect
+* 12\_volume\_creation\_for\_datalake
+* 13\_pipe\_creation\_for\_data\_ingestion
+* 15\_scd\_type\_2\_1
+
+:-: ![](.topwrite/assets/image_1736480652293.png =594)
+
+### 任务调度与提交运行
+
+调度开发好的 SCD 任务，每分钟执行一次。
+导航到开发->任务页面，打开如下任务并逐一配置调度：
+
+* 14\_scd\_type\_1
+* 16\_scd\_type\_2\_2
+
+:-: ![](.topwrite/assets/image_1736480815329.png =623)
+
+### 提交任务
+
+配置好调度后，点击“提交”，任务将以一分钟的周期进行调度运行，更新目标表里的数据。
+
+^
+
+:-: ![](.topwrite/assets/image_1736480973764.png =624)
+
+### 生成测试数据
+
+#### 生成测试数据并PUT到数据湖Volume上
+
+```PYTHON
+#!pip install faker
+from faker import Faker
+import csv
+import uuid
+import random
+from decimal import Decimal
+from datetime import datetime
+from clickzetta.zettapark.session import Session
+import json
+RECORD_COUNT = 10000
+fake = Faker()
+```
+
+```PYTHON
+current_time = datetime.now().strftime("%Y%m%d%H%M%S")
+print(current_time)
+```
+
+```PYTHON
+file_path = f'FakeDataset/customer_{current_time}.csv'
+```
+
+```PYTHON
+def create_csv_file():
+    with open(file_path, 'w', newline='') as csvfile:
+        fieldnames = ["customer_id","first_name","last_name","email","street",
+                      "city","state","country"
+                     ]
+        writer = csv.DictWriter(csvfile, fieldnames=fieldnames)
+
+        writer.writeheader()
+        for i in range(RECORD_COUNT):
+            #print(i)
+            writer.writerow(
+                {
+                    "customer_id": str(uuid.uuid4()),
+                    'first_name': fake.first_name(),
+                    'last_name': fake.last_name(),
+                    'email': fake.email(),
+                    'street': fake.street_address(),
+                    'city': fake.city(),
+                    'state': fake.state(),
+                    'country': fake.country()
+                }
+            )
+```
+
+```PYTHON
+def put_file_into_volume():
+    # 从配置文件中读取参数
+    with open('security/config-uat.json', 'r') as config_file:
+        config = json.load(config_file)
+    
+    # 创建会话
+    session = Session.builder.configs(config).create()
+    session.file.put(file_path,"volume://scd_demo/")
+    session.sql("show volume directory scd_demo").show()
+    session.close()
+```
+
+```PYTHON
+if __name__ == '__main__':
+    create_csv_file()
+    put_file_into_volume()
+```
+
+* 执行上述代码，会往Volume里PUT一个新文件，Pipe会自动检测到该新文件并文件的数据写入到customer\_raw表里。
+
+:-: ![](.topwrite/assets/image_1736481547753.png =403)
+
+* 14\_scd\_type\_1任务配置了周期调度，每分钟会进行scd\_type\_1的计算并将结果merge into进customer表。
+
+:-: ![](.topwrite/assets/image_1736481597919.png =419)
+
+* Table Stream会自动检测customer表数据的变化，并将变化数据保存在customer\_table\_changes。
+
+:-: ![](.topwrite/assets/image_1736481635363.png =416)
+
+* 14\_scd\_type\_2\_2任务配置了周期调度，每分钟会进行scd\_type\_2的计算并将结果merge into进customer\_history表。
+
+:-: ![](.topwrite/assets/image_1736481671328.png =425)
+
+### 监控和维护
+
+#### Pipe监控
+
+* 使用SHOW PIPES命令查看PIPE对象列表
+
+```SQL
+SHOW PIPES;
+```
+
+* 使用DESC PIPE命令查看指定PIPE对象详细信息
+
+```SQL
+DESC PIPE volume_pipe_cdc_demo;
+```
+
+:-: ![](.topwrite/assets/image_1736483133453.png =562)
+
+* 查看pipe copy作业执行情况
+
+通过作业历史中的query\_tag来筛选,所有的pipe执行的copy作业都会在query\_tag打上标签:格式为pipe.worksapce\_name.schema\_name.pipe\_name
+
+本指南worksapce\_name是ql\_ws，schema\_name是SCD\_SCH，pipe name是volume\_pipe\_cdc\_demo，因此query\_tag是：
+
+pipe.ql\_ws.scd\_sch.volume\_pipe\_cdc\_demo
+
+导航到计算->作业历史：
+
+^
+
+:-: ![](.topwrite/assets/image_1736482319263.png =553)
+
+^
+
+点击“更多筛选”，在QueryTag里输入“pipe.ql\_ws.scd\_sch.volume\_pipe\_cdc\_demo”进行过滤：
+
+:-:
+![](.topwrite/assets/image_1736482668378.png =617)
+
+####
+
+#### 周期调度任务
+
+导航到运维监控->任务运维->周期任务：
+
+:-:
+![](.topwrite/assets/image_1736482942259.png =634)
+
+^
+
+查看任务实例：
+
+^
+
+:-: ![](.topwrite/assets/image_1736483055041.png =627)
+
+^
+
+## 资料
+
+[Connection](connection-guide.md)
+
+[External Volume](datalake_volume.md)
+
+[Pipe](pipe-storage-object.md)
+
+[Table Stream](table_stream.md)
+
+[Merge Into](MERGE.md)