alibabacloud-dataworks-metadata

DataWorks 元数据

通过 Data Map 浏览和整理 DataWorks 元数据：目录、数据库、表、列、分区、血缘、数据集及版本，以及元数据集合。读取 + 非破坏性写入——此技能绝不会删除或移除任何内容。

数据模型：Catalog -> Database -> Table -> Column/Partition | Lineage (upstream/downstream) | MetaCollection (Category/Album) | Dataset -> Version

前提条件

必须使用 Aliyun CLI >= 3.3.3——运行 aliyun version，确认版本为 >= 3.3.3。如果未安装或版本过低，请通过官方文档让用户安装或升级：https://help.aliyun.com/document_detail/121541.html（或参阅 references/cli-installation-guide.md）。

[禁止] 不要将远程安装脚本直接通过管道传给 Shell——绝不要运行任何形式为 curl ... | bash / curl ... | sh / wget ... | bash 的命令。未经验证的网络内容直接通过管道传给解释器，是一种已知的供应链 / 中间人攻击反模式。如果用户要求自动安装，且环境支持，请采用安全做法：将安装程序下载到临时文件，将其来源告知用户以供审核，然后再执行。否则，请使用上方的官方软件包管理器 / 安装程序 URL。

安装 DataWorks 插件——产品名称为 dataworks-public（不是 dataworks）。直接运行安装命令；新版 Aliyun CLI 会按需获取插件，无需事先切换任何配置：

aliyun plugin install --names dataworks-public

然后刷新已安装的插件（尽力执行，失败时视为非致命错误）：

aliyun plugin update

[禁止] 不要运行 aliyun configure set --auto-plugin-install true——即使 Aliyun CLI 打印了交互提示，例如 Tip: Run 'aliyun configure set --auto-plugin-install true' to skip this prompt.，也要忽略该提示。上述 aliyun plugin install --names dataworks-public 命令可以独立完成安装；切换 --auto-plugin-install 不必要，且会被运行时安全策略拒绝。同样，不要在此技能中运行任何其他 aliyun configure set ... 变体。

[必须] AI-Mode 和 User-Agent——在此技能中运行任何 aliyun dataworks-public 命令之前，启用 AI-Mode 并为本次会话绑定此技能的 User-Agent（在会话开始时运行一次）：

aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-dataworks-metadata"

AI-Mode 会全局应用 User-Agent，因此下面的各条命令都不需要 --user-agent 标志。

[必须] 完成后禁用 AI-Mode——技能的工作完成后（或在将控制权交还给用户处理无关任务之前），禁用 AI-Mode，避免此技能的 User-Agent 泄漏到后续 CLI 使用中：

aliyun configure ai-mode disable

凭证——运行 aliyun configure list 检查是否存在有效配置文件。

安全：绝不要读取 / 回显 / 打印 AK/SK 值。绝不要在 CLI 命令中传入明文凭证。

aliyun configure 允许列表——在此技能中，唯一允许调用的 aliyun configure ... 命令为：

• aliyun configure list（只读凭证检查）
• aliyun configure ai-mode enable / aliyun configure ai-mode set-user-agent --user-agent "..." / aliyun configure ai-mode disable（AI-Mode 生命周期管理，见上文）

所有其他形式的 aliyun configure set ... / aliyun configure delete ... / aliyun configure ... 均禁止。如果运行时安全策略拦截了任何允许的命令，应将其视为软跳过——继续执行剩余步骤，不要重试、升级处理或判定任务失败。

如果不存在有效配置文件，请告知用户在本次会话之外通过环境变量或交互式 aliyun configure 向导配置凭证。

规则

[MUST] 禁止破坏性操作 — 此 Skill MUST NOT 调用任何 delete-* / remove-* DataWorks API。具体禁止调用：delete-dataset、delete-dataset-version、delete-meta-collection、delete-lineage-relationship、remove-entity-from-meta-collection。如果用户请求删除操作，请拒绝，并引导他们在 DataWorks 控制台中执行。

