@clickzetta/cz-cli-linux-x64 0.3.0 → 0.3.1

package/bin/skills/clickzetta-external-catalog/references/external-catalog-ddl.md

@@ -0,0 +1,130 @@
+# External Catalog 参考
+
+> 来源：https://www.yunqi.tech/documents/external-catalog-summary 等
+
+> ⚠️ External Catalog 当前处于公开预览阶段。目前只有 instance admin 角色可以查询 Catalog。
+
+## 概述
+
+External Catalog 映射外部数据系统（Hive、Iceberg、Databricks）的数据库，使 Lakehouse 可对其执行**只读**联邦查询。
+
+**支持的数据源**：
+- Apache Hive（通过 Hive Metastore）
+- Iceberg REST Catalog（如 Snowflake OpenCatalog）
+- Databricks Unity Catalog
+
+---
+
+## 创建流程（以 Hive 为例）
+
+### 步骤 1：创建存储连接
+
+```sql
+-- OSS
+CREATE STORAGE CONNECTION IF NOT EXISTS catalog_storage_oss
+  TYPE OSS
+  ACCESS_ID = 'LTAIxxxxxxxxxxxx'
+  ACCESS_KEY = 'T8Gexxxxxxmtxxxxxx'
+  ENDPOINT = 'oss-cn-hangzhou-internal.aliyuncs.com';
+
+-- COS
+CREATE STORAGE CONNECTION IF NOT EXISTS catalog_storage_cos
+  TYPE COS
+  ACCESS_KEY = '<access_key>'
+  SECRET_KEY = '<secret_key>'
+  REGION = 'ap-shanghai'
+  APP_ID = '1310000503';
+
+-- S3
+CREATE STORAGE CONNECTION IF NOT EXISTS catalog_storage_s3
+  TYPE S3
+  ACCESS_KEY = '<access_key>'
+  SECRET_KEY = '<secret_key>'
+  REGION = 'us-east-1';
+```
+
+### 步骤 2：创建 Catalog Connection
+
+```sql
+-- Hive Metastore
+CREATE CATALOG CONNECTION IF NOT EXISTS catalog_api_connection
+  TYPE hms
+  hive_metastore_uris = 'host:9083'
+  storage_connection = 'catalog_storage_oss';
+```
+
+参数说明：
+- `type`：连接类型，目前支持 `hms`（Hive Metastore Service）
+- `hive_metastore_uris`：HMS 服务地址，格式 `host:port`，端口通常为 9083
+- `storage_connection`：已创建的存储连接名称
+
+### 步骤 3：创建 External Catalog
+
+```sql
+CREATE EXTERNAL CATALOG my_external_catalog
+  CONNECTION catalog_api_connection;
+```
+
+---
+
+## 查看 Catalog
+
+```sql
+-- 列出所有 Catalog
+SHOW CATALOGS;
+
+-- 查看 Catalog 详情
+DESC CATALOG my_external_catalog;
+DESC CATALOG EXTENDED my_external_catalog;
+```
+
+---
+
+## 查看 Catalog 下的对象
+
+```sql
+-- 查看 Schema 列表
+SHOW SCHEMAS IN my_external_catalog;
+
+-- 查看 Schema 列表（含类型：managed/external）
+SHOW SCHEMAS EXTENDED IN my_external_catalog;
+
+-- 查看表列表
+SHOW TABLES IN my_external_catalog.my_schema;
+
+-- 查看表结构
+DESC TABLE my_external_catalog.my_schema.my_table;
+```
+
+---
+
+## 查询外部数据
+
+```sql
+-- 三层命名空间语法（必须）
+SELECT * FROM my_external_catalog.my_schema.my_table;
+
+-- 联邦查询（外部表 JOIN 内部表）
+SELECT e.*, i.region
+FROM my_external_catalog.hive_schema.orders e
+JOIN public.dim_region i ON e.region_id = i.id;
+```
+
+⚠️ 查询 External Catalog 下的表**必须**使用三层结构语法（catalog.schema.table），不支持 `USE` 切换 catalog。
+
+---
+
+## 删除 Catalog
+
+```sql
+DROP CATALOG IF EXISTS my_external_catalog;
+```
+
+---
+
+## 注意事项
+
+- External Catalog 为**只读**，不支持写入操作
+- HMS 所在服务器网络需与 Lakehouse 打通（可通过 PrivateLink 实现）
+- 目前只有 `instance_admin` 角色可以创建和查询 External Catalog
+- Databricks Unity Catalog 要求与 Lakehouse 在同一云平台（如同在 AWS 上）

