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

package/bin/skills/clickzetta-volume-manager/references/volume-ddl.md

@@ -1,194 +0,0 @@
-# Volume 管理参考
-
-> 来源：https://www.yunqi.tech/documents/datalake_volume_object 等
-
-## Volume 类型
-
-| 类型 | 说明 |
-|---|---|
-| 外部 Volume（External Volume） | 挂载 OSS/COS/S3 等对象存储路径 |
-| 内部 Volume（Internal Volume） | 系统托管存储，含 User Volume、Table Volume、命名 Volume |
-
----
-
-## CREATE EXTERNAL VOLUME
-
-```sql
--- OSS
-CREATE EXTERNAL VOLUME my_oss_volume
-  LOCATION 'oss://<bucket>/<path>'
-  USING CONNECTION my_oss_conn
-  DIRECTORY = (ENABLE = TRUE, AUTO_REFRESH = TRUE)
-  RECURSIVE = TRUE;
-
--- COS
-CREATE EXTERNAL VOLUME my_cos_volume
-  LOCATION 'cos://<bucket>/<path>'
-  USING CONNECTION my_cos_conn
-  DIRECTORY = (ENABLE = TRUE)
-  RECURSIVE = TRUE;
-
--- S3
-CREATE EXTERNAL VOLUME my_s3_volume
-  LOCATION 's3://<bucket>/<path>'
-  USING CONNECTION my_s3_conn
-  DIRECTORY = (ENABLE = TRUE)
-  RECURSIVE = TRUE;
-```
-
-参数说明：
-- `LOCATION`：对象存储路径
-- `USING CONNECTION`：已创建的 STORAGE CONNECTION 名称
-- `DIRECTORY`：目录功能配置，`ENABLE=TRUE` 开启目录索引，`AUTO_REFRESH=TRUE` 自动刷新
-- `RECURSIVE`：是否递归扫描子目录
-
----
-
-## ALTER VOLUME
-
-```sql
--- 刷新目录元数据
-ALTER VOLUME my_oss_volume REFRESH;
-```
-
----
-
-## DROP VOLUME
-
-```sql
-DROP VOLUME IF EXISTS my_oss_volume;
-```
-
----
-
-## SHOW / DESC VOLUME
-
-```sql
--- 列出所有 Volume
-SHOW VOLUMES;
-
--- 按条件过滤（SHOW VOLUMES 不支持 WHERE，使用 information_schema）
-SELECT volume_name, volume_type, volume_region, volume_creator
-FROM information_schema.volumes
-WHERE volume_type = 'EXTERNAL';
-
--- 按名称查找
-SELECT * FROM information_schema.volumes
-WHERE volume_name = 'my_oss_volume';
-
--- 查看 Volume 详情
-DESC VOLUME my_oss_volume;
-
--- 查看 Volume 目录下的文件
-SHOW VOLUME DIRECTORY my_oss_volume;
-```
-
----
-
-## 查看目录元数据（DIRECTORY 函数）
-
-```sql
--- 查看 Volume 目录元数据（需先 ALTER VOLUME REFRESH）
-SELECT * FROM DIRECTORY(VOLUME my_oss_volume);
-```
-
----
-
-## User Volume 操作
-
-```sql
--- 查看 User Volume 文件列表
-SHOW USER VOLUME DIRECTORY;
-
--- 上传文件到 User Volume 根目录
-PUT '/local/path/file.csv' TO USER VOLUME;
-
--- 上传并指定目标路径
-PUT '/local/path/file.csv' TO USER VOLUME FILE 'subdir/file.csv';
-
--- 通配符上传多个文件
-PUT '/local/path/images/*' TO USER VOLUME SUBDIRECTORY 'images/';
-
--- 下载文件
-GET USER VOLUME FILE 'subdir/file.csv' TO '/local/output/';
-
--- 删除文件
-REMOVE USER VOLUME FILE 'subdir/file.csv';
-
--- 删除目录下所有文件
-REMOVE USER VOLUME SUBDIRECTORY '/';
-```
-
----
-
-## 从 Volume 查询数据（SELECT FROM VOLUME）
-
-```sql
--- 查询 CSV 文件
-SELECT * FROM VOLUME my_oss_volume
-USING CSV
-OPTIONS('header' = 'true', 'sep' = ',')
-SUBDIRECTORY 'data/'
-LIMIT 100;
-
--- 查询 Parquet 文件
-SELECT * FROM VOLUME my_oss_volume
-USING PARQUET
-FILES('part-00001.parquet', 'part-00002.parquet');
-
--- 正则匹配文件
-SELECT * FROM VOLUME my_oss_volume
-USING PARQUET
-REGEXP '.*2024-0[1-3].parquet';
-
--- 查询 User Volume 文件
-SELECT * FROM USER VOLUME
-USING CSV
-OPTIONS('header' = 'true')
-FILES('data.csv')
-LIMIT 10;
-```
-
-支持格式：`CSV`、`PARQUET`、`ORC`、`JSON`、`BSON`
-
-CSV OPTIONS 常用参数：
-- `header`：是否有表头，默认 `false`
-- `sep`：列分隔符，默认 `,`
-- `compression`：压缩格式（gzip/zstd/zlib）
-- `multiLine`：是否支持多行字段，默认 `false`
-
----
-
-## COPY INTO TABLE（从 Volume 导入）
-
-```sql
-COPY INTO my_table
-FROM VOLUME my_oss_volume
-USING CSV
-OPTIONS('header' = 'true')
-SUBDIRECTORY 'data/';
-```
-
-## COPY INTO VOLUME（导出到 Volume）
-
-```sql
--- 导出表到 External Volume
-COPY INTO VOLUME my_oss_volume
-SUBDIRECTORY 'export/'
-FROM TABLE my_table
-FILE_FORMAT = (TYPE = CSV);
-
--- 导出查询结果
-COPY INTO VOLUME my_oss_volume
-SUBDIRECTORY 'export/'
-FROM (SELECT * FROM orders WHERE year = 2024)
-FILE_FORMAT = (TYPE = PARQUET COMPRESSION = 'GZIP');
-
--- 导出到 User Volume
-COPY INTO USER VOLUME
-SUBDIRECTORY 'export/'
-FROM TABLE my_table
-FILE_FORMAT = (TYPE = CSV);
-```
-
-> ⚠️ 导出用 `FILE_FORMAT = (TYPE = ...)` 指定格式，不是 `USING`。`USING` 仅用于 `SELECT FROM VOLUME`。

