@clickzetta/cz-cli-darwin-arm64 0.3.19 → 0.3.21

package/bin/skills/clickzetta-metadata/references/instance-views-reference.md

@@ -0,0 +1,276 @@
+# 实例级 INFORMATION_SCHEMA 视图字段说明
+
+> 来源：https://www.yunqi.tech/documents/instance-informaiton-schema
+> 已通过实际 Lakehouse 连接验证（cn-shanghai-alicloud, f8866243）
+
+访问路径：`SYS.information_schema.<视图名>`
+权限要求：INSTANCE ADMIN
+
+实例级视图覆盖所有工作空间，包含已删除对象（`DELETE_TIME IS NULL` 过滤现存对象）。
+
+**完整视图列表（排除 mysql 相关）：**
+WORKSPACES · SCHEMAS · TABLES · COLUMNS · VIEWS · USERS · ROLES ·
+JOB_HISTORY · MATERIALIZED_VIEW_REFRESH_HISTORY · AUTOMV_REFRESH_HISTORY ·
+VOLUMES · CONNECTIONS · OBJECT_PRIVILEGES · SORTKEY_CANDIDATES ·
+**STORAGE_METERING**（存储费用）· **INSTANCE_USAGE**（计算费用）
+
+> 费用视图（STORAGE_METERING / INSTANCE_USAGE）字段详见 [metering-views-reference.md](metering-views-reference.md)
+
+---
+
+## WORKSPACES 视图
+
+| 字段名 | 类型 | 说明 |
+|---|---|---|
+| WORKSPACE_ID | STRING | 工作空间 ID |
+| WORKSPACE_NAME | STRING | 工作空间名称 |
+| WORKSPACE_CREATOR | STRING | 工作空间所有者 |
+| WORKSPACE_CREATOR_ID | STRING | 所有者账号 ID |
+| WORKSPACE_STORAGE | BIGINT | 存储用量（字节，不含外部表和外部数据湖） |
+| CREATE_TIME | TIMESTAMP | 创建时间 |
+| LAST_MODIFY_TIME | TIMESTAMP | 修改时间 |
+| COMMENT | STRING | 注释 |
+| DELETE_TIME | TIMESTAMP | 删除时间（NULL 表示未删除） |
+| PROPERTIES | MAP\<STRING,STRING> | 自定义属性 |
+
+---
+
+## SCHEMAS 视图
+
+| 字段名 | 类型 | 说明 |
+|---|---|---|
+| CATALOG_NAME | STRING | 所属 WORKSPACE 名称 |
+| SCHEMA_ID | STRING | Schema ID |
+| SCHEMA_NAME | STRING | Schema 名称 |
+| TYPE | STRING | EXTERNAL / MANAGED |
+| SCHEMA_CREATOR | STRING | 所有者账号名称 |
+| SCHEMA_CREATOR_ID | STRING | 所有者账号 ID |
+| CREATE_TIME | TIMESTAMP | 创建时间 |
+| LAST_MODIFY_TIME | TIMESTAMP | 修改时间 |
+| COMMENT | STRING | 注释 |
+| DELETE_TIME | TIMESTAMP | 删除时间（NULL 表示未删除） |
+| PROPERTIES | MAP\<STRING,STRING> | 自定义属性 |
+
+---
+
+## TABLES 视图
+
+| 字段名 | 类型 | 说明 |
+|---|---|---|
+| TABLE_CATALOG | STRING | 所属 WORKSPACE 名称 |
+| TABLE_CATALOG_ID | STRING | WORKSPACE ID |
+| TABLE_SCHEMA | STRING | 所属 Schema |
+| TABLE_SCHEMA_ID | STRING | Schema ID |
+| TABLE_NAME | STRING | 表名 |
+| TABLE_ID | STRING | 表 ID |
+| TABLE_CREATOR | STRING | 表所有者 |
+| TABLE_CREATOR_ID | STRING | 表创建者 ID |
+| TABLE_TYPE | STRING | EXTERNAL TABLE / VIRTUAL_VIEW / MATERIALIZED VIEW / MANAGED_TABLE |
+| ROW_COUNT | BIGINT | 行数（估计值） |
+| BYTES | BIGINT | 存储大小（估计值） |
+| CREATE_TIME | TIMESTAMP | 创建时间 |
+| LAST_MODIFY_TIME | TIMESTAMP | 修改时间 |
+| DATA_LIFECYCLE | BIGINT | 生命周期（天），NULL 表示永久 |
+| IS_PARTITIONED | BOOLEAN | 是否分区表 |
+| IS_CLUSTERED | BOOLEAN | 是否分桶表 |
+| COMMENT | STRING | 表注释 |
+| DELETE_TIME | TIMESTAMP | 删除时间（NULL 表示未删除） |
+| PROPERTIES | MAP\<STRING,STRING> | 自定义属性 |
+
+---
+
+## COLUMNS 视图
+
+| 字段名 | 类型 | 说明 |
+|---|---|---|
+| TABLE_CATALOG | STRING | 所属 WORKSPACE 名称 |
+| TABLE_CATALOG_ID | STRING | WORKSPACE ID |
+| TABLE_SCHEMA | STRING | 所属 Schema |
+| TABLE_SCHEMA_ID | STRING | Schema ID |
+| TABLE_NAME | STRING | 表名 |
+| TABLE_ID | STRING | 表 ID |
+| COLUMN_NAME | STRING | 字段名 |
+| COLUMN_ID | STRING | 字段 ID |
+| COLUMN_DEFAULT | STRING | 字段默认值（保留值） |
+| IS_NULLABLE | BOOLEAN | 是否可为 NULL |
+| DATA_TYPE | STRING | 字段类型 |
+| IS_PARTITIONING_COLUMN | BOOLEAN | 是否分区字段 |
+| IS_CLUSTERING_COLUMN | BOOLEAN | 是否 CLUSTER 字段 |
+| IS_PRIMARY_KEY | BOOLEAN | 是否主键 |
+| COMMENT | STRING | 字段注释 |
+| DELETE_TIME | TIMESTAMP | 删除时间（NULL 表示未删除） |
+
+---
+
+## VIEWS 视图
+
+| 字段名 | 类型 | 说明 |
+|---|---|---|
+| TABLE_CATALOG | STRING | 所属 WORKSPACE 名称 |
+| TABLE_CATALOG_ID | STRING | WORKSPACE ID |
+| TABLE_SCHEMA | STRING | 所属 Schema |
+| TABLE_SCHEMA_ID | STRING | Schema ID |
+| TABLE_NAME | STRING | 视图名 |
+| TABLE_ID | STRING | 视图 ID |
+| TABLE_CREATOR | STRING | 视图所有者账号名称 |
+| TABLE_CREATOR_ID | STRING | 视图所有者账号 ID |
+| VIEW_DEFINITION | STRING | 创建视图的 SQL 语句 |
+| CREATE_TIME | TIMESTAMP | 创建时间 |
+| LAST_MODIFY_TIME | TIMESTAMP | 修改时间 |
+| COMMENT | STRING | 视图注释 |
+| DELETE_TIME | TIMESTAMP | 删除时间（NULL 表示未删除） |
+
+---
+
+## USERS 视图
+
+| 字段名 | 类型 | 说明 |
+|---|---|---|
+| WORKSPACE_NAME | STRING | 所在工作空间 |
+| WORKSPACE_ID | STRING | 空间 ID |
+| USER_ID | STRING | 系统生成的用户 ID |
+| USER_NAME | STRING | 用户名（WORKSPACE_NAME + USER_NAME 拼接） |
+| ROLE_NAME | STRING | 拥有的角色（逗号分隔） |
+| ADD_TIME | TIMESTAMP | 用户创建时间 |
+| EMAIL | STRING | 用户邮箱 |
+| TELEPHONE | STRING | 用户电话 |
+| LAST_SUCCESS_LOGIN | TIMESTAMP | 上次登录时间 |
+| COMMENT | STRING | 描述信息 |
+| DELETE_TIME | TIMESTAMP | 删除时间（NULL 表示未删除） |
+| PROPERTIES | MAP\<STRING,STRING> | 自定义属性 |
+
+---
+
+## ROLES 视图
+
+| 字段名 | 类型 | 说明 |
+|---|---|---|
+| WORKSPACE_NAME | STRING | 所在工作空间 |
+| WORKSPACE_ID | STRING | 空间 ID |
+| ROLE_NAME | STRING | 角色名称 |
+| ROLE_ID | STRING | 角色 ID |
+| USER_NAME | STRING | 被授予该角色的用户（逗号分隔） |
+| USER_ID | STRING | 被授予该角色的用户 ID |
+| COMMENT | STRING | 描述信息 |
+| DELETE_TIME | TIMESTAMP | 删除时间（NULL 表示未删除） |
+
+---
+
+## JOB_HISTORY 视图
+
+| 字段名 | 类型 | 说明 |
+|---|---|---|
+| WORKSPACE_NAME | STRING | 作业所在空间 |
+| WORKSPACE_ID | STRING | 空间 ID |
+| JOB_ID | STRING | 作业 ID |
+| JOB_NAME | STRING | 作业名称 |
+| JOB_CREATOR_ID | STRING | 执行用户 ID |
+| JOB_CREATOR | STRING | 执行用户 |
+| STATUS | STRING | SETUP / RESUMING_CLUSTER / QUEUED / RUNNING / SUCCESS / FAILED / CANCELED |
+| CRU | DECIMAL(38,5) | 消耗的计算资源 |
+| ERROR_MESSAGE | STRING | 错误信息 |
+| JOB_TYPE | STRING | 作业类型：SQL |
+| JOB_TEXT | STRING | 执行的 SQL 语句 |
+| START_TIME | TIMESTAMP | 开始时间 |
+| END_TIME | TIMESTAMP | 结束时间 |
+| EXECUTION_TIME | DOUBLE | 执行时间（秒） |
+| INPUT_BYTES | BIGINT | 实际扫描数据量 |
+| CACHE_HIT | BIGINT | 从缓存读取的数据量 |
+| OUTPUT_BYTES | BIGINT | 输出字节数 |
+| INPUT_OBJECTS | STRING | 输入表名（格式：[SCHEMA].[TABLE]，多个逗号分隔） |
+| OUTPUT_OBJECTS | STRING | 输出表名 |
+| CLIENT_INFO | STRING | 客户端信息（JDBC/SDK/Web/Java SDK） |
+| VIRTUAL_CLUSTER | STRING | 使用的计算集群 |
+| VIRTUAL_CLUSTER_ID | BIGINT | 计算集群 ID |
+| ROWS_PRODUCED | BIGINT | 处理的总记录数 |
+| ROWS_INSERTED | BIGINT | 插入行数 |
+| ROWS_UPDATED | BIGINT | 更新行数 |
+| ROWS_DELETED | BIGINT | 删除行数 |
+| JOB_CONFIG | STRING | 提交时的参数信息 |
+| JOB_PRIORITY | STRING | 作业优先级 |
+| INPUT_TABLES | STRING | 输入表（JSON 格式数组） |
+| OUTPUT_TABLES | STRING | 输出对象名称 |
+| QUERY_TAG | STRING | 用户设置的 TAG |
+
+---
+
+## MATERIALIZED_VIEW_REFRESH_HISTORY 视图
+
+| 字段名 | 类型 | 说明 |
+|---|---|---|
+| WORKSPACE_ID | BIGINT | 空间 ID |
+| WORKSPACE_NAME | STRING | 空间名称 |
+| SCHEMA_ID | BIGINT | Schema ID |
+| SCHEMA_NAME | STRING | Schema 名称 |
+| MATERIALIZED_VIEW_ID | BIGINT | 物化视图 ID |
+| MATERIALIZED_VIEW_NAME | STRING | 物化视图名称 |
+| CREDITS_USED | DECIMAL | 刷新消耗的计费 |
+| VIRTUAL_CLUSTER_ID | BIGINT | 虚拟集群 ID |
+| VIRTUAL_CLUSTER | STRING | 虚拟集群名称（自动刷新时有值） |
+| STATUS | STRING | PENDING / RUNNING / FINISHED / FAILED |
+| REFRESH_MODE | STRING | INCREMENTAL / FULL_REFRESH / NO_DATA |
+| STATISTICS | STRING | 增量刷新的记录数 |
+| SCHEDULE_START_TIME | TIMESTAMP_LTZ | 计划刷新时间 |
+| START_TIME | TIMESTAMP_LTZ | 实际开始时间 |
+| END_TIME | TIMESTAMP_LTZ | 结束时间 |
+| ERROR_MESSAGE | STRING | 刷新失败信息 |
+
+---
+
+## VOLUMES 视图
+
+| 字段名 | 类型 | 说明 |
+|---|---|---|
+| VOLUME_CATALOG | STRING | 所属 Workspace 名称 |
+| VOLUME_CATALOG_ID | STRING | 所属 Workspace ID |
+| VOLUME_SCHEMA | STRING | 所属 Schema 名称 |
+| VOLUME_SCHEMA_ID | STRING | Schema ID |
+| VOLUME_NAME | STRING | Volume 名称 |
+| VOLUME_ID | STRING | Volume ID |
+| VOLUME_URL | STRING | Volume 绑定的 URL |
+| VOLUME_REGION | STRING | Volume 所属区域 |
+| VOLUME_TYPE | STRING | INTERNAL / EXTERNAL |
+| VOLUME_CREATOR | STRING | Volume 的 owner |
+| CONNECTION_NAME | STRING | 引用的 Connection 名称 |
+| CONNECTION_ID | STRING | 引用的 Connection ID |
+| PROPERTIES | MAP\<STRING,STRING> | 保留字段 |
+| COMMENT | STRING | 注释 |
+| CREATE_TIME | TIMESTAMP | 创建时间 |
+| LAST_MODIFY_TIME | TIMESTAMP | 修改时间 |
+
+---
+
+## CONNECTIONS 视图
+
+| 字段名 | 类型 | 说明 |
+|---|---|---|
+| WORKSPACE_NAME | STRING | 所在空间 |
+| WORKSPACE_ID | STRING | 空间 ID |
+| CONNECTION_NAME | STRING | 连接对象名称 |
+| CONNECTION_ID | STRING | 连接 ID |
+| CONNECTION_KIND | STRING | STORAGE CONNECTION / API CONNECTION |
+| TYPE | STRING | FILE_SYSTEM / CLOUD_FUNCTION |
+| PROVIDER | STRING | FILE_SYSTEM 时：OSS / COS；CLOUD_FUNCTION 时：aliyun / tencent |
+| REGION | STRING | 连接的 region（如 ap-shanghai / cn-beijing） |
+| SOURCE_CREATOR | STRING | 创建者 |
+| CREATED_TIME | TIMESTAMP | 创建时间 |
+| COMMENT | STRING | 注释 |
+| PROPERTIES | MAP\<STRING,STRING> | 保留字段 |
+
+---
+
+## OBJECT_PRIVILEGES 视图
+
+| 字段名 | 类型 | 说明 |
+|---|---|---|
+| GRANTOR | TEXT | 授出权限的用户 |
+| GRANTEE | TEXT | 被授予权限的 user_name 或 role_name |
+| GRANTED_TO | TEXT | USER / ROLE |
+| OBJECT_CATALOG | TEXT | 被授予对象所在的工作空间或 catalog 名称 |
+| OBJECT_SCHEMA | TEXT | 被授予对象所在的 Schema（对象不在 Schema 下则为空） |
+| OBJECT_NAME | TEXT | 被授权的对象名称 |
+| OBJECT_TYPE | TEXT | 被授权对象的类型 |
+| SUB_OBJECT_TYPE | TEXT | 子对象类型 |
+| PRIVILEGE_TYPE | TEXT | 被授予的具体权限 |
+| IS_GRANTABLE | TEXT | 授权时是否有 WITH GRANT OPTION |
+| AUTHORIZATION_TIME | TIMESTAMP_LTZ | 权限授予时间 |

