@clickzetta/cz-cli-darwin-x64 0.3.81 → 0.3.83

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/LICENSE

@@ -0,0 +1,16 @@
+ClickZetta Skills License
+© 2026 Yunqi Inc. All rights reserved.
+LICENSE: Use of these materials (including all code, prompts, assets, files, and other components of these skills (collectively, "Skills")) is governed by your agreement with ClickZetta for the Service. If no separate agreement exists, use is governed by ClickZetta's Terms of Service (available at: https://yunqi.tech/documents/user-aggrement).
+Your applicable agreement is referred to as the "Agreement." "Service" is as defined in the Agreement.
+ADDITIONAL RESTRICTIONS: Notwithstanding anything in the Agreement to the contrary, you may not:
+
+Extract from the Service or retain copies of the Skills outside use with the Service;
+Reproduce or copy the Skills, except for temporary copies created automatically during authorized use of the Service;
+Create derivative works based on the Skills;
+Distribute, sublicense, or transfer the Skills to any third party;
+Make, offer to sell, sell, or import any inventions embodied in the Skills; nor,
+Reverse engineer, decompile, or disassemble the Skills.
+
+The receipt, viewing, or possession of the Skills does not convey or imply any license or right beyond those expressly granted above.
+Yunqi retains all rights, title, and interest in the Skills, including all copyrights, trademarks, patents, and all other applicable intellectual property rights.
+THE SKILLS ARE PROVIDED "AS IS," WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SKILLS OR THE USE OR OTHER DEALINGS IN THE SKILLS.

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 配置 |