@clickzetta/cz-cli-darwin-x64 0.3.39 → 0.3.41

package/bin/skills/clickzetta-semantic-view/SKILL.md

@@ -0,0 +1,207 @@
+---
+name: clickzetta-semantic-view
+description: |
+  创建和查询 ClickZetta Lakehouse 语义视图（Semantic View）。语义视图是架构级逻辑
+  数据模型对象，通过声明逻辑表、维度、指标、过滤器，将复杂的多表 JOIN 和聚合逻辑封装
+  为业务友好的语义层，使用 semantic_view() 函数查询，无需手写 JOIN。
+  当前为邀测功能（1.3 版本起）。
+  当用户说"创建语义视图"、"semantic view"、"语义层"、"定义指标"、"定义维度"、
+  "semantic_view() 怎么用"、"统一指标口径"、"业务语义模型"、"逻辑表"、
+  "DIMENSIONS"、"METRICS"、"FILTERS"、"DROP SEMANTIC VIEW"、
+  "SHOW SEMANTIC VIEWS"时触发。
+  Keywords: semantic view, dimension, metric, logical model, unified metrics, semantic layer
+---
+
+# ClickZetta 语义视图（Semantic View）
+
+阅读 [references/semantic-view-reference.md](references/semantic-view-reference.md) 了解完整语法。
+
+---
+
+## 概述
+
+语义视图是 ClickZetta Lakehouse 的**架构级逻辑数据模型对象**，解决两类核心问题：
+
+- **数据分析**：统一维度和指标定义，业务用户无需编写复杂 JOIN 即可查询跨表数据
+- **数据治理**：集中管理表关系、维度、指标定义，确保全组织使用相同数据口径
+
+> ⚠️ 当前为**邀测功能**（1.3 版本），需联系技术支持开通。
+
+---
+
+## 四大组件
+
+| 组件 | 关键字 | 说明 |
+|---|---|---|
+| 逻辑表 | `TABLES` | 映射物理表，声明主键和外键关系，引擎自动处理 JOIN |
+| 维度 | `DIMENSIONS` | 分类属性（谁/什么/哪里/何时），支持计算维度 |
+| 指标 | `METRICS` | 聚合度量（SUM/AVG/COUNT/MIN/MAX），业务 KPI |
+| 过滤器 | `FILTERS` | 预定义可重用过滤条件（语义注解，不可直接传入查询） |
+
+---
+
+## 创建语义视图
+
+```sql
+CREATE SEMANTIC VIEW <视图名>
+TABLES (
+    <表别名> AS <schema>.<物理表>
+        PRIMARY KEY (<列名>)
+        [ FOREIGN KEY (<列名>) REFERENCES <其他表别名> ]
+        [ WITH SYNONYMS ('<同义词>') ]
+        [ COMMENT = '<说明>' ]
+    [ , ... ]
+)
+[ FILTERS (
+    <表别名>.<过滤器名> AS <布尔表达式>
+    [ , ... ]
+) ]
+DIMENSIONS (
+    { <表别名>.<维度名> | <维度名> } AS <表达式>
+        [ WITH SYNONYMS = ('<同义词>' [ , ... ]) ]
+        [ is_unique = { true | false } ]
+        [ is_time = { true | false } ]
+        [ enum_values = [ <值1>, <值2>, ... ] ]
+        [ COMMENT = '<说明>' ]
+    [ , ... ]
+)
+METRICS (
+    <表别名>.<指标名> AS <聚合表达式>
+        [ COMMENT = '<说明>' ]
+    [ , ... ]
+)
+[ COMMENT = '<视图说明>' ];
+```
+
+### 完整示例（TPC-H 收入分析）
+
+```sql
+DROP SEMANTIC VIEW IF EXISTS tpch_rev_analysis;
+CREATE SEMANTIC VIEW tpch_rev_analysis
+TABLES (
+    customers AS tpch.customer
+        PRIMARY KEY (c_custkey)
+        COMMENT = '客户主表',
+    orders AS tpch.orders
+        PRIMARY KEY (o_orderkey)
+        FOREIGN KEY (o_custkey) REFERENCES customers
+        WITH SYNONYMS ('销售订单')
+        COMMENT = '订单表',
+    line_items AS tpch.lineitem
+        PRIMARY KEY (l_orderkey, l_linenumber)
+        FOREIGN KEY (l_orderkey) REFERENCES orders
+        COMMENT = '订单明细'
+)
+FILTERS (
+    customers.is_building AS customers.c_mktsegment = 'BUILDING'
+)
+DIMENSIONS (
+    customers.customer_name AS c_name
+        WITH SYNONYMS = ('客户名称', 'customer name')
+        is_unique = true
+        COMMENT = '客户名称',
+    orders.order_date AS o_orderdate
+        is_time = true
+        COMMENT = '下单日期',
+    orders.order_year AS YEAR(o_orderdate)
+        COMMENT = '下单年份',
+    orders.order_status AS o_orderstatus
+        enum_values = ['O', 'F', 'P']
+        COMMENT = '订单状态'
+)
+METRICS (
+    customers.customer_count AS COUNT(c_custkey)
+        COMMENT = '客户总数',
+    orders.avg_order_value AS AVG(o_totalprice)
+        COMMENT = '平均订单金额',
+    orders.total_revenue AS SUM(o_totalprice)
+        COMMENT = '总收入'
+)
+COMMENT = '收入分析语义视图';
+```
+
+---
+
+## 查询语义视图
+
+使用 `semantic_view()` 表函数，**无需手写 JOIN 和 GROUP BY**：
+
+```sql
+-- 基础查询：按订单日期统计平均订单金额
+SELECT * FROM semantic_view(
+    tpch_rev_analysis,
+    DIMENSIONS orders.order_date,
+    METRICS orders.avg_order_value
+);
+
+-- 多维度查询：按日期和客户名称
+SELECT * FROM semantic_view(
+    tpch_rev_analysis,
+    DIMENSIONS orders.order_date,
+    DIMENSIONS customers.customer_name,
+    METRICS orders.avg_order_value
+);
+
+-- 使用短名称（名称唯一时可省略表别名前缀）
+SELECT * FROM semantic_view(
+    tpch_rev_analysis,
+    DIMENSIONS order_date,
+    DIMENSIONS customer_name,
+    METRICS avg_order_value
+);
+
+-- 加 WHERE 过滤（需将过滤列定义为 DIMENSION）
+SELECT * FROM semantic_view(
+    tpch_rev_analysis,
+    DIMENSIONS customers.customer_name,
+    DIMENSIONS orders.order_status,
+    METRICS orders.total_revenue
+) WHERE order_status = 'O';
+```
+
+### 与传统 SQL 对比
+
+```sql
+-- 传统 SQL（需手写 JOIN + GROUP BY）
+SELECT o.o_orderdate, c.c_name, AVG(o.o_totalprice)
+FROM tpch.orders o
+JOIN tpch.customer c ON o.o_custkey = c.c_custkey
+GROUP BY o.o_orderdate, c.c_name;
+
+-- 语义视图（自动处理 JOIN 和聚合）
+SELECT * FROM semantic_view(
+    tpch_rev_analysis,
+    DIMENSIONS order_date,
+    DIMENSIONS customer_name,
+    METRICS avg_order_value
+);
+```
+
+---
+
+## 管理命令
+
+```sql
+-- 删除（推荐先删再建，确保幂等）
+DROP SEMANTIC VIEW IF EXISTS tpch_rev_analysis;
+
+-- 列出当前 Schema 的所有语义视图
+SHOW SEMANTIC VIEWS;
+SHOW SEMANTIC VIEWS IN my_schema;
+
+-- 查看详细定义（逻辑表、维度、指标、外键）
+DESC EXTENDED tpch_rev_analysis;
+```
+
+---
+
+## 注意事项
+
+1. **TABLES 定义顺序**：被外键引用的表必须先定义（如 `customers` 必须在 `orders` 之前）
+2. **FILTERS 是语义注解**：`FILTERS` 中的命名过滤器不能作为 `semantic_view()` 的参数，WHERE 子句只能引用 `DIMENSIONS` 中定义的列名（短名），不能用物理列名
+3. **WHERE 只能用 DIMENSION 短名**：`WHERE customer_name = 'Alice'` ✅，`WHERE c_name = 'Alice'` ❌
+4. **短名称 vs 限定名称**：名称在视图内唯一时可用短名称，有冲突时必须用 `表别名.名称`
+5. **幂等创建**：始终先 `DROP SEMANTIC VIEW IF EXISTS` 再创建，避免重复执行报错
+6. **计算维度**：DIMENSIONS 支持表达式，如 `YEAR(CAST(order_date AS DATE))` 提取年份
+7. **指标聚合函数**：仅支持 `COUNT`、`AVG`、`SUM`、`MIN`、`MAX`
+8. **DIMENSIONS 和 METRICS 可单独使用**：可以只查 METRICS（全局聚合），也可以只查 DIMENSIONS（去重列表）