package/bin/skills/clickzetta-external-function/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: clickzetta-external-function
+description: |
+  在 ClickZetta Lakehouse 中创建和使用外部函数（External Function / UDF），
+  通过 Python 或 Java 扩展 SQL 计算能力，调用 LLM、图像识别、自定义算法等外部服务。
+  覆盖 CREATE API CONNECTION（阿里云FC/腾讯云SCF/AWS Lambda）、
+  CREATE EXTERNAL FUNCTION、Python UDF 代码结构与打包、
+  内置 AI_COMPLETE 和 AI_EMBEDDING 函数的使用。
+  当用户说"外部函数"、"UDF"、"自定义函数"、"External Function"、
+  "Remote Function"、"调用 LLM"、"AI_COMPLETE"、"AI_EMBEDDING"、
+  "文本向量化"、"调用阿里云函数计算"、"调用云函数"、"Python UDF"、
+  "Java UDF"、"CREATE EXTERNAL FUNCTION"时触发。
+  Keywords: external function, UDF, Python UDF, Java UDF, LLM, custom function
+---
+
+# ClickZetta External Function
+
+External Function 让 SQL 可以调用外部计算能力（LLM、图像识别、自定义算法），通过 Python/Java 编写函数逻辑，部署在云函数服务上执行。
+
+阅读 [references/external-function-ddl.md](references/external-function-ddl.md) 了解完整语法。
+
+---
+
+## 两种使用路径
+
+| 路径 | 适用场景 | 复杂度 |
+|---|---|---|
+| **内置 AI 函数**（AI_COMPLETE / AI_EMBEDDING） | 调用 LLM 生成文本、文本向量化 | 低，只需创建 API Connection |
+| **External Function** | 自定义算法、图像处理、私有模型 | 高，需部署云函数 |
+
+---
+
+## 路径一：内置 AI 函数（推荐）
+
+### 1. 创建 AI API Connection
+
+```sql
+CREATE API CONNECTION conn_bailian
+    TYPE ai_function
+    PROVIDER = 'bailian'
+    BASE_URL = 'https://dashscope.aliyuncs.com/api/v1'
+    API_KEY = 'sk-xxxxxxxxxxxxxxxxxxxxxxxx';
+```
+
+### 2. AI_COMPLETE — 调用 LLM
+
+```sql
+-- 文本摘要
+SELECT id,
+       AI_COMPLETE('connection:conn_bailian', '请用一句话总结：' || content) AS summary
+FROM articles;
+
+-- 情感分析
+SELECT id, review,
+       AI_COMPLETE('connection:conn_bailian',
+           '判断以下评论的情感（正面/负面/中性），只返回一个词：' || review) AS sentiment
+FROM user_reviews;
+
+-- 通过平台 Endpoint（管理员预配置）
+SELECT AI_COMPLETE('endpoint:my_llm_endpoint', prompt_col) AS result
+FROM my_table;
+```
+
+### 3. AI_EMBEDDING — 文本向量化
+
+```sql
+-- 批量生成 embedding
+SELECT id, content,
+       AI_EMBEDDING('connection:conn_bailian', content) AS vec
+FROM documents;
+
+-- 语义搜索（结合向量索引）
+SELECT id, content,
+       cosine_distance(vec, AI_EMBEDDING('connection:conn_bailian', '用户查询')) AS dist
+FROM doc_embeddings
+ORDER BY dist
+LIMIT 10;
+```
+
+---
+
+## 路径二：External Function（自定义 UDF）
+
+### 整体流程
+
+```
+1. 开通云函数服务（阿里云FC / 腾讯云SCF / AWS Lambda）
+2. 编写 Python/Java 函数代码
+3. 打包上传到对象存储或 User Volume
+4. 授权 Lakehouse 访问云函数服务（RAM 角色）
+5. CREATE API CONNECTION
+6. CREATE EXTERNAL FUNCTION
+7. 在 SQL 中调用
+```
+
+### 步骤 1：创建云函数 API Connection
+
+```sql
+-- 阿里云 FC
+CREATE API CONNECTION IF NOT EXISTS my_fc_conn
+  TYPE CLOUD_FUNCTION
+  PROVIDER = 'aliyun'
+  REGION = 'cn-shanghai'
+  ROLE_ARN = 'acs:ram::1234567890:role/CzUDFRole'
+  NAMESPACE = 'default'
+  CODE_BUCKET = 'my-oss-bucket';
+
+-- 腾讯云 SCF
+CREATE API CONNECTION IF NOT EXISTS my_scf_conn
+  TYPE CLOUD_FUNCTION
+  PROVIDER = 'tencent'
+  REGION = 'ap-shanghai'
+  ROLE_ARN = 'qcs::cam::uin/1234567890:roleName/CzUDFRole'
+  NAMESPACE = 'default'
+  CODE_BUCKET = 'my-cos-bucket';
+```
+
+### 步骤 2：编写 Python UDF
+
+```python
+# upper.py
+try:
+    from cz.udf import annotate
+except ImportError:
+    annotate = lambda _: lambda _: _
+
+@annotate("string->string")
+class Upper(object):
+    def evaluate(self, arg):
+        if arg is None:
+            return None
+        return arg.upper()
+```
+
+打包上传：
+```bash
+zip -rq upper.zip upper.py
+```
+
+```sql
+-- 上传到 User Volume（在 ClickZetta Studio 或 CLI 中执行，source_path 使用绝对路径）
+PUT '/path/to/upper.zip' TO USER VOLUME;
+```
+
+### 步骤 3：创建 External Function
+
+```sql
+-- ⚠️ CREATE EXTERNAL FUNCTION 不支持 OR REPLACE，只支持 IF NOT EXISTS
+-- ❌ 错误：CREATE OR REPLACE EXTERNAL FUNCTION ...
+-- ✅ 正确：
+-- 使用 User Volume 存放代码（无需 OSS）
+CREATE EXTERNAL FUNCTION IF NOT EXISTS public.str_upper
+  AS 'upper.Upper'
+  USING FILE = 'volume:user://~/upper.zip'
+  CONNECTION = my_fc_conn
+  WITH PROPERTIES ('remote.udf.api' = 'python3.mc.v0')
+  COMMENT '字符串转大写';
+
+-- 使用 OSS 存放代码
+CREATE EXTERNAL FUNCTION IF NOT EXISTS public.str_upper
+  AS 'upper.Upper'
+  USING FILE = 'oss://my-bucket/functions/upper.zip'
+  CONNECTION = my_fc_conn
+  WITH PROPERTIES ('remote.udf.api' = 'python3.mc.v0');
+```
+
+### 步骤 4：调用函数
+
+```sql
+-- ⚠️ 调用外部函数必须使用完整 Schema 路径，不能省略 schema
+-- ❌ 错误：SELECT str_upper(name) FROM my_table;
+-- ✅ 正确：
+SELECT id, public.str_upper(name) AS upper_name FROM my_table;
+```
+
+---
+
+## 管理操作
+
+```sql
+-- 查看所有外部函数
+SHOW EXTERNAL FUNCTIONS;
+SHOW EXTERNAL FUNCTIONS LIKE 'str_%';
+
+-- 删除函数（注意：用 DROP FUNCTION，不是 DROP EXTERNAL FUNCTION）
+DROP FUNCTION IF EXISTS public.str_upper;
+```
+
+> ⚠️ **注意**：`CREATE FUNCTION`（SQL 内联函数）只支持 SQL 表达式，不支持 Python/JavaScript 等编程语言。需要编程语言逻辑请使用 `CREATE EXTERNAL FUNCTION`。
+
+---
+
+## 常见问题
+
+| 问题 | 原因 | 解决方案 |
+|---|---|---|
+| 函数调用超时 | 云函数冷启动或执行慢 | 增大超时配置，或预热函数 |
+| 依赖库 ABI 不兼容 | 在 macOS/Windows 打包 | 用 `quay.io/pypa/manylinux2014_x86_64` 容器打包 |
+| 代码包 > 500MB | 依赖过大 | 改用容器镜像方式部署 |
+| AI_COMPLETE 报错 | API Key 无效或余额不足 | 检查 API Connection 的 API_KEY |
+| ROLE_ARN 权限不足 | RAM 角色未授权 | 参考文档配置 AliyunFCFullAccess + OSS 权限 |
+| 函数调用报"not found" | 省略了 Schema 前缀 | 必须用完整路径：`schema.function_name(...)` |
+| CREATE OR REPLACE 报错 | EXTERNAL FUNCTION 不支持 OR REPLACE | 改用 `CREATE EXTERNAL FUNCTION IF NOT EXISTS` |

