@clickzetta/cz-cli-darwin-arm64 0.3.81 → 0.3.83

package/bin/skills/clickzetta-external-catalog/LICENSE

@@ -0,0 +1,16 @@
+ClickZetta Skills License
+© 2026 Yunqi Inc. All rights reserved.
+LICENSE: Use of these materials (including all code, prompts, assets, files, and other components of these skills (collectively, "Skills")) is governed by your agreement with ClickZetta for the Service. If no separate agreement exists, use is governed by ClickZetta's Terms of Service (available at: https://yunqi.tech/documents/user-aggrement).
+Your applicable agreement is referred to as the "Agreement." "Service" is as defined in the Agreement.
+ADDITIONAL RESTRICTIONS: Notwithstanding anything in the Agreement to the contrary, you may not:
+
+Extract from the Service or retain copies of the Skills outside use with the Service;
+Reproduce or copy the Skills, except for temporary copies created automatically during authorized use of the Service;
+Create derivative works based on the Skills;
+Distribute, sublicense, or transfer the Skills to any third party;
+Make, offer to sell, sell, or import any inventions embodied in the Skills; nor,
+Reverse engineer, decompile, or disassemble the Skills.
+
+The receipt, viewing, or possession of the Skills does not convey or imply any license or right beyond those expressly granted above.
+Yunqi retains all rights, title, and interest in the Skills, including all copyrights, trademarks, patents, and all other applicable intellectual property rights.
+THE SKILLS ARE PROVIDED "AS IS," WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SKILLS OR THE USE OR OTHER DEALINGS IN THE SKILLS.

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

@@ -0,0 +1,123 @@
+---
+name: clickzetta-external-catalog
+description: |
+  配置和使用 ClickZetta Lakehouse External Catalog，实现对 Hive、Iceberg、Databricks、
+  Snowflake Open Catalog 等外部数据源的联邦查询（只读）。覆盖完整创建流程：存储连接 →
+  Catalog Connection → External Catalog，以及 SHOW/DESC/查询外部表等操作。
+  支持数据源：Hive（OSS/COS/S3/HDFS）、Databricks Unity Catalog、
+  Snowflake Open Catalog（通过 Iceberg，OAuth 认证）。
+  当用户说"外部数据目录"、"External Catalog"、"联邦查询"、"Hive 联邦"、
+  "访问 Hive 数据"、"Databricks 联邦"、"Iceberg 联邦"、"跨数据源查询"、
+  "不迁移数据直接查询"、"Catalog Connection"、"Snowflake 联邦"、
+  "访问 Snowflake 数据"时触发。
+  Keywords: external catalog, Hive, Iceberg, Databricks, Snowflake, federation, read-only
+---
+
+# ClickZetta External Catalog
+
+> ⚠️ 创建 External Catalog 需要 `instance_admin` 角色。查询权限可通过 GRANT 授予其他用户。
+
+阅读 [references/external-catalog-ddl.md](references/external-catalog-ddl.md) 了解完整语法。
+
+## 概述
+
+External Catalog 让 Lakehouse 可以**不迁移数据**，直接对外部数据系统（Hive、Iceberg、Databricks）执行只读联邦查询。
+
+**支持数据源**：Apache Hive · Iceberg REST Catalog · Databricks Unity Catalog
+
+---
+
+## 创建流程（三步）
+
+### 步骤 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';
+```
+
+### 步骤 2：创建 Catalog Connection
+
+```sql
+CREATE CATALOG CONNECTION IF NOT EXISTS hive_catalog_conn
+  TYPE hms
+  hive_metastore_uris = 'hms-host:9083'
+  storage_connection = 'catalog_storage_oss';
+```
+
+### 步骤 3：创建 External Catalog
+
+```sql
+-- ⚠️ CREATE EXTERNAL CATALOG 不支持 COMMENT 子句，加了会报错
+-- ❌ 错误：CREATE EXTERNAL CATALOG my_hive_catalog CONNECTION hive_catalog_conn COMMENT '...';
+-- ✅ 正确：
+CREATE EXTERNAL CATALOG my_hive_catalog
+  CONNECTION hive_catalog_conn;
+
+-- 如需带选项（如 Iceberg REST）：
+CREATE EXTERNAL CATALOG my_iceberg_catalog
+  CONNECTION iceberg_conn
+  OPTIONS ('key1' = 'value1', 'key2' = 'value2');
+```
+
+---
+
+## 验证连通性
+
+```sql
+-- 查看 Schema 列表（验证连通）
+SHOW SCHEMAS IN my_hive_catalog;
+
+-- 查看表列表
+SHOW TABLES IN my_hive_catalog.my_schema;
+
+-- 查询数据
+SELECT * FROM my_hive_catalog.my_schema.my_table LIMIT 10;
+```
+
+---
+
+## 查看与管理
+
+```sql
+-- 列出所有 Catalog
+SHOW CATALOGS;
+
+-- 查看 Catalog 详情
+DESC CATALOG my_hive_catalog;
+
+-- 查看表结构
+DESC TABLE my_hive_catalog.my_schema.my_table;
+
+-- 删除 Catalog
+DROP CATALOG IF EXISTS my_hive_catalog;
+```
+
+---
+
+## 联邦查询示例
+
+```sql
+-- 外部 Hive 表 JOIN 内部 Lakehouse 表
+SELECT h.order_id, h.amount, d.region_name
+FROM my_hive_catalog.sales.orders h
+JOIN public.dim_region d ON h.region_id = d.id
+WHERE h.order_date >= '2024-01-01';
+```
+
+⚠️ 必须使用三层命名空间语法：`catalog.schema.table`
+
+---
+
+## 常见问题
+
+| 问题 | 原因 | 解决方案 |
+|---|---|---|
+| 无法连接 HMS | 网络未打通 | 通过 PrivateLink 打通 Lakehouse 与 HMS 服务器网络 |
+| 权限不足 | 非 instance_admin | 联系管理员授予 instance_admin 角色 |
+| 查询报错找不到表 | 未使用三层语法 | 使用 `catalog.schema.table` 格式 |
+| Databricks 连接失败 | 不在同一云平台 | 确保 Databricks 存储与 Lakehouse 在同一云平台 |

package/bin/skills/clickzetta-external-catalog/eval_cases.jsonl

@@ -0,0 +1,5 @@
+{"case_id":"001","type":"should_call","user_input":"怎么在 ClickZetta 里直接查询 Hive 的数据？","expected_skill":"clickzetta-external-catalog","expected_output_contains":["External Catalog","CREATE CATALOG CONNECTION"]}
+{"case_id":"002","type":"should_call","user_input":"怎么创建 External Catalog 连接 Iceberg REST Catalog？","expected_skill":"clickzetta-external-catalog","expected_output_contains":["CREATE EXTERNAL CATALOG","iceberg"]}
+{"case_id":"003","type":"should_call","user_input":"联邦查询外部表的三层命名空间怎么写？","expected_skill":"clickzetta-external-catalog","expected_output_contains":["catalog.schema.table"]}
+{"case_id":"004","type":"should_call","user_input":"怎么不迁移数据直接查询 Databricks 的表？","expected_skill":"clickzetta-external-catalog","expected_output_contains":["Databricks","External Catalog"]}
+{"case_id":"005","type":"should_call","user_input":"创建 External Catalog 需要什么权限？","expected_skill":"clickzetta-external-catalog","expected_output_contains":["instance_admin"]}

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/LICENSE

@@ -0,0 +1,16 @@
+ClickZetta Skills License
+© 2026 Yunqi Inc. All rights reserved.
+LICENSE: Use of these materials (including all code, prompts, assets, files, and other components of these skills (collectively, "Skills")) is governed by your agreement with ClickZetta for the Service. If no separate agreement exists, use is governed by ClickZetta's Terms of Service (available at: https://yunqi.tech/documents/user-aggrement).
+Your applicable agreement is referred to as the "Agreement." "Service" is as defined in the Agreement.
+ADDITIONAL RESTRICTIONS: Notwithstanding anything in the Agreement to the contrary, you may not:
+
+Extract from the Service or retain copies of the Skills outside use with the Service;
+Reproduce or copy the Skills, except for temporary copies created automatically during authorized use of the Service;
+Create derivative works based on the Skills;
+Distribute, sublicense, or transfer the Skills to any third party;
+Make, offer to sell, sell, or import any inventions embodied in the Skills; nor,
+Reverse engineer, decompile, or disassemble the Skills.
+
+The receipt, viewing, or possession of the Skills does not convey or imply any license or right beyond those expressly granted above.
+Yunqi retains all rights, title, and interest in the Skills, including all copyrights, trademarks, patents, and all other applicable intellectual property rights.
+THE SKILLS ARE PROVIDED "AS IS," WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SKILLS OR THE USE OR OTHER DEALINGS IN THE SKILLS.

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 = '<key>';
+```
+
+### 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/eval_cases.jsonl

