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

package/bin/skills/clickzetta-concepts/SKILL.md

@@ -0,0 +1,282 @@
+---
+name: clickzetta-concepts
+description: |
+  介绍 ClickZetta Lakehouse 的核心概念、对象模型和独特设计，帮助用户建立正确认知。
+  覆盖：账户/实例/工作空间/Schema 层级，Workspace 与 Database/Catalog 的对应关系，
+  VCluster 三种类型与 CRU 计费，Dynamic Table 增量刷新机制，Table Stream CDC，
+  三层缓存体系，Pipe 持续导入，Synonym 跨 Schema 别名，权限体系（RBAC/ACL），
+  以及与 Snowflake/Databricks 的关键差异对比。
+  还覆盖品牌关系：ClickZetta（技术品牌）= 云器（国内）= Singdata（国际），
+  以及国内（云器）和国际（Singdata）的控制台、API、JDBC 地址。
+  当用户说"工作空间是什么"、"Schema 和 Database 什么关系"、"Catalog 是什么"、
+  "实例和工作空间的区别"、"VCluster 是什么"、"CRU 是什么"、"内部表和外部表区别"、
+  "动态表和物化视图区别"、"Table Stream 是什么"、"Pipe 是什么"、"同义词是什么"、
+  "Lakehouse 架构"、"对象层级"、"权限体系"、"和 Snowflake 概念对比"、
+  "和 Databricks 概念对比"、"存算分离"、"CBO 增量计算"、
+  "云器是什么"、"Singdata 是什么"、"ClickZetta 和云器什么关系"、
+  "国际版地址"、"Singdata 地址"、"API 地址"、"控制台地址"、
+  "service 参数填什么"、"JDBC 地址"、"连接地址"时触发。
+  Keywords: concepts, architecture, workspace, schema, instance, VCluster, object model
+---
+
+# ClickZetta Lakehouse 核心概念
+
+阅读 [references/object-model.md](references/object-model.md) 了解完整对象层级和差异对比。
+阅读 [references/brands-and-endpoints.md](references/brands-and-endpoints.md) 了解品牌关系（云器/Singdata/ClickZetta）和各环境服务地址。
+
+---
+
+## 对象层级总览
+
+```
+账户 (Account)
+└── 服务实例 (Instance)          ← 对应一个云区域部署，资源隔离单元
+    └── 工作空间 (Workspace)      ← 业务隔离单元，≈ Snowflake Database / Databricks Catalog
+        ├── Schema               ← 命名空间，≈ 传统 Database / Snowflake Schema
+        │   ├── 内部表 (Managed Table)   — Iceberg · ACID · Time Travel
+        │   ├── 外部表 (External Table)  — Delta/Hudi/Kafka · 只读
+        │   ├── 视图 / 动态表 / 物化视图
+        │   ├── Volume            — User/Table/External(OSS/S3/COS)
+        │   ├── Table Stream      — CDC 变更捕获（ClickZetta 特有）
+        │   ├── Pipe              — 持续导入（Kafka/OSS）
+        │   ├── 函数 / External Function
+        │   ├── 索引（BloomFilter/倒排/向量）
+        │   └── 同义词 (Synonym)  — 跨 Schema 别名（ClickZetta 特有）
+        ├── Share                 — 跨账户零拷贝共享
+        ├── Connection            — Storage/API 连接
+        └── External Catalog      — Hive/Iceberg/Databricks 联邦查询
+```
+
+---
+
+## 与其他系统的概念对比
+
+| ClickZetta | Snowflake | Databricks | 传统数据库 | 关键差异 |
+|---|---|---|---|---|
+| 服务实例 (Instance) | Account | Workspace | 数据库服务器 | ClickZetta 一个账户可多实例多云 |
+| 工作空间 (Workspace) | Database | Catalog | Database | 连接时必须指定 |
+| Schema | Schema | Schema/Database | Schema | 权限边界，支持 EXTERNAL 类型 |
+| VCluster | Warehouse | SQL Warehouse | — | 三种类型，CRU 细粒度计费 |
+| Dynamic Table | Dynamic Table | Streaming Table | — | 基于 CBO 的增量刷新，非流式 |
+| Table Stream | Stream | — | — | 需先开启 change_tracking |
+| Pipe | Pipe | Auto Loader | — | 每个 Pipe 对应独立 Volume |
+| Volume | Stage | External Location | — | 三种子类型：User/Table/External |
+| Share | Share | Delta Sharing | — | 跨实例零拷贝，消费方无存储费 |
+| Synonym | — | — | Synonym | 支持跨 Schema 别名 |
+| CRU | Credit | DBU | — | 跨云统一算力单位 |
+| **Studio（内置）** | **需第三方** | **需第三方** | **—** | **内置调度/集成/数据质量/目录** |
+
+> Studio 详细介绍见 [clickzetta-studio skill](../clickzetta-studio/SKILL.md)
+
+---
+
+## ClickZetta 独特概念详解
+
+### 1. CRU（Compute Resource Unit）— 跨云统一算力单位
+
+CRU 是 ClickZetta 对 IaaS 计算资源的抽象，**在不同云平台、不同 CPU 架构下提供一致的算力**。
+
+- 计费单位：CRU × 时（集群运行时间）
+- 集群停止时不计费，自动停止最小 15 秒
+- 旧规格代码（XS/S/M/L/XL）已迁移为数字（1/2/4/8/16 CRU）
+
+```sql
+-- 创建 4 CRU 通用型集群
+CREATE VCLUSTER my_gp TYPE GENERAL SIZE 4;
+
+-- 创建分析型集群（弹性 1-4 副本，每副本 8 CRU）
+CREATE VCLUSTER my_ap TYPE ANALYTICS SIZE 8 MIN_INSTANCE 1 MAX_INSTANCE 4;
+```
+
+### 2. VCluster 三种类型 — 不同场景不同集群
+
+| 类型 | 弹性方式 | 规格步长 | 适用场景 | 特殊能力 |
+|---|---|---|---|---|
+| 通用型 (GENERAL) | 纵向（规格扩缩） | 1 CRU | ETL、批量导入、Ad-Hoc | 自动小文件合并（Dynamic Table 推荐） |
+| 分析型 (ANALYTICS) | 横向（副本 1-10） | 2^n CRU | 高并发 BI、在线查询 | 本地缓存 PRELOAD_TABLES |
+| 同步型 (INTEGRATION) | — | 0.25 CRU | 数据集成、CDC 同步 | 最小 0.25 CRU 小规格 |
+
+**关键差异**：Dynamic Table 必须用通用型（GP），分析型（AP）不支持小文件合并，会导致文件碎片化。
+
+### 3. Dynamic Table — 声明式增量计算（非流式）
+
+Dynamic Table 是 ClickZetta 的核心特色之一，**通过 SQL 声明加工逻辑，系统自动判断增量/全量计算策略**。
+
+与 Snowflake Dynamic Table 的关键差异：
+- ClickZetta 基于 **CBO（Cost-Based Optimizer）** 自适应选择增量/全量算法
+- `CREATE OR REPLACE` 保留数据和权限（Snowflake 会清空数据）
+- 最小刷新间隔 **1 分钟**（非秒级流式）
+- 建议用 **GP 集群**（AP 集群不支持小文件合并）
+
+```sql
+-- 声明式增量计算，系统自动处理增量逻辑
+CREATE OR REPLACE DYNAMIC TABLE dws_order_daily
+  REFRESH interval 5 MINUTE
+  VCLUSTER default_gp
+AS
+SELECT date_trunc('day', order_time) AS dt,
+       SUM(amount) AS total_amount,
+       COUNT(*) AS order_cnt
+FROM ods_orders
+GROUP BY 1;
+
+-- 手动触发刷新
+REFRESH DYNAMIC TABLE dws_order_daily;
+```
+
+### 4. Table Stream — CDC 变更捕获对象
+
+Table Stream 是 SQL 对象，记录表的 DML 变更（INSERT/UPDATE/DELETE），**消费后自动推进 offset**。
+
+与 Snowflake Stream 的关键差异：
+- **必须先开启 `change_tracking`**（Snowflake 不需要）
+- 实时写入数据需等待 **1 分钟**后才可被 Stream 读取
+- 支持在 Table、Dynamic Table、Materialized View、Kafka 外部表上创建
+
+```sql
+-- 第一步：开启变更跟踪（必须）
+ALTER TABLE orders SET PROPERTIES ('change_tracking' = 'true');
+
+-- 第二步：创建 Stream
+CREATE TABLE STREAM orders_stream
+  ON TABLE orders
+  WITH PROPERTIES ('TABLE_STREAM_MODE' = 'STANDARD', 'SHOW_INITIAL_ROWS' = 'FALSE');
+
+-- 消费 Stream（DML 操作后 offset 自动推进）
+INSERT INTO orders_summary
+SELECT __change_type, order_id, amount
+FROM orders_stream
+WHERE __change_type = 'INSERT';
+```
+
+Stream 元数据字段：
+- `__change_type`：INSERT / UPDATE_BEFORE / UPDATE_AFTER / DELETE
+- `__commit_version`：提交版本号
+- `__commit_timestamp`：提交时间戳
+
+### 5. Pipe — 持续导入对象
+
+Pipe 是 SQL 对象，持续自动将数据从 Kafka 或对象存储导入到表中。
+
+**ClickZetta 特有限制**：每个 Pipe 必须对应独立的 Volume，不可复用。
+
+```sql
+-- OSS 持续导入（LIST_PURGE 扫描模式）
+CREATE PIPE oss_orders_pipe
+  VIRTUAL_CLUSTER = 'default_gp'
+  INGEST_MODE = 'LIST_PURGE'
+AS COPY INTO orders
+   FROM VOLUME my_oss_volume
+   USING CSV OPTIONS('header'='true');
+
+-- Kafka 持续导入
+CREATE PIPE kafka_events_pipe
+  VIRTUAL_CLUSTER = 'default_gp'
+  BATCH_INTERVAL_IN_SECONDS = '60'
+  BATCH_SIZE_PER_KAFKA_PARTITION = '500000'
+AS COPY INTO events
+   FROM (SELECT * FROM READ_KAFKA(...));
+```
+
+### 6. 三层缓存体系
+
+ClickZetta 有三种独立缓存，理解它们对性能调优至关重要：
+
+| 缓存类型 | 作用范围 | 适用集群 | 说明 |
+|---|---|---|---|
+| 查询结果缓存 (Result Cache) | 工作空间共享 | GP + AP | 相同 SQL 直接返回缓存结果 |
+| 元数据缓存 (Metadata Cache) | 工作空间共享 | GP + AP | 表结构、分区信息缓存 |
+| 本地磁盘缓存 (Local Disk Cache) | 集群本地节点 | GP + AP | 热数据文件缓存，集群停止后释放 |
+
+**主动缓存**（仅 AP 集群）：集群启动时自动预加载指定表的最新数据。
+
+```sql
+-- 设置 AP 集群预加载表（集群启动时自动缓存）
+ALTER VCLUSTER my_ap SET PRELOAD_TABLES = "sales.orders,sales.products";
+
+-- 查看缓存状态
+SHOW PRELOAD CACHED STATUS;
+SHOW EXTENDED PRELOAD CACHED STATUS;
+```
+
+### 7. Synonym（同义词）— 跨 Schema 别名
+
+Synonym 是 ClickZetta 特有的对象类型，为表/Stream/动态表/物化视图/Volume/函数创建跨 Schema 别名，**无需复制数据**。
+
+```sql
+-- 在 schema_b 中为 schema_a 的表创建别名
+CREATE SYNONYM schema_b.orders_alias FOR schema_a.orders;
+
+-- 直接查询别名（数据实时与原表一致）
+SELECT * FROM schema_b.orders_alias;
+
+-- Volume 同义词（必须加 VOLUME 关键字）
+CREATE VOLUME SYNONYM my_schema.vol_alias FOR data_schema.raw_volume;
+
+-- 函数同义词（必须加 FUNCTION 关键字）
+CREATE FUNCTION SYNONYM my_schema.fn_alias FOR data_schema.my_function;
+```
+
+### 8. Sort Key 智能推荐（Auto Index）
+
+ClickZetta 会自动分析查询历史，推荐最优排序列（Sort Key），通过 `information_schema.sortkey_candidates` 查看。
+
+```sql
+-- 开启自动分析（每天收集，分析最近 150 分钟的作业）
+ALTER WORKSPACE quick_start SET PROPERTIES ('auto_index' = 'day');
+
+-- 查看推荐结果
+SELECT table_name, col, statement, ratio
+FROM information_schema.sortkey_candidates
+ORDER BY ratio DESC;
+
+-- 应用推荐（执行 statement 列中的 SQL）
+ALTER TABLE sales.orders SET PROPERTIES ("hint.sort.columns" = "order_date");
+```
+
+---
+
+## 核心概念详解
+
+### 工作空间（Workspace）
+
+**业务隔离单元**，是日常操作的主要边界。
+
+- 连接时必须指定（等同于 Snowflake Database / Databricks Catalog）
+- 每个 Workspace 有独立的：用户角色、VCluster、任务调度、INFORMATION_SCHEMA
+- SQL 三层命名：`workspace_name.schema_name.table_name`
+- 通过 `USE SCHEMA` 切换默认 Schema
+
+### Schema
+
+**命名空间**，是权限授予的边界。
+
+- 类型：`MANAGED`（平台托管存储）/ `EXTERNAL`（外部数据湖路径）
+- 一个 Workspace 下可有多个 Schema
+- 可对整个 Schema 批量授权：`GRANT SELECT ON ALL TABLES IN SCHEMA my_schema TO ROLE ...`
+
+### 权限体系关键点
+
+- **无超级用户**：所有操作必须明确授权，无法绕过权限检查
+- **实例角色与工作空间角色互不影响**：`instance_admin` 不能直接操作工作空间数据
+- **自定义角色仅工作空间级**：不支持实例级自定义角色，且只能通过 SQL 创建
+- **新用户默认无权限**：加入实例后获得 `instance_user` 角色，需显式授予工作空间角色才能操作数据
+
+```sql
+-- 新用户加入后必须授予工作空间角色
+GRANT ROLE workspace_analyst TO USER new_user;
+
+-- 创建自定义角色（仅 SQL，不支持 Web 端）
+CREATE ROLE data_engineer;
+GRANT SELECT, INSERT ON ALL TABLES IN SCHEMA dw TO ROLE data_engineer;
+GRANT ROLE data_engineer TO USER alice;
+```
+
+---
+
+## 存储架构关键点
+
+- **存算分离**：VCluster 停止时不产生计算费用，存储按 GiB 独立计费
+- **开放格式**：内部表基于 Apache Iceberg，可被 Spark/Trino 直接读取
+- **多云多地域**：阿里云上海、腾讯云上海/北京/广州、AWS 北京
+- **私有存储（BYOS）**：支持使用自己的 OSS/S3/COS 账号存储数据