package/bin/skills/clickzetta-metadata/references/metering-views-reference.md

@@ -0,0 +1,137 @@
+# 费用计量视图字段说明
+
+> 已通过实际 Lakehouse 连接验证（cn-shanghai-alicloud, f8866243）
+> 访问路径：`SYS.information_schema.<视图名>`
+> 权限要求：INSTANCE ADMIN
+
+---
+
+## STORAGE_METERING 视图
+
+存储费用明细，按天、按工作空间、按 SKU 记录存储计量数据。
+
+实际字段（16列）：
+
+| 字段名 | 类型 | 说明 |
+|---|---|---|
+| ACCOUNT_ID | BIGINT | 账户 ID |
+| ACCOUNT_NAME | STRING | 账户名称 |
+| INSTANCE_ID | BIGINT | 实例 ID |
+| REGION_NAME | STRING | 地域名称（如 阿里云-华东2（上海）） |
+| SKU_CATEGORY | STRING | 费用类别：`storage` / `network` |
+| SKU_NAME | STRING | 具体 SKU 名称（见下表） |
+| WORKSPACE_ID | BIGINT | 工作空间 ID |
+| WORKSPACE_NAME | STRING | 工作空间名称 |
+| MEASUREMENT_START | TIMESTAMP | 计量周期开始时间（通常为某天 00:00:00） |
+| MEASUREMENT_END | TIMESTAMP | 计量周期结束时间（通常为某天 23:59:59） |
+| MEASUREMENTS_UNIT | STRING | 计量单位（如 `yuan/GB/day`、`yuan/gb`、`none`） |
+| MEASUREMENTS_CONSUMPTION | DECIMAL | 消耗量（单位由 MEASUREMENTS_UNIT 决定） |
+| PRICE_RATE | DECIMAL | 单价 |
+| AMOUNT | DECIMAL | 费用金额（元） |
+| DISCOUNT_RATE | DECIMAL | 折扣率（1.0 = 无折扣） |
+| TOTAL_AFTER_DISCOUNT | DECIMAL | 折后金额（元） |
+
+### SKU 枚举值
+
+| SKU_CATEGORY | SKU_NAME | MEASUREMENTS_UNIT | 说明 |
+|---|---|---|---|
+| storage | 托管存储容量 | yuan/GB/day | 内部表数据文件存储 |
+| storage | 多版本未删除存储 | none | Time Travel 历史版本存储 |
+| network | 数据查询Internet数据传输 | yuan/gb | 公网数据传输 |
+
+---
+
+## INSTANCE_USAGE 视图
+
+计算费用明细，按天、按工作空间、按 SKU 记录计算资源使用数据。
+
+实际字段（16列，与 STORAGE_METERING 相同结构）：
+
+| 字段名 | 类型 | 说明 |
+|---|---|---|
+| ACCOUNT_ID | BIGINT | 账户 ID |
+| ACCOUNT_NAME | STRING | 账户名称 |
+| INSTANCE_ID | BIGINT | 实例 ID |
+| REGION_NAME | STRING | 地域名称 |
+| SKU_CATEGORY | STRING | 费用类别：`compute` |
+| SKU_NAME | STRING | 具体 SKU 名称（见下表） |
+| WORKSPACE_ID | BIGINT | 工作空间 ID |
+| WORKSPACE_NAME | STRING | 工作空间名称 |
+| MEASUREMENT_START | TIMESTAMP | 计量周期开始时间 |
+| MEASUREMENT_END | TIMESTAMP | 计量周期结束时间 |
+| MEASUREMENTS_UNIT | STRING | 计量单位（`yuan/cru`） |
+| MEASUREMENTS_CONSUMPTION | DECIMAL | 消耗的 CRU 量 |
+| PRICE_RATE | DECIMAL | 单价（元/CRU） |
+| AMOUNT | DECIMAL | 费用金额（元） |
+| DISCOUNT_RATE | DECIMAL | 折扣率 |
+| TOTAL_AFTER_DISCOUNT | DECIMAL | 折后金额（元） |
+
+### SKU 枚举值
+
+| SKU_CATEGORY | SKU_NAME | 说明 |
+|---|---|---|
+| compute | AP类型计算集群 | 分析型 VCluster 费用 |
+| compute | GP类型计算集群 | 通用型 VCluster 费用 |
+| compute | 任务调度 | Studio 任务调度费用 |
+| compute | 数据集成 | 离线/实时同步任务费用 |
+| compute | 流式集成 | 流式数据集成费用 |
+
+---
+
+## 常用费用查询
+
+```sql
+-- 本月各工作空间计算费用汇总
+SELECT workspace_name,
+       sku_name,
+       ROUND(SUM(measurements_consumption), 2) AS total_cru,
+       ROUND(SUM(amount), 2) AS total_yuan
+FROM SYS.information_schema.instance_usage
+WHERE measurement_start >= DATE_TRUNC('month', CURRENT_DATE)
+GROUP BY workspace_name, sku_name
+ORDER BY total_yuan DESC;
+
+-- 本月各工作空间存储费用汇总
+SELECT workspace_name,
+       sku_name,
+       ROUND(SUM(measurements_consumption), 4) AS consumption,
+       measurements_unit,
+       ROUND(SUM(amount), 4) AS total_yuan
+FROM SYS.information_schema.storage_metering
+WHERE measurement_start >= DATE_TRUNC('month', CURRENT_DATE)
+GROUP BY workspace_name, sku_name, measurements_unit
+ORDER BY workspace_name, total_yuan DESC;
+
+-- 按天统计计算费用趋势（最近 30 天）
+SELECT DATE(measurement_start) AS dt,
+       sku_name,
+       ROUND(SUM(amount), 2) AS daily_yuan
+FROM SYS.information_schema.instance_usage
+WHERE measurement_start >= CURRENT_DATE - INTERVAL 30 DAY
+GROUP BY DATE(measurement_start), sku_name
+ORDER BY dt, daily_yuan DESC;
+
+-- 存储 + 计算综合费用（本月）
+SELECT cost_type, workspace_name,
+       ROUND(SUM(amount), 2) AS total_yuan
+FROM (
+  SELECT 'compute' AS cost_type, workspace_name, amount
+  FROM SYS.information_schema.instance_usage
+  WHERE measurement_start >= DATE_TRUNC('month', CURRENT_DATE)
+  UNION ALL
+  SELECT 'storage' AS cost_type, workspace_name, amount
+  FROM SYS.information_schema.storage_metering
+  WHERE measurement_start >= DATE_TRUNC('month', CURRENT_DATE)
+) t
+GROUP BY cost_type, workspace_name
+ORDER BY cost_type, total_yuan DESC;
+```
+
+---
+
+## 注意事项
+
+- 两个视图数据保留范围：从实例创建起至今（验证数据最早可追溯到 2025-01）
+- `WORKSPACE_NAME` 可能为 NULL（对应实例级别的费用，不归属特定工作空间）
+- `AMOUNT` 字段为实际计费金额（元），`TOTAL_AFTER_DISCOUNT` 为折后金额
+- 与 `JOB_HISTORY.CRU` 的区别：JOB_HISTORY 记录单次作业的 CRU 消耗，INSTANCE_USAGE 是按天汇总的计费数据，含金额