package/bin/skills/clickzetta-semantic-view/eval_cases.jsonl

@@ -0,0 +1,12 @@
+{"case_id":"001","type":"should_call","user_input":"怎么创建语义视图","expected_skill":"clickzetta-semantic-view","expected_output_contains":["CREATE SEMANTIC VIEW"]}
+{"case_id":"002","type":"should_call","user_input":"semantic_view() 函数怎么查询","expected_skill":"clickzetta-semantic-view","expected_output_contains":["semantic_view"]}
+{"case_id":"003","type":"should_call","user_input":"语义视图里怎么定义维度和指标","expected_skill":"clickzetta-semantic-view","expected_output_contains":["DIMENSIONS","METRICS"]}
+{"case_id":"004","type":"should_call","user_input":"怎么用语义层统一指标口径","expected_skill":"clickzetta-semantic-view","expected_output_contains":["语义"]}
+{"case_id":"005","type":"should_call","user_input":"SHOW SEMANTIC VIEWS 怎么用","expected_skill":"clickzetta-semantic-view","expected_output_contains":["SHOW SEMANTIC VIEWS"]}
+{"case_id":"006","type":"should_call","user_input":"语义视图的 FILTERS 怎么定义","expected_skill":"clickzetta-semantic-view","expected_output_contains":["FILTERS"]}
+{"case_id":"007","type":"should_call","user_input":"DROP SEMANTIC VIEW 怎么删除","expected_skill":"clickzetta-semantic-view","expected_output_contains":["DROP SEMANTIC VIEW"]}
+{"case_id":"008","type":"should_not_call","user_input":"怎么创建普通视图","forbidden_skill":"clickzetta-semantic-view"}
+{"case_id":"009","type":"should_not_call","user_input":"帮我写一个数据看板","forbidden_skill":"clickzetta-semantic-view"}
+{"case_id":"010","type":"should_not_call","user_input":"怎么做数据建模","forbidden_skill":"clickzetta-semantic-view"}
+{"case_id":"011","type":"should_not_call","user_input":"Superset 怎么连接","forbidden_skill":"clickzetta-semantic-view"}
+{"case_id":"012","type":"should_not_call","user_input":"怎么创建物化视图","forbidden_skill":"clickzetta-semantic-view"}

