DataWorks 元数据

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

数据模型：Catalog -> Database -> Table -> Column/Partition | Lineage（上游/下游） | 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 形式。将未验证的网络内容直接管道到解释器是已知的供应链 / MITM 反模式。如果用户请求自动安装且环境支持，安全模式是：下载安装器到临时文件，向用户展示其来源以供审查，然后才执行。否则，使用上方官方包管理器 / 安装器 URL。
DataWorks 插件安装 —— 产品名是 dataworks-public（不是 dataworks）。直接运行安装；现代 Aliyun CLI 按需获取插件，无需任何预先配置开关：
```bash
aliyun plugin install --names dataworks-public
```
然后刷新已安装插件（尽力而为，失败视为非致命）：
```bash
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 不必要，且被运行时安全策略拒绝。同样，不要在本 Skill 内运行任何其他 aliyun configure set ... 变体。
[必须] AI-Mode 与 User-Agent —— 在本 Skill 中运行任何 aliyun dataworks-public 命令前，启用 AI-Mode 并为会话绑定本 Skill 的 user-agent（会话开始时运行一次）：
```bash
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 —— 本 Skill 工作完成时（或在将控制权交还用户处理无关任务前），禁用 AI-Mode 以避免将本 Skill 的 user-agent 泄漏到后续 CLI 使用中：
```bash
aliyun configure ai-mode disable
```
凭证 —— 运行 aliyun configure list 检查有效 profile。
安全：绝不读取 / 回显 / 打印 AK/SK 值。绝不在 CLI 命令中传字面凭证。
aliyun configure 允许清单 —— 在本 Skill 内，唯一允许的 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 ... 形式均被禁止。如果任何允许的调用被运行时安全策略拦截，视为软跳过——继续剩余步骤，不重试、不升级、不让任务失败。
如果不存在有效 profile，请用户在本会话之外通过环境变量或交互式 aliyun configure 向导配置凭证。

规则

[必须] 无破坏性操作 —— 本 Skill 不得调用任何 delete-* / remove-* DataWorks API。具体禁止：delete-dataset、delete-dataset-version、delete-meta-collection、delete-lineage-relationship、remove-entity-from-meta-collection。如果用户请求删除，拒绝并指引他们在 DataWorks 控制台执行。
[必须] CLI 超时 —— 本 Skill 中每次 aliyun dataworks-public 调用都必须同时包含 --read-timeout 60 和 --connect-timeout 10（秒），以防止命令无限挂起。下方命令示例已嵌入这些标志；改写命令时请保留它们。如果请求超时，向用户呈现错误——不要静默重试超过一次。
[必须] 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。
[必须] 任何写入前用户确认 —— 对于任何 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。user-agent 通过前置条件章节的 AI-Mode 全局设置，因此下方无需逐命令 --user-agent 标志。所有 list 命令支持 --page-number 和 --page-size。

1. 目录与实体浏览

列出爬虫类型

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

列出目录（--parent-meta-entity-id 必填："dlf" 或 "starrocks:<instance_id>"）

aliyun dataworks-public list-catalogs --region <RegionId> --parent-meta-entity-id "<ParentMetaEntityId>" --page-size 20 --read-timeout 60 --connect-timeout 10

获取库 / 表详情

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

列出表（--parent-meta-entity-id："maxcompute-project:::project_name" 或 "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

更新表业务元数据（写入——先与用户确认；幂等：相同值可安全重新应用）

aliyun dataworks-public update-table-business-metadata --region <RegionId> --id <TableId> --readme "<description>" --read-timeout 60 --connect-timeout 10


### 2. 列与分区

列出 / 获取列

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

更新列业务元数据（写入——先与用户确认；相同值幂等）

aliyun dataworks-public update-column-business-metadata --region <RegionId> --id <ColumnId> --description "<description>" --read-timeout 60 --connect-timeout 10

列出 / 获取分区（仅 MaxCompute / HMS）

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. 数据血缘

下游：用 --src-entity-id | 上游：用 --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

两个实体间的关系

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

注册血缘关系（写入——至少一侧必须是自定义对象）。幂等性：调用前先运行上方 list-lineage-relationships 确保此 src/dst 对之间尚不存在关系；若存在，复用现有关系而非创建新的。删除超出范围——如需撤销请用控制台。

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. 数据集与版本

列出 / 获取数据集（读）

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

创建数据集（写入）。幂等性：创建前先用 --project-id 调用 list-datasets 并按 --name 搜索；若同名 + 同 origin + 同 data-type 的数据集已存在，返回其 id 而非重新创建。--init-version 必填，JSON 含 Comment/Url/MountPath。删除超出范围。

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

更新数据集（写入——先与用户确认；相同值幂等）

aliyun dataworks-public update-dataset --region <RegionId> --id <DatasetId> --name "<NewName>" --comment "<NewComment>" --read-timeout 60 --connect-timeout 10

列出 / 获取 / 预览数据集版本（读；每个数据集最多 20 个版本）

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

创建数据集版本（写入）。幂等性：创建前调用 list-dataset-versions 查找同 Url+MountPath 的现有版本；若找到则复用。配额：每个数据集最多 20 个版本。删除超出范围。

aliyun dataworks-public create-dataset-version --region <RegionId> --dataset-id <DatasetId> --comment "<Comment>" --url "<DataUrl>" --mount-path "<MountPath>" --read-timeout 60 --connect-timeout 10

更新数据集版本（写入——先与用户确认；相同值幂等）

aliyun dataworks-public update-dataset-version --region <RegionId> --id <VersionId> --comment "<NewComment>" --read-timeout 60 --connect-timeout 10


### 5. 元数据集合

列出 / 获取集合（读；type：Category 或 Album——PascalCase，不是大写）

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

创建集合（写入）。幂等性：创建前用相同 --type 调用 list-meta-collections 并搜索同名 + 同 parent-id 的；若找到则返回其 id。删除超出范围。

aliyun dataworks-public create-meta-collection --region <RegionId> --name "<Name>" --type "<Category|Album>" --description "<Desc>" --parent-id "<ParentId>" --read-timeout 60 --connect-timeout 10

更新集合（写入——先与用户确认；相同值幂等）

aliyun dataworks-public update-meta-collection --region <RegionId> --id <CollectionId> --name "<NewName>" --description "<NewDesc>" --read-timeout 60 --connect-timeout 10

列出集合中当前实体（读）

aliyun dataworks-public list-entities-in-meta-collection --region <RegionId> --id <CollectionId> --page-size 20 --read-timeout 60 --connect-timeout 10

向集合添加实体（写入）。幂等性：添加前调用 list-entities-in-meta-collection 检查实体 id 是否已存在；若存在则跳过。移除超出范围。

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）。
  • Schema 兜底 —— 若 MaxCompute 表未找到，用 :default: schema（三级模型）重试。
  • 限制 —— 每个数据集最多 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成功验证步骤