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

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

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

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

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

@@ -1,117 +0,0 @@
----
-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` 语法