package/bin/skills/clickzetta-zettapark/SKILL.md

@@ -1,248 +0,0 @@
----
-name: clickzetta-zettapark
-description: |
-  使用 ZettaPark Python 库操作 ClickZetta Lakehouse 数据。ZettaPark 提供类 pandas 的
-  DataFrame API，将 Python 操作翻译为 SQL 在 Lakehouse 中分布式执行。
-  覆盖 Session 创建、DataFrame 构建与转换（filter/select/join/groupBy）、
-  结果收集（collect/to_pandas/show）、写入表（save_as_table）、
-  文件操作（PUT/GET）、执行 SQL 等完整工作流。
-  当用户说"ZettaPark"、"zettapark"、"DataFrame API"、"Python 操作 Lakehouse"、
-  "save_as_table"、"session.table"、"session.sql"、"collect()"、"to_pandas"、
-  "Python 数据工程"、"Python 写入 Lakehouse"、"Python 读取 Lakehouse"、
-  "clickzetta_zettapark_python"时触发。
-  Keywords: ZettaPark, DataFrame, pandas-like, Python, SQL translation, distributed compute
----
-
-# ClickZetta ZettaPark
-
-ZettaPark 是 ClickZetta Lakehouse 的 Python DataFrame 框架，将 Python 操作翻译为 SQL 在 Lakehouse 中分布式执行，提供类 pandas 的开发体验。
-
-阅读 [references/zettapark-api.md](references/zettapark-api.md) 了解完整 API。
-
-## 安装
-
-> ⚠️ **Python 版本要求**：推荐 **Python 3.12**（最低 3.10，不支持 3.9 及以下）
-
-```bash
-# 方式 1：venv（Python 内置，推荐）
-python3.12 -m venv .venv
-source .venv/bin/activate   # macOS/Linux  |  .venv\Scripts\activate (Windows)
-pip install clickzetta_zettapark_python -i https://pypi.tuna.tsinghua.edu.cn/simple
-
-# 方式 2：pyenv（需要切换 Python 版本时）
-pyenv install 3.12.9 && pyenv local 3.12.9
-python -m venv .venv && source .venv/bin/activate
-pip install clickzetta_zettapark_python -i https://pypi.tuna.tsinghua.edu.cn/simple
-
-# 方式 3：conda（数据科学环境）
-conda create -n lakehouse python=3.12 -y && conda activate lakehouse
-pip install clickzetta_zettapark_python -i https://pypi.tuna.tsinghua.edu.cn/simple
-```
-
----
-
-## 创建会话
-
-```python
-from clickzetta.zettapark.session import Session
-
-connection_parameters = {
-    "username": "your_username",
-    "password": "your_password",
-    "service": "cn-shanghai-alicloud.api.clickzetta.com",
-    "instance": "your_instance_id",
-    "workspace": "your_workspace",
-    "schema": "public",
-    "vcluster": "default_ap",
-}
-
-session = Session.builder.configs(connection_parameters).create()
-
-# 验证连接
-session.sql("SELECT current_user(), current_workspace()").show()
-```
-
----
-
-## 核心工作流
-
-### 读取数据
-
-```python
-from clickzetta.zettapark import functions as F
-
-# 从表读取
-df = session.table("orders")
-df = session.table("my_schema.orders")
-
-# 从 SQL 读取
-df = session.sql("SELECT * FROM orders WHERE year = 2024")
-
-# 从 Python 数据创建
-df = session.create_dataframe([[1, "Alice", 100.0], [2, "Bob", 200.0]],
-                               schema=["id", "name", "amount"])
-```
-
-### 转换数据
-
-```python
-# 过滤、选择、新增列
-result = (
-    session.table("orders")
-    .filter(F.col("status") == "completed")
-    .select("order_id", "customer_id", "amount")
-    .with_column("tax", F.col("amount") * 0.1)
-    .sort(F.col("amount").desc())
-    .limit(100)
-)
-```
-
-### 聚合
-
-```python
-summary = (
-    session.table("orders")
-    .group_by("category")
-    .agg(
-        F.sum("amount").as_("total"),
-        F.count("*").as_("cnt"),
-        F.avg("amount").as_("avg_amount"),
-    )
-)
-summary.show()
-```
-
-### JOIN
-
-```python
-orders = session.table("orders")
-customers = session.table("customers")
-
-result = orders.join(
-    customers,
-    orders["customer_id"] == customers["id"],
-    "left"
-).select(
-    orders["order_id"],
-    customers["name"],
-    orders["amount"]
-)
-```
-
-### 写入数据
-
-```python
-# 追加到已有表
-df.write.save_as_table("result_table", mode="append")
-
-# 覆盖写入（自动建表）
-df.write.save_as_table("result_table", mode="overwrite")
-```
-
-### 获取结果
-
-```python
-# 打印预览
-df.show(20)
-
-# 收集为 Row 列表
-rows = df.collect()
-for row in rows:
-    print(row["id"], row["name"])
-
-# 转为 Pandas DataFrame（小数据量）
-pandas_df = df.to_pandas()
-
-# 获取行数
-print(df.count())
-```
-
----
-
-## 典型场景
-
-### 场景 1：ETL 数据处理
-
-```python
-from clickzetta.zettapark.session import Session
-from clickzetta.zettapark import functions as F
-
-session = Session.builder.configs(config).create()
-
-# 读取原始数据
-raw = session.table("bronze.raw_orders")
-
-# 清洗转换
-cleaned = (
-    raw
-    .filter(F.isnotnull(F.col("order_id")))
-    .filter(F.col("amount") > 0)
-    .with_column("order_date", F.col("created_at").cast("DATE"))
-    .with_column("year_month", F.date_format(F.col("order_date"), "yyyy-MM"))
-    .select("order_id", "customer_id", "amount", "order_date", "year_month")
-)
-
-# 写入 Silver 层
-cleaned.write.save_as_table("silver.orders_cleaned", mode="overwrite")
-
-session.close()
-```
-
-### 场景 2：特征工程（机器学习）
-
-```python
-from clickzetta.zettapark import functions as F
-
-customer = session.table("clickzetta_sample_data.tpch_100g.customer")
-orders = session.table("clickzetta_sample_data.tpch_100g.orders")
-
-# 构建客户消费特征
-customer_features = (
-    orders
-    .group_by("o_custkey")
-    .agg(
-        F.sum("o_totalprice").as_("total_spend"),
-        F.count("*").as_("order_count"),
-        F.avg("o_totalprice").as_("avg_order_value"),
-        F.max("o_orderdate").as_("last_order_date"),
-    )
-    .join(customer, orders["o_custkey"] == customer["c_custkey"])
-    .select("c_custkey", "c_name", "total_spend", "order_count", "avg_order_value")
-)
-
-customer_features.write.save_as_table("ml_features.customer_features", mode="overwrite")
-```
-
-### 场景 3：从本地文件导入
-
-```python
-import json
-import gzip
-from clickzetta.zettapark.session import Session
-
-session = Session.builder.configs(config).create()
-
-# 读取本地 JSON 数据
-data = []
-with gzip.open('data.json.gz', 'rt', encoding='utf-8') as f:
-    for line in f:
-        if line.strip():
-            data.append(json.loads(line))
-
-# 创建 DataFrame 并写入
-df = session.create_dataframe(data)
-df.write.save_as_table("my_table", mode="overwrite")
-
-session.close()
-```
-
----
-
-## 常见问题
-
-| 问题 | 原因 | 解决方案 |
-|---|---|---|
-| `collect()` 超时 | 数据量过大或集群规格不足 | 增大 `sdk.job.timeout`，或先 `limit()` 测试 |
-| `to_pandas()` 内存溢出 | 结果集过大 | 先聚合/过滤再转 pandas，或分批处理 |
-| 列名冲突（JOIN 后） | 两表有同名列 | 用 `df_left["col"]` 明确指定来源 |
-| `save_as_table` 报错 | 表已存在且 mode 不对 | 使用 `mode="overwrite"` 或 `mode="append"` |