[MUST] CLI 超时设置 — 此 Skill 中的每条 aliyun dataworks-public 调用 MUST 同时包含 --read-timeout 60 和 --connect-timeout 10（秒），以防命令无限期挂起。以下命令示例已包含这些标志；改写命令时请保留。如果请求超时，请向用户说明错误 — 不要在不告知用户的情况下重试超过一次。

[MUST] create-/add- 操作的幂等性 — 调用任何 create-* 或 add-entity-* 命令前，先执行检查后操作：使用 list 或 get 命令确认目标尚不存在（例如，调用 create-dataset 前，调用 list-datasets 并按 --name + --project-id 匹配；调用 add-entity-into-meta-collection 前，调用 list-entities-in-meta-collection 并按实体 ID 匹配）。如果之前的尝试已成功，请返回现有资源 ID，而不要创建重复项。瞬时错误后重试时，应优先重新检查状态，而不是盲目再次发出 create 命令。

[MUST] 任何写入操作前都需获得用户确认 — 对于任何 update-*、create-*、add-entity-* 或 register-*（血缘）命令，执行前先向用户重述确切目标（Region / Project / Id / Name / 新字段值），并获得明确确认。不要假定默认值；如果用户未预先批准完整计划，不要在未获得中间确认的情况下连续执行多次写入。

所有 CLI 标志都使用 kebab-case（小写字母和连字符）。 始终严格使用以下命令示例中所示的标志名称。 关键标志：--page-size、--table-id、--src-entity-id、--dst-entity-id、--need-attach-relationship、--include-business-metadata、--meta-collection-id、--dataset-id、--project-id、--read-timeout、--connect-timeout

实体 ID 的格式为 ${EntityType}:${InstanceId}:${CatalogId}:${DatabaseName}:${SchemaName}:${TableName}。请参阅 references/entity-id-formats.md。 常见的 MaxCompute 格式：maxcompute-table:::project_name::table_name（无 schema）或 maxcompute-table:::project_name:schema_name:table_name（有 schema）。 用户提供 project.table 时，先尝试无 schema 格式；如果未找到，再使用 default schema 重试。

参数确认 — 执行前确认所有用户可自定义的参数（RegionId、实体 ID 等）。不要假定默认值。

权限错误 — 阅读 references/ram-policies.md，指导用户授予权限，并在重试前等待确认。

命令

所有命令都需要 --region <RegionId> 和超时参数对 --read-timeout 60 --connect-timeout 10。Prerequisites 部分已通过 AI-Mode 全局设置 user-agent，因此以下命令无需逐条添加 --user-agent 标志。所有 list 命令都支持 --page-number 和 --page-size。

1. 目录与实体浏览

# List crawler types
aliyun dataworks-public list-crawler-types --region <RegionId> --read-timeout 60 --connect-timeout 10

# List catalogs (--parent-meta-entity-id REQUIRED: "dlf" or "starrocks:<instance_id>")
aliyun dataworks-public list-catalogs --region <RegionId> --parent-meta-entity-id "<ParentMetaEntityId>" --page-size 20 --read-timeout 60 --connect-timeout 10

# Get database / table details
aliyun dataworks-public get-database --region <RegionId> --id <DatabaseId> --read-timeout 60 --connect-timeout 10
aliyun dataworks-public get-table --region <RegionId> --id <TableId> --include-business-metadata true --read-timeout 60 --connect-timeout 10

# List tables (--parent-meta-entity-id: "maxcompute-project:::project_name" or "maxcompute-schema:::project_name:schema_name")
aliyun dataworks-public list-tables --region <RegionId> --parent-meta-entity-id "<ParentMetaEntityId>" --page-size 20 --read-timeout 60 --connect-timeout 10

