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

package/bin/skills/clickzetta-file-import-pipeline/SKILL.md

@@ -10,6 +10,40 @@ description: |
 
 # URL/文件数据导入工作流
 
+## 向导：收集必要信息
+
+开始导入前，优先使用交互式问答工具（如 `question`）收集以下信息并弹出选项菜单；若无此类工具，则用文字一次性列出所有问题：
+
+```
+question({
+  questions: [
+    {
+      question: "文件来源？",
+      options: [
+        { label: "HTTP/HTTPS URL", description: "提供完整链接，自动下载" },
+        { label: "本地文件", description: "本地路径，上传到 User Volume" },
+        { label: "已在 Volume 上", description: "提供 Volume 名称和文件路径" },
+        { label: "外部 Volume（OSS/S3/COS）", description: "提供外部存储路径" }
+      ]
+    },
+    {
+      question: "写入模式？",
+      options: [
+        { label: "create（自动建表）", description: "表不存在，推断 schema 后建表" },
+        { label: "append（追加）", description: "追加到已有表，不删除历史数据" },
+        { label: "overwrite（覆盖）", description: "清空已有表再写入" }
+      ]
+    }
+  ]
+})
+```
+
+**如果用户已经提供了足够信息，直接进入工作流，不再弹出菜单。**
+
+**如果用户已经提供了足够信息（如"把这个 URL 的 CSV 导入到 ods.orders 表"），直接进入步骤 1，不再重复询问。**
+
+---
+
 ## 指令
 
 ### 步骤 1：获取源文件并上传到 Volume