package/bin/skills/clickzetta-zettapark/references/zettapark-api.md

@@ -1,283 +0,0 @@
-# ZettaPark 快速参考
-
-> 来源：https://www.yunqi.tech/documents/ZettaparkQuickStart
-
-## 安装
-
-```bash
-pip install clickzetta_zettapark_python -U -i https://pypi.tuna.tsinghua.edu.cn/simple
-```
-
----
-
-## 创建会话
-
-```python
-from clickzetta.zettapark.session import Session
-
-connection_parameters = {
-    "username": "your_username",
-    "password": "your_password",
-    "service": "cn-shanghai-alicloud.api.clickzetta.com",
-    "instance": "your_instance_id",
-    "workspace": "your_workspace",
-    "schema": "public",
-    "vcluster": "default_ap",
-}
-
-session = Session.builder.configs(connection_parameters).create()
-```
-
-带 hints（超时、query_tag 等）：
-
-```python
-connection_parameters = {
-    "username": "your_username",
-    "password": "your_password",
-    "service": "cn-shanghai-alicloud.api.clickzetta.com",
-    "instance": "your_instance_id",
-    "workspace": "your_workspace",
-    "schema": "public",
-    "vcluster": "default_ap",
-    "hints": {
-        "sdk.job.timeout": 300,
-        "query_tag": "my_zettapark_app",
-    }
-}
-
-session = Session.builder.configs(connection_parameters).create()
-```
-
-从 JSON 配置文件读取：
-
-```python
-import json
-with open('config.json', 'r') as f:
-    config = json.load(f)
-session = Session.builder.configs(config).create()
-```
-
-验证连接：
-
-```python
-session.sql("SELECT current_user(), current_workspace(), current_vcluster()").show()
-```
-
-关闭会话：
-
-```python
-session.close()
-```
-
----
-
-## 构建 DataFrame
-
-```python
-# 从表创建
-df = session.table("my_schema.my_table")
-
-# 从 SQL 创建
-df = session.sql("SELECT * FROM orders WHERE year = 2024")
-
-# 从 Python 数据创建
-df = session.create_dataframe([1, 2, 3, 4]).to_df("id")
-df = session.create_dataframe([[1, "Alice"], [2, "Bob"]], schema=["id", "name"])
-
-# 从 Row 对象创建
-from clickzetta.zettapark import Row
-df = session.create_dataframe([Row(id=1, name="Alice"), Row(id=2, name="Bob")])
-
-# 带 Schema 创建
-from clickzetta.zettapark.types import IntegerType, StringType, StructType, StructField
-schema = StructType([StructField("id", IntegerType()), StructField("name", StringType())])
-df = session.create_dataframe([[1, "Alice"], [2, "Bob"]], schema)
-
-# 范围序列
-df = session.range(1, 10, 2).to_df("n")  # 1,3,5,7,9
-```
-
----
-
-## DataFrame 转换操作
-
-```python
-from clickzetta.zettapark import functions as F
-
-# 过滤行
-df.filter(F.col("age") > 18)
-df.filter(F.col("status") == "active")
-df.where(F.col("amount") > 1000)
-
-# 选择列
-df.select("id", "name", "amount")
-df.select(F.col("id"), F.col("name").as_("user_name"))
-
-# 新增/修改列
-df.with_column("total", F.col("price") * F.col("qty"))
-df.with_column("upper_name", F.upper(F.col("name")))
-
-# 重命名列
-df.rename(F.col("old_name"), "new_name")
-
-# 排序
-df.sort(F.col("amount").desc())
-df.order_by(F.col("created_at").asc())
-
-# 去重
-df.distinct()
-df.drop_duplicates(["user_id"])
-
-# 限制行数
-df.limit(100)
-
-# 删除列
-df.drop("unnecessary_col")
-```
-
----
-
-## 聚合操作
-
-```python
-from clickzetta.zettapark import functions as F
-
-# 分组聚合
-df.group_by("category").agg(
-    F.sum("amount").as_("total_amount"),
-    F.count("*").as_("order_count"),
-    F.avg("price").as_("avg_price"),
-    F.max("amount").as_("max_amount"),
-    F.min("amount").as_("min_amount"),
-)
-
-# 全局聚合
-df.agg(F.count("*"), F.sum("amount"))
-```
-
----
-
-## JOIN 操作
-
-```python
-# 内连接
-df_orders.join(df_customers, df_orders["customer_id"] == df_customers["id"])
-
-# 左连接
-df_orders.join(df_customers, df_orders["customer_id"] == df_customers["id"], "left")
-
-# 选择连接后的列（避免列名冲突）
-result = df_orders.join(df_customers, df_orders["customer_id"] == df_customers["id"]) \
-    .select(df_orders["order_id"], df_customers["name"], df_orders["amount"])
-```
-
----
-
-## 执行与结果获取
-
-```python
-# 打印前 N 行（触发执行）
-df.show()
-df.show(20)
-
-# 收集所有结果为 Row 列表
-rows = df.collect()
-for row in rows:
-    print(row["id"], row["name"])
-
-# 转换为 Pandas DataFrame
-pandas_df = df.to_pandas()
-
-# 获取行数
-count = df.count()
-
-# 获取列名
-print(df.columns)
-
-# 查看 Schema
-df.schema.print_tree()
-```
-
----
-
-## 写入数据
-
-```python
-# 写入已有表（追加）
-df.write.save_as_table("my_table", mode="append")
-
-# 覆盖写入
-df.write.save_as_table("my_table", mode="overwrite")
-
-# 自动建表并写入（overwrite 会重建表）
-df.write.save_as_table("new_table", mode="overwrite")
-
-# 写入指定 Schema 下的表
-df.write.save_as_table("my_schema.my_table", mode="append")
-```
-
----
-
-## 执行 SQL
-
-```python
-# 执行 DDL/DML
-session.sql("CREATE TABLE IF NOT EXISTS t (id INT, name STRING)").collect()
-session.sql("INSERT INTO t VALUES (1, 'Alice')").collect()
-
-# 执行查询并获取 DataFrame
-df = session.sql("SELECT * FROM orders WHERE amount > 1000")
-df.show()
-
-# 切换 Schema
-session.use_schema("my_schema")
-```
-
----
-
-## 文件操作（Volume）
-
-```python
-# 上传文件到 User Volume
-session.file.put("/local/path/data.csv", "volume:user://~/data/")
-
-# 下载文件
-session.file.get("volume:user://~/data/data.csv", "/local/output/")
-
-# 列出 User Volume 文件
-session.sql("LIST USER VOLUME").show()
-session.sql("SHOW USER VOLUME DIRECTORY").show()
-```
-
----
-
-## 常用 functions 速查
-
-```python
-from clickzetta.zettapark import functions as F
-
-# 字符串
-F.upper(col), F.lower(col), F.concat(col1, col2)
-F.substring(col, 1, 3), F.trim(col), F.length(col)
-
-# 数值
-F.abs(col), F.round(col, 2), F.floor(col), F.ceil(col)
-F.sqrt(col), F.pow(col, 2)
-
-# 日期时间
-F.current_date(), F.current_timestamp()
-F.year(col), F.month(col), F.day(col)
-F.date_add(col, 7), F.datediff(col1, col2)
-
-# 条件
-F.when(F.col("status") == "A", "Active").otherwise("Inactive")
-F.coalesce(col1, col2)  # 第一个非 null 值
-F.isnull(col), F.isnotnull(col)
-
-# 聚合
-F.count("*"), F.sum(col), F.avg(col), F.max(col), F.min(col)
-F.count_distinct(col)
-
-# 类型转换
-F.col("amount").cast(IntegerType())
-```