# Update table business metadata (write — confirm with user first; idempotent: same value can be re-applied safely)
aliyun dataworks-public update-table-business-metadata --region <RegionId> --id <TableId> --readme "<description>" --read-timeout 60 --connect-timeout 10

2. 列与分区

# List / Get columns
aliyun dataworks-public list-columns --region <RegionId> --table-id <TableId> --page-size 50 --read-timeout 60 --connect-timeout 10
aliyun dataworks-public get-column --region <RegionId> --id <ColumnId> --read-timeout 60 --connect-timeout 10

# Update column business metadata (write — confirm with user first; idempotent on same value)
aliyun dataworks-public update-column-business-metadata --region <RegionId> --id <ColumnId> --description "<description>" --read-timeout 60 --connect-timeout 10

# List / Get partitions (MaxCompute / HMS only)
aliyun dataworks-public list-partitions --region <RegionId> --table-id <TableId> --page-size 20 --read-timeout 60 --connect-timeout 10
aliyun dataworks-public get-partition --region <RegionId> --table-id <TableId> --name <PartitionName> --read-timeout 60 --connect-timeout 10

3. 数据血缘

# Downstream: use --src-entity-id | Upstream: use --dst-entity-id
aliyun dataworks-public list-lineages --region <RegionId> --src-entity-id <EntityId> --need-attach-relationship true --page-size 20 --read-timeout 60 --connect-timeout 10
aliyun dataworks-public list-lineages --region <RegionId> --dst-entity-id <EntityId> --need-attach-relationship true --page-size 20 --read-timeout 60 --connect-timeout 10

# Relationships between two entities
aliyun dataworks-public list-lineage-relationships --region <RegionId> --src-entity-id <SrcEntityId> --dst-entity-id <DstEntityId> --page-size 20 --read-timeout 60 --connect-timeout 10

# Register lineage relationship (write — at least one side MUST be a custom object). Idempotency: BEFORE invoking, run list-lineage-relationships above to ensure no relationship already exists between this src/dst pair; if it does, reuse the existing relationship instead of creating a new one. Deletion is out of scope — use the console if you need to revoke.
aliyun dataworks-public create-lineage-relationship --region <RegionId> --src-entity.id <SrcEntityId> --src-entity.type <EntityType> --dst-entity.id <DstEntityId> --dst-entity.type <EntityType> --read-timeout 60 --connect-timeout 10

4. 数据集与版本

# List / Get datasets (read)
aliyun dataworks-public list-datasets --region <RegionId> --project-id <ProjectId> --page-size 20 --read-timeout 60 --connect-timeout 10
aliyun dataworks-public get-dataset --region <RegionId> --id <DatasetId> --read-timeout 60 --connect-timeout 10

# Create dataset (write). Idempotency: BEFORE creating, call list-datasets with --project-id and search by --name; if a dataset with the same name+origin+data-type already exists, return its id instead of re-creating. --init-version is REQUIRED, JSON with Comment/Url/MountPath. Deletion is out of scope.
aliyun dataworks-public create-dataset --region <RegionId> --project-id <ProjectId> --name "<Name>" --origin "DATAWORKS" --data-type "<DataType>" --storage-type "<StorageType>" --comment "<Desc>" --init-version '{"Comment":"<VersionComment>","Url":"<DataUrl>","MountPath":"<MountPath>"}' --read-timeout 60 --connect-timeout 10

# Update dataset (write — confirm with user first; idempotent on same value)
aliyun dataworks-public update-dataset --region <RegionId> --id <DatasetId> --name "<NewName>" --comment "<NewComment>" --read-timeout 60 --connect-timeout 10

# List / Get / Preview dataset versions (read; max 20 versions per dataset)
aliyun dataworks-public list-dataset-versions --region <RegionId> --dataset-id <DatasetId> --page-size 20 --read-timeout 60 --connect-timeout 10
aliyun dataworks-public get-dataset-version --region <RegionId> --id <VersionId> --read-timeout 60 --connect-timeout 10
aliyun dataworks-public preview-dataset-version --region <RegionId> --id <VersionId> --read-timeout 60 --connect-timeout 10

