alibabacloud-dlf-manage

DLF Data Lake Metadata Query

Alibaba Cloud Data Lake Formation（DLF）のカタログ、データベース、テーブルのメタデータリソースをクエリします。

重大：このスキルで提供される Python SDK スクリプトのみを使用してください。 すべての操作は、scripts/dlf_metadata_query.py を介して DLF Python SDK（alibabacloud-dlfnext20250310）で実行します。 このスキルでは、シェルベースのコマンドラインクライアントは呼び出さず、AI-Mode の設定も必要ありません。

• 絶対にシェルベースのコマンドラインクライアント経由でアクセスしないでください。このスキルでは DLF は公開されていません
• 絶対にcurl、wget、その他の HTTP クライアントを使って DLF API を直接呼び出さないでください
• 必ずこのスキルで提供される scripts/dlf_metadata_query.py スクリプトを使用してください。このスクリプトは DLF Python SDK をラップしています
• すべてのクエリ操作は python3 scripts/dlf_metadata_query.py <action> [options] を介して実行します

アーキテクチャ

Catalog (Data Catalog)
  └── Database
        └── Table
              ├── Schema (column definitions)
              ├── PartitionKeys (partition keys)
              ├── PrimaryKeys (primary keys)
              └── Options (table properties)

インストール

pip install -r requirements.txt

requirements.txt では、再現可能なインストールのため、推移的依存関係をすべて（alibabacloud-dlfnext20250310==3.0.0 を含む）固定しています。

事前確認：Python SDK の依存関係

python3 -c "from alibabacloud_dlfnext20250310.client import Client; print('SDK OK')"

インストールされていない場合は、pip install -r requirements.txt を実行してください。

認証

事前確認：Alibaba Cloud の認証情報が必要です

デフォルトの認証情報チェーン（CredentialClient）を使用して、認証情報を自動的に取得します。サポートされる情報源は、優先順位の高い順に次のとおりです。

1. 環境変数（ALIBABA_CLOUD_ACCESS_KEY_ID / ALIBABA_CLOUD_ACCESS_KEY_SECRET）
2. 設定ファイル（~/.alibabacloud/credentials）
3. ECS インスタンス RAM ロール
4. OIDC ロール ARN

セキュリティルール：

• AK/SK の値を読み取ったり、表示したり、出力したりすることは絶対にしないでください
• 会話やコマンドラインで、AK/SK を直接入力するようユーザーに求めることは絶対にしないでください
• コード内で AK/SK を明示的に処理または渡すことは絶対にしないでください。デフォルトの認証情報チェーンを利用してください

認証情報の設定については、https://help.aliyun.com/document_detail/378659.html を参照してください。

RAM 権限

このスキルでは読み取り専用操作（List / Get）のみを行います。必要な権限の一覧については、references/ram-policies.md を参照してください。

[必須] 権限エラーへの対応： 実行中のいずれかの時点で、権限エラーが原因でコマンドまたは API 呼び出しが失敗した場合は、次の手順に従ってください。

1. references/ram-policies.md を読み、このスキルで必要な権限の一覧を確認します
2. 必要な権限が付与されたことをユーザーが確認するまで待機します

パラメーターの確認

重要：パラメーターの確認 — API を呼び出す前に、 次のユーザー固有のパラメーターをユーザーに確認してください。推測してはいけません。 リージョンのデフォルトは cn-hangzhou です。ユーザーが指定しない場合は、確認せずにデフォルトを使用してください。

パラメーター	必須	説明	デフォルト
region	いいえ	リージョン ID	cn-hangzhou
catalog_name	条件付き	カタログ名（--catalog。GetCatalog に必要）	-
catalog_id	条件付き	カタログ ID（--catalog-id。データベース／テーブルのクエリに必要。例：clg-paimon-xxxx）	-
database	条件付き	データベース名（--database）	-
table	条件付き	テーブル名（--table）	-

コアワークフロー

スクリプトは環境変数から AK/SK を自動的に読み取り、値が設定されていない場合は明確なエラーを報告します。 リージョンのデフォルトは cn-hangzhou です。ユーザーが指定しない場合はデフォルトを使用してください。

メタデータのクエリには 必ず scripts/dlf_metadata_query.py を使用してください。シェルベースのコマンドラインクライアントや curl は使用しないでください。アクション名には kebab-case を使用します。

重要 — list と list-*-details のどちらを使うか：要件を満たす最も軽量なアクションを選んでください。

• 名前／ID の一覧表示（あいまい検索を含む）には、list-databases／list-tables を使用してください。これらは ListDatabases／ListTables API を呼び出します。
• 属性／Schema／プロパティの全情報には、list-database-details／list-table-details／get-database／get-table を使用してください。これらは、より負荷の高い *-details／Get* API を呼び出します。
• ユーザーが設定全体、Schema、またはプロパティを明示的に求めていない限り、デフォルトでは軽量な list-* アクションを使用してください。名前だけが必要なときに list-*-details を呼び出すのは誤りです。

クエリ操作

# ---- Catalog ----

# 1. List all Catalogs (names + minimal info — preferred for listing/searching)
python3 scripts/dlf_metadata_query.py list-catalogs

# 2. Fuzzy-search Catalogs by name (uses ListCatalogs)
python3 scripts/dlf_metadata_query.py list-catalogs --pattern test

