alibabacloud-odps-information-schema

ODPS 信息架构

此技能仅用于查询信息架构（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。

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

租户级与项目级 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 适配。

MCP 配置请参阅 references/mcp-tools-reference.md。

执行渠道

当 mcp__maxcompute-catalog__* 工具可用时，优先使用 MCP。遇到连接或身份验证错误时，回退到 odpscmd。

渠道	用途	关键细节
MCP（租户级）	DQL、元数据、搜索	execute_sql + hints={"odps.namespace.schema":"true"}；同步查询最多返回 1000 行；cost_sql 支持 IS 视图（已于 2026-04 验证）
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。

重要规则

1. 始终设置命名空间标记——每个租户级 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 直接读取不会采集此字段；实际访问后最多延迟 24h
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 视图需要 3 个字段作为键——连接任意两个 IS 视图时，ON 条件必须包含 table_catalog、table_schema 和 table_name。缺少其中任意一个都会导致多目录环境中的结果不正确

项目级 IS 适配

此技能中的所有 SQL 模板默认使用租户级语法（SYSTEM_CATALOG.INFORMATION_SCHEMA.* + 命名空间标记）。如果环境仅支持项目级 IS，请对生成的每条 SQL 应用以下机械转换：

转换项	租户级（默认）	项目级
视图前缀	SYSTEM_CATALOG.INFORMATION_SCHEMA.	Information_Schema.
命名空间标记（MCP）	hints={"odps.namespace.schema":"true"}	hints={}（移除标记）
命名空间标记（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

转换示例：

-- Tenant-level (default):
SET odps.namespace.schema=true;
SELECT table_name, data_length FROM SYSTEM_CATALOG.INFORMATION_SCHEMA.TABLES WHERE ...

-- Project-level (after transformation):
SELECT table_name, data_length FROM Information_Schema.tables WHERE ...

何时切换：如果租户级查询返回 Table not found（且已正确设置命名空间标记），或用户明确表示他们仅有项目级 IS，请将上述转换规则应用于之后的所有查询。

关键列名参考

概念	正确	错误
表大小	data_length	size_bytes、size
任务实例	inst_id	task_id
任务提交者	owner_name	task_owner
任务项目	task_catalog（租户级）	project_name、task_schema（仅项目级 IS）
任务错误	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。

路由索引

SKILL.md 包含关键列名和命名空间规则。仅在需要时加载子文件：

• **如果匹配多行，请加载所有匹配的文件。**例如，非英语术语的因果查询需要同时加载 terminology.md 和 playbooks+causal-templates。
• 如果 SKILL.md 中的内联信息（下表）已足够，则不要加载额外文件。
• 与 IS 视图无关？ → 此技能不适用。请使用 MCP 工具（list_tables、get_table_schema、execute_sql）或 odpscmd 进行 DDL/DML/常规查询。

查询类型	适用情况	加载额外文件
不是 IS 查询	DDL/DML、列出表、运行 SQL、常规 ODPS	无 — 改用 MCP 工具或 odpscmd
单视图查询	查询一个 IS 视图，不含 JOIN	无 — 仅使用 SKILL.md
实时监控	TASKS / QUOTA_USAGE	无 — 仅使用 SKILL.md
2 个或更多 IS 视图 JOIN	组合多个视图	references/joins.md
命名指标/模板	“注释覆盖率”“CU 趋势”“僵尸表检测”	references/verified-queries.md + references/metrics.md
多步骤诊断	“CU 为什么激增？”、根因分析	references/playbooks.md + references/causal-templates.md
非英语同义词	“cpu时间”“作业时长”“存储占用”或任何 CJK/本地化术语	references/terminology.md（或使用下方的内联映射）
架构/字段查询	“X 有哪些列？”	references/views-reference.md
访问被拒绝错误	无权访问 IS 视图	references/ram-policies.md
故障排除	找不到表、超时等	references/TROUBLESHOOTING.md

反模式：以下情况不要加载额外文件

用户说	看起来像	实际上是	加载
“存储压力，列出排名前 20 的表”	诊断	单视图	仅使用 SKILL.md
“权限审计，谁对 X 有 SELECT 权限”	操作手册	单视图	仅使用 SKILL.md
“按所有者归因成本”	因果分析	单视图	仅使用 SKILL.md

