alibabacloud-odps-information-schema

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ODPS Information Schema

This skill is for Information Schema (IS) metadata queries ONLY. If the user's question is about DDL/DML, listing tables, or general MaxCompute usage (not IS views), do NOT use this skill — use MCP tools (list_tables, get_table_schema) or odpscmd instead.

Query MaxCompute metadata through INFORMATION_SCHEMA views for storage, cost, permission, task, and governance analysis.

本技能仅用于Information Schema（IS）元数据查询。 如果用户的问题涉及DDL/DML操作、列出表或通用MaxCompute使用（非IS视图相关），请勿使用本技能——请使用MCP工具（list_tables、get_table_schema）或odpscmd。

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

Prerequisites <a name="prerequisites"></a>

前提条件 <a name="prerequisites"></a>

MANDATORY: Every IS query MUST set namespace flag. Without it, ALL queries fail with "Table not found".
MCP:
hints={"odps.namespace.schema":"true"}
in
execute_sql
odpscmd:
SET odps.namespace.schema=true;
before each query
No exceptions. Applies to ALL
SYSTEM_CATALOG.INFORMATION_SCHEMA.*
queries.

IS views require tenant-level permission. If you get access errors, the user needs tenant-level role — see references/ram-policies.md for Policy template.

Data freshness: History views (TASKS_HISTORY, TUNNELS_HISTORY) have ~5 min delay, realtime views ~3 hours. For yesterday's data, query after 06:00 to ensure completeness.

Tenant-level vs Project-level IS: MaxCompute has two IS levels. Tenant-level (
SYSTEM_CATALOG.INFORMATION_SCHEMA.*
) is the default — it covers all projects under the same metadata center and is recommended. Project-level (
Information_Schema.*
) is per-project only, requires
install package Information_Schema.systables
, and is being deprecated (since 2024-03 new projects no longer auto-install). Key differences: (1) project-level has fewer views (no CATALOGS, VOLUMES, FOREIGN_SERVERS, SCHEMAS, PARTITION_ACCESS_INFO, TABLE_ACCESS_INFO, QUOTA_USAGE; has SCHEMA_PRIVILEGES which tenant lacks); (2) project-level TASKS_HISTORY has
task_schema
while tenant-level does NOT; (3) project-level
table_catalog
is always
odps
while tenant-level is the actual project name. See Project-level IS Adaptation for transformation rules.

For MCP configuration, see references/mcp-tools-reference.md.