package/bin/skills/clickzetta-semantic-view/references/semantic-view-reference.md

@@ -0,0 +1,167 @@
+# 语义视图完整语法参考
+
+> 来源：https://www.yunqi.tech/documents/semantic_view
+> 功能状态：邀测（1.3 版本起）
+
+---
+
+## CREATE SEMANTIC VIEW 完整语法
+
+```sql
+CREATE SEMANTIC VIEW <视图名称>
+TABLES (
+    <逻辑表定义> [ , ... ]
+)
+[ FILTERS (
+    <过滤器定义> [ , ... ]
+) ]
+DIMENSIONS (
+    <维度定义> [ , ... ]
+)
+METRICS (
+    <指标定义> [ , ... ]
+)
+[ COMMENT = '<视图说明>' ];
+```
+
+**约束**：`DIMENSIONS` 和 `METRICS` 至少包含其中一个。
+
+---
+
+## 逻辑表定义语法
+
+```sql
+<表别名> AS <schema>.<物理表名>
+    PRIMARY KEY ( <列名> [ , ... ] )
+    [ FOREIGN KEY ( <列名> ) REFERENCES <其他逻辑表别名> ]
+    [ WITH SYNONYMS ( '<同义词>' [ , ... ] ) ]
+    [ COMMENT = '<说明>' ]
+```
+
+| 参数 | 说明 |
+|---|---|
+| `<表别名> AS <schema>.<物理表>` | 为物理表指定逻辑别名，后续维度/指标/外键均用此别名引用 |
+| `PRIMARY KEY` | 主键列，用于确定表间关系类型（一对多/一对一） |
+| `FOREIGN KEY ... REFERENCES` | 外键关系，引擎据此自动处理 JOIN；引用目标必须是逻辑表别名 |
+| `WITH SYNONYMS` | 逻辑表同义词，增强可发现性 |
+
+**注意**：被外键引用的表必须在 TABLES 子句中先定义。
+
+---
+
+## 过滤器定义语法
+
+```sql
+<逻辑表别名>.<过滤器名> AS <布尔表达式>
+```
+
+示例：
+```sql
+FILTERS (
+    customers.is_building AS customers.c_mktsegment = 'BUILDING',
+    orders.is_open AS orders.o_orderstatus = 'O'
+)
+```
+
+**重要**：FILTERS 是面向 AI/元数据层的语义注解，**不能**作为 `semantic_view()` 函数参数直接传入。若要在查询中过滤，需将对应列定义为 DIMENSION，再用外层 WHERE 子句。
+
+---
+
+## 维度定义语法
+
+```sql
+{ <逻辑表别名>.<维度名> | <维度名> } AS <表达式>
+    [ WITH SYNONYMS = ( '<同义词>' [ , ... ] ) ]
+    [ is_unique = { true | false } ]
+    [ is_time = { true | false } ]
+    [ enum_values = [ <值1>, <值2>, ... ] ]
+    [ COMMENT = '<说明>' ]
+```
+
+| 参数 | 说明 |
+|---|---|
+| `AS <表达式>` | 可以是列名，也可以是计算表达式（如 `YEAR(o_orderdate)`） |
+| `WITH SYNONYMS` | 维度同义词，用户可用不同业务术语引用同一维度 |
+| `is_unique = true` | 标识该维度值唯一（如客户名称），帮助引擎优化 |
+| `is_time = true` | 标识为时间类型维度（如订单日期） |
+| `enum_values` | 限定允许的枚举值，提升查询准确性 |
+
+---
+
+## 指标定义语法
+
+```sql
+<逻辑表别名>.<指标名> AS <聚合表达式>
+    [ COMMENT = '<说明>' ]
+```
+
+支持的聚合函数：`COUNT`、`AVG`、`SUM`、`MIN`、`MAX`
+
+示例：
+```sql
+METRICS (
+    orders.total_revenue AS SUM(o_totalprice)
+        COMMENT = '总收入',
+    orders.avg_order_value AS AVG(o_totalprice)
+        COMMENT = '平均订单金额',
+    customers.customer_count AS COUNT(c_custkey)
+        COMMENT = '客户总数'
+)
+```
+
+---
+
+## semantic_view() 查询函数语法
+
+```sql
+SELECT *
+FROM semantic_view(
+    <视图名称>,
+    DIMENSIONS <维度名> [ , DIMENSIONS <维度名> ... ],
+    METRICS <指标名> [ , METRICS <指标名> ... ]
+)
+[ WHERE <过滤条件> ];
+```
+
+- 维度名可用限定名（`表别名.维度名`）或短名（名称唯一时）
+- 结果自动按指定维度分组，无需写 GROUP BY
+- WHERE 子句中的列名使用短名（不含表别名前缀）
+
+---
+
+## 管理命令
+
+| 命令 | 说明 |
+|---|---|
+| `CREATE SEMANTIC VIEW` | 创建语义视图 |
+| `DROP SEMANTIC VIEW IF EXISTS <名称>` | 删除语义视图 |
+| `SHOW SEMANTIC VIEWS` | 列出当前 Schema 所有语义视图 |
+| `SHOW SEMANTIC VIEWS IN <schema>` | 列出指定 Schema 的语义视图 |
+| `DESC EXTENDED <名称>` | 查看详细定义（逻辑表/维度/指标/外键/索引） |
+
+---
+
+## 最佳实践
+
+```sql
+-- 1. 幂等创建（始终先删再建）
+DROP SEMANTIC VIEW IF EXISTS my_view;
+CREATE SEMANTIC VIEW my_view ...;
+
+-- 2. 使用有意义的业务术语命名
+-- 好：customer_name, total_revenue, order_date
+-- 差：c_name, sum_totalprice, o_orderdate
+
+-- 3. 合理设置维度元数据
+-- is_time=true 用于日期/时间维度
+-- is_unique=true 用于主键类维度（如客户ID、订单号）
+-- enum_values 用于状态类维度（如订单状态）
+
+-- 4. 计算维度示例
+DIMENSIONS (
+    orders.order_year AS YEAR(o_orderdate)   -- 从日期提取年份
+        COMMENT = '下单年份',
+    orders.order_month AS MONTH(o_orderdate) -- 从日期提取月份
+        COMMENT = '下单月份'
+)
+```

