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

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

@@ -1,167 +0,0 @@
-# 语义视图完整语法参考
-
-> 来源：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

@@ -1,92 +0,0 @@
----
-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/references/flink.md

@@ -1,147 +0,0 @@
-# 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 配置 |

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

@@ -1,132 +0,0 @@
-# Spark Connector 详细参考
-
-## Maven 依赖
-
-```xml
-<dependencies>
-    <dependency>
-        <groupId>org.apache.spark</groupId>
-        <artifactId>spark-sql_2.12</artifactId>
-        <version>3.4.0</version>
-        <scope>provided</scope>
-    </dependency>
-    <dependency>
-        <groupId>com.clickzetta</groupId>
-        <artifactId>spark-clickzetta</artifactId>
-        <version>1.0.0</version>
-    </dependency>
-</dependencies>
-```
-
-> ⚠️ `spark-clickzetta` JAR 需从 ClickZetta 官方下载，不在 Maven Central。联系 ClickZetta 支持获取。
-
-## 连接参数
-
-| 参数 | 必填 | 说明 |
-|---|---|---|
-| `endpoint` | ✅ | 如 `your_instance.cn-shanghai-alicloud.api.clickzetta.com` |
-| `username` | ✅ | 用户名 |
-| `password` | ✅ | 密码 |
-| `workspace` | ✅ | 工作空间 |
-| `virtualCluster` | ✅ | 虚拟集群，默认 `default_ap` |
-| `schema` | ✅ | Schema 名称 |
-| `table` | ✅ | 目标表名 |
-
-## 完整 Scala 示例
-
-```scala
-import org.apache.spark.sql.SparkSession
-
-object SparkToLakehouse {
-  def main(args: Array[String]): Unit = {
-    val spark = SparkSession.builder()
-      .appName("SparkToLakehouse")
-      .getOrCreate()
-
-    val endpoint = sys.env("CZ_ENDPOINT")
-    val username = sys.env("CZ_USERNAME")
-    val password = sys.env("CZ_PASSWORD")
-    val workspace = sys.env("CZ_WORKSPACE")
-
-    // 读取
-    val df = spark.read.format("clickzetta")
-      .option("endpoint", endpoint)
-      .option("username", username)
-      .option("password", password)
-      .option("workspace", workspace)
-      .option("virtualCluster", "default_ap")
-      .option("schema", "silver")
-      .option("table", "orders_cleaned")
-      .load()
-
-    // 转换
-    import org.apache.spark.sql.functions._
-    val result = df
-      .filter(col("amount") > 0)
-      .groupBy("region")
-      .agg(sum("amount").as("total_revenue"), count("*").as("order_count"))
-
-    // 写入（必须写全部字段，不支持主键表）
-    result.write.format("clickzetta")
-      .option("endpoint", endpoint)
-      .option("username", username)
-      .option("password", password)
-      .option("workspace", workspace)
-      .option("virtualCluster", "default_ap")
-      .option("schema", "gold")
-      .option("table", "region_summary")
-      .mode("append")
-      .save()
-
-    spark.stop()
-  }
-}
-```
-
-## Python（PySpark）示例
-
-```python
-from pyspark.sql import SparkSession
-import os
-
-spark = SparkSession.builder.appName("PySparkToLakehouse").getOrCreate()
-
-options = {
-    "endpoint": os.environ["CZ_ENDPOINT"],
-    "username": os.environ["CZ_USERNAME"],
-    "password": os.environ["CZ_PASSWORD"],
-    "workspace": os.environ["CZ_WORKSPACE"],
-    "virtualCluster": "default_ap",
-    "schema": "public",
-    "table": "orders",
-}
-
-# 读取
-df = spark.read.format("clickzetta").options(**options).load()
-df.show(5)
-
-# 写入
-df.write.format("clickzetta").options(**options).mode("append").save()
-```
-
-## 类型映射
-
-| Spark 类型 | Lakehouse 类型 |
-|---|---|
-| BooleanType | BOOLEAN |
-| IntegerType | INT32 |
-| LongType | INT64 |
-| FloatType | FLOAT32 |
-| DoubleType | FLOAT64 |
-| StringType | STRING |
-| TimestampType | TIMESTAMP |
-| DateType | DATE |
-| ArrayType | ARRAY |
-| MapType | MAP |
-| StructType | STRUCT |
-
-## 限制
-
-- **不支持主键表写入**：目标表不能有主键，否则报错
-- **必须写全部字段**：DataFrame schema 必须与目标表完全匹配，不支持部分字段写入
-- **仅支持 append 模式**：不支持 overwrite（会报错）