强制要求：所有IS查询必须设置命名空间标志。 未设置的话，所有查询都会因"表不存在"失败。
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年3月起，新项目不再自动安装）。核心差异：(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。

Execution Channels <a name="channels"></a>

执行渠道 <a name="channels"></a>

MCP preferred when

mcp__maxcompute-catalog__*

tools are available. Fall back to odpscmd on connection/auth errors.

Channel	Use For	Key Detail
MCP (tenant-level)	DQL, metadata, search	`execute_sql` + `hints={"odps.namespace.schema":"true"}` ; sync limit 1000 rows; `cost_sql` supports IS views (verified 2026-04)
MCP (project-level)	DQL, metadata, search	`execute_sql` + `hints={}` (no namespace flag); view prefix: `Information_Schema.*`
odpscmd (tenant-level)	DDL/DML, large results, MCP unavailable	`SET odps.namespace.schema=true;` prefix required
odpscmd (project-level)	DDL/DML, large results, MCP unavailable	No namespace flag; view prefix: `Information_Schema.*`

See references/mcp-tools-reference.md for 15 MCP tools with routing guide.

当

mcp__maxcompute-catalog__*

工具可用时，优先使用MCP。如果出现连接/认证错误，再回退到odpscmd。

执行渠道	适用场景	关键细节
MCP（租户级）	DQL、元数据、搜索	`execute_sql` + `hints={"odps.namespace.schema":"true"}` ；同步查询限制1000行； `cost_sql` 支持IS视图（2026年4月已验证）
MCP（项目级）	DQL、元数据、搜索	`execute_sql` + `hints={}` （无需命名空间标志）；视图前缀： `Information_Schema.*`
odpscmd（租户级）	DDL/DML、大结果集、MCP不可用	必须添加前缀 `SET odps.namespace.schema=true;`
odpscmd（项目级）	DDL/DML、大结果集、MCP不可用	无需命名空间标志；视图前缀： `Information_Schema.*`

请查看references/mcp-tools-reference.md了解15种MCP工具及路由指南。

Important Rules <a name="rules"></a>

重要规则 <a name="rules"></a>

Always set namespace flag — every tenant-level IS query, no exceptions. Project-level IS queries do NOT need this flag
Filter by
ds
— TASKS_HISTORY / TUNNELS_HISTORY are partitioned; always add
```
ds
```
filter to avoid full scan
No SELECT * — use explicit column names
Cross-metadata-center NOT supported — each region is independent
last_access_time is NULL for partitioned tables — use
```
COALESCE(last_access_time, last_modified_time)
```
or check PARTITIONS view. Also: not collected for ALGO jobs or Hologres direct reads; up to 24h delay from actual access.
status values — TASKS_HISTORY:
```
Terminated
```
(normal),
```
Failed
```
,
```
Cancelled
```
(rare). Never count Terminated as failure.

operate_type values — TUNNELS_HISTORY:

UPLOADLOG

DOWNLOADLOG

DOWNLOADINSTANCELOG

STORAGEAPIREAD

STORAGEAPIWRITE

Views without time fields — COLUMNS has no time column. TABLE_PRIVILEGES/COLUMN_PRIVILEGES have no time column, only
```
expired
```
. These views support static snapshot only, not time-series.
cost_cpu / cost_mem are DOUBLE — unit: 100×core×seconds / MB×seconds. Convert to CU-hours:
```
cost_cpu / 100 / 3600
```

Duration — use

DATEDIFF(end_time, start_time, 'ss')

(seconds). No

duration_ms

column exists.

Non-existent fields trap — see Critical Column Reference below
JOIN IS views requires 3-field key — when joining any two IS views, the ON condition MUST include
```
table_catalog
```
,
```
table_schema
```
, AND
```
table_name
```
. Missing any one causes incorrect results in multi-catalog environments

始终设置命名空间标志——所有租户级IS查询必须设置，无例外。项目级IS查询无需此标志
按
ds
过滤——TASKS_HISTORY / TUNNELS_HISTORY为分区表；必须添加
```
ds
```
过滤以避免全表扫描
**禁止使用SELECT ***——使用明确的列名
不支持跨元数据中心——每个区域相互独立
分区表的last_access_time为NULL——使用
```
COALESCE(last_access_time, last_modified_time)
```
或查看PARTITIONS视图。此外：ALGO作业或Hologres直接读取不会收集该数据；与实际访问时间最多有24小时延迟。
状态值——TASKS_HISTORY：
```
Terminated
```
（正常结束）、
```
Failed
```
（失败）、
```
Cancelled
```
（罕见）。请勿将Terminated统计为失败。

操作类型值——TUNNELS_HISTORY：

UPLOADLOG

、

DOWNLOADLOG

、

DOWNLOADINSTANCELOG

、

STORAGEAPIREAD

、

STORAGEAPIWRITE

无时间字段的视图——COLUMNS无时间列。TABLE_PRIVILEGES/COLUMN_PRIVILEGES无时间列，仅包含
```
expired
```
字段。这些视图仅支持静态快照，不支持时间序列查询。
cost_cpu / cost_mem为DOUBLE类型——单位：100×核×秒 / MB×秒。转换为CU小时：
```
cost_cpu / 100 / 3600
```
时长计算——使用
```
DATEDIFF(end_time, start_time, 'ss')
```
（秒）。不存在
```
duration_ms
```
列。
不存在字段陷阱——请查看下方的关键列参考
关联IS视图需要三字段键——关联任意两个IS视图时，ON条件必须包含
```
table_catalog
```
、
```
table_schema
```
和
```
table_name
```
。在多目录环境中，缺少任意一个都会导致结果错误

Project-level IS Adaptation <a name="project-level-adaptation"></a>

项目级IS适配 <a name="project-level-adaptation"></a>

All SQL templates in this skill default to tenant-level syntax (

SYSTEM_CATALOG.INFORMATION_SCHEMA.*

+ namespace flag). If the environment only supports project-level IS, apply these mechanical transformations to every generated SQL:

Transform	Tenant-level (default)	Project-level
View prefix	`SYSTEM_CATALOG.INFORMATION_SCHEMA.`	`Information_Schema.`
Namespace flag (MCP)	`hints={"odps.namespace.schema":"true"}`	`hints={}` (remove flag)
Namespace flag (odpscmd)	`SET odps.namespace.schema=true;`	Remove entirely
Scope	All projects in metadata center	Current project only
Views unavailable	—	CATALOGS, VOLUMES, FOREIGN_SERVERS, SCHEMAS, PARTITION_ACCESS_INFO, TABLE_ACCESS_INFO, QUOTA_USAGE
View exclusive to this level	—	SCHEMA_PRIVILEGES
TASKS_HISTORY extra column	—	`task_schema` (project name; tenant-level lacks this)
`table_catalog` value	Actual project name	Fixed `odps`

Example transformation:

-- 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 ...

When to switch: If a tenant-level query fails with

Table not found

(and namespace flag is correctly set), or if the user explicitly says they only have project-level IS, apply the transformation rules above to all subsequent queries.

本技能中的所有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`

转换示例：

-- 租户级（默认）：
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

，或用户明确表示仅支持项目级IS，请对后续所有查询应用上述转换规则。

Critical Column Name Reference <a name="column-reference"></a>

关键列名称参考 <a name="column-reference"></a>

Concept	Correct	Wrong
Table size	`data_length`	~~size_bytes~~, ~~size~~
Task instance	`inst_id`	~~task_id~~
Task submitter	`owner_name`	~~task_owner~~
Task project	`task_catalog` (tenant-level)	~~project_name~~, ~~task_schema~~ (project-level IS only)
Task error	`result`	~~error_message~~
Task duration	`DATEDIFF(end_time, start_time, 'ss')`	~~duration_ms~~
Task status	`status`	~~task_status~~
Task input size	`input_bytes`	~~scan_bytes~~, ~~processed_bytes~~
Table comment	`table_comment`	~~comment~~
Column comment	`column_comment`	~~comment~~
Privilege grantee	`user_name` , `user_id`	~~grantee~~
Privilege time	`expired`	~~grant_time~~
Resource size	`size`	~~size_bytes~~
Tunnel session	`session_id`	~~tunnel_id~~
Tunnel data size	`data_size`	~~size_bytes~~
User identity	`identity_provider`	—
Timestamp type	`DATETIME`	~~TIMESTAMP~~
Table modified	`last_modified_time`	~~last_ddl_time~~
cost_cpu type	`DOUBLE`	~~BIGINT~~

For verified query examples using these columns, see references/verified-queries.md.

概念	正确列名	错误列名
表大小	`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。

Routing Index <a name="routing"></a>

路由索引 <a name="routing"></a>

SKILL.md contains critical column names and namespace rules. Load sub-files only when needed:

If multiple rows match, load ALL matched files. E.g., a non-English term causal query needs both terminology.md and playbooks+causal-templates.
If SKILL.md inline info (tables below) is sufficient, do NOT load extra files.
NOT about IS views? → This skill is not applicable. Use MCP tools (list_tables, get_table_schema, execute_sql) or odpscmd for DDL/DML/general queries.

Query Type	When	Load Extra File
NOT an IS query	DDL/DML, list tables, run SQL, general ODPS	None — use MCP tools or odpscmd instead
Single-view query	One IS view, no JOIN	None — SKILL.md only
Live monitoring	TASKS / QUOTA_USAGE	None — SKILL.md only
2+ IS view JOIN	Combining views	references/joins.md
Named metric/template	"comment coverage", "CU trend", "zombie table detection"	references/verified-queries.md + references/metrics.md
Multi-step diagnosis	"Why did CU spike?", root-cause analysis	references/playbooks.md + references/causal-templates.md
Non-English synonyms	"cpu时间", "作业时长", "存储占用", or any CJK/localized terms	references/terminology.md (or use inline mapping below)
Schema/field lookup	"What columns does X have?"	references/views-reference.md
Access denied error	Permission denied on IS view	references/ram-policies.md
Troubleshooting	Table not found, timeout, etc.	references/TROUBLESHOOTING.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视图，无关联	无——仅使用SKILL.md
实时监控	TASKS / QUOTA_USAGE	无——仅使用SKILL.md
2个及以上IS视图关联	组合多个视图	references/joins.md
指定指标/模板	"注释覆盖率"、"CU趋势"、"僵尸表检测"	references/verified-queries.md + references/metrics.md
多步骤诊断	"CU突增原因？"、根因分析	references/playbooks.md + references/causal-templates.md
非英文同义词	"cpu时间"、"作业时长"、"存储占用"或任何CJK/本地化术语	references/terminology.md（或使用下方内置映射）
Schema/字段查询	"X视图包含哪些列？"	references/views-reference.md
访问被拒绝错误	IS视图权限被拒绝	references/ram-policies.md
故障排查	表不存在、超时等	references/TROUBLESHOOTING.md

Anti-pattern: Do NOT load extra files for these

反模式：以下场景请勿加载额外文件

User says	Looks like	Actually is	Load
"storage pressure, list top 20 tables"	Diagnostics	Single-view	SKILL.md only
"permission audit, who has SELECT on X"	Playbook	Single-view	SKILL.md only
"cost attribution by owner"	Causal	Single-view	SKILL.md only

用户提问	表面类型	实际类型	是否加载额外文件
"存储压力大，列出Top20表"	诊断类	单视图查询	仅使用SKILL.md
"权限审计，谁拥有X表的SELECT权限"	剧本类	单视图查询	仅使用SKILL.md
"按所有者进行成本归因"	因果类	单视图查询	仅使用SKILL.md

Inline Join Conditions (for 2+ view JOINs)

内置关联条件（适用于2个及以上视图关联）

When joining IS views, you MUST include

table_catalog

table_schema

, AND

table_name

in join conditions. Common join paths:

Left	Right	Join Condition
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`

For all 16 join paths, see references/joins.md. The 7 most common paths are inlined below.

关联IS视图时，必须在关联条件中包含

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种最常见的路径。

Inline Terminology Mapping (common non-English terms)

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

Non-English term	English equivalent	Correct column/source	Common mistake
cpu时间 / CPU消耗	CPU time / CPU consumption	`cost_cpu` (DOUBLE), ÷100÷3600 = CU·hour	~~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	NOT available in IS views	—
CU时 / CU消耗	CU-hours / CU consumption	`SUM(cost_cpu) / 100.0 / 3600`	—
任务失败率	Task failure rate	`status='Failed'` ratio in TASKS_HISTORY	—

For all 59 terms, see references/terminology.md.

非英文术语	英文对应	正确列/来源	常见错误
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。

Error Recovery <a name="error-recovery"></a>

错误恢复 <a name="error-recovery"></a>

Error Signal	Root Cause	Fix
`Table not found` on IS view	Missing namespace flag	Add `SET odps.namespace.schema=true;` / `hints={"odps.namespace.schema":"true"}` . Verify with Q30 smoke test
`Access denied` / `Permission denied` on IS view	Missing tenant-level role	Verify access with `check_access(include_grants=true)` . User needs tenant-level role — load references/ram-policies.md for Policy template
`Table not found` on `SYSTEM_CATALOG.INFORMATION_SCHEMA.*` (namespace flag correctly set)	Environment only supports project-level IS	Apply Project-level IS Adaptation transformation rules to all subsequent queries: switch prefix to `Information_Schema.*` , remove namespace flag
`Information_Schema not found` / `Package not installed`	Project-level IS not installed in this project	User must run `install package Information_Schema.systables` as project owner or Super_Administrator. After install, query as `Information_Schema.view_name` (no namespace flag). Note: project-level IS is being deprecated — prefer tenant-level
`Object 'Information_Schema' not found` on new project	New projects (since 2024-03) don't auto-install project-level IS	Switch to tenant-level IS ( `SYSTEM_CATALOG.INFORMATION_SCHEMA.*` ) or manually install package
TASKS_HISTORY query slow/expensive	No `ds` filter	Add `WHERE ds >= TO_CHAR(DATEADD(GETDATE(), -14, 'dd'), 'yyyymmdd')`
MCP returns exactly 1000 rows	Sync limit truncation	Re-run with `async=true` , or add tighter WHERE/LIMIT
`Column not found`	Used non-existent column	Check Critical Column Reference above — common: `size_bytes` → `data_length` , `task_status` → `status`
TUNNELS_HISTORY sync timeout (>30s)	Tunnel record volume much larger than TASKS_HISTORY	Use `async=true` + `get_instance` , or reduce ds to 1 day
Async timeout (>30s)	Large scan	Use `cost_sql` first; add `ds` filter; split query
IS view shows no recent data	~5 min delay for history views	Query yesterday's data after 06:00
odpscmd query hangs	Large result set or full-table scan	Use `odps_is_query.sh -t <seconds>` to set timeout (default 300s); add `ds` filter
Namespace flag set but still `Table not found`	Other causes (wrong project, typo, schema issue)	Load references/TROUBLESHOOTING.md for T1–T7 scenarios

错误信号	根本原因	修复方案
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已被废弃——优先使用租户级
新项目提示 `Object 'Information_Schema' not found`	自2024年3月起，新项目不再自动安装项目级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同步查询超时（>30秒）	Tunnel记录量远大于TASKS_HISTORY	使用 `async=true` + `get_instance` ，或缩小 `ds` 范围至1天
异步查询超时（>30秒）	扫描数据量过大	先使用 `cost_sql` 估算；添加 `ds` 过滤；拆分查询
IS视图无最新数据	历史视图有约5分钟延迟	昨日数据请在06:00之后查询
odpscmd查询挂起	结果集过大或全表扫描	使用 `odps_is_query.sh -t <seconds>` 设置超时（默认300秒）；添加 `ds` 过滤
已设置命名空间标志但仍提示 `Table not found`	其他原因（错误项目、拼写错误、Schema问题）	加载references/TROUBLESHOOTING.md查看T1–T7场景

Core Views <a name="core-views"></a>

核心视图 <a name="core-views"></a>

View	Purpose	Key Columns
`TABLES`	Table metadata	table_name, owner_name, data_length, table_type, lifecycle, last_modified_time
`COLUMNS`	Column metadata	column_name, data_type, column_comment, is_partition_key
`PARTITIONS`	Partition metadata	partition_name, data_length, create_time, last_modified_time
`TASKS`	Running jobs (live, seconds delay)	inst_id, task_name, owner_name, status, cpu_usage (core×100), mem_usage (MB)
`TASKS_HISTORY`	Query history	inst_id, task_name, owner_name, status, task_type, start_time, end_time, result, cost_cpu, input_bytes, ds
`TUNNELS_HISTORY`	Tunnel history	session_id, object_name, operate_type, data_size, owner_name, ds
`TABLE_PRIVILEGES`	Table permissions	table_name, user_name, privilege_type, expired
`TABLE_ACCESS_INFO` ⚠️	Table access stats	table_name, access_count, access_bytes, last_access_time
`QUOTA_USAGE`	Subscription quota monitoring	name, cpu_elastic_quota_max, cpu_elastic_quota_used, mem_elastic_quota_max, mem_elastic_quota_used
`USERS`	Project users	user_name, user_id, identity_provider
`USER_ROLES`	User-role mapping	user_name, role_name, user_role_catalog
`CATALOGS` ⚠️	Project list	catalog_name, status, owner_name, region

For all 31 views with complete field definitions, see references/views-reference.md. Views marked ⚠️ are tenant-level only (not available in project-level IS).

视图	用途	关键列
`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不可用）。

Additional Resources <a name="resources"></a>

额外资源 <a name="resources"></a>

references/views-reference.md — Complete field definitions for all 31 IS views
references/verified-queries.md — 30 pre-validated SQL query templates (including smoke test)
references/entities.md — Entity-to-table mapping
references/metrics.md — Metric definitions with SQL expressions
references/joins.md — Join paths between views
references/playbooks.md — 23 diagnostic scenario playbooks
references/causal-templates.md — Root-cause analysis templates
references/terminology.md — 59-term synonym dictionary for NL2SQL
references/ram-policies.md — Tenant permission setup and Policy template
references/mcp-tools-reference.md — 15 MCP tools with routing guide + MCP setup + installation
scripts/odps_is_query.sh — CLI query tool (16 query types + custom, including smoke-test). Supports
```
-t <seconds>
```
for timeout (default 300s),
```
-d YYYYMMDD
```
for date,
```
-p
```
for project. Custom mode only allows SELECT (DDL/DML rejected).
references/TROUBLESHOOTING.md — 7 error scenarios with fix templates (T1–T7)

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 — 59条NL2SQL同义词词典
references/ram-policies.md — 租户权限设置及策略模板
references/mcp-tools-reference.md — 15种MCP工具及路由指南 + MCP设置 + 安装说明
scripts/odps_is_query.sh — CLI查询工具（16种查询类型 + 自定义查询，包含冒烟测试）。支持
```
-t <seconds>
```
设置超时（默认300秒），
```
-d YYYYMMDD
```
指定日期，
```
-p
```
指定项目。自定义模式仅允许SELECT语句（拒绝DDL/DML）。
references/TROUBLESHOOTING.md — 7种错误场景及修复模板（T1–T7）

Official Documentation <a name="docs"></a>

官方文档 <a name="docs"></a>

MaxCompute Tenant-level Information Schema

MaxCompute 租户级Information Schema