MaxCompute 元数据分析与诊断

技能文档

---
name: alibabacloud-odps-information-schema
title: MaxCompute 元数据分析与诊断
category: 办公效率
description: 通过 Information Schema 视图查询 MaxCompute (ODPS) 元数据，支持存储分析、费用归因、权限审计、任务诊断和治理分析。当用户询问表存储统计、查询历史、权限审计、费用分析、CU 消耗趋势、僵尸表检测、通道审计、元数据治理诊断时触发。触发词：Information Schema、元数据查询、存储分析、费用归因、权限审计、任务诊断、CU 消耗、僵尸表。
---

# MaxCompute 元数据分析与诊断

**本技能仅用于 Information Schema (IS) 元数据查询。** 如果用户的问题涉及 DDL/DML、列表或 MaxCompute 常规用法（非 IS 视图），请勿使用本技能，改用 MCP 工具（list_tables、get_table_schema）或 odpscmd。

通过 INFORMATION_SCHEMA 视图查询 MaxCompute 元数据，支持存储、费用、权限、任务和治理分析。

## 前置条件

> **强制要求：每条租户级 IS 查询必须设置 namespace 标志。** 否则所有查询都会报 "Table not found" 错误。
> - **MCP**：在 `execute_sql` 中设置 `hints={"odps.namespace.schema":"true"}`
> - **odpscmd**：在每条查询前执行 `SET odps.namespace.schema=true;`
> - 无例外。适用于所有 `SYSTEM_CATALOG.INFORMATION_SCHEMA.*` 查询。

> IS 视图需要租户级权限。如果遇到访问错误，用户需要租户级角色 — 参见 [references/ram-policies.md](references/ram-policies.md) 获取 Policy 模板。

> **数据时效性**：历史视图（TASKS_HISTORY、TUNNELS_HISTORY）有约 5 分钟延迟，实时视图约 3 小时。查询昨天的数据建议在 06:00 之后以确保完整性。