内联连接条件（用于 2 个及以上视图的 JOIN）

连接 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。下方内联列出了最常见的 7 种路径。

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

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

所有 59 个术语请参阅 references/terminology.md。

错误恢复

错误信号	根本原因	解决方法
IS 视图中出现 Table not found	缺少命名空间标志	添加 SET odps.namespace.schema=true; / hints={"odps.namespace.schema":"true"}。使用 Q30 冒烟测试进行验证
IS 视图中出现 Access denied / Permission denied	缺少租户级角色	使用 check_access(include_grants=true) 验证访问权限。用户需要租户级角色——加载 references/ram-policies.md 中的策略模板
SYSTEM_CATALOG.INFORMATION_SCHEMA.* 中出现 Table not found（命名空间标志已正确设置）	环境仅支持项目级 IS	将 项目级 IS 适配转换规则应用于所有后续查询：将前缀改为 Information_Schema.*，移除命名空间标志
出现 Information_Schema not found / Package not installed	此项目未安装项目级 IS	用户必须以项目所有者或 Super_Administrator 身份运行 install package Information_Schema.systables。安装后，使用 Information_Schema.view_name 查询（无需命名空间标志）。注意：项目级 IS 正在弃用——建议优先使用租户级 IS
新项目中出现 Object 'Information_Schema' not found	新项目（自 2024-03 起）不会自动安装项目级 IS	切换到租户级 IS（SYSTEM_CATALOG.INFORMATION_SCHEMA.*）或手动安装包
TASKS_HISTORY 查询缓慢或开销较大	没有 ds 过滤条件	添加 WHERE ds >= TO_CHAR(DATEADD(GETDATE(), -14, 'dd'), 'yyyymmdd')
MCP 恰好返回 1000 行	同步限制导致截断	使用 async=true 重新运行，或添加更严格的 WHERE/LIMIT 条件
出现 Column not found	使用了不存在的列	查看上方的关键列参考——常见情况：size_bytes→data_length、task_status→status
TUNNELS_HISTORY 同步超时（>30s）	Tunnel 记录量远大于 TASKS_HISTORY	使用 async=true + get_instance，或将 ds 范围缩短至 1 天
异步超时（>30s）	扫描量较大	先使用 cost_sql；添加 ds 过滤条件；拆分查询
IS 视图没有显示近期数据	历史视图约有 5 分钟延迟	06:00 后查询前一天的数据
odpscmd 查询挂起	结果集较大或进行了全表扫描	使用 odps_is_query.sh -t <seconds> 设置超时时间（默认 300s）；添加 ds 过滤条件
已设置命名空间标志，但仍出现 Table not found	其他原因（项目错误、拼写错误、架构问题）	加载 references/TROUBLESHOOTING.md，查看 T1–T7 场景

核心视图

视图	用途	关键列
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 (core×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。标记为 ⚠️ 的视图仅限租户级（项目级 IS 中不可用）。

其他资源

• references/views-reference.md — 全部 31 个 IS 视图的完整字段定义
• references/verified-queries.md — 30 个预先验证的 SQL 查询模板（包括冒烟测试）
• references/entities.md — 实体与表的映射
• references/metrics.md — 带 SQL 表达式的指标定义
• references/joins.md — 视图之间的联接路径
• references/playbooks.md — 23 个诊断场景操作手册
• references/causal-templates.md — 根因分析模板
• references/terminology.md — 用于 NL2SQL 的 59 词同义词词典
• references/ram-policies.md — 租户权限设置和 Policy 模板
• references/mcp-tools-reference.md — 15 个 MCP 工具，附路由指南、MCP 设置和安装说明
• scripts/odps_is_query.sh — CLI 查询工具（16 种查询类型及自定义模式，包括冒烟测试）。支持使用 -t <seconds> 设置超时（默认 300s）、使用 -d YYYYMMDD 指定日期，以及使用 -p 指定项目。自定义模式仅允许 SELECT（拒绝 DDL/DML）。
• references/TROUBLESHOOTING.md — 7 种错误场景及修复模板（T1–T7）

官方文档

• MaxCompute Tenant-level Information Schema