package/bin/skills/clickzetta-external-function/references/external-function-ddl.md

@@ -0,0 +1,171 @@
+# External Function DDL 参考
+
+> 来源：https://www.yunqi.tech/documents/CREATE_EXTERNATL_FUNCTION 等
+
+## 概念
+
+External Function（外部函数）是通过 Python/Java 编写、在云函数服务（阿里云 FC / 腾讯云 SCF / AWS Lambda）上执行的自定义 UDF。可调用：
+- **在线服务**：LLM API、图像识别 API 等
+- **离线模型**：打包上传的 Hugging Face 模型等
+
+支持函数类型：UDF（标量）、UDAF（聚合，仅 Java）、UDTF（表函数，仅 Java）
+
+---
+
+## CREATE API CONNECTION（云函数连接）
+
+```sql
+CREATE API CONNECTION IF NOT EXISTS my_fc_conn
+  TYPE CLOUD_FUNCTION
+  PROVIDER = 'aliyun'           -- 'aliyun' | 'tencent' | 'aws'
+  REGION = 'cn-shanghai'
+  ROLE_ARN = 'acs:ram::1234567890:role/CzUDFRole'
+  NAMESPACE = 'default'         -- 腾讯云必填，其他填 'default'
+  CODE_BUCKET = 'my-oss-bucket';
+```
+
+| 参数 | 说明 |
+|---|---|
+| PROVIDER | `'aliyun'` / `'tencent'` / `'aws'` |
+| REGION | 阿里云：`cn-shanghai`；腾讯云：`ap-beijing`；AWS：`cn-northwest-1` |
+| ROLE_ARN | 授权给 Lakehouse 的 RAM 角色 ARN |
+| NAMESPACE | 腾讯云命名空间（必填）；其他填 `'default'` |
+| CODE_BUCKET | 存放函数代码包的 OSS/COS/S3 bucket 名称 |
+
+---
+
+## CREATE EXTERNAL FUNCTION
+
+```sql
+CREATE EXTERNAL FUNCTION IF NOT EXISTS my_schema.my_udf
+  AS 'module_name.ClassName'
+  USING FILE = 'oss://my-bucket/functions/code.zip'
+  CONNECTION = my_fc_conn
+  WITH PROPERTIES (
+      'remote.udf.api' = 'python3.mc.v0'   -- Python: python3.mc.v0 | Java: java8.hive2.v0
+  )
+  COMMENT '自定义函数说明';
+```
+
+### 资源文件地址格式
+
+```
+-- OSS/COS/S3
+oss://bucket-name/path/to/code.zip
+cos://bucket-name/path/to/code.zip
+s3://bucket-name/path/to/code.zip
+
+-- User Volume（无需开通对象存储）
+volume:user://~/code.zip
+
+-- External Volume
+volume://workspace.schema.volume_name/code.zip
+```
+
+### WITH PROPERTIES 参数
+
+| 参数 | 值 | 说明 |
+|---|---|---|
+| `remote.udf.api` | `python3.mc.v0` | Python 3.10 运行时 |
+| `remote.udf.api` | `java8.hive2.v0` | Java 8 Hive 风格 UDF |
+| `remote.udf.protocol` | `http.arrow.v0` | 默认，访问云函数的协议 |
+
+---
+
+## Python UDF 代码结构
+
+```python
+#!/usr/bin/env python
+try:
+    from cz.udf import annotate
+except ImportError:
+    annotate = lambda _: lambda _: _
+
+@annotate("string->string")   # 函数签名：输入类型->返回类型
+class Upper(object):
+    def evaluate(self, arg):
+        if arg is None:
+            return None
+        return arg.upper()
+```
+
+### 函数签名格式
+
+```
+"input_type1,input_type2->return_type"
+
+# 示例
+"string->string"           # 字符串转字符串
+"string,int->double"       # 两个输入，返回 double
+"string->array<string>"    # 返回数组
+```
+
+支持类型：`string`、`int`、`bigint`、`double`、`float`、`boolean`、`array<T>`、`map<K,V>`
+
+### 打包上传
+
+```bash
+# 安装依赖到当前目录
+pip3 install httpx pydantic -t .
+
+# 打包（< 500MB）
+zip -rq code.zip ./*
+```
+
+```sql
+-- 上传到 User Volume（在 ClickZetta Studio 或 CLI 中执行，source_path 使用绝对路径）
+PUT '/path/to/code.zip' TO USER VOLUME;
+```
+
+---
+
+## 管理操作
+
+```sql
+-- 查看外部函数列表
+SHOW EXTERNAL FUNCTIONS;
+SHOW EXTERNAL FUNCTIONS LIKE 'my_%';
+
+-- 删除外部函数
+DROP FUNCTION IF EXISTS my_schema.my_udf;
+```
+
+---
+
+## 内置 AI 函数（无需部署云函数）
+
+### AI_COMPLETE（调用 LLM）
+
+```sql
+-- 通过 API Connection 调用（需先创建连接）
+CREATE API CONNECTION conn_bailian
+    TYPE ai_function
+    PROVIDER = 'bailian'
+    BASE_URL = 'https://dashscope.aliyuncs.com/api/v1'
+    API_KEY = 'sk-xxxxxxxxxxxxxxxxxxxxxxxx';
+
+-- 调用 LLM 生成文本
+SELECT AI_COMPLETE('connection:conn_bailian', '请用一句话总结：' || content) AS summary
+FROM articles
+LIMIT 10;
+
+-- 通过平台 Endpoint 调用（管理员预配置）
+SELECT AI_COMPLETE('endpoint:my_llm_endpoint', prompt_col) AS result
+FROM my_table;
+```
+
+### AI_EMBEDDING（文本向量化）
+
+```sql
+-- 将文本转为向量（用于语义搜索）
+SELECT id, content,
+       AI_EMBEDDING('connection:conn_bailian', content) AS embedding
+FROM documents;
+
+-- 结合向量索引做语义搜索
+SELECT id, content,
+       cosine_distance(embedding, AI_EMBEDDING('connection:conn_bailian', '查询文本')) AS dist
+FROM doc_embeddings
+ORDER BY dist
+LIMIT 10;
+```

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

