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

package/bin/skills/clickzetta-metadata-query/SKILL.md

@@ -0,0 +1,298 @@
+---
+name: clickzetta-metadata-query
+description: |
+  通过 SHOW / DESC 命令族和 load_history() 函数查询 ClickZetta Lakehouse 对象元数据。
+  覆盖所有 SHOW 命令（TABLES/SCHEMAS/CATALOGS/COLUMNS/VOLUMES/CONNECTIONS/JOBS/VCLUSTERS/
+  PIPES/SHARES/USERS/ROLES/GRANTS/FUNCTIONS/TABLE STREAMS/PARTITIONS/SYNONYMS/INDEX/
+  DYNAMIC TABLE REFRESH HISTORY/TABLES HISTORY），所有 DESC 命令（TABLE/SCHEMA/HISTORY/
+  VCLUSTER/VOLUME/CONNECTION/FUNCTION/VIEW/DYNAMIC TABLE/SHARE/INDEX/TABLE STREAM），
+  SHOW CREATE TABLE，load_history()，FROM (SHOW ...) 子查询，上下文函数。
+  与 information_schema 的区别：SHOW/DESC 是实时命令，返回当前状态；
+  information_schema 是元数据视图，有约 15 分钟延迟但支持复杂 SQL 分析。
+  当用户说"查看表列表"、"查看字段"、"查看作业"、"SHOW TABLES"、"DESC TABLE"、
+  "查看分区"、"查看历史版本"、"查看删除的表"、"查看导入历史"、"load_history"、
+  "SHOW JOBS"、"查看集群状态"、"查看连接"、"查看权限"、"SHOW GRANTS"、
+  "查看函数"、"查看 Volume"、"查看 Share"、"查看 Catalog"时触发。
+  Keywords: SHOW, DESC, DESCRIBE, metadata, load_history, object info
+---
+
+# ClickZetta 元数据查询命令
+
+阅读 [references/show-desc-reference.md](references/show-desc-reference.md) 了解完整语法和返回字段。
+
+---
+
+## SHOW / DESC 与 information_schema 的选择
+
+| 场景 | 推荐方式 | 原因 |
+|---|---|---|
+| 快速查看当前状态 | `SHOW` / `DESC` | 实时，无延迟 |
+| 复杂 SQL 分析、聚合统计 | `information_schema` | 支持 JOIN/GROUP BY/WHERE |
+| 查看已删除对象 | `SHOW TABLES HISTORY` | 专用命令 |
+| 费用分析 | `SYS.information_schema.instance_usage` | 含金额字段 |
+| 导入文件去重 | `load_history()` | 专用函数 |
+
+---
+
+## 当前上下文
+
+```sql
+-- 查看当前连接的工作空间、Schema、用户、集群
+SELECT current_workspace(), current_schema(), current_user(), current_vcluster();
+```
+
+---
+
+## SHOW 命令速查
+
+### 数据对象
+
+```sql
+-- Schema
+SHOW SCHEMAS;
+SHOW SCHEMAS EXTENDED;          -- 含 type 字段（managed/external）
+SHOW SCHEMAS LIKE 'ods%';
+-- SHOW SCHEMAS 支持 WHERE（如 WHERE schema_name LIKE '%xxx%'）
+
+-- 表（含视图/物化视图/动态表/外部表）
+SHOW TABLES;
+SHOW TABLES IN my_schema;
+SHOW TABLES LIKE '%order%';
+-- WHERE 支持字段：table_name / is_view / is_materialized_view / is_external / is_dynamic
+SHOW TABLES WHERE is_view = false AND is_materialized_view = false;  -- 普通表
+SHOW TABLES WHERE is_view = true;                                    -- 视图
+SHOW TABLES WHERE is_materialized_view = true;                       -- 物化视图
+SHOW TABLES WHERE is_dynamic = true;                                 -- 动态表
+SHOW TABLES WHERE is_external = true;                                -- 外部表
+-- ⚠️ SHOW VIEWS IN schema 语法不支持，用 SHOW TABLES WHERE is_view=true
+
+-- 字段
+SHOW COLUMNS IN my_schema.my_table;
+SHOW COLUMNS FROM my_table IN my_schema;
+
+-- 完整建表语句（表/视图/物化视图/动态表）
+SHOW CREATE TABLE my_table;
+
+-- 分区
+SHOW PARTITIONS my_table;
+SHOW PARTITIONS EXTENDED my_table;          -- 含 rows/bytes/files/时间戳
+SHOW PARTITIONS my_table PARTITION (dt = '2024-01');  -- 按分区值过滤
+-- ⚠️ SHOW PARTITIONS WHERE dt='x' 不支持，需用 PARTITION() 子句
+
+-- Volume（不支持 IN schema，用 WHERE 过滤）
+SHOW VOLUMES;
+SHOW VOLUMES LIKE '%oss%';
+SHOW VOLUMES WHERE schema_name = 'my_schema';
+
+-- Table Stream
+SHOW TABLE STREAMS;
+SHOW TABLE STREAMS IN my_schema;
+SHOW TABLE STREAMS LIKE '%orders%';
+
+-- 同义词
+SHOW SYNONYMS IN my_schema;
+
+-- 索引
+SHOW INDEX IN my_schema.my_table;
+
+-- 语义视图
+SHOW SEMANTIC VIEWS;
+SHOW SEMANTIC VIEWS IN my_schema;
+
+-- 函数
+SHOW FUNCTIONS LIKE '%date%';           -- 内置函数（按名称过滤）
+SHOW EXTERNAL FUNCTIONS;                -- 用户创建的外部函数
+-- ⚠️ 不支持 IN schema 子句，SHOW EXTERNAL FUNCTIONS IN my_schema 会报语法错误
+```
+
+### Catalog（联邦查询）
+
+```sql
+-- 查看所有 Catalog（含 SHARED 和 EXTERNAL 类型）
+SHOW CATALOGS;
+-- 返回：workspace_name, created_time, category(SHARED/EXTERNAL)
+
+-- 查看 Catalog 下的 Schema
+SHOW SCHEMAS IN catalog_name;
+
+-- 查看 Catalog.Schema 下的表
+SHOW TABLES IN catalog_name.schema_name;
+```
+
+### 计算与连接
+
+```sql
+-- 计算集群
+SHOW VCLUSTERS;
+SHOW VCLUSTERS WHERE state = 'RUNNING';
+SHOW VCLUSTERS WHERE vcluster_type = 'ANALYTICS';
+
+-- 作业（最近 7 天，最多 10000 条）
+SHOW JOBS LIMIT 20;
+SHOW JOBS IN VCLUSTER default_ap LIMIT 20;
+
+-- 动态表刷新历史（最近 7 天）
+SHOW DYNAMIC TABLE REFRESH HISTORY LIMIT 20;
+SHOW DYNAMIC TABLE REFRESH HISTORY WHERE state = 'FAILED';
+
+-- 连接对象
+SHOW CONNECTIONS;
+SHOW CONNECTIONS LIKE '%oss%';
+SHOW CONNECTIONS WHERE category = 'STORAGE';
+
+-- Pipe
+SHOW PIPES;
+SHOW PIPES IN my_schema;
+```
+
+### 用户、权限与共享
+
+```sql
+-- 用户
+SHOW USERS;
+
+-- 角色
+SHOW ROLES;
+
+-- 权限
+SHOW GRANTS TO USER alice;
+SHOW GRANTS TO ROLE analyst_role;
+
+-- 数据共享
+SHOW SHARES;
+-- 返回：share_name, provider, provider_instance, provider_workspace, scope, to_instance, kind(OUTBOUND/INBOUND)
+```
+
+### 历史记录
+
+```sql
+-- 表历史（含已删除表，delete_time 为 NULL 表示未删除）
+-- 返回字段说明：
+--   delete_time：删除时间，NULL 表示表仍存在
+--   retention_time：Time Travel 保留期（秒），保留期内可用 UNDROP 恢复或 AS OF 查询历史数据
+SHOW TABLES HISTORY;
+SHOW TABLES HISTORY IN my_schema;
+SHOW TABLES HISTORY LIKE '%temp%';
+```
+
+---
+
+## DESC 命令速查
+
+```sql
+-- 表/视图/动态表/物化视图字段
+DESC my_table;
+DESC EXTENDED my_table;          -- 含 last_modified_time/properties/statistics
+
+-- Schema
+DESC SCHEMA my_schema;
+DESC SCHEMA EXTENDED my_schema;  -- 含 creator/created_time/type
+
+-- 计算集群
+DESC VCLUSTER default_ap;
+DESC VCLUSTER EXTENDED default_ap;
+
+-- Volume
+DESC VOLUME my_volume;
+DESC VOLUME EXTENDED my_volume;
+
+-- 连接对象
+DESC CONNECTION my_oss_conn;
+DESC CONNECTION EXTENDED my_oss_conn;
+
+-- 外部函数（仅支持用户创建的外部函数，不支持内置函数）
+DESC FUNCTION my_schema.my_function;
+
+-- 视图（返回字段列表）
+DESC VIEW my_view;
+
+-- 动态表（返回字段 + 调度配置）
+DESC TABLE my_dt;
+
+-- 索引
+DESC INDEX idx_name;
+
+-- Table Stream
+DESC TABLE STREAM my_stream;
+
+-- Share（返回共享的对象列表）
+DESC SHARE my_share_name;
+-- 返回：kind(WORKSPACE/SCHEMA/TABLE), name, shared_on
+
+-- Catalog
+DESC CATALOG my_catalog;
+```
+
+---
+
+## DESC HISTORY — 查看版本历史
+
+```sql
+-- 表/动态表/物化视图的版本历史（依赖 data_retention_days）
+DESC HISTORY my_table;
+-- 返回：version, time, total_rows, total_bytes, user, operation, job_id, stats
+-- operation 值：INSERT_INTO / UPDATE / DELETE / ALTER / CREATE / REFRESH 等
+```
+
+---
+
+## load_history() — 查看文件导入历史
+
+```sql
+-- 参数必须是带引号的字符串（含 schema 前缀）
+SELECT * FROM load_history('my_schema.my_table');
+SELECT file_path, last_copy_time, file_size, status, first_error_message
+FROM load_history('my_schema.my_table')
+ORDER BY last_copy_time DESC
+LIMIT 20;
+-- ⚠️ load_history(schema.table) 不带引号会报错
+```
+
+---
+
+## FROM (SHOW ...) 子查询 — 重要特性
+
+SHOW 命令结果可以直接作为子查询使用，支持 WHERE/GROUP BY/JOIN 等操作：
+
+```sql
+-- 过滤 SHOW 结果
+SELECT schema_name, table_name
+FROM (SHOW TABLES IN my_schema)
+WHERE is_view = false;
+
+-- 统计各类型表数量
+SELECT
+  CASE WHEN is_view THEN 'VIEW'
+       WHEN is_materialized_view THEN 'MV'
+       WHEN is_dynamic THEN 'DT'
+       WHEN is_external THEN 'EXTERNAL'
+       ELSE 'TABLE' END AS type,
+  COUNT(*) AS cnt
+FROM (SHOW TABLES IN my_schema)
+GROUP BY 1;
+
+-- 查看挂起的集群
+SELECT name, state FROM (SHOW VCLUSTERS) WHERE state = 'SUSPENDED';
+
+-- 结合 information_schema 深度分析
+SELECT t.table_name, t.is_dynamic, i.create_time, i.row_count
+FROM (SHOW TABLES WHERE is_dynamic = true) t
+LEFT JOIN information_schema.tables i
+  ON t.table_name = i.table_name AND t.schema_name = i.table_schema;
+```
+
+**注意**：不支持创建包含 SHOW 命令的视图（`CREATE VIEW AS SELECT * FROM (SHOW TABLES)` 会失败）。
+
+---
+
+## 注意事项
+
+1. **`SHOW SCHEMAS WHERE`**：不支持，需用 `SHOW SCHEMAS EXTENDED` 后应用层过滤
+2. **`SHOW VIEWS IN schema`**：语法报错，用 `SHOW TABLES WHERE is_view=true`
+3. **`SHOW VOLUMES IN schema`**：语法报错，用 `SHOW VOLUMES WHERE schema_name='x'`
+4. **`SHOW PARTITIONS WHERE col='x'`**：不支持按分区列名过滤，用 `PARTITION(col='x')` 子句
+5. **`load_history()` 语法**：参数必须是带引号的字符串 `'schema.table'`
+6. **`DESC FUNCTION`**：仅支持用户创建的外部函数，不支持内置函数
+7. **`SHOW JOBS`**：只显示最近 7 天，最多 10000 条；**不支持 ORDER BY 子句**，需用 LIMIT 控制返回量
+8. **`SHOW DYNAMIC TABLE REFRESH HISTORY`**：只显示最近 7 天，最多 10000 条
+9. **`LIKE` 和 `WHERE` 不能同时用**：用 `FROM (SHOW TABLES) WHERE table_name LIKE 'x%'` 替代