# 3. Get Catalog details (by name) — use only when full Catalog config is needed
python3 scripts/dlf_metadata_query.py get-catalog --catalog <catalog_name>

# 4. Get Catalog details (by ID) — use only when full Catalog config is needed
python3 scripts/dlf_metadata_query.py get-catalog-by-id --id <catalog_id>

# ---- Database ----

# 5. List databases (NAMES only — DEFAULT for "list / show / which databases", calls ListDatabases)
python3 scripts/dlf_metadata_query.py list-databases --catalog-id <catalog_id>

# 6. List database details (full attributes, calls ListDatabaseDetails) — use ONLY when the user asks for properties / configs / location / owner
python3 scripts/dlf_metadata_query.py list-database-details --catalog-id <catalog_id>

# 7. Get a single database's details (calls GetDatabase) — use when the user asks for ONE specific database's full info
python3 scripts/dlf_metadata_query.py get-database --catalog-id <catalog_id> --database <db_name>

# ---- Table ----

# 8. List tables (NAMES only — DEFAULT for "list / show / which tables", calls ListTables)
python3 scripts/dlf_metadata_query.py list-tables --catalog-id <catalog_id> --database <db_name>

# 9. Fuzzy-search tables by name (DEFAULT for "search / find tables matching ...", calls ListTables)
python3 scripts/dlf_metadata_query.py list-tables --catalog-id <catalog_id> --database <db_name> --pattern user%

# 10. List table details with Schema (calls ListTableDetails) — use ONLY when the user explicitly asks for Schema / columns / properties of all tables
python3 scripts/dlf_metadata_query.py list-table-details --catalog-id <catalog_id> --database <db_name>

# 11. Get a single table's details with Schema (calls GetTable) — use when the user asks for ONE specific table's Schema
python3 scripts/dlf_metadata_query.py get-table --catalog-id <catalog_id> --database <db_name> --table <table_name>

リージョンを指定する（デフォルトは cn-hangzhou）：--region cn-shanghai を追加します。

一般的なクエリの流れ

1. list-catalogs          → get catalog_name and catalog_id (names only)
2. list-databases         → use catalog_id to view available database names
3. list-tables            → use catalog_id + database to view available table names
4. get-table              → use catalog_id + database + table to view ONE table's Schema

Schema はユーザーが実際に求めている情報であるため、手順 4（get-table）のみが「詳細」呼び出しです。手順 1～3 では、軽量な list-* アクションを使用します。

あいまい検索

すべての list 操作は、% をワイルドカードとして使用するあいまいな名前検索用の --pattern 引数に対応しています。ユーザーが一致したすべての項目の Schema／プロパティ全体を明示的に求めていない限り、パターン検索には軽量な list-* アクションを使用してください。

# Search Catalogs whose name contains "test"
python3 scripts/dlf_metadata_query.py list-catalogs --pattern %test%

# Search databases whose name starts with "prod_"
python3 scripts/dlf_metadata_query.py list-databases --catalog-id <catalog_id> --pattern prod_%

# Search tables whose name starts with "user" (DEFAULT — calls ListTables)
python3 scripts/dlf_metadata_query.py list-tables --catalog-id <catalog_id> --database <db_name> --pattern user%

アンチパターン：名前による検索に list-table-details --pattern ... を使用しないでください。これは ListTableDetails を呼び出し、必要以上に負荷が高くなります。一致したすべてのテーブルの Schema／カラムをユーザーが明示的に求めている場合に限り、list-table-details を使用してください。

出力形式

• List 操作：{"count": N, "items": [...]}
• Get 操作：単一の JSON オブジェクト
• エラー：{"error": "...", "hint": "..."}

検証

list-catalogs が Catalog の一覧を返す場合、接続と権限は正常に機能しています。

python3 scripts/dlf_metadata_query.py list-catalogs --region cn-hangzhou

詳しい検証手順については、references/verification-method.md を参照してください。

ベストプラクティス

1. list-*-details／get-* より、軽量な list-* アクションを優先してください。 リソースの名前、ID、またはあいまい検索の一覧表示だけが必要な場合は、ListCatalogs／ListDatabases／ListTables を呼び出す list-catalogs／list-databases／list-tables を必ず使用してください。list-*-details または get-* を使用するのは、ユーザーが設定全体、Schema、カラム、プロパティ、所有者、またはロケーションを明示的に求めている場合に限ります。軽量な API で要件を満たせるのに、より負荷の高い API を使用するのは誤りです。
2. Get の前に List を使用する：まず list-catalogs で catalog_id を取得し、次にその catalog_id を使ってデータベースとテーブルをクエリします。
3. 軽量なアクションであいまい検索を行う：--pattern 引数はあいまい検索に対応しています。完全な Schema も求められている場合を除き、list-table-details ではなく list-tables で使用してください。
4. ページネーション：データ量が多い場合は、ページ分けされたクエリに --max-results と --page-token を使用してください。
5. Catalog ID と名前の違い：Database／Table のクエリには、Catalog 名ではなく catalog_id（例：clg-paimon-xxxx）を使用してください。

参考資料

参考資料	説明
references/related-apis.md	API の一覧とパラメーターの説明
references/ram-policies.md	RAM 権限ポリシー
references/acceptance-criteria.md	受け入れ基準
references/verification-method.md	検証方法
DLF API overview	公式 API ドキュメント
DLF product documentation	製品ドキュメント
Python SDK PyPI	SDK バージョン情報