@@ -0,0 +1,117 @@
+---
+name: clickzetta-file-import-pipeline
+description: |
+  从 URL、本地文件或 Volume 路径将数据导入到 ClickZetta 表中，覆盖文件下载、格式推断、
+  表创建、COPY INTO 导入、结果验证的完整流程。当用户说"导入数据"、"从 URL 加载"、
+  "上传 CSV 到表"、"文件导入"、"COPY INTO"时触发。包含 ClickZetta USER VOLUME 机制、
+  COPY INTO 语法、格式推断规则、写入模式语义等平台特有知识。
+  Keywords: file import, URL, CSV, JSON, Parquet, COPY INTO, Volume
+---
+
+# URL/文件数据导入工作流
+
+## 指令
+
+### 步骤 1：获取源文件并上传到 Volume
+根据数据来源选择对应方式：
+- HTTP/HTTPS URL：使用 `put_file_to_volume` 的 source_path 参数直接传入 URL，工具会自动下载并上传
+- 本地文件：使用 `put_file_to_volume` 指定 source_path 为本地路径
+- Volume 路径（`volume://vol_name/path`）：文件已在 Volume 上，跳过此步骤
+- 记录上传后的 Volume 名称和文件名，后续步骤需要
+
+### 步骤 2：推断文件格式
+根据文件扩展名推断格式（ClickZetta COPY INTO 支持的格式）：
+- `.csv`, `.tsv`, `.txt` → CSV 格式
+- `.json`, `.jsonl`, `.ndjson` → JSON 格式
+- `.parquet`, `.pq` → PARQUET 格式
+- `.orc` → ORC 格式
+- `.bson` → BSON 格式
+如果扩展名不明确，使用 `preview_volume_data` 预览文件内容来确认格式和 schema。
+
+### 步骤 3：确认或创建目标表
+根据写入模式处理目标表：
+- **create 模式**：表必须不存在。使用 `preview_volume_data` 推断 schema，然后用 `create_table` 创建表
+- **append 模式**：表必须已存在。用 `desc_object`(object_type='TABLE') 确认表存在并检查列兼容性
+- **overwrite 模式**：表存在则先清空。用 `write_query` 执行 `TRUNCATE TABLE table_name`，再执行 COPY INTO
+
+### 步骤 4：执行 COPY INTO 导入数据
+使用 `write_query` 执行 COPY INTO 语句。核心语法：
+
+```sql
+COPY INTO target_table
+FROM VOLUME volume_name
+USING format_type
+FILES('filename');
+```
+
+对于 USER VOLUME（通过 put_file_to_volume 上传的文件）：
+```sql
+COPY INTO target_table
+FROM USER VOLUME
+USING CSV
+FILES('uploaded_filename');
+```
+
+CSV 格式可附加 OPTIONS：
+```sql
+COPY INTO target_table
+FROM VOLUME vol USING CSV
+FILES('data.csv')
+OPTIONS('header'='true', 'sep'=',', 'quote'='"', 'nullValue'='');
+```
+
+overwrite 模式使用 COPY OVERWRITE：
+```sql
+COPY OVERWRITE INTO target_table
+FROM VOLUME vol USING CSV FILES('data.csv');
+```
+
+### 步骤 5：验证导入结果
+使用 `read_query` 执行验证查询：
+```sql
+SELECT COUNT(*) as row_count FROM target_table;
+SELECT * FROM target_table LIMIT 5;
+```
+确认行数符合预期，数据内容正确。
+
+## 示例
+
+### 示例 1：从 URL 导入 CSV 到新表
+```
+1. put_file_to_volume(source_path='https://example.com/data.csv', target_volume='my_vol')
+2. preview_volume_data(source_volume='my_vol', files='data.csv', format='CSV', limit='5')
+   → 推断出列: id INT, name STRING, value DOUBLE
+3. create_table(table_name='imported_data', columns='id INT, name STRING, value DOUBLE')
+4. write_query(query="COPY INTO imported_data FROM VOLUME my_vol USING CSV FILES('data.csv') OPTIONS('header'='true')")
+5. read_query(query="SELECT COUNT(*) FROM imported_data")
+```
+
+### 示例 2：追加 Parquet 数据到已有表
+```
+1. put_file_to_volume(source_path='/local/new_batch.parquet', target_volume='data_vol')
+2. desc_object(object_name='existing_table', object_type='TABLE')  → 确认表存在
+3. write_query(query="COPY INTO existing_table FROM VOLUME data_vol USING PARQUET FILES('new_batch.parquet')")
+4. read_query(query="SELECT COUNT(*) FROM existing_table")
+```
+
+## 故障排除
+
+错误：COPY INTO 报 "table not found"
+原因：create 模式下表未创建，或 append 模式下表名拼写错误
+解决方案：先用 `show_object_list`(object_type='TABLES') 确认表是否存在
+
+错误：COPY INTO 报 "file not found"
+原因：FILES 中的文件名与 Volume 上的实际文件名不匹配
+解决方案：用 `list_files_on_volume` 确认文件名，注意大小写敏感
+
+错误：CSV 导入列数不匹配
+原因：CSV 文件有 header 行但未指定 OPTIONS(header='true')，导致 header 被当作数据行
+解决方案：添加 OPTIONS(header='true')，或检查 CSV 分隔符是否正确（sep 参数）
+
+错误：COPY INTO 报 "schema mismatch"
+原因：文件中的数据类型与目标表列定义不兼容
+解决方案：用 `preview_volume_data` 预览实际数据，调整表定义或使用列映射
+
+错误：overwrite 模式数据未清空
+原因：使用了普通 COPY INTO 而非 COPY OVERWRITE INTO
+解决方案：overwrite 模式必须使用 `COPY OVERWRITE INTO` 语法