@clickzetta/cz-cli-linux-x64 0.3.4 → 0.3.5

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

@@ -1,163 +0,0 @@
-# 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

@@ -1,212 +0,0 @@
-# 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 分钟后再查询 |