@@ -0,0 +1,4 @@
+{"case_id":"001","type":"should_call","user_input":"怎么创建一个调用 LLM 的外部函数？需要哪些步骤？","expected_skill":"clickzetta-external-function","expected_output_contains":["API CONNECTION","EXTERNAL FUNCTION"]}
+{"case_id":"002","type":"should_call","user_input":"AI_COMPLETE 和 AI_EMBEDDING 内置函数怎么用？","expected_skill":"clickzetta-external-function","expected_output_contains":["AI_COMPLETE","AI_EMBEDDING"]}
+{"case_id":"003","type":"should_call","user_input":"Python UDF 的代码结构和打包方式是什么？","expected_skill":"clickzetta-external-function","expected_output_contains":["Python","def"]}
+{"case_id":"004","type":"should_call","user_input":"怎么创建 API CONNECTION 连接阿里云函数计算？","expected_skill":"clickzetta-external-function","expected_output_contains":["API CONNECTION"]}

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 = '<key>';
+
+-- 调用 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/LICENSE

@@ -0,0 +1,16 @@
+ClickZetta Skills License
+© 2026 Yunqi Inc. All rights reserved.
+LICENSE: Use of these materials (including all code, prompts, assets, files, and other components of these skills (collectively, "Skills")) is governed by your agreement with ClickZetta for the Service. If no separate agreement exists, use is governed by ClickZetta's Terms of Service (available at: https://yunqi.tech/documents/user-aggrement).
+Your applicable agreement is referred to as the "Agreement." "Service" is as defined in the Agreement.
+ADDITIONAL RESTRICTIONS: Notwithstanding anything in the Agreement to the contrary, you may not:
+
+Extract from the Service or retain copies of the Skills outside use with the Service;
+Reproduce or copy the Skills, except for temporary copies created automatically during authorized use of the Service;
+Create derivative works based on the Skills;
+Distribute, sublicense, or transfer the Skills to any third party;
+Make, offer to sell, sell, or import any inventions embodied in the Skills; nor,
+Reverse engineer, decompile, or disassemble the Skills.
+
+The receipt, viewing, or possession of the Skills does not convey or imply any license or right beyond those expressly granted above.
+Yunqi retains all rights, title, and interest in the Skills, including all copyrights, trademarks, patents, and all other applicable intellectual property rights.
+THE SKILLS ARE PROVIDED "AS IS," WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SKILLS OR THE USE OR OTHER DEALINGS IN THE SKILLS.