package/bin/skills/clickzetta-java-sdk/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: clickzetta-java-sdk
+description: |
+  使用 ClickZetta Java SDK 将数据批量或实时写入 Lakehouse 表。
+  覆盖 BulkloadStream（本地文件/数据库批量上传）和 RealtimeStream（Kafka 实时消费写入）
+  两种接口的完整使用模式，包括 Maven 依赖、连接 URL 格式、行写入 API、
+  状态监控、Options 调优和常见错误处理。
+  当用户说"Java SDK"、"BulkloadStream"、"RealtimeStream"、
+  "Java 写入 Lakehouse"、"Java 批量上传"、"Kafka Java 写入"、
+  "clickzetta-java"、"Maven 依赖"、"Java 数据导入"时触发。
+  Keywords: Java SDK, BulkloadStream, RealtimeStream, Kafka consumer, batch write, real-time write
+---
+
+# ClickZetta Java SDK
+
+Java SDK 提供两种写入接口：
+- **BulkloadStream** — 批量写入，适合定时 ETL、本地文件导入（不支持主键表，不适合 5 分钟以内的高频写入）
+- **RealtimeStream** — 实时写入，适合 Kafka 消费、流式数据接入（秒级可查）
+
+阅读 [references/bulkload.md](references/bulkload.md) 了解批量写入，[references/realtime.md](references/realtime.md) 了解实时写入。
+
+---
+
+## Maven 依赖
+
+```xml
+<!-- clickzetta-java 最新版本见 https://central.sonatype.com/artifact/com.clickzetta/clickzetta-java -->
+<dependency>
+    <groupId>com.clickzetta</groupId>
+    <artifactId>clickzetta-java</artifactId>
+    <version>2.0.0</version>
+</dependency>
+```
+
+RealtimeStream + Kafka 还需要：
+
+```xml
+<dependency>
+    <groupId>org.apache.kafka</groupId>
+    <artifactId>kafka-clients</artifactId>
+    <version>3.2.0</version>
+</dependency>
+```
+
+---
+
+## 连接 URL 格式
+
+```java
+// 推荐：显式参数方式（2.0.0+ 支持，不依赖 URL 解析）
+ClickZettaClient client = ClickZettaClient.newBuilder()
+    .service("cn-shanghai-alicloud.api.clickzetta.com")
+    .instance("your_instance")
+    .workspace("your_workspace")
+    .schema("public")
+    .username("your_user")
+    .password("your_password")
+    .vcluster("default")
+    .build();
+
+// 兼容：URL 方式（BulkloadStream 用 virtualcluster=，RealtimeStream 用 vcluster=）
+String bulkUrl = MessageFormat.format(
+    "jdbc:clickzetta://{0}.{1}/{2}?schema={3}&username={4}&password={5}&virtualcluster={6}",
+    instance, region_endpoint, workspace, schema, username, password, vcluster
+);
+String rtUrl = MessageFormat.format(
+    "jdbc:clickzetta://{0}.{1}/{2}?schema={3}&username={4}&password={5}&vcluster={6}",
+    instance, region_endpoint, workspace, schema, username, password, vcluster
+);
+ClickZettaClient client = ClickZettaClient.newBuilder().url(url).build();
+```
+
+JDBC 连接（DDL / 查询）：
+
+```java
+// 2.0.0+ 驱动类：com.clickzetta.client.jdbc.ClickZettaDriver
+// 1.x 驱动类：com.clickzetta.jdbc.ClickZettaDriver
+Class.forName("com.clickzetta.client.jdbc.ClickZettaDriver");
+Connection conn = DriverManager.getConnection(jdbcUrl);
+```
+
+---
+
+## BulkloadStream 快速示例
+
+```java
+// 创建 BulkloadStream
+BulkloadStream stream = client.newBulkloadStreamBuilder()
+    .schema("public")
+    .table("orders")
+    .operate(RowStream.BulkLoadOperate.APPEND)
+    .build();
+
+// 写入数据（列索引从 0 开始，顺序与建表 DDL 一致）
+Row row = stream.createRow();
+row.setValue(0, "order-001");   // STRING
+row.setValue(1, 1);             // INT
+row.setValue(2, 299.99);        // DOUBLE
+stream.apply(row);              // ⚠️ 必须调用，否则数据不发送到服务端
+
+// 关闭并等待完成
+stream.close();
+while (stream.getState() == StreamState.RUNNING) {
+    Thread.sleep(1000);
+}
+if (stream.getState() == StreamState.FAILED) {
+    throw new RuntimeException(stream.getErrorMessage());
+}
+client.close();
+```
+
+---
+
+## RealtimeStream 快速示例
+
+```java
+// Options 调优
+Options options = Options.builder()
+    .withMutationBufferLinesNum(10)  // 缓冲行数
+    .build();
+
+// 创建 RealtimeStream（普通表，APPEND_ONLY）
+RealtimeStream stream = client.newRealtimeStreamBuilder()
+    .operate(RowStream.RealTimeOperate.APPEND_ONLY)
+    .options(options)
+    .schema("public")
+    .table("events")
+    .build();
+
+// 写入数据（用列名，不用索引）
+Row row = stream.createRow(Stream.Operator.INSERT);
+row.setValue("id", 1);
+row.setValue("event", "{\"type\":\"click\"}");
+stream.apply(row);
+stream.close();
+```
+
+## RealtimeStream CDC 示例（主键表 UPSERT / DELETE）
+
+```java
+// 建表：CREATE TABLE orders (txid STRING NOT NULL PRIMARY KEY, amount DOUBLE, status STRING);
+
+RealtimeStream stream = client.newRealtimeStreamBuilder()
+    .operate(RowStream.RealTimeOperate.CDC)   // 主键表必须用 CDC
+    .options(options)
+    .schema("public")
+    .table("orders")
+    .build();
+
+// UPSERT：存在则更新，不存在则插入
+Row row = stream.createRow(Stream.Operator.UPSERT);
+row.setValue("txid", "order-001");
+row.setValue("amount", 299.99);
+row.setValue("status", "paid");
+stream.apply(row);
+
+// DELETE_IGNORE：删除，目标行不存在时自动忽略
+Row del = stream.createRow(Stream.Operator.DELETE_IGNORE);
+del.setValue("txid", "order-001");
+stream.apply(del);
+
+stream.close();
+```
+
+---
+
+## 选择指南
+
+| 场景 | 推荐接口 |
+|---|---|
+| 定时批量 ETL（每小时/每天） | BulkloadStream |
+| Kafka 实时消费 | RealtimeStream |
+| 5 分钟以内高频写入 | RealtimeStream |
+| 主键表写入（UPSERT / DELETE） | RealtimeStream CDC 模式 |
+
+---
+
+## 使用限制
+
+| 限制 | BulkloadStream | RealtimeStream |
+|---|---|---|
+| 主键表 | ❌ 不支持 | ✅ CDC 模式支持 |
+| 高频写入（< 5 分钟） | ❌ 不适合 | ✅ 支持 |
+| 数据可见延迟 | 写完 close() 后可见 | ~1 分钟后可见 |
+| Table Stream/Dynamic Table 可见 | close() 后 | ~1 分钟后 |
+| 表结构变更 | 重建 Stream | 停止任务，变更后约 90 分钟重启 |