package/bin/skills/clickzetta-spark-flink-connector/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: clickzetta-spark-flink-connector
+description: |
+  使用 Spark Connector 或 Flink Write Connector 将数据写入 ClickZetta Lakehouse。
+  覆盖 Spark DataFrame 读写配置（Maven 依赖、连接参数、read/write 代码）、
+  Flink Table API 写入（CDC 模式 igs-dynamic-table、仅追加模式 igs-dynamic-table-append-only）、
+  checkpoint 配置、buffer/flush 调优，以及主键表限制等关键约束。
+  当用户说"Spark Connector"、"Flink Connector"、"Spark 写入 Lakehouse"、
+  "Flink 写入 Lakehouse"、"spark-clickzetta"、"igs-flink-connector"、
+  "Spark DataFrame 写入"、"Flink CDC 写入"、"Flink sink"、
+  "spark.read.format clickzetta"时触发。
+  Keywords: Spark, Flink, DataFrame, connector, read, write, CDC, igs-dynamic-table
+---
+
+# ClickZetta Spark & Flink Connector
+
+阅读 [references/spark.md](references/spark.md) 了解 Spark Connector，[references/flink.md](references/flink.md) 了解 Flink Write Connector。
+
+---
+
+## 关键约束（必读）
+
+| 约束 | Spark Connector | Flink Connector |
+|---|---|---|
+| 主键表写入 | ❌ 不支持 | ✅ 支持（igs-dynamic-table 模式） |
+| 部分字段写入 | ❌ 必须写全部字段 | ✅ 支持 |
+| CDC（UPDATE/DELETE） | ❌ 仅 append | ✅ igs-dynamic-table 模式支持 |
+| Spark 版本 | 3.4.0+ | — |
+| Flink 版本 | — | 1.15.2+ |
+
+---
+
+## Spark Connector 快速示例
+
+```scala
+// 写入
+df.write.format("clickzetta")
+  .option("endpoint", "your_instance.cn-shanghai-alicloud.api.clickzetta.com")
+  .option("username", sys.env("CZ_USERNAME"))
+  .option("password", sys.env("CZ_PASSWORD"))
+  .option("workspace", "your_workspace")
+  .option("virtualCluster", "default_ap")
+  .option("schema", "public")
+  .option("table", "orders")
+  .mode("append")
+  .save()
+
+// 读取
+val df = spark.read.format("clickzetta")
+  .option("endpoint", "your_instance.cn-shanghai-alicloud.api.clickzetta.com")
+  .option("username", sys.env("CZ_USERNAME"))
+  .option("password", sys.env("CZ_PASSWORD"))
+  .option("workspace", "your_workspace")
+  .option("virtualCluster", "default_ap")
+  .option("schema", "public")
+  .option("table", "orders")
+  .load()
+```
+
+---
+
+## Flink Connector 快速示例
+
+```sql
+-- CDC 模式（支持 INSERT/UPDATE/DELETE，目标表需有主键）
+CREATE TABLE lakehouse_sink (
+    order_id   INT,
+    status     STRING,
+    amount     DOUBLE,
+    PRIMARY KEY (order_id) NOT ENFORCED
+) WITH (
+    'connector'       = 'igs-dynamic-table',
+    'curl'            = 'jdbc:clickzetta://your_instance.cn-shanghai-alicloud.api.clickzetta.com/default?username=user&password=***&schema=public',
+    'schema-name'     = 'public',
+    'table-name'      = 'orders',
+    'sink.parallelism' = '1',
+    'properties'      = 'authentication:true'
+);
+
+INSERT INTO lakehouse_sink SELECT order_id, status, amount FROM source_table;
+```
+
+---
+
+## 选择指南
+
+| 场景 | 推荐方案 |
+|---|---|
+| Spark ETL 批量写入（无主键表） | Spark Connector |
+| Flink 实时流写入（无主键表） | Flink igs-dynamic-table-append-only |
+| Flink CDC 同步（有主键表，含 UPDATE/DELETE） | Flink igs-dynamic-table |
+| 高频实时写入（Java 应用） | Java SDK RealtimeStream |