package/bin/skills/clickzetta-concepts/references/brands-and-endpoints.md

@@ -0,0 +1,79 @@
+# ClickZetta 品牌关系与服务地址
+
+## 品牌关系
+
+ClickZetta 是技术品牌名，同一产品在不同市场使用不同品牌：
+
+| 品牌 | 市场 | 官网 | 文档 |
+|---|---|---|---|
+| **云器（Yunqi）** | 国内 | www.yunqi.tech | www.yunqi.tech/documents |
+| **Singdata** | 国际 | www.singdata.com | www.singdata.com/documents |
+| **ClickZetta** | 技术品牌（通用） | — | — |
+
+> **云器 Lakehouse = ClickZetta Lakehouse = Singdata Lakehouse**，三者指同一产品。
+> 用户提到"云器"、"Singdata"、"ClickZetta"时，均指同一 Lakehouse 平台。
+
+---
+
+## 国内（云器）服务地址
+
+控制台：`https://<instance_name>.app.clickzetta.com`
+
+JDBC URL 格式：`jdbc:clickzetta://<instance_name>.<region_code>.api.clickzetta.com/<workspace>`
+
+| 云服务商 | 区域 | Region Code | API 地址 |
+|---|---|---|---|
+| 阿里云 | 上海 | `cn-shanghai-alicloud` | `<instance>.cn-shanghai-alicloud.api.clickzetta.com` |
+| 阿里云 | 杭州 | `cn-hangzhou-alicloud` | `<instance>.cn-hangzhou-alicloud.api.clickzetta.com` |
+| 阿里云 | 北京 | `cn-beijing-alicloud` | `<instance>.cn-beijing-alicloud.api.clickzetta.com` |
+| 腾讯云 | 上海 | `cn-shanghai-tencentcloud` | `<instance>.cn-shanghai-tencentcloud.api.clickzetta.com` |
+| 华为云 | 上海 | `cn-shanghai-huaweicloud` | `<instance>.cn-shanghai-huaweicloud.api.clickzetta.com` |
+
+---
+
+## 国际（Singdata）服务地址
+
+账户控制台：`https://accounts.app.singdata.com` 或 `https://<account_name>.accounts.app.singdata.com`
+
+实例控制台：`https://<instance_name>.app.singdata.com`
+
+工作空间列表：`https://<instance_name>.app.lakehouse.singdata.com/workspace`
+
+JDBC URL 格式：`jdbc:clickzetta://<instance_name>.<region_code>.api.singdata.com/<workspace>`
+
+Streaming API Host：`<instance_name>.streamingapi.singdata.com`
+
+| 云服务商 | 区域 | Region Code | API 地址 |
+|---|---|---|---|
+| 阿里云 | 新加坡 | `ap-southeast-1-alicloud` | `<instance>.ap-southeast-1-alicloud.api.singdata.com` |
+| Amazon Web Services | 新加坡 | `ap-southeast-1-aws` | `<instance>.ap-southeast-1-aws.api.singdata.com` |
+
+---
+
+## SDK / 连接参数中的地址格式
+
+Python SDK（`clickzetta-connector-python`）的 `service` 参数填 API 地址（不含 `jdbc:clickzetta://` 前缀和实例名）：
+
+```python
+# 国内（云器）
+conn = connect(service='cn-shanghai-alicloud.api.clickzetta.com', instance='your_instance', ...)
+
+# 国际（Singdata）
+conn = connect(service='ap-southeast-1-alicloud.api.singdata.com', instance='your_instance', ...)
+```
+
+Java SDK（`clickzetta-java`）的 `.service()` 参数同理：
+
+```java
+// 国内（云器）
+ClickZettaClient.newBuilder()
+    .service("cn-shanghai-alicloud.api.clickzetta.com")
+    .instance("your_instance")
+    ...
+
+// 国际（Singdata）
+ClickZettaClient.newBuilder()
+    .service("ap-southeast-1-alicloud.api.singdata.com")
+    .instance("your_instance")
+    ...
+```