package/bin/skills/clickzetta-java-sdk/eval_cases.jsonl

@@ -0,0 +1,12 @@
+{"case_id":"001","type":"should_call","user_input":"用 Java SDK BulkloadStream 批量写入数据到 Lakehouse","expected_skill":"clickzetta-java-sdk","expected_output_contains":["BulkloadStream"]}
+{"case_id":"002","type":"should_call","user_input":"Java 怎么消费 Kafka 实时写入 Lakehouse","expected_skill":"clickzetta-java-sdk","expected_output_contains":["RealtimeStream"]}
+{"case_id":"003","type":"should_call","user_input":"clickzetta-java 的 Maven 依赖怎么配","expected_skill":"clickzetta-java-sdk","expected_output_contains":["groupId","clickzetta-java"]}
+{"case_id":"004","type":"should_call","user_input":"BulkloadStream 和 RealtimeStream 有什么区别","expected_skill":"clickzetta-java-sdk","expected_output_contains":["BulkloadStream","RealtimeStream"]}
+{"case_id":"005","type":"should_call","user_input":"Java SDK 连接 URL 格式是什么","expected_skill":"clickzetta-java-sdk","expected_output_contains":["URL"]}
+{"case_id":"006","type":"should_call","user_input":"Java 批量上传本地文件到 Lakehouse","expected_skill":"clickzetta-java-sdk","expected_output_contains":["BulkloadStream"]}
+{"case_id":"007","type":"should_call","user_input":"RealtimeStream 的 setValue 怎么用","expected_skill":"clickzetta-java-sdk","expected_output_contains":["setValue"]}
+{"case_id":"008","type":"should_not_call","user_input":"Python SDK 怎么连接 Lakehouse","forbidden_skill":"clickzetta-java-sdk"}
+{"case_id":"009","type":"should_not_call","user_input":"帮我写一个 Spring Boot 应用","forbidden_skill":"clickzetta-java-sdk"}
+{"case_id":"010","type":"should_not_call","user_input":"Flink 怎么写入 Lakehouse","forbidden_skill":"clickzetta-java-sdk"}
+{"case_id":"011","type":"should_not_call","user_input":"怎么创建 VCluster","forbidden_skill":"clickzetta-java-sdk"}
+{"case_id":"012","type":"should_not_call","user_input":"MySQL JDBC 连接怎么配置","forbidden_skill":"clickzetta-java-sdk"}

package/bin/skills/clickzetta-java-sdk/references/bulkload.md