package/bin/skills/clickzetta-spark-flink-connector/eval_cases.jsonl

@@ -0,0 +1,5 @@
+{"case_id":"001","type":"should_call","user_input":"怎么用 Spark DataFrame 写入 ClickZetta Lakehouse？","expected_skill":"clickzetta-spark-flink-connector","expected_output_contains":["format(\"clickzetta\")","write"]}
+{"case_id":"002","type":"should_call","user_input":"Flink CDC 写入 ClickZetta 支持 UPDATE 和 DELETE 吗？","expected_skill":"clickzetta-spark-flink-connector","expected_output_contains":["igs-dynamic-table","CDC"]}
+{"case_id":"003","type":"should_call","user_input":"Spark Connector 支持写入主键表吗？","expected_skill":"clickzetta-spark-flink-connector","expected_output_contains":["不支持","Flink"]}
+{"case_id":"004","type":"should_call","user_input":"Flink 写入 ClickZetta 需要什么版本？","expected_skill":"clickzetta-spark-flink-connector","expected_output_contains":["1.15"]}
+{"case_id":"005","type":"should_call","user_input":"Flink 写入主键表的 sink.parallelism 有什么限制？","expected_skill":"clickzetta-spark-flink-connector","expected_output_contains":["1"]}

package/bin/skills/clickzetta-spark-flink-connector/references/flink.md

