alibabacloud-dlf-manage

DLF 数据湖元数据查询

查询阿里云 Data Lake Formation（DLF）中的 Catalog、Database 和 Table 元数据资源。

关键：只能使用此 Skill 提供的 Python SDK 脚本。 所有操作均通过 scripts/dlf_metadata_query.py 调用 DLF Python SDK（alibabacloud-dlfnext20250310）。 此 Skill 不会调用任何基于 Shell 的命令行客户端，也不需要配置 AI-Mode。

• 请勿尝试通过任何基于 Shell 的命令行客户端访问——此 Skill 不支持通过此类客户端访问 DLF
• 请勿使用 curl、wget 或其他 HTTP 客户端直接调用 DLF API
• 必须使用此 Skill 提供的 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。

身份验证

预检：需要阿里云凭证

使用默认凭证链（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 权限

此 Skill 仅涉及只读操作（List / Get）。完整权限列表请参阅 references/ram-policies.md。

[MUST] 权限失败处理： 执行过程中，任何命令或 API 调用因权限错误而失败时，请遵循以下流程：

1. 阅读 references/ram-policies.md，了解此 SKILL 所需的完整权限列表
2. 暂停操作，并等待用户确认已授予所需权限

参数确认

重要：参数确认——调用 API 前， 必须与用户确认以下特定于用户的参数；不得自行假设。 region 默认为 cn-hangzhou；若用户未指定，请直接使用默认值，无需询问。

参数	必填	说明	默认值
region	否	区域 ID	cn-hangzhou
catalog_name	有条件必填	Catalog 名称（--catalog，调用 GetCatalog 时必填）	-
catalog_id	有条件必填	Catalog ID（--catalog-id，查询数据库/表时必填，例如 clg-paimon-xxxx）	-
database	有条件必填	Database 名称（--database）	-
table	有条件必填	Table 名称（--table）	-

核心工作流

脚本会自动从环境变量中读取 AK/SK；如果缺少这些变量，会明确报错。 区域默认为 cn-hangzhou；如果用户未指定区域，请使用默认值。

必须使用 scripts/dlf_metadata_query.py 查询元数据。请勿使用基于 Shell 的命令行客户端或 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。
• 默认使用轻量级的 list-* 操作，除非用户明确要求完整配置、Schema 或属性。只需名称时调用 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

只有第 4 步（get-table）是“详情”调用，因为用户实际需要的是 Schema。第 1–3 步继续使用轻量级的 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。

输出格式

• 列表操作：{"count": N, "items": [...]}
• 获取操作：单个 JSON 对象
• 错误：{"error": "...", "hint": "..."}

验证

如果 list-catalogs 返回 Catalog 列表，则说明连接和权限正常：

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

详细验证步骤请参阅 references/verification-method.md。

最佳实践

1. 优先使用轻量级的 list-* 操作，而非 list-*-details / get-*。 如果任务只需列出资源的名称、ID或进行模糊匹配，必须使用 list-catalogs / list-databases / list-tables（这些操作会调用 ListCatalogs / ListDatabases / ListTables）。只有在用户明确要求完整配置、Schema、列、属性、所有者或位置时，才使用 list-*-details 或 get-*。轻量级操作已足够时仍调用开销更大的 API，是错误的。
2. 先 List，再 Get：先使用 list-catalogs 获取 catalog_id，再使用 catalog_id 查询数据库和表。
3. 使用轻量级操作进行模糊搜索：--pattern 参数支持模糊匹配；除非同时需要完整 Schema，否则请在 list-tables（而非 list-table-details）中使用该参数。
4. 分页：数据量较大时，使用 --max-results 和 --page-token 进行分页查询。
5. Catalog ID 与名称：查询数据库 / 表时，请使用 catalog_id（例如 clg-paimon-xxxx），而非 Catalog 名称。

参考资料

参考资料	描述
references/related-apis.md	完整的 API 列表和参数说明
references/ram-policies.md	RAM 权限策略
references/acceptance-criteria.md	验收标准
references/verification-method.md	验证方法
DLF API 概览	官方 API 文档
DLF 产品文档	产品文档
Python SDK PyPI	SDK 版本信息