> **租户级 vs 项目级 IS**：MaxCompute 有两个 IS 级别。**租户级**（`SYSTEM_CATALOG.INFORMATION_SCHEMA.*`）是默认级别，覆盖同一元数据中心下的所有项目，**推荐使用**。**项目级**（`Information_Schema.*`）仅限单项目，需要 `install package Information_Schema.systables`，**正在废弃**（自 2024-03 起新项目不再自动安装）。主要区别：(1) 项目级视图更少（缺少 CATALOGS、VOLUMES、FOREIGN_SERVERS、SCHEMAS、PARTITION_ACCESS_INFO、TABLE_ACCESS_INFO、QUOTA_USAGE；但有 SCHEMA_PRIVILEGES 而租户级没有）；(2) 项目级 TASKS_HISTORY 有 `task_schema` 列而租户级没有；(3) 项目级 `table_catalog` 固定为 `odps`，租户级为实际项目名。详见[项目级 IS 适配](#项目级-is-适配)。

MCP 配置参见 [references/mcp-tools-reference.md](references/mcp-tools-reference.md)。

## 技能工作流

### 步骤1：确定执行通道

根据可用工具选择执行通道。**优先使用 MCP**，当 MaxCompute MCP 工具可用时；连接或认证出错时回退到 odpscmd。

| 通道 | 适用场景 | 关键说明 |
|------|----------|----------|
| **MCP（租户级）** | DQL、元数据、搜索 | `execute_sql` + `hints={"odps.namespace.schema":"true"}`；同步上限 1000 行；`cost_sql` 支持 IS 视图 |
| **MCP（项目级）** | DQL、元数据、搜索 | `execute_sql` + `hints={}`（不设 namespace 标志）；视图前缀：`Information_Schema.*` |
| **odpscmd（租户级）** | DDL/DML、大结果集、MCP 不可用 | 必须加 `SET odps.namespace.schema=true;` 前缀 |
| **odpscmd（项目级）** | DDL/DML、大结果集、MCP 不可用 | 不设 namespace 标志；视图前缀：`Information_Schema.*` |

15 个 MCP 工具的路由指南详见 [references/mcp-tools-reference.md](references/mcp-tools-reference.md)。

### 步骤2：设置 namespace 标志

每条租户级 IS 查询都必须设置 namespace 标志，项目级 IS 查询不需要此标志。

### 步骤3：路由查询

根据查询类型决定是否加载额外参考文件：

- **如果多个条件匹配，加载所有匹配文件。** 例如非中文术语的因果分析需要同时加载 terminology.md 和 playbooks + causal-templates。
- **如果 SKILL.md 内联信息已足够，不加载额外文件。**
- **不是 IS 查询？** → 本技能不适用。改用 MCP 工具或 odpscmd。

| 查询类型 | 何时使用 | 加载额外文件 |
|----------|----------|--------------|
| **非 IS 查询** | DDL/DML、列表、运行 SQL、常规 ODPS | 不加载 — 改用 MCP 工具或 odpscmd |
| **单视图查询** | 单个 IS 视图，无 JOIN | 不加载 — 仅 SKILL.md |
| **实时监控** | TASKS / QUOTA_USAGE | 不加载 — 仅 SKILL.md |
| **2+ 视图 JOIN** | 组合多个视图 | [references/joins.md](references/joins.md) |
| **命名指标/模板** | "注释覆盖率"、"CU 趋势"、"僵尸表检测" | [references/verified-queries.md](references/verified-queries.md) + [references/metrics.md](references/metrics.md) |
| **多步诊断** | "CU 为什么飙升？"、根因分析 | [references/playbooks.md](references/playbooks.md) + [references/causal-templates.md](references/causal-templates.md) |
| **非英文同义词** | "cpu时间"、"作业时长"、"存储占用" 等术语 | [references/terminology.md](references/terminology.md) |
| **字段结构查询** | "X 有哪些列？" | [references/views-reference.md](references/views-reference.md) |
| **访问被拒** | IS 视图权限错误 | [references/ram-policies.md](references/ram-policies.md) |
| **故障排查** | Table not found、超时等 | [references/TROUBLESHOOTING.md](references/TROUBLESHOOTING.md) |

#### 反模式：以下场景不要加载额外文件

| 用户说 | 看起来像 | 实际上是 | 加载 |
|--------|----------|----------|------|
| "存储压力，列出前 20 张表" | 诊断 | 单视图 | 仅 SKILL.md |
| "权限审计，谁对 X 有 SELECT" | Playbook | 单视图 | 仅 SKILL.md |
| "按 owner 的费用归因" | 因果分析 | 单视图 | 仅 SKILL.md |

### 步骤4：构建并执行查询

遵循以下重要规则：

1. **始终设置 namespace 标志** — 每条租户级 IS 查询，无例外。项目级 IS 查询不需要此标志
2. **按 `ds` 过滤** — TASKS_HISTORY / TUNNELS_HISTORY 是分区视图；始终添加 `ds` 过滤避免全表扫描
3. **禁止 SELECT \*** — 使用显式列名
4. **不支持跨元数据中心** — 每个区域独立
5. **last_access_time 对分区表为 NULL** — 使用 `COALESCE(last_access_time, last_modified_time)` 或检查 PARTITIONS 视图。另外：ALGO 作业和 Hologres 直读不采集；与实际访问有最多 24 小时延迟
6. **status 值** — TASKS_HISTORY：`Terminated`（正常）、`Failed`、`Cancelled`（罕见）。不要将 Terminated 计为失败
7. **operate_type 值** — TUNNELS_HISTORY：`UPLOADLOG`、`DOWNLOADLOG`、`DOWNLOADINSTANCELOG`、`STORAGEAPIREAD`、`STORAGEAPIWRITE`
8. **无时间字段的视图** — COLUMNS 无时间列。TABLE_PRIVILEGES/COLUMN_PRIVILEGES 无时间列，只有 `expired`。这些视图仅支持静态快照
9. **cost_cpu / cost_mem 为 DOUBLE** — 单位：100×核心×秒 / MB×秒。转换为 CU·小时：`cost_cpu / 100 / 3600`
10. **耗时** — 使用 `DATEDIFF(end_time, start_time, 'ss')`（秒）。不存在 `duration_ms` 列
11. **不存在的字段陷阱** — 参见下方关键列名对照表
12. **JOIN IS 视图需要三字段键** — 关联任意两个 IS 视图时，ON 条件必须包含 `table_catalog`、`table_schema` 和 `table_name`。缺少任何一个都会在多目录环境下产生错误结果

### 步骤5：错误恢复

| 错误信号 | 根因 | 修复方法 |
|----------|------|----------|
| IS 视图报 `Table not found` | 缺少 namespace 标志 | 添加 `SET odps.namespace.schema=true;` / `hints={"odps.namespace.schema":"true"}` |
| IS 视图报 `Access denied` | 缺少租户级角色 | 用 `check_access(include_grants=true)` 验证。用户需要租户级角色 — 加载 [references/ram-policies.md](references/ram-policies.md) |
| `SYSTEM_CATALOG.INFORMATION_SCHEMA.*` 报 `Table not found`（namespace 标志已正确设置） | 环境仅支持项目级 IS | 对所有后续查询应用[项目级 IS 适配](#项目级-is-适配)转换规则 |
| `Information_Schema not found` | 项目级 IS 未安装 | 用户须以项目 Owner 或 Super_Administrator 身份运行 `install package Information_Schema.systables` |
| 新项目报 `Object 'Information_Schema' not found` | 新项目（2024-03 起）不自动安装 | 切换到租户级 IS 或手动安装 |
| TASKS_HISTORY 查询慢/贵 | 无 `ds` 过滤 | 添加 `WHERE ds >= TO_CHAR(DATEADD(GETDATE(), -14, 'dd'), 'yyyymmdd')` |
| MCP 恰好返回 1000 行 | 同步限制截断 | 使用 `async=true` 重跑，或收紧 WHERE/LIMIT |
| `Column not found` | 使用了不存在的列 | 检查下方关键列名对照表 |
| TUNNELS_HISTORY 同步超时 | Tunnel 记录量远大于 TASKS_HISTORY | 使用 `async=true` + `get_instance`，或将 ds 缩减到 1 天 |
| odpscmd 查询挂起 | 大结果集或全表扫描 | 使用 `odps_is_query.sh -t <秒数>` 设置超时（默认 300s）；添加 `ds` 过滤 |

## 项目级 IS 适配

所有 SQL 模板默认使用**租户级**语法（`SYSTEM_CATALOG.INFORMATION_SCHEMA.*` + namespace 标志）。如果环境仅支持**项目级** IS，对每条生成的 SQL 做以下机械性转换：

| 转换项 | 租户级（默认） | 项目级 |
|--------|---------------|--------|
| 视图前缀 | `SYSTEM_CATALOG.INFORMATION_SCHEMA.` | `Information_Schema.` |
| Namespace 标志（MCP） | `hints={"odps.namespace.schema":"true"}` | `hints={}`（移除标志） |
| Namespace 标志（odpscmd） | `SET odps.namespace.schema=true;` | 完全移除 |
| 范围 | 元数据中心下所有项目 | 仅当前项目 |
| 不可用的视图 | — | CATALOGS、VOLUMES、FOREIGN_SERVERS、SCHEMAS、PARTITION_ACCESS_INFO、TABLE_ACCESS_INFO、QUOTA_USAGE |
| 仅此级别有的视图 | — | SCHEMA_PRIVILEGES |
| TASKS_HISTORY 额外列 | — | `task_schema`（项目名；租户级没有） |
| `table_catalog` 值 | 实际项目名 | 固定 `odps` |

**转换示例：**
```
-- 租户级（默认）：
SET odps.namespace.schema=true;
SELECT table_name, data_length FROM SYSTEM_CATALOG.INFORMATION_SCHEMA.TABLES WHERE ...

-- 项目级（转换后）：
SELECT table_name, data_length FROM Information_Schema.tables WHERE ...
```

**何时切换**：如果租户级查询报 `Table not found`（且 namespace 标志已正确设置），或用户明确表示只有项目级 IS，则对所有后续查询应用上述转换规则。

## 关键列名对照表

| 概念 | 正确写法 | 错误写法 |
|------|----------|----------|
| 表大小 | `data_length` | ~~size_bytes~~、~~size~~ |
| 任务实例 | `inst_id` | ~~task_id~~ |
| 任务提交者 | `owner_name` | ~~task_owner~~ |
| 任务项目 | `task_catalog`（租户级） | ~~project_name~~、~~task_schema~~（仅项目级） |
| 任务错误 | `result` | ~~error_message~~ |
| 任务耗时 | `DATEDIFF(end_time, start_time, 'ss')` | ~~duration_ms~~ |
| 任务状态 | `status` | ~~task_status~~ |
| 任务输入大小 | `input_bytes` | ~~scan_bytes~~、~~processed_bytes~~ |
| 表注释 | `table_comment` | ~~comment~~ |
| 列注释 | `column_comment` | ~~comment~~ |
| 权限被授权人 | `user_name`、`user_id` | ~~grantee~~ |
| 权限时间 | `expired` | ~~grant_time~~ |
| 资源大小 | `size` | ~~size_bytes~~ |
| Tunnel 会话 | `session_id` | ~~tunnel_id~~ |
| Tunnel 数据大小 | `data_size` | ~~size_bytes~~ |
| 用户身份 | `identity_provider` | — |
| 时间戳类型 | `DATETIME` | ~~TIMESTAMP~~ |
| 表修改时间 | `last_modified_time` | ~~last_ddl_time~~ |
| cost_cpu 类型 | `DOUBLE` | ~~BIGINT~~ |

已验证的查询示例参见 [references/verified-queries.md](references/verified-queries.md)。

### 内联 JOIN 条件（2+ 视图关联）

关联 IS 视图时，JOIN 条件必须包含 `table_catalog`、`table_schema` 和 `table_name`。常见关联路径：

| 左表 | 右表 | 关联条件 |
|------|------|----------|
| TABLES | COLUMNS | `t.table_catalog = c.table_catalog AND t.table_schema = c.table_schema AND t.table_name = c.table_name` |
| TABLES | PARTITIONS | `t.table_catalog = p.table_catalog AND t.table_schema = p.table_schema AND t.table_name = p.table_name` |
| TABLES | TABLE_PRIVILEGES | `t.table_catalog = p.table_catalog AND t.table_schema = p.table_schema AND t.table_name = p.table_name` |
| TABLES | TABLE_ACCESS_INFO | `t.table_catalog = a.table_catalog AND t.table_schema = a.table_schema AND t.table_name = a.table_name` |
| TABLES | TABLE_LABELS | `t.table_catalog = l.table_catalog AND t.table_schema = l.table_schema AND t.table_name = l.table_name` |
| USERS | USER_ROLES | `u.user_id = ur.user_id` |
| COLUMNS | COLUMN_LABELS | `c.table_catalog = l.table_catalog AND c.table_schema = l.table_schema AND c.table_name = l.table_name AND c.column_name = l.column_name` |

全部 16 条关联路径详见 [references/joins.md](references/joins.md)。以上内联了最常用的 7 条。

### 内联术语映射（常见非英文术语）

| 非英文术语 | 英文等价 | 正确列/来源 | 常见错误 |
|-----------|----------|-------------|----------|
| cpu时间 / CPU消耗 | CPU time / consumption | `cost_cpu`（DOUBLE），÷100÷3600 = CU·小时 | ~~cpu_time~~ |
| 作业时长 / 任务耗时 | Task duration | `DATEDIFF(end_time, start_time, 'ss')` | ~~duration_ms~~ |
| 存储占用 / 表大小 | Storage usage | `data_length`（÷1073741824 = GB） | ~~size_bytes~~ |
| 僵尸表 | Zombie table | TABLES + TABLE_ACCESS_INFO | — |
| 排队时间 | Queue wait time | IS 视图中不可用 | — |
| CU时 / CU消耗 | CU-hours | `SUM(cost_cpu) / 100.0 / 3600` | — |
| 任务失败率 | Task failure rate | TASKS_HISTORY 中 `status='Failed'` 占比 | — |

全部 59 个术语详见 [references/terminology.md](references/terminology.md)。

## 核心视图

| 视图 | 用途 | 关键列 |
|------|------|--------|
| `TABLES` | 表元数据 | table_name, owner_name, data_length, table_type, lifecycle, last_modified_time |
| `COLUMNS` | 列元数据 | column_name, data_type, column_comment, is_partition_key |
| `PARTITIONS` | 分区元数据 | partition_name, data_length, create_time, last_modified_time |
| `TASKS` | 运行中的任务（实时，秒级延迟） | inst_id, task_name, owner_name, status, cpu_usage（核心×100）, mem_usage（MB） |
| `TASKS_HISTORY` | 查询历史 | inst_id, task_name, owner_name, status, task_type, start_time, end_time, result, cost_cpu, input_bytes, ds |
| `TUNNELS_HISTORY` | Tunnel 历史 | session_id, object_name, operate_type, data_size, owner_name, ds |
| `TABLE_PRIVILEGES` | 表权限 | table_name, user_name, privilege_type, expired |
| `TABLE_ACCESS_INFO` ⚠️ | 表访问统计 | table_name, access_count, access_bytes, last_access_time |
| `QUOTA_USAGE` | 包年包月配额监控 | name, cpu_elastic_quota_max, cpu_elastic_quota_used, mem_elastic_quota_max, mem_elastic_quota_used |
| `USERS` | 项目用户 | user_name, user_id, identity_provider |
| `USER_ROLES` | 用户-角色映射 | user_name, role_name, user_role_catalog |
| `CATALOGS` ⚠️ | 项目列表 | catalog_name, status, owner_name, region |

全部 31 个视图的完整字段定义详见 [references/views-reference.md](references/views-reference.md)。标记 ⚠️ 的视图为**租户级专属**（项目级 IS 不可用）。

## 参考资料

- [references/views-reference.md](references/views-reference.md) — 全部 31 个 IS 视图的完整字段定义
- [references/verified-queries.md](references/verified-queries.md) — 30 个预验证 SQL 查询模板（含冒烟测试）
- [references/entities.md](references/entities.md) — 实体到表的映射
- [references/metrics.md](references/metrics.md) — 指标定义与 SQL 表达式
- [references/joins.md](references/joins.md) — 视图间的关联路径
- [references/playbooks.md](references/playbooks.md) — 23 个诊断场景手册
- [references/causal-templates.md](references/causal-templates.md) — 根因分析模板
- [references/terminology.md](references/terminology.md) — 59 个术语的同义词词典
- [references/ram-policies.md](references/ram-policies.md) — 租户权限配置与 Policy 模板
- [references/mcp-tools-reference.md](references/mcp-tools-reference.md) — 15 个 MCP 工具及路由指南
- [scripts/odps_is_query.sh](scripts/odps_is_query.sh) — CLI 查询工具（16 种查询类型 + 自定义，含冒烟测试）。支持 `-t <秒数>` 超时（默认 300s）、`-d YYYYMMDD` 日期、`-p` 项目。自定义模式仅允许 SELECT
- [references/TROUBLESHOOTING.md](references/TROUBLESHOOTING.md) — 7 个错误场景及修复模板（T1–T7）

## 官方文档

- [MaxCompute 租户级 Information Schema](https://help.aliyun.com/zh/maxcompute/user-guide/tenant-level-information-schema)

使用说明

# MaxCompute 元数据分析与诊断

通过 Information Schema 视图查询 MaxCompute 元数据，支持存储分析、费用归因、权限审计、任务诊断和治理分析。

## 使用

查询存储前 20 张表：

```bash
./scripts/odps_is_query.sh top-storage
```

查询指定日期的失败任务：

```bash
./scripts/odps_is_query.sh failed-tasks -d 20240101
```

按 owner 归因 CU 消耗：

```bash
./scripts/odps_is_query.sh cost-by-owner
```

检测 90 天未访问的僵尸表：

```bash
./scripts/odps_is_query.sh zombie-tables
```

自定义查询（自动添加 namespace 标志）：

```bash
./scripts/odps_is_query.sh custom 'SELECT table_name, data_length FROM SYSTEM_CATALOG.INFORMATION_SCHEMA.TABLES LIMIT 10;'
```

## 工作原理

技能通过租户级 `SYSTEM_CATALOG.INFORMATION_SCHEMA.*` 视图查询元数据，支持 MCP 和 odpscmd 两种执行通道。内置 16 种预定义查询类型和自定义 SQL 模式，覆盖存储分析、成本归因、权限审计、任务诊断、通道审计和治理分析等场景。包含 30 个预验证 SQL 模板、23 个诊断手册和 59 个术语映射，支持自然语言到 SQL 的精准转换。

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。