@@ -0,0 +1,147 @@
+# Flink Write Connector 详细参考
+
+## Maven 依赖
+
+```xml
+<dependency>
+    <groupId>com.clickzetta</groupId>
+    <artifactId>igs-flink-connector-1.15</artifactId>  <!-- 按 Flink 版本替换 -->
+    <version>联系 ClickZetta 支持获取版本号</version>
+</dependency>
+<!-- Flink 核心（provided） -->
+<dependency>
+    <groupId>org.apache.flink</groupId>
+    <artifactId>flink-streaming-java</artifactId>
+    <version>1.15.2</version>
+    <scope>provided</scope>
+</dependency>
+<dependency>
+    <groupId>org.apache.flink</groupId>
+    <artifactId>flink-table-api-java-bridge</artifactId>
+    <version>1.15.2</version>
+    <scope>provided</scope>
+</dependency>
+```
+
+## 两种写入模式
+
+### 模式 1：igs-dynamic-table（CDC，支持主键表）
+
+```sql
+-- 目标表必须有主键
+CREATE TABLE lakehouse_orders_sink (
+    order_id   INT,
+    customer   STRING,
+    amount     DOUBLE,
+    status     STRING,
+    updated_at TIMESTAMP(3),
+    PRIMARY KEY (order_id) NOT ENFORCED
+) WITH (
+    'connector'        = 'igs-dynamic-table',
+    'curl'             = 'jdbc:clickzetta://your_instance.cn-shanghai-alicloud.api.clickzetta.com/default?username=user&password=***&schema=public&virtualcluster=default_ap',
+    'schema-name'      = 'public',
+    'table-name'       = 'orders',
+    'sink.parallelism' = '1',          -- 主键表必须为 1
+    'properties'       = 'authentication:true'
+);
+```
+
+### 模式 2：igs-dynamic-table-append-only（仅追加，无主键表）
+
+```sql
+CREATE TABLE lakehouse_events_sink (
+    event_id   BIGINT,
+    user_id    BIGINT,
+    event_type STRING,
+    event_time TIMESTAMP(3)
+) WITH (
+    'connector'        = 'igs-dynamic-table-append-only',
+    'curl'             = 'jdbc:clickzetta://your_instance.cn-shanghai-alicloud.api.clickzetta.com/default?username=user&password=***&schema=public&virtualcluster=default_ap',
+    'schema-name'      = 'public',
+    'table-name'       = 'events',
+    'sink.parallelism' = '4',          -- 无主键表可提高并行度
+    'properties'       = 'authentication:true'
+);
+```
+
+## 完整 CDC 同步示例（MySQL → Lakehouse）
+
+```sql
+-- 1. MySQL CDC 源表
+CREATE TABLE mysql_orders_source (
+    order_id   INT,
+    customer   STRING,
+    amount     DOUBLE,
+    status     STRING,
+    updated_at TIMESTAMP(3),
+    PRIMARY KEY (order_id) NOT ENFORCED
+) WITH (
+    'connector' = 'mysql-cdc',
+    'hostname'  = 'mysql-host',
+    'port'      = '3306',
+    'username'  = 'cdc_user',
+    'password'  = 'cdc_password',
+    'database-name' = 'orders_db',
+    'table-name'    = 'orders'
+);
+
+-- 2. Lakehouse Sink（CDC 模式）
+CREATE TABLE lakehouse_orders_sink (
+    order_id   INT,
+    customer   STRING,
+    amount     DOUBLE,
+    status     STRING,
+    updated_at TIMESTAMP(3),
+    PRIMARY KEY (order_id) NOT ENFORCED
+) WITH (
+    'connector'        = 'igs-dynamic-table',
+    'curl'             = 'jdbc:clickzetta://...',
+    'schema-name'      = 'public',
+    'table-name'       = 'orders',
+    'sink.parallelism' = '1',
+    'properties'       = 'authentication:true'
+);
+
+-- 3. 同步
+INSERT INTO lakehouse_orders_sink SELECT * FROM mysql_orders_source;
+```
+
+## Buffer 与 Flush 调优
+
+```sql
+-- 在 WITH 子句中添加调优参数
+'mutation.buffer.lines.num'  = '500'    -- 每批缓冲行数（默认 100）
+'mutation.buffer.space'      = '10MB'   -- 缓冲区大小（默认 5MB）
+'mutation.buffer.max.num'    = '8'      -- 并发缓冲区数（默认 5）
+'mutation.flush.interval'    = '5000'   -- flush 间隔毫秒（默认 10000）
+'flush.mode'                 = 'AUTO_FLUSH_BACKGROUND'  -- 异步 flush（默认）
+```
+
+## Checkpoint 配置（Java）
+
+```java
+StreamExecutionEnvironment env = StreamExecutionEnvironment.getExecutionEnvironment();
+
+// 生产环境必须开启 checkpoint
+env.enableCheckpointing(60000);  // 每 60 秒一次
+env.getCheckpointConfig().setCheckpointingMode(CheckpointingMode.EXACTLY_ONCE);
+env.getCheckpointConfig().setMaxConcurrentCheckpoints(1);
+env.getCheckpointConfig().setMinPauseBetweenCheckpoints(30000);
+env.getCheckpointConfig().setCheckpointTimeout(120000);
+```
+
+## 私有网络访问
+
+```sql
+-- 内网访问（VPC 内部）
+'properties' = 'authentication:true,isInternal:true,isDirect:false'
+```
+
+## 常见问题
+
+| 问题 | 原因 | 解决方案 |
+|---|---|---|
+| 写入主键表数据不更新 | 使用了 append-only 模式 | 改用 `igs-dynamic-table` 模式 |
+| 并行度 > 1 时数据乱序 | 主键表要求顺序写入 | 主键表 `sink.parallelism` 必须设为 `1` |
+| checkpoint 失败 | 未配置 checkpoint 或超时 | 增大 `setCheckpointTimeout`，检查网络 |
+| 连接超时 | 网络不通或认证失败 | 检查 `curl` 中的 username/password，确认 VPC 配置 |