alibabacloud-odps-information-schema

ODPS Information Schema

このスキルは 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 ビューにはテナントレベルの権限が必要です。アクセスエラーが発生した場合は、ユーザーにテナントレベルのロールが必要です。Policy のテンプレートについては、references/ram-policies.md を参照してください。

データの鮮度：履歴ビュー（TASKS_HISTORY、TUNNELS_HISTORY）には約 5 分の遅延があり、リアルタイムビューには約 3 時間の遅延があります。前日のデータを取得するには、データの完全性を確保するため、06:00 以降にクエリしてください。

テナントレベルとプロジェクトレベルの IS：MaxCompute には 2 つの 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. 必ず 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. IS ビューの JOIN には 3 フィールドのキーが必要です — 2 つの IS ビューを JOIN する場合、ON 条件には必ず table_catalog、table_schema、table_name を含めてください。いずれかが欠けると、複数のカタログがある環境で正しくない結果になります

プロジェクトレベル 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

変換例：

-- 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 で失敗した場合（namespace フラグが正しく設定されていることが前提）、またはユーザーがプロジェクトレベルの 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
トンネルセッション	session_id	tunnel_id
トンネルデータサイズ	data_size	size_bytes
ユーザーID	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 を使用
単一ビューのクエリ	JOIN を含まない、1 つの IS ビューに関するクエリ	なし — 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

アンチパターン：次の場合、追加ファイルを読み込まないでください

ユーザーの発言	そう見えるもの	実際の内容	読み込むファイル
"storage pressure, list top 20 tables"	診断	単一ビュー	SKILL.md のみ
"permission audit, who has SELECT on X"	プレイブック	単一ビュー	SKILL.md のみ
"cost attribution by owner"	因果分析	単一ビュー	SKILL.md のみ

インライン結合条件（2つ以上のビューを結合する場合）

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種類のパスを以下にインラインで示します。

インライン用語マッピング（よく使われる英語以外の用語）

英語以外の用語	英語での表現	正しいカラム／ソース	よくある誤り
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	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 は廃止予定のため、テナントレベルを優先してください
新しいプロジェクトで 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）	トンネルレコードの件数が 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 が発生する	その他の原因（プロジェクト間違い、タイプミス、スキーマの問題）	T1～T7 のシナリオについて references/TROUBLESHOOTING.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 (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	トンネル履歴	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 — 検証済み SQL クエリテンプレート 30 個（スモークテストを含む）
• 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 — テナント権限の設定とポリシーテンプレート
• references/mcp-tools-reference.md — ルーティングガイド、MCP のセットアップ、インストールを含む 15 個の MCP ツール
• scripts/odps_is_query.sh — コマンドラインクエリツール（スモークテストを含む、16 種類のクエリとカスタムクエリに対応）。タイムアウトには -t <seconds>（デフォルトは 300s）、日付には -d YYYYMMDD、プロジェクトには -p を使用できます。カスタムモードでは SELECT のみが許可されます（DDL/DML は拒否されます）。
• references/TROUBLESHOOTING.md — 修正テンプレート付きのエラーシナリオ 7 件（T1～T7）

公式ドキュメント

• MaxCompute Tenant-level Information Schema