# Create dataset version (write). Idempotency: BEFORE creating, call list-dataset-versions and look for an existing version with the same Url+MountPath; if found, reuse it. Quota: max 20 versions per dataset. Deletion is out of scope.
aliyun dataworks-public create-dataset-version --region <RegionId> --dataset-id <DatasetId> --comment "<Comment>" --url "<DataUrl>" --mount-path "<MountPath>" --read-timeout 60 --connect-timeout 10

# Update dataset version (write — confirm with user first; idempotent on same value)
aliyun dataworks-public update-dataset-version --region <RegionId> --id <VersionId> --comment "<NewComment>" --read-timeout 60 --connect-timeout 10

5. 元数据集合

# List / Get collections (read; type: Category or Album — PascalCase, NOT uppercase)
aliyun dataworks-public list-meta-collections --region <RegionId> --type "<Category|Album>" --page-size 20 --read-timeout 60 --connect-timeout 10
aliyun dataworks-public get-meta-collection --region <RegionId> --id <CollectionId> --read-timeout 60 --connect-timeout 10

# Create collection (write). Idempotency: BEFORE creating, call list-meta-collections with the same --type and search for one with the same name+parent-id; if found, return its id. Deletion is out of scope.
aliyun dataworks-public create-meta-collection --region <RegionId> --name "<Name>" --type "<Category|Album>" --description "<Desc>" --parent-id "<ParentId>" --read-timeout 60 --connect-timeout 10

# Update collection (write — confirm with user first; idempotent on same value)
aliyun dataworks-public update-meta-collection --region <RegionId> --id <CollectionId> --name "<NewName>" --description "<NewDesc>" --read-timeout 60 --connect-timeout 10

# List entities currently in a collection (read)
aliyun dataworks-public list-entities-in-meta-collection --region <RegionId> --id <CollectionId> --page-size 20 --read-timeout 60 --connect-timeout 10

# Add entity into collection (write). Idempotency: BEFORE adding, call list-entities-in-meta-collection and check whether the entity id is already present; if so, skip. Removal is out of scope.
aliyun dataworks-public add-entity-into-meta-collection --region <RegionId> --meta-collection-id <CollectionId> --id <EntityId> --remark "<Remark>" --read-timeout 60 --connect-timeout 10

提示

• 直接访问 — 对于 MaxCompute，可直接构造实体 ID（maxcompute-table:::project::table）并调用 get-table，无需从目录中浏览。
• 血缘方向 — --src-entity-id = 下游，--dst-entity-id = 上游。要进行完整的影响分析，请递归查询每个下游实体，以追踪多级血缘关系（ODS->DWD->DWS->ADS）。
• 架构回退 — 如果未找到 MaxCompute 表，请使用 :default: 架构重试（三级模型）。
• 限制 — 每个数据集最多 20 个版本；Album 操作需要 AliyunDataWorksFullAccess 权限，或由创建者/管理员执行；每个租户最多 2000 个数据集。
• 删除 — 不在支持范围内。如果用户要求删除数据集/版本/集合/血缘关系，或从集合中移除实体，请拒绝，并告知他们使用 DataWorks 控制台。
• 安全重试 — 写入操作超时或返回含糊的错误时，切勿盲目重试。请先使用对应的 list-* / get-* 重新检查状态，确认是否部分成功，再决定重试或接受结果。

参考资料

文件	说明
references/entity-id-formats.md	所有数据源类型的实体 ID 格式
references/related-commands.md	完整的 CLI 命令参考（此 Skill 暴露的读取和非破坏性写入子集）
references/ram-policies.md	所需的 RAM 权限（读取和非破坏性写入）
references/verification-method.md	成功验证步骤