package/bin/skills/clickzetta-concepts/references/object-model.md

@@ -0,0 +1,311 @@
+# ClickZetta Lakehouse 对象模型完整参考
+
+> 来源：官方产品文档 yunqi.tech
+> 参考：clickzetta-lakehouse-architecture.html
+
+---
+
+## ClickZetta 独特概念速查
+
+| 概念 | 独特之处 | 常见误区 |
+|---|---|---|
+| CRU | 跨云统一算力单位，旧规格 XS/S/M/L 已迁移为数字 1/2/4/8 | 不是 Snowflake Credit，不是 DBU |
+| VCluster 三类型 | GP/AP/Integration 各有适用场景，Dynamic Table 必须用 GP | AP 集群不支持小文件合并 |
+| Dynamic Table | CBO 自适应增量/全量，`OR REPLACE` 保留数据 | 最小 1 分钟，非秒级流式 |
+| Table Stream | 需先 `ALTER TABLE SET PROPERTIES ('change_tracking'='true')` | 实时写入数据需等 1 分钟才可读 |
+| Pipe | 每个 Pipe 对应独立 Volume，不可复用 | 不是 Snowflake Snowpipe，无自动触发 |
+| Synonym | 支持跨 Schema 别名，VOLUME/FUNCTION 类型需显式声明关键字 | 不是视图，不复制数据 |
+| 权限体系 | 无超级用户；实例角色与工作空间角色互不影响 | instance_admin 不能直接操作工作空间数据 |
+| Workspace | 连接时必须指定，≈ Snowflake Database | 不是 Databricks Workspace（那个是实例级） |
+| Schema TYPE | MANAGED（内部托管）/ EXTERNAL（外部数据湖） | EXTERNAL Schema 不支持 DML |
+
+---
+
+## 完整对象层级
+
+```
+账户 (Account)
+│  全局唯一 · SSO/MFA · 实名认证
+│
+└── 服务实例 (Instance)
+    │  资源隔离 · 多云多地域 · Instance Role
+    │
+    └── 工作空间 (Workspace)
+        │  业务隔离 · Workspace Role · VCluster 绑定 · 任务调度
+        │
+        ├── Schema（数据库/命名空间）
+        │   │  MANAGED / EXTERNAL 类型
+        │   │
+        │   ├── 内部表 (Managed Table)     — Iceberg · ACID · Time Travel · 索引
+        │   ├── 外部表 (External Table)    — Delta/Hudi/Kafka · 只读
+        │   ├── 视图 (View)               — 虚拟 · 无存储
+        │   ├── 动态表 (Dynamic Table)    — 声明式增量刷新
+        │   ├── 物化视图 (Materialized View) — 预计算 · 定时刷新
+        │   ├── Volume                    — User/Table/External(OSS/S3/COS)
+        │   ├── Table Stream              — CDC 变更捕获
+        │   ├── Pipe                      — Kafka/OSS 持续导入
+        │   ├── 函数 / External Function  — SQL UDF / Python / Java
+        │   ├── 索引                      — BloomFilter / Inverted / Vector(HNSW)
+        │   └── 同义词 (Synonym)          — 跨 Schema 别名
+        │
+        ├── Share                         — 跨账户零拷贝数据共享
+        ├── Connection                    — Storage(OSS/COS/S3) / API(云函数)
+        └── External Catalog              — Hive HMS / Iceberg REST / Databricks Unity
+```
+
+---
+
+## 工作空间（Workspace）详解
+
+### 核心定位
+
+Workspace 是 ClickZetta 中**业务隔离的最小单元**，也是连接时必须指定的对象。
+
+- 等同于 Snowflake 的 **Database**，或 Databricks 的 **Catalog**
+- 每个 Workspace 有独立的：用户角色、VCluster、任务调度、INFORMATION_SCHEMA
+- 连接参数中的 `workspace` 字段即指定此对象
+
+### 管理命令
+
+```sql
+-- 查看所有工作空间（需 instance_admin）
+SHOW WORKSPACES;
+
+-- 查看工作空间详情
+DESC WORKSPACE my_workspace;
+
+-- 修改注释
+ALTER WORKSPACE my_workspace SET COMMENT '生产环境';
+
+-- 查看属性
+SHOW PROPERTIES IN WORKSPACE my_workspace;
+```
+
+### DESC WORKSPACE 输出字段
+
+| 字段 | 说明 |
+|---|---|
+| name | 工作空间名称 |
+| creator | 创建者 |
+| created_time | 创建时间 |
+| last_modified_time | 最后修改时间 |
+| comment | 注释 |
+
+---
+
+## Schema 详解
+
+### 核心定位
+
+Schema 是 ClickZetta 中的**命名空间**，用于组织数据对象。
+
+- 等同于传统数据库的 **Database** 或 **Schema**（注意：不同系统叫法不同）
+- 是权限授予的边界（可对整个 Schema 授权）
+- 类型：`MANAGED`（平台托管存储）/ `EXTERNAL`（外部数据湖路径）
+
+### 管理命令
+
+```sql
+-- 创建 Schema
+CREATE SCHEMA my_schema;
+
+-- 创建外部 Schema（指向外部数据湖）
+CREATE EXTERNAL SCHEMA ext_schema LOCATION 'oss://bucket/path/';
+
+-- 切换默认 Schema
+USE SCHEMA my_schema;
+
+-- 查看所有 Schema
+SHOW SCHEMAS;
+
+-- 查看 Schema 详情
+DESC SCHEMA my_schema;
+
+-- 修改 Schema
+ALTER SCHEMA my_schema RENAME TO new_schema;
+ALTER SCHEMA my_schema SET COMMENT '数据仓库层';
+
+-- 删除 Schema（需先删除其中的对象）
+DROP SCHEMA my_schema;
+DROP SCHEMA IF EXISTS my_schema CASCADE;  -- 级联删除所有对象
+```
+
+---
+
+## VCluster（计算集群）详解
+
+### 三种类型对比
+
+| 属性 | 通用型 (GENERAL) | 分析型 (ANALYTICS) | 同步型 (INTEGRATION) |
+|---|---|---|---|
+| 适用场景 | ETL、批量导入、Ad-Hoc | 高并发 BI、在线查询 | 数据集成、CDC 同步 |
+| 弹性方式 | 纵向（规格扩缩） | 横向（副本数 1-10） | — |
+| 最小规格 | 1 CRU | 1 CRU | 0.25 CRU |
+| 最大规格 | 256 CRU | 256 CRU | 256 CRU |
+| 规格步长 | 1 CRU | 2^n CRU | 0.25 CRU |
+| 本地缓存 | 不支持 | 支持（PRELOAD） | 不支持 |
+| 小文件合并 | 支持（Dynamic Table 推荐） | 不支持 | — |
+
+### 任务类型与集群对应
+
+| 任务类型 | 推荐集群 |
+|---|---|
+| SQL ETL / 批量导入 | 通用型 |
+| Ad-Hoc 查询 / BI | 分析型 |
+| Dynamic Table（低频大量） | 通用型 |
+| Dynamic Table（高频小量） | 分析型 |
+| 离线同步 / 实时同步 / CDC | 同步型 |
+| Python / Shell / JDBC 任务 | 不使用 VCluster |
+
+### 管理命令
+
+```sql
+-- 创建通用型集群
+CREATE VCLUSTER my_gp TYPE GENERAL SIZE 4;
+
+-- 创建分析型集群（弹性 1-4 副本）
+CREATE VCLUSTER my_ap TYPE ANALYTICS SIZE 8 MIN_INSTANCE 1 MAX_INSTANCE 4;
+
+-- 启动 / 停止
+ALTER VCLUSTER my_gp RESUME;
+ALTER VCLUSTER my_gp SUSPEND;
+
+-- 查看所有集群
+SHOW VCLUSTERS;
+```
+
+---
+
+## 用户与权限体系
+
+### 用户层级
+
+```
+全局账号用户（Global User）
+│  在账户层面管理，user_name 全局唯一
+│
+└── 服务实例用户（Instance User）
+    │  全局用户自动同步，默认获得 instance_user 角色（无数据权限）
+    │
+    └── 工作空间用户（Workspace User）
+        通过 GRANT ROLE 授予工作空间角色后才能操作数据
+```
+
+### 用户类型
+
+| 类型 | 说明 |
+|---|---|
+| 普通用户 | 代表实际人员，可 Web 登录 |
+| 系统服务用户 | 平台内置，默认禁用（如 sysservice_auto_mv） |
+| 自定义服务用户 | 用于自动化程序，不可 Web 登录，可用 JDBC |
+
+### 预置角色
+
+| 角色 | 级别 | 权限范围 |
+|---|---|---|
+| instance_admin | 实例级 | 管理所有工作空间、用户、External Catalog |
+| instance_user | 实例级 | 默认角色，无数据权限 |
+| workspace_admin | 工作空间级 | 管理空间内所有对象和用户 |
+| workspace_dev | 工作空间级 | 读写权限 + 任务管理 |
+| workspace_analyst | 工作空间级 | 只读权限 |
+
+### 授权命令
+
+```sql
+-- 将角色授予用户
+GRANT ROLE workspace_dev TO USER alice;
+
+-- 授予表权限
+GRANT SELECT ON TABLE my_schema.my_table TO ROLE analyst_role;
+GRANT SELECT ON ALL TABLES IN SCHEMA my_schema TO ROLE analyst_role;
+
+-- 授予 information_schema 查询权限
+GRANT ALL ON ALL VIEWS IN SCHEMA information_schema TO ROLE analyst_role;
+
+-- 撤销权限
+REVOKE SELECT ON TABLE my_schema.my_table FROM ROLE analyst_role;
+
+-- 创建自定义角色（仅工作空间级，仅 SQL）
+CREATE ROLE my_custom_role;
+```
+
+---
+
+## 数据类型速查
+
+| 分类 | 类型 |
+|---|---|
+| 整数 | TINYINT / SMALLINT / INT / BIGINT |
+| 浮点 | FLOAT / DOUBLE / DECIMAL(p,s) |
+| 字符串 | CHAR(n) / VARCHAR(n) / STRING（最大 16MB） |
+| 时间 | DATE / TIMESTAMP（带时区 LTZ）/ TIMESTAMP_NTZ / INTERVAL |
+| 布尔 | BOOLEAN |
+| 复杂 | ARRAY\<T\> / MAP\<K,V\> / STRUCT\<field:type,...\> |
+| AI 专用 | VECTOR(FLOAT, n)（最大 65535 维）/ VECTOR(TINYINT, n) |
+| 特殊 | JSON / BINARY / BITMAP（Roaring Bitmap） |
+
+---
+
+## 平台架构层次
+
+```
+客户端层：Studio IDE · JDBC/ODBC · Python SDK · ZettaPark · BI 工具 · MCP Server
+    ↓
+计算层：VCluster（GENERAL / ANALYTICS / INTEGRATION）
+    ↓
+服务层：SQL 解析优化 · 向量化执行引擎 · Dynamic Table · AI Gateway · Result Cache
+    ↓
+存储层：内部表(Iceberg) · 外部表 · Volume · Time Travel · External Catalog · Share
+    ↓
+底层对象存储：阿里云 OSS · AWS S3 · 腾讯云 COS
+```
+
+**存算分离**：计算层和存储层独立扩展，VCluster 停止时不产生计算费用，存储按 GiB 计费。
+
+---
+
+## 数据对象横向对比
+
+### Dynamic Table vs Materialized View vs View
+
+| 维度 | 动态表 (Dynamic Table) | 物化视图 (Materialized View) | 视图 (View) |
+|---|---|---|---|
+| 数据存储 | 有（物化） | 有（物化） | 无（虚拟） |
+| 刷新方式 | 自动增量/全量（CBO 决策） | 手动或定时全量 | 每次查询实时执行 |
+| 最小刷新间隔 | 1 分钟 | 无限制（手动） | — |
+| Time Travel | 支持 | 不支持 | 不支持 |
+| UNDROP | 支持 | 不支持 | 不支持 |
+| CREATE OR REPLACE | 支持（保留数据和权限） | 支持 | 支持 |
+| 推荐集群 | GP（通用型） | GP 或 AP | — |
+| 适用场景 | 实时 ETL、多层级联 | BI 加速、固定聚合 | 简单逻辑封装 |
+
+### Table Stream 两种模式
+
+| 模式 | 捕获内容 | 典型用途 |
+|---|---|---|
+| STANDARD | INSERT + UPDATE_BEFORE + UPDATE_AFTER + DELETE | CDC UPSERT，MERGE INTO 消费 |
+| APPEND_ONLY | 仅 INSERT | 日志追加，简单 ETL |
+
+**STANDARD 模式的 delta 语义**：记录两个 offset 之间的净变化。若一行先 INSERT 后 DELETE，delta 中该行消失（不会出现 INSERT+DELETE 两条记录）。
+
+### Pipe 两种导入模式
+
+| 模式 | 触发方式 | 适用场景 | 云支持 |
+|---|---|---|---|
+| LIST_PURGE | 定期扫描 Volume 目录 | 通用，任何对象存储 | 全部 |
+| EVENT_NOTIFICATION | 云消息队列事件触发 | 低延迟，近实时 | 仅阿里云 OSS + AWS S3 |
+
+---
+
+## 地域与连接信息
+
+| 云服务商 | 地域 | 区域代码 | API Endpoint |
+|---|---|---|---|
+| 阿里云 | 华东2（上海） | cn-shanghai-alicloud | cn-shanghai-alicloud.api.clickzetta.com |
+| 腾讯云 | 华东（上海） | ap-shanghai-tencentcloud | ap-shanghai-tencentcloud.api.clickzetta.com |
+| 腾讯云 | 华北（北京） | ap-beijing-tencentcloud | ap-beijing-tencentcloud.api.clickzetta.com |
+| 腾讯云 | 华南（广州） | ap-guangzhou-tencentcloud | ap-guangzhou-tencentcloud.api.clickzetta.com |
+| AWS | 北京 | cn-north-1-aws | cn-north-1-aws.api.clickzetta.com |
+
+JDBC URL 格式：`jdbc:clickzetta://<instance_name>.<region_id>.api.clickzetta.com/`
+