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

package/bin/skills/clickzetta-kafka-ingest-pipeline/references/kafka-pipe-syntax.md

@@ -1,186 +0,0 @@
-# Kafka Pipe SQL 语法参考
-
-> 来源：https://www.yunqi.tech/documents/pipe-kafka 和 https://www.yunqi.tech/documents/pipe-kafka-bestpractice-1
-
-## CREATE PIPE（READ_KAFKA 方式）
-
-```sql
-CREATE [ OR REPLACE ] PIPE <pipe_name>
-  VIRTUAL_CLUSTER = <vcluster_name>
-  [ BATCH_INTERVAL_IN_SECONDS = <seconds> ]
-  [ BATCH_SIZE_PER_KAFKA_PARTITION = <count> ]
-  [ MAX_SKIP_BATCH_COUNT_ON_ERROR = <count> ]
-  [ INITIAL_DELAY_IN_SECONDS = <seconds> ]
-  [ RESET_KAFKA_GROUP_OFFSETS = '<offset_value>' ]
-AS
-INSERT INTO <target_table> [ ( <col1>, <col2>, ... ) ]
-SELECT <expr> [, ...]
-FROM TABLE(
-  READ_KAFKA(
-    KAFKA_BROKER => '<broker_host>:<port>',
-    KAFKA_TOPIC  => '<topic_name>',
-    KAFKA_GROUP_ID => '<consumer_group>',
-    KAFKA_DATA_FORMAT => '<json | csv | avro>',
-    [ KAFKA_SASL_USERNAME => '<username>', ]
-    [ KAFKA_SASL_PASSWORD => '<password>' ]
-  )
-);
-```
-
-### 参数说明
-
-| 参数 | 必填 | 默认值 | 说明 |
-|------|------|--------|------|
-| `VIRTUAL_CLUSTER` | 是 | — | 执行 Pipe 任务的计算集群 |
-| `BATCH_INTERVAL_IN_SECONDS` | 否 | 60 | 批处理间隔（秒），即数据新鲜度 |
-| `BATCH_SIZE_PER_KAFKA_PARTITION` | 否 | 500000 | 每个 Kafka 分区每批最大消息数 |
-| `MAX_SKIP_BATCH_COUNT_ON_ERROR` | 否 | 30 | 出错时跳过批次的最大重试次数 |
-| `INITIAL_DELAY_IN_SECONDS` | 否 | 0 | 首个作业调度延迟 |
-| `RESET_KAFKA_GROUP_OFFSETS` | 否 | — | 启动时消费位点（仅创建时生效） |
-
-### RESET_KAFKA_GROUP_OFFSETS 可选值
-
-| 值 | 说明 |
-|----|------|
-| `'none'` | 无操作，使用 Kafka `auto.offset.reset`（默认 latest） |
-| `'valid'` | 检查当前位点是否过期，将过期分区重置到 earliest |
-| `'earliest'` | 重置到最早位点 |
-| `'latest'` | 重置到最新位点 |
-| `'<毫秒时间戳>'` | 重置到指定时间戳对应位点（如 `'1737789688000'`） |
-
-### READ_KAFKA 参数（在 Pipe 中 vs 独立使用）
-
-| 特性 | 独立使用 READ_KAFKA | 在 Pipe 中使用 |
-|------|-------------------|---------------|
-| 消费者组 | 临时，执行完即销毁 | 持久，保持消费位置 |
-| 位置管理 | 手动指定 `KAFKA_OFFSET` | Pipe 自动管理，**不要设置** `KAFKA_OFFSET` |
-| 执行方式 | 一次性查询 | 持续调度执行 |
-| 默认起始位置 | earliest（探查历史数据） | latest（处理新数据） |
-
-### JSON 字段提取语法
-
-```sql
--- $1 表示整行 JSON
-$1:field_name::TYPE              -- 提取顶层字段
-$1:nested.field::TYPE            -- 提取嵌套字段（点号访问）
-PARSE_JSON($1:field::STRING)     -- 将字符串字段解析为 JSON 对象
-```
-
----
-
-## CREATE PIPE（Kafka 外部表 + Table Stream 方式）
-
-### 步骤 1：创建 Kafka Storage Connection
-
-```sql
-CREATE STORAGE CONNECTION IF NOT EXISTS <conn_name>
-  TYPE KAFKA
-  BOOTSTRAP_SERVERS = ['<host1>:<port1>', '<host2>:<port2>']
-  SECURITY_PROTOCOL = '<PLAINTEXT | SASL_PLAINTEXT>';
-```
-
-### 步骤 2：创建 Kafka 外部表
-
-```sql
-CREATE EXTERNAL TABLE <ext_table_name>
-  USING KAFKA
-  OPTIONS (
-    'group_id' = '<consumer_group>',
-    'topics' = '<topic_name>',
-    'starting_offset' = '<earliest | latest>'
-  )
-  CONNECTION <conn_name>;
-```
-
-固定字段：
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| topic | STRING | Kafka 主题名称 |
-| partition | INT | 分区 ID |
-| offset | BIGINT | 分区内偏移量 |
-| timestamp | TIMESTAMP_LTZ | 消息时间戳 |
-| timestamp_type | STRING | 时间戳类型 |
-| headers | MAP<STRING, BINARY> | 消息头 |
-| key | BINARY | 消息键 |
-| value | BINARY | 消息体 |
-
-### 步骤 3：创建 Table Stream
-
-```sql
-CREATE TABLE STREAM <stream_name>
-  ON TABLE <ext_table_name>
-  WITH PROPERTIES ('TABLE_STREAM_MODE' = 'APPEND_ONLY');
-```
-
-### 步骤 4：创建 Pipe
-
-```sql
-CREATE PIPE <pipe_name>
-  VIRTUAL_CLUSTER = <vcluster_name>
-  [ BATCH_INTERVAL_IN_SECONDS = <seconds> ]
-AS
-COPY INTO <target_table>
-SELECT <expr> [, ...]
-FROM <stream_name>;
-```
-
----
-
-## ALTER PIPE
-
-```sql
--- 暂停
-ALTER PIPE <pipe_name> SET PIPE_EXECUTION_PAUSED = true;
-
--- 恢复
-ALTER PIPE <pipe_name> SET PIPE_EXECUTION_PAUSED = false;
-
--- 修改属性（每次只能改一个）
-ALTER PIPE <pipe_name> SET BATCH_INTERVAL_IN_SECONDS = 120;
-ALTER PIPE <pipe_name> SET BATCH_SIZE_PER_KAFKA_PARTITION = 1000000;
-ALTER PIPE <pipe_name> SET VIRTUAL_CLUSTER = 'new_vc';
-ALTER PIPE <pipe_name> SET COPY_JOB_HINT = '{"cz.sql.split.kafka.strategy":"size","cz.mapper.kafka.message.size":"200000"}';
-```
-
-> 不支持修改 COPY/INSERT 语句逻辑，需删除 Pipe 后重建。
-> 修改 `COPY_JOB_HINT` 会覆盖所有已有 hints，需一次性设置全部参数。
-
----
-
-## 监控
-
-```sql
--- 查看 Pipe 详情（含延迟信息）
-DESC PIPE <pipe_name>;
-DESC PIPE EXTENDED <pipe_name>;
-
--- 查看所有 Pipe
-SHOW PIPES;
-
--- 查看加载历史
-SELECT * FROM TABLE(load_history('<schema>.<table>'))
-ORDER BY last_load_time DESC LIMIT 20;
-
--- 通过 query_tag 查看 Pipe 作业
--- 格式：pipe.<workspace_name>.<schema_name>.<pipe_name>
-SHOW JOBS WHERE query_tag = 'pipe.my_workspace.ods.kafka_orders_pipe';
-```
-
----
-
-## DROP PIPE
-
-```sql
-DROP PIPE [ IF EXISTS ] <pipe_name>;
-```
-
-## 参考文档
-
-- [Pipe 简介](https://www.yunqi.tech/documents/pipe-summary)
-- [借助 read_kafka 函数持续导入](https://www.yunqi.tech/documents/pipe-kafka)
-- [借助 Kafka 外表 Table Stream 持续导入](https://www.yunqi.tech/documents/pipe-kafka-table-stream)
-- [最佳实践：使用 Pipe 高效接入 Kafka 数据](https://www.yunqi.tech/documents/pipe-kafka-bestpractice-1)
-- [read_kafka 函数](https://www.yunqi.tech/documents/read_kafka)
-- [Kafka 外部表](https://www.yunqi.tech/documents/kafka-external-table)
-- [PIPE 导入语法](https://www.yunqi.tech/documents/pipe-syntax)

package/bin/skills/clickzetta-lakehouse-connect/SKILL.md

@@ -1,218 +0,0 @@
----
-name: clickzetta-lakehouse-connect
-description: |
-  Guide for connecting to ClickZetta Lakehouse via SDK/JDBC. Covers Python SDK (clickzetta.connect), ZettaPark Session (DataFrame API), SQLAlchemy (ORM/BI tools), and JDBC (Java). Use this skill when user needs to configure a connection from external tools or code — NOT for querying data inside czcode (use execute_sql/list_objects tools instead). Trigger for: "Python SDK 连接", "JDBC 连接", "SQLAlchemy 配置", "ZettaPark 怎么用", "连接报错", "clickzetta-connector-python", "clickzetta-sqlalchemy".
-  Keywords: connection, Python SDK, JDBC, SQLAlchemy, ZettaPark, driver, connect
----
-
-# ClickZetta Lakehouse 连接指南
-
-## 指令
-
-### 步骤 0：自动获取连接参数（优先）
-
-**在询问用户之前，先尝试从本地配置文件自动读取连接参数。**
-
-按以下优先级查找配置文件（找到第一个即停止）：
-1. `/app/.clickzetta/lakehouse_connection/connections.json`
-2. `config/lakehouse_connection/connections.json`
-3. `~/.clickzetta/connections.json`
-4. `/app/.clickzetta/connections.json`
-
-找到配置文件后：
-- 解析 JSON，提取 `connections` 数组
-- 根据用户描述的区域/环境匹配对应连接（如"阿里云上海"匹配 `service` 含 `cn-shanghai-alicloud` 的连接）
-- 若有 `is_default: true` 且用户未指定区域，使用默认连接
-- **不要将密码或完整配置输出到对话中**，仅内部使用
-
-若配置文件不存在或无匹配连接，再向用户询问：service、instance、workspace、username、password、schema、vcluster。
-
-### 步骤 1：确认连接方式
-
-根据用户场景选择连接方式，阅读对应参考文件：
-
-| 用户需求 | 参考文件 |
-|:--|:--|
-| Python 脚本 / 自动化 / 执行 SQL | [references/python-sdk.md](references/python-sdk.md) |
-| DataFrame / 数据工程 | [references/zettapark-session.md](references/zettapark-session.md) |
-| ORM / Web 应用 / BI 工具（Superset） | [references/sqlalchemy.md](references/sqlalchemy.md) |
-| Java 应用 / BI 工具（DBeaver） | [references/jdbc.md](references/jdbc.md) |
-| 多环境配置文件管理 | [references/config-file.md](references/config-file.md) |
-
-不确定时参考决策树：
-- 需要 DataFrame 操作 → ZettaPark Session
-- 需要 ORM / SQLAlchemy 集成 → SQLAlchemy
-- Java 应用 → JDBC
-- 其他 Python 场景（含直接执行 SQL）→ Python SDK
-
-### 步骤 2：确认 service 地址
-
-`service` 参数必须包含区域前缀，根据实例所在区域选择：
-
-**云器 Lakehouse（国内版，`clickzetta.com`）**
-
-| 云厂商 | 区域 | service 地址 |
-|:--|:--|:--|
-| 阿里云 | 华东2（上海） | `cn-shanghai-alicloud.api.clickzetta.com` |
-| 腾讯云 | 华东（上海） | `ap-shanghai-tencentcloud.api.clickzetta.com` |
-| 腾讯云 | 华北（北京） | `ap-beijing-tencentcloud.api.clickzetta.com` |
-| 腾讯云 | 华南（广州） | `ap-guangzhou-tencentcloud.api.clickzetta.com` |
-| AWS | 中国（北京） | `cn-north-1-aws.api.clickzetta.com` |
-
-**Singdata Lakehouse（国际版，`singdata.com`）**
-
-| 云厂商 | 区域 | service 地址 |
-|:--|:--|:--|
-| 阿里云 | 亚太东南1（新加坡） | `ap-southeast-1-alicloud.api.singdata.com` |
-| AWS | 亚太（新加坡） | `ap-southeast-1-aws.api.singdata.com` |
-
-控制台：`https://{instance}.{region}.app.clickzetta.com`
-
-### 步骤 3：执行查询或提供可运行代码
-
-**若用户要求执行查询（如 SHOW SCHEMAS、SELECT、SHOW TABLES 等）：**
-
-1. 确认 `clickzetta-connector-python` 已安装：
-   ```bash
-   pip3 show clickzetta-connector-python
-   ```
-   若未安装，执行：`pip3 install clickzetta-connector-python --user`
-
-2. 使用步骤 0 获取的连接参数直接执行查询，将结果格式化后展示给用户。
-
-**若用户要求生成代码：**
-
-阅读对应参考文件后，根据参数生成完整可运行代码。所有参数均为必填，`vcluster` 默认值为 `default_ap`。
-
-密码含特殊字符时（SQLAlchemy URI），提醒用户用 `urllib.parse.quote_plus()` 编码。
-
-## 示例
-
-### 示例 0：自动读取配置并执行查询
-
-```python
-import json, os, clickzetta
-
-# 按优先级查找配置文件
-config_paths = [
-    "/app/.clickzetta/lakehouse_connection/connections.json",
-    "config/lakehouse_connection/connections.json",
-    os.path.expanduser("~/.clickzetta/connections.json"),
-    "/app/.clickzetta/connections.json",
-]
-config = None
-for path in config_paths:
-    if os.path.exists(path):
-        with open(path) as f:
-            config = json.load(f)
-        break
-
-# 选择目标连接（示例：匹配阿里云上海）
-conn_cfg = next(
-    (c for c in config["connections"] if "cn-shanghai-alicloud" in c.get("service", "")),
-    None
-) or next((c for c in config["connections"] if c.get("is_default")), config["connections"][0])
-
-conn = clickzetta.connect(
-    service=conn_cfg["service"],
-    instance=conn_cfg["instance"],
-    workspace=conn_cfg["workspace"],
-    schema=conn_cfg.get("schema", "public"),
-    username=conn_cfg["username"],
-    password=conn_cfg["password"],
-    vcluster=conn_cfg.get("vcluster", "default_ap")
-)
-cursor = conn.cursor()
-cursor.execute("SHOW SCHEMAS")
-for row in cursor.fetchall():
-    print(row[0])
-cursor.close()
-conn.close()
-```
-
-### 示例 1：Python SDK 连接并查询
-
-```python
-import clickzetta
-
-conn = clickzetta.connect(
-    service="cn-shanghai-alicloud.api.clickzetta.com",
-    instance="my_instance",
-    workspace="my_workspace",
-    schema="public",
-    username="my_user",
-    password="my_password",
-    vcluster="default_ap"
-)
-cursor = conn.cursor()
-cursor.execute("SELECT * FROM orders LIMIT 10")
-for row in cursor.fetchall():
-    print(row)
-cursor.close()
-conn.close()
-```
-
-### 示例 2：ZettaPark 按 region 汇总 revenue
-
-```python
-from clickzetta.zettapark.session import Session
-from clickzetta.zettapark import functions as F
-
-session = Session.builder.configs({
-    "service": "cn-shanghai-alicloud.api.clickzetta.com",
-    "instance": "my_instance", "workspace": "my_workspace",
-    "schema": "public", "username": "my_user",
-    "password": "my_password", "vcluster": "default_ap"
-}).create()
-
-session.table("sales") \
-    .group_by(F.col("region")) \
-    .agg(F.sum("revenue").as_("total_revenue")) \
-    .write.save_as_table("sales_summary", mode="overwrite")
-session.close()
-```
-
-## 故障排除
-
-| 错误信息 | 原因 | 解决方案 |
-|:--|:--|:--|
-| `Connection refused` | service 地址不正确或网络不通 | 检查 service 是否匹配区域（参见步骤 2 区域表） |
-| `Authentication failed` | 用户名或密码错误 | 核实 username 和 password |
-| `Workspace not found` | 工作空间名称不存在 | 在控制台确认 workspace 拼写 |
-| `Instance not found` | 实例名称不存在 | 在控制台确认 instance 拼写 |
-| `Timeout` | 查询超时 | 增大 `hints` 中的 `sdk.job.timeout`（默认 300 秒） |
-| `VCluster not available` | 虚拟集群未启动或名称错误 | 确认 vcluster 名称，检查集群状态 |
-| SQLAlchemy URL 解析错误 | 密码含特殊字符 | 用 `urllib.parse.quote_plus()` 对密码 URL 编码 |
-| `ClassNotFoundException` | JDBC 驱动未在 classpath | 确保 `clickzetta-java` JAR 已加入 classpath |
-
-## 安装
-
-> ⚠️ **Python 版本要求**：推荐 **Python 3.12**（最低 3.10）。Python 3.9 及以下不支持。
-
-| 连接方式 | 安装命令 |
-|:--|:--|
-| Python SDK | `pip install clickzetta-connector-python -i https://pypi.tuna.tsinghua.edu.cn/simple` |
-| ZettaPark | `pip install clickzetta-zettapark-python -i https://pypi.tuna.tsinghua.edu.cn/simple` |
-| SQLAlchemy | `pip install clickzetta-connector-python clickzetta-sqlalchemy -i https://pypi.tuna.tsinghua.edu.cn/simple` |
-| JDBC | Maven: `com.clickzetta:clickzetta-java` |
-
-```bash
-# 方式 1：venv（Python 内置，推荐）
-python3.12 -m venv .venv
-source .venv/bin/activate          # macOS/Linux
-# .venv\Scripts\activate           # Windows
-pip install clickzetta-connector-python 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-connector-python 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-connector-python clickzetta-zettapark-python \
-    -i https://pypi.tuna.tsinghua.edu.cn/simple
-```

package/bin/skills/clickzetta-lakehouse-connect/evals/evals.json

@@ -1,35 +0,0 @@
-{
-  "skill_name": "clickzetta-lakehouse-connect",
-  "evals": [
-    {
-      "id": 1,
-      "prompt": "我需要用 Python 连接 ClickZetta，实例名是 my_instance，工作空间是 analytics，region 是上海阿里云，用户名 alice，密码 secret123。帮我写一段查询 orders 表前 10 行的代码。",
-      "expected_output": "使用 clickzetta.connect() 或 clickzetta-connector-python，包含所有必填参数（service/instance/workspace/schema/username/password/vcluster），并演示 cursor.execute + fetchall 查询",
-      "files": []
-    },
-    {
-      "id": 2,
-      "prompt": "我想用 ZettaPark 做数据工程，需要读取 sales 表，按 region 分组求 revenue 总和，然后写回到 sales_summary 表。帮我写完整代码。",
-      "expected_output": "使用 Session.builder.configs().create()，展示 session.table() + group_by + agg + write.save_as_table()，包含连接参数配置",
-      "files": []
-    },
-    {
-      "id": 3,
-      "prompt": "我在用 Apache Superset 连接 ClickZetta，SQLAlchemy URI 应该怎么填？密码是 P@ss#2024，需要注意什么？",
-      "expected_output": "提供正确的 clickzetta:// URI 格式，指出密码特殊字符需要 quote_plus 编码，给出编码后的示例",
-      "files": []
-    },
-    {
-      "id": 4,
-      "prompt": "连接云器 Lakehouse 报错 Connection refused，我的 service 填的是 api.clickzetta.com，实例在上海腾讯云，怎么排查？",
-      "expected_output": "识别 service 地址填错，给出正确的上海腾讯云地址 ap-shanghai-tencentcloud.api.clickzetta.com，并提供排查步骤",
-      "files": []
-    },
-    {
-      "id": 5,
-      "prompt": "我有三个环境：dev/staging/prod，都在同一个 ClickZetta 实例上但不同 workspace。想用 connections.json 统一管理，并在代码里切换。怎么配置？",
-      "expected_output": "提供 connections.json 多连接配置示例（含 is_default），展示 switch_connection() 用法，说明文件放置路径",
-      "files": []
-    }
-  ]
-}