@@ -0,0 +1,163 @@
+# BulkloadStream 详细参考
+
+> 适合：定时 ETL、本地文件导入、数据库迁移
+> 不适合：主键表、5 分钟以内高频写入
+
+## Maven 依赖
+
+```xml
+<!-- 最新版本见 https://central.sonatype.com/artifact/com.clickzetta/clickzetta-java -->
+<dependency>
+    <groupId>com.clickzetta</groupId>
+    <artifactId>clickzetta-java</artifactId>
+    <version>2.0.0</version>
+</dependency>
+```
+
+最新版本见 [Maven Central](https://central.sonatype.com/artifact/com.clickzetta/clickzetta-java)
+
+## 使用限制
+
+- **不支持主键（pk）表写入**
+- **不适合时间间隔小于 5 分钟的高频写入**
+- 写入完成 `close()` 后数据才可见
+
+## 完整示例：读取本地 CSV 写入 Lakehouse
+
+### 建表
+
+```sql
+CREATE TABLE bulk_order_items (
+    order_id            STRING,
+    order_item_id       INT,
+    product_id          STRING,
+    seller_id           STRING,
+    shipping_limit_date STRING,
+    price               DOUBLE,
+    freight_value       DOUBLE
+);
+```
+
+### Java 代码（BulkloadFile 类）
+
+```java
+import com.clickzetta.client.BulkloadStream;
+import com.clickzetta.client.ClickZettaClient;
+import com.clickzetta.client.RowStream;
+import com.clickzetta.client.StreamState;
+import com.clickzetta.platform.client.api.Row;
+
+import java.io.BufferedReader;
+import java.io.File;
+import java.io.FileReader;
+import java.text.MessageFormat;
+
+public class BulkloadFile {
+    private static ClickZettaClient client;
+    private static final String password = "";
+    private static final String table = "bulk_order_items";
+    private static final String workspace = "";
+    private static final String schema = "public";
+    private static final String vc = "default";
+    private static final String user = "";
+    static BulkloadStream bulkloadStream;
+
+    public static void main(String[] args) throws Exception {
+        initialize();
+        File csvFile = new File("olist_order_items_dataset.csv");
+        BufferedReader reader = new BufferedReader(new FileReader(csvFile));
+        reader.readLine(); // 跳过 header 行
+
+        String line;
+        while ((line = reader.readLine()) != null) {
+            String[] values = line.split(",");
+            // 类型转换必须与建表 DDL 一致
+            String orderId = values[0];
+            int orderItemId = Integer.parseInt(values[1]);
+            String productId = values[2];
+            String sellerId = values[3];
+            String shippingLimitDate = values[4];
+            double price = Double.parseDouble(values[5]);
+            double freightValue = Double.parseDouble(values[6]);
+
+            Row row = bulkloadStream.createRow();
+            // ⚠️ BulkloadStream 用列索引（从 0 开始），顺序与建表 DDL 一致
+            row.setValue(0, orderId);
+            row.setValue(1, orderItemId);
+            row.setValue(2, productId);
+            row.setValue(3, sellerId);
+            row.setValue(4, shippingLimitDate);
+            row.setValue(5, price);
+            row.setValue(6, freightValue);
+            // ⚠️ 必须调用 apply()，否则数据不发送到服务端
+            bulkloadStream.apply(row);
+        }
+
+        reader.close();
+        bulkloadStream.close();
+        waitForBulkloadCompletion();
+        client.close();
+        System.out.println("Data inserted successfully!");
+    }
+
+    private static void initialize() throws Exception {
+        // 推荐：显式参数方式（2.0.0+ 支持）
+        client = ClickZettaClient.newBuilder()
+            .service("cn-shanghai-alicloud.api.clickzetta.com")
+            .instance("your_instance")
+            .workspace(workspace)
+            .schema(schema)
+            .username(user)
+            .password(password)
+            .vcluster(vc)
+            .build();
+        bulkloadStream = client.newBulkloadStreamBuilder()
+            .schema(schema)
+            .table(table)
+            .operate(RowStream.BulkLoadOperate.APPEND)
+            .build();
+    }
+
+    private static void waitForBulkloadCompletion() throws InterruptedException {
+        while (bulkloadStream.getState() == StreamState.RUNNING) {
+            Thread.sleep(1000);
+        }
+        if (bulkloadStream.getState() == StreamState.FAILED) {
+            throw new RuntimeException(bulkloadStream.getErrorMessage());
+        }
+    }
+}
+```
+
+## 关键 API
+
+| API | 说明 |
+|---|---|
+| `bulkloadStream.createRow()` | 创建行对象（无参数） |
+| `row.setValue(int index, Object value)` | 按列索引设值（从 0 开始） |
+| `bulkloadStream.apply(row)` | 发送行到服务端（必须调用） |
+| `bulkloadStream.close()` | 关闭并触发提交 |
+| `bulkloadStream.getState()` | 获取状态：RUNNING / SUCCEEDED / FAILED |
+| `bulkloadStream.getErrorMessage()` | 获取失败原因 |
+
+## 类型映射
+
+| Java 类型 | Lakehouse 类型 |
+|---|---|
+| `Long` / `long` | BIGINT |
+| `Integer` / `int` | INT |
+| `Double` / `double` | DOUBLE |
+| `String` | STRING / VARCHAR |
+| `Boolean` | BOOLEAN |
+| `java.sql.Timestamp` | TIMESTAMP |
+| `java.sql.Date` | DATE |
+| `BigDecimal` | DECIMAL |
+
+## 常见问题
+
+| 问题 | 原因 | 解决方案 |
+|---|---|---|
+| 数据写入后查不到 | 未调用 `apply()` 或未等待 RUNNING 结束 | 确认每行都调用 `apply()`，等待状态变为 SUCCEEDED |
+| 主键表写入报错 | BulkloadStream 不支持主键表 | 改用 JDBC + MERGE 或 Flink igs-dynamic-table |
+| 列值类型不匹配 | Java 类型与建表 DDL 不一致 | 写入前做类型转换（parseInt、parseDouble 等） |
+| 连接失败 | URL 参数名错误 | BulkloadStream 用 `virtualcluster=`，不是 `vcluster=` |

package/bin/skills/clickzetta-java-sdk/references/realtime.md

@@ -0,0 +1,212 @@
+# RealtimeStream 实时写入参考
+
+> 适合：Kafka 消费写入、高频实时数据接入（秒级可查）、主键表 CDC 写入
+
+## Maven 依赖
+
+```xml
+<!-- 最新版本见 https://central.sonatype.com/artifact/com.clickzetta/clickzetta-java -->
+<dependency>
+    <groupId>com.clickzetta</groupId>
+    <artifactId>clickzetta-java</artifactId>
+    <version>2.0.0</version>
+</dependency>
+<dependency>
+    <groupId>org.apache.kafka</groupId>
+    <artifactId>kafka-clients</artifactId>
+    <version>3.2.0</version>
+</dependency>
+```
+
+## 使用限制
+
+- 实时写入的数据可以秒级查询
+- table stream、dynamic table 需等待约 **1 分钟**才能看到写入数据
+- 表结构变更时，需停止任务，变更后约 **90 分钟**重新启动
+
+## 操作模式
+
+| 模式 | 适用表 | 可用 Operator |
+|---|---|---|
+| `RealTimeOperate.APPEND_ONLY` | 普通表 | `Stream.Operator.INSERT` |
+| `RealTimeOperate.CDC` | 主键表 | `Stream.Operator.UPSERT`、`Stream.Operator.DELETE_IGNORE` |
+
+## 普通表写入（APPEND_ONLY）
+
+```java
+// 推荐：显式参数方式（2.0.0+ 支持，不依赖 URL 解析）
+ClickZettaClient client = ClickZettaClient.newBuilder()
+    .service("cn-shanghai-alicloud.api.clickzetta.com")
+    .instance("your_instance")
+    .workspace(workspace)
+    .schema(schema)
+    .username(user)
+    .password(password)
+    .vcluster(vc)
+    .build();
+Options options = Options.builder().withMutationBufferLinesNum(10).build();
+
+RealtimeStream stream = client.newRealtimeStreamBuilder()
+    .operate(RowStream.RealTimeOperate.APPEND_ONLY)
+    .options(options)
+    .schema(schema)
+    .table("events")
+    .build();
+
+// ⚠️ RealtimeStream 用列名（不是索引）
+Row row = stream.createRow(Stream.Operator.INSERT);
+row.setValue("id", 1);
+row.setValue("event", "{\"type\":\"click\"}");
+stream.apply(row);
+```
+
+## 主键表写入（CDC 模式）
+
+```java
+// 建表（主键表）
+// CREATE TABLE orders (`txid` STRING PRIMARY KEY, `amount` DOUBLE, `status` STRING);
+
+RealtimeStream stream = client.newRealtimeStreamBuilder()
+    .operate(RowStream.RealTimeOperate.CDC)
+    .options(options)
+    .schema(schema)
+    .table("orders")
+    .build();
+
+// UPSERT：存在则更新，不存在则插入
+Row row = stream.createRow(Stream.Operator.UPSERT);
+row.setValue("txid", "order-001");
+row.setValue("amount", 299.99);
+row.setValue("status", "paid");
+stream.apply(row);
+
+// DELETE_IGNORE：删除，目标行不存在时自动忽略
+Row delRow = stream.createRow(Stream.Operator.DELETE_IGNORE);
+delRow.setValue("txid", "order-001");
+stream.apply(delRow);
+```
+
+## 完整示例：Kafka → Lakehouse
+
+### KafkaReader 类
+
+```java
+import org.apache.kafka.clients.consumer.ConsumerConfig;
+import org.apache.kafka.clients.consumer.KafkaConsumer;
+import java.util.Collections;
+import java.util.Properties;
+
+public class KafkaReader {
+    private KafkaConsumer<String, String> consumer;
+
+    public KafkaReader() {
+        Properties props = new Properties();
+        props.put(ConsumerConfig.BOOTSTRAP_SERVERS_CONFIG, "localhost:9092");
+        props.put(ConsumerConfig.GROUP_ID_CONFIG, "test-group");
+        props.put(ConsumerConfig.KEY_DESERIALIZER_CLASS_CONFIG,
+            "org.apache.kafka.common.serialization.StringDeserializer");
+        props.put(ConsumerConfig.VALUE_DESERIALIZER_CLASS_CONFIG,
+            "org.apache.kafka.common.serialization.StringDeserializer");
+        props.put(ConsumerConfig.ENABLE_AUTO_COMMIT_CONFIG, "true");
+        props.put(ConsumerConfig.AUTO_COMMIT_INTERVAL_MS_CONFIG, "1000");
+        consumer = new KafkaConsumer<>(props);
+    }
+
+    public KafkaConsumer<String, String> readFromTopic(String topic) {
+        consumer.subscribe(Collections.singleton(topic));
+        return consumer;
+    }
+}
+```
+
+### Kafka2Lakehouse 主类
+
+```java
+import com.clickzetta.client.ClickZettaClient;
+import com.clickzetta.client.RealtimeStream;
+import com.clickzetta.client.RowStream;
+import com.clickzetta.platform.client.api.Options;
+import com.clickzetta.platform.client.api.Row;
+import com.clickzetta.platform.client.api.Stream;
+import org.apache.kafka.clients.consumer.ConsumerRecord;
+import org.apache.kafka.clients.consumer.ConsumerRecords;
+import org.apache.kafka.clients.consumer.KafkaConsumer;
+import java.time.Duration;
+
+public class Kafka2Lakehouse {
+    private static ClickZettaClient client;
+    private static final String password = "";
+    private static final String table = "realtime_stream";
+    private static final String workspace = "";
+    private static final String schema = "public";
+    private static final String user = "";
+    private static final String vc = "default";
+    static RealtimeStream realtimeStream;
+
+    public static void main(String[] args) throws Exception {
+        initialize();
+        KafkaReader kafkaReader = new KafkaReader();
+        final KafkaConsumer<String, String> consumer = kafkaReader.readFromTopic("lakehouse-stream");
+        int i = 1;
+        while (true) {
+            ConsumerRecords<String, String> records = consumer.poll(Duration.ofSeconds(1));
+            for (ConsumerRecord<String, String> record : records) {
+                Row row = realtimeStream.createRow(Stream.Operator.INSERT);
+                row.setValue("id", i++);
+                row.setValue("event", record.value());
+                realtimeStream.apply(row);
+            }
+        }
+    }
+
+    private static void initialize() throws Exception {
+        Options options = Options.builder().withMutationBufferLinesNum(10).build();
+        client = ClickZettaClient.newBuilder()
+            .service("cn-shanghai-alicloud.api.clickzetta.com")
+            .instance("your_instance")
+            .workspace(workspace)
+            .schema(schema)
+            .username(user)
+            .password(password)
+            .vcluster(vc)
+            .build();
+        realtimeStream = client.newRealtimeStreamBuilder()
+            .operate(RowStream.RealTimeOperate.APPEND_ONLY)
+            .options(options)
+            .schema(schema)
+            .table(table)
+            .build();
+    }
+}
+```
+
+## 关键 API
+
+| API | 说明 |
+|---|---|
+| `realtimeStream.createRow(Stream.Operator.INSERT)` | 普通表插入行 |
+| `realtimeStream.createRow(Stream.Operator.UPSERT)` | 主键表 upsert 行 |
+| `realtimeStream.createRow(Stream.Operator.DELETE_IGNORE)` | 主键表删除行 |
+| `row.setValue(String columnName, Object value)` | 按列名设值（不是索引） |
+| `realtimeStream.apply(row)` | 发送行到服务端 |
+| `Options.builder().withMutationBufferLinesNum(n)` | 设置缓冲行数（默认 10） |
+
+## BulkloadStream vs RealtimeStream 对比
+
+| 维度 | BulkloadStream | RealtimeStream |
+|---|---|---|
+| 列设值方式 | `setValue(int index, value)` | `setValue(String name, value)` |
+| URL 参数 | `virtualcluster=` | `vcluster=` |
+| createRow 参数 | 无参数 | `Stream.Operator.INSERT/UPSERT/DELETE_IGNORE` |
+| 适用频率 | 低频（≥5 分钟/批） | 高频（秒级） |
+| 数据可见延迟 | close() 后可见 | ~1 分钟后可见 |
+| 主键表 | ❌ | ✅ CDC 模式 |
+
+## 常见问题
+
+| 问题 | 原因 | 解决方案 |
+|---|---|---|
+| 连接失败 | URL 参数名错误 | RealtimeStream 用 `vcluster=`，不是 `virtualcluster=` |
+| 列名找不到 | 列名拼写错误 | 列名区分大小写，与建表 DDL 保持一致 |
+| 表结构变更后写入失败 | 旧 Stream 实例缓存了旧 schema | 停止任务，变更后等约 90 分钟再重启 |
+| dynamic table 看不到数据 | 实时写入有 ~1 分钟确认延迟 | 等待 1 分钟后再查询 |