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

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

@@ -1,199 +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（Connection 必须使用小写 access_id/access_key）
-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`：是否递归扫描子目录
-
-> ⚠️ 上传新文件后如果 `SHOW VOLUME DIRECTORY` 未显示，执行 `ALTER VOLUME name REFRESH` 手动刷新。
-
----
-
-## 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);
-```
-
-> ⚠️ **关键区分**：
-> - **导入**（COPY INTO TABLE / SELECT FROM VOLUME）：用 `USING CSV/PARQUET/JSON` + `OPTIONS(...)`
-> - **导出**（COPY INTO VOLUME）：用 `FILE_FORMAT = (TYPE = CSV/PARQUET/JSON)`
-> - 两者语法不可混用！

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"` |