package/bin/skills/clickzetta-metadata-query/references/show-desc-reference.md

@@ -0,0 +1,326 @@
+# SHOW / DESC 命令完整语法参考
+
+> 已通过实际 Lakehouse 连接验证（cn-shanghai-alicloud, f8866243, quick_start）
+
+---
+
+## SHOW 命令通用语法
+
+```sql
+SHOW <object_type_plural>
+[ IN <scope> ]
+[ LIKE '<pattern>' | WHERE <expression> ]
+[ LIMIT <num> ]
+```
+
+### 作用域（IN）对应关系
+
+| 对象类型 | IN 作用域 | 示例 |
+|---|---|---|
+| TABLE / VIEW / SYNONYM / TABLE STREAM / PIPE | `IN schema_name` | `SHOW TABLES IN sales` |
+| SCHEMA / VCLUSTER / USERS / ROLES / PIPES | `IN workspace_name` | `SHOW SCHEMAS IN my_ws` |
+| 作业 | `IN VCLUSTER vc_name`（可选） | `SHOW JOBS IN VCLUSTER prod` |
+| 索引 / 列 | `IN table_name` 或 `FROM table_name` | `SHOW COLUMNS IN orders` |
+| 分区 | 不支持 IN，直接跟表名 | `SHOW PARTITIONS my_table` |
+| VOLUME | 不支持 IN，用 WHERE external/connection 过滤 | `SHOW VOLUMES WHERE external=true` |
+| CONNECTION / SHARE / FUNCTION / CATALOG | 不支持作用域限定 | `SHOW CONNECTIONS` |
+
+### WHERE 支持的对象和字段（实测验证）
+
+| 对象 | LIKE | WHERE | 可过滤字段 |
+|---|---|---|---|
+| TABLE | ✅ | ✅ | `table_name`, `is_view`, `is_materialized_view`, `is_external`, `is_dynamic` |
+| TABLE STREAM | ✅ | ✅ | `create_time`, `name`, `table_name`, `mode`, `comment` |
+| CONNECTION | ✅ | ✅ | `name`, `category`, `type`, `enabled`, `created_time` |
+| VCLUSTER | ✅ | ✅ | `name`, `vcluster_type`, `state`, `creator`, `create_time`, `running_jobs`, `queued_jobs` 等 |
+| VOLUME | ✅ | ✅ | `external`（true/false）, `connection` — ⚠️ 不支持 `schema_name` 过滤 |
+| JOB | ❌ | ✅ | `status`, `creator`, `priority`, `vcluster_name`, `job_id`, `start_time`, `end_time` |
+| SHARE | ✅ | ✅ | `share_name`, `provider`, `provider_instance`, `scope`, `kind` |
+| SYNONYM | ✅ | ✅ | `synonym_name`, `create_time`, `target_type`, `target_name` |
+| PIPE | ✅ | ✅ | `pipe_name`, `pipe_kind`, `status`, `copy_statement` |
+| SCHEMA | ✅ | ✅ | `schema_name` — ⚠️ `type` 字段不存在 |
+| TABLE_HISTORY | ❌ | ✅ | `table_name` |
+| CATALOG | ✅ | ✅ | `category` |
+| ROLE | ✅ | ❌ | — |
+| USER | ❌ | ❌ | — |
+| FUNCTION | ❌ | ❌ | `SHOW FUNCTIONS` 不支持 LIKE/WHERE；用 `SHOW EXTERNAL FUNCTIONS LIKE '%xxx%'` 查用户自定义函数 |
+| GRANT | ❌ | ❌ | 用 `SHOW GRANTS ON/TO` 语法代替；⚠️ 不支持 LIMIT |
+
+---
+
+## SHOW TABLES 返回字段
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| schema_name | STRING | 所属 Schema |
+| table_name | STRING | 对象名称 |
+| is_view | BOOLEAN | 是否为视图 |
+| is_materialized_view | BOOLEAN | 是否为物化视图 |
+| is_external | BOOLEAN | 是否为外部表 |
+| is_dynamic | BOOLEAN | 是否为动态表 |
+
+常用过滤示例：
+
+```sql
+-- 列出指定 Schema 下所有 Dynamic Table（最常用）
+SHOW TABLES IN my_schema WHERE is_dynamic;
+
+-- 列出当前 Schema 下所有 Dynamic Table
+SHOW TABLES WHERE is_dynamic;
+
+-- 其他类型过滤
+SHOW TABLES WHERE is_view = true;
+SHOW TABLES WHERE is_materialized_view = true;
+SHOW TABLES WHERE is_external = true;
+SHOW TABLES WHERE is_view = false AND is_materialized_view = false;  -- 普通表
+```
+
+**注意**：`SHOW VIEWS IN schema` 语法不支持，需用 `SHOW TABLES WHERE is_view=true`
+
+---
+
+## SHOW CATALOGS 返回字段
+
+| 字段 | 说明 |
+|---|---|
+| workspace_name | Catalog 名称 |
+| created_time | 创建时间 |
+| category | SHARED（共享 Catalog）/ EXTERNAL（外部 Catalog） |
+
+---
+
+## SHOW VOLUMES 返回字段
+
+| 字段 | 说明 |
+|---|---|
+| schema_name | 所属 Schema |
+| volume_name | Volume 名称 |
+| create_time | 创建时间 |
+| external | 是否为外部 Volume（BOOLEAN） |
+| workspace_name | 所属工作空间 |
+| url | 绑定的存储路径 |
+| recursive_file_lookup | 是否递归扫描 |
+| connection | 引用的 Connection 名称 |
+
+**注意**：`SHOW VOLUMES IN schema` 语法不支持；`WHERE schema_name='x'` 也不支持 — 只能用 `WHERE external=true/false` 或 `WHERE connection='xxx'` 过滤
+
+---
+
+## SHOW SHARES 返回字段
+
+| 字段 | 说明 |
+|---|---|
+| share_name | Share 名称 |
+| provider | 提供方账户名 |
+| provider_instance | 提供方实例 ID |
+| provider_workspace | 提供方工作空间 |
+| scope | PRIVATE / PUBLIC |
+| to_instance | 消费方实例（逗号分隔） |
+| kind | OUTBOUND（对外共享）/ INBOUND（接收共享） |
+
+---
+
+## SHOW TABLES HISTORY 返回字段
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| schema_name | STRING | 所属 Schema |
+| table_name | STRING | 表名 |
+| create_time | TIMESTAMP | 创建时间 |
+| creator | STRING | 创建者 |
+| rows | BIGINT | 行数 |
+| bytes | BIGINT | 大小 |
+| comment | STRING | 注释 |
+| retention_time | INT | 数据保留天数 |
+| delete_time | TIMESTAMP | 删除时间（NULL 表示未删除） |
+
+---
+
+## SHOW PARTITIONS EXTENDED 返回字段
+
+| 字段 | 说明 |
+|---|---|
+| partitions | 分区值（如 `dt=2024-01`） |
+| total_rows | 分区行数 |
+| bytes | 分区大小 |
+| total_files | 文件数 |
+| created_time | 分区创建时间 |
+| last_modified_time | 最后修改时间（生命周期从此起算） |
+| last_data_time | 最后数据写入时间 |
+| last_compaction_time | 最后 compaction 时间 |
+
+**注意**：`SHOW PARTITIONS WHERE dt='2024-01'` 不支持，需用 `SHOW PARTITIONS my_table PARTITION(dt='2024-01')`
+
+---
+
+## SHOW JOBS 返回字段
+
+| 字段 | 说明 |
+|---|---|
+| job_id | 作业 ID |
+| status | SETUP / SUCCEED / FAILED / CANCELLED |
+| creator | 提交用户 |
+| priority | 优先级 |
+| start_time | 开始时间 |
+| end_time | 结束时间 |
+| execution_time | 执行时长（INTERVAL 类型） |
+| vcluster_name | 使用的集群 |
+| job_text | SQL 语句 |
+| query_tag | 用户标签 |
+
+---
+
+## SHOW FUNCTIONS / SHOW EXTERNAL FUNCTIONS 返回字段
+
+| 字段 | 说明 |
+|---|---|
+| name | 函数名称（注意：列名是 `name`，不是 `function_name`） |
+| type | 函数类型 |
+
+> `SHOW FUNCTIONS` 列出所有内置函数和用户自定义函数，不支持 LIKE/WHERE。
+> `SHOW EXTERNAL FUNCTIONS` 只列用户创建的外部函数，支持 `LIKE '%pattern%'`。
+
+---
+
+## SHOW DYNAMIC TABLE REFRESH HISTORY 返回字段
+
+```sql
+-- 全局（所有动态表，最近 7 天）
+SHOW DYNAMIC TABLE REFRESH HISTORY LIMIT 20;
+SHOW DYNAMIC TABLE REFRESH HISTORY WHERE state = 'FAILED';
+
+-- 指定表
+SHOW DYNAMIC TABLE REFRESH HISTORY WHERE name = 'my_dt' LIMIT 10;
+SHOW DYNAMIC TABLE REFRESH HISTORY WHERE name = 'my_dt' AND state = 'SUCCEED' LIMIT 20;
+```
+
+| 字段 | 说明 |
+|---|---|
+| workspace_name | 工作空间 |
+| schema_name | Schema |
+| name | 动态表名 |
+| virtual_cluster | 使用集群 |
+| start_time / end_time | 刷新时间 |
+| duration | 耗时（INTERVAL） |
+| state | SUCCEED / FAILED / RUNNING |
+| refresh_trigger | MANUAL / SYSTEM_SCHEDULED |
+| refresh_mode | NO_DATA / FULL / INCREMENTAL |
+| error_message | 失败信息 |
+| source_tables | 基表信息 |
+| stats | 增量刷新条数 |
+
+---
+
+## SHOW CONNECTIONS 返回字段
+
+| 字段 | 说明 |
+|---|---|
+| name | 连接名称（注意：列名是 `name`，不是 `connection_name`） |
+| category | STORAGE / API / CATALOG |
+| type | OSS / COS / S3 / KAFKA / CLOUD_FUNCTION / DATABRICKS_UNITY_CATALOG 等 |
+| enabled | ENABLED / DISABLED |
+| created_time | 创建时间 |
+
+---
+
+## DESC 命令支持的对象类型
+
+| 对象类型 | 语法 | EXTENDED 支持 | 说明 |
+|---|---|---|---|
+| table/view/dynamic_table/materialized_view/external_table | `DESC TABLE [EXTENDED] name` | ✅ | 所有表类型统一用 DESC TABLE |
+| semantic_view | `DESC EXTENDED name` | — | 返回维度/指标/逻辑表定义 |
+| schema | `DESC SCHEMA [EXTENDED] name` | ✅ | EXTENDED 返回创建者、时间、权限等 |
+| vcluster | `DESC VCLUSTER name` | ❌ | — |
+| connection | `DESC CONNECTION [EXTENDED] name` | ✅ | EXTENDED 返回完整属性 |
+| catalog | `DESC CATALOG name` | ❌ | — |
+| stream/table_stream | `DESC TABLE STREAM name` | ❌ | — |
+| job | `DESC JOB job_id` | ❌ | object_name 为 job_id |
+| share | `DESC SHARE name` | ❌ | 返回 share 中包含的对象 |
+| index | `DESC INDEX [EXTENDED] name` | ✅ | — |
+| function/external_function | `DESC FUNCTION [EXTENDED] name` | ✅ | 仅支持用户创建的函数 |
+| volume | `DESC VOLUME name` | ❌ | — |
+| pipe | `DESC PIPE name` | ❌ | — |
+
+> ⚠️ `DESC FUNCTION` 不支持内置函数（如 `year`、`count`），只支持用户创建的外部函数。
+
+---
+
+## DESC HISTORY 返回字段
+
+| 字段 | 说明 |
+|---|---|
+| version | 版本号 |
+| time | 操作时间 |
+| total_rows | 该版本行数 |
+| total_bytes | 该版本大小 |
+| user | 操作用户 |
+| operation | INSERT_INTO / UPDATE / DELETE / ALTER / CREATE / REFRESH 等 |
+| job_id | 对应作业 ID |
+| stats | 增量刷新统计（动态表专有） |
+| source_tables | 基表信息（动态表专有） |
+
+---
+
+## load_history() 语法
+
+```sql
+-- 正确：参数为带引号的字符串
+SELECT * FROM load_history('schema_name.table_name');
+SELECT * FROM load_history('schema_name.table_name') LIMIT 100;
+
+-- 错误：不能用裸表名
+-- SELECT * FROM load_history(schema.table);  ❌
+-- SELECT * FROM load_history(TABLE schema.table);  ❌
+```
+
+返回字段：`file_path`, `last_copy_time`, `file_size`, `status`, `first_error_message`
+
+保留时间：7 天
+
+---
+
+## FROM (SHOW ...) 子查询
+
+大多数 SHOW 命令支持作为子查询使用，可实现排序、过滤、JOIN 等操作：
+
+```sql
+-- ✅ 支持子查询的 SHOW 命令
+SELECT * FROM (SHOW TABLES) WHERE is_view = false ORDER BY table_name;
+SELECT * FROM (SHOW SCHEMAS) WHERE schema_name LIKE 'mcp%';
+SELECT * FROM (SHOW VCLUSTERS) WHERE state = 'RUNNING' ORDER BY name;
+SELECT * FROM (SHOW USERS);
+SELECT * FROM (SHOW ROLES);
+SELECT * FROM (SHOW SHARES);
+SELECT * FROM (SHOW CONNECTIONS);
+SELECT * FROM (SHOW JOBS) WHERE status = 'FAILED';
+SELECT * FROM (SHOW GRANTS);
+SELECT * FROM (SHOW FUNCTIONS) WHERE name LIKE '%count%';
+SELECT * FROM (SHOW DYNAMIC TABLE REFRESH HISTORY) WHERE state = 'FAILED';
+SELECT * FROM (SHOW COLUMNS FROM my_table);
+
+-- ❌ 不支持子查询
+-- SELECT * FROM (SHOW CREATE TABLE my_table);  -- parser return null
+```
+
+> 💡 **SHOW 结果排序的唯一方法**：`SHOW ... ORDER BY` 不支持，但可用子查询：
+> ```sql
+> SELECT * FROM (SHOW TABLES) ORDER BY table_name;
+> SELECT * FROM (SHOW VCLUSTERS) ORDER BY create_time DESC;
+> ```
+
+---
+
+## 常见陷阱
+
+| 命令 | 陷阱 | 正确做法 |
+|---|---|---|
+| `SHOW SCHEMAS WHERE type=...` | `type` 字段不存在 | `SHOW SCHEMAS WHERE schema_name LIKE '%xxx%'` |
+| `SHOW VIEWS IN schema` | 语法不支持 | `SHOW TABLES WHERE is_view=true` |
+| `SHOW VOLUMES IN schema` | 语法不支持 | `SHOW VOLUMES WHERE external=true/false` 或 `WHERE connection='xxx'` |
+| `SHOW VOLUMES WHERE schema_name='x'` | `schema_name` 字段不可过滤 | `SHOW VOLUMES LIKE '%name%'` |
+| `SHOW PARTITIONS t WHERE dt='x'` | 不支持按分区列 WHERE | `SHOW PARTITIONS t PARTITION(dt='x')` |
+| `load_history(schema.table)` | 需要字符串 | `load_history('schema.table')` |
+| `DESC FUNCTION year` | 不支持内置函数 | 仅支持用户创建的外部函数 |
+| `LIKE` + `WHERE` 同时用 | 不支持 | 用 `WHERE table_name LIKE 'x%'` 代替，或用子查询 `SELECT * FROM (SHOW TABLES) WHERE table_name LIKE 'x%'` |
+| `SHOW GRANTS ... LIMIT n` | 不支持 LIMIT | 直接 `SHOW GRANTS TO USER name` |
+| `SHOW FUNCTIONS LIKE '%xxx%'` | 不支持 LIKE | 用 `SHOW EXTERNAL FUNCTIONS LIKE '%xxx%'` |