DataWorks 元数据

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

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

前提条件

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

[禁止] 不得将远程安装脚本直接通过管道传入命令行解释器——严禁运行任何以下形式的命令：curl ... | bash / curl ... | sh / wget ... | bash。将未经验证的网络内容直接通过管道传入解释器，是一种已知的供应链 / MITM 反模式。如果用户请求自动安装且环境支持，安全做法是：将安装程序下载到临时文件，向用户说明其来源以供审查，之后方可执行。否则，应改用上文的官方软件包管理器 / 安装程序 URL。

DataWorks 插件安装——产品名称为 dataworks-public（而不是 dataworks）。直接运行安装命令；新版阿里云 CLI 可按需获取插件，无需预先切换任何配置开关：

```bash

aliyun plugin install --names dataworks-public

```

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

```bash

aliyun plugin update

```

[禁止] 不得运行 aliyun configure set --auto-plugin-install true——即使阿里云 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 的用户代理绑定到当前会话（在会话开始时运行一次）：

```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 标志。

[必须] 完成后禁用 AI-Mode — 当 Skill 的工作完成时（或在将控制权交还给用户以处理无关任务之前），必须禁用 AI-Mode，以免该 Skill 的用户代理泄漏到后续的 CLI 使用中：

```bash

aliyun configure ai-mode disable

```

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

安全：严禁读取/回显/打印 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 ... 形式。如果任何允许的调用被运行时安全策略拦截，应将其视为软跳过——继续执行剩余步骤，并且不得重试、升级处理或使任务失败。

如果不存在有效的配置文件，请指示用户在此会话之外通过环境变量或交互式 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-* 命令之前，必须执行先检查再执行：通过列出或获取资源，验证目标尚不存在（例如，调用 create-dataset 之前，先调用 list-datasets，并按 --name + --project-id 进行匹配；调用 add-entity-into-meta-collection 之前，先调用 list-entities-in-meta-collection，并按实体 ID 进行匹配）。如果之前的尝试已经成功，则返回现有资源 ID，而不要创建重复资源。如果在发生瞬时错误后重试，应优先重新检查状态，而不是盲目重新发出创建请求。

[必须] 任何写入前均须获得用户确认——对于任何 update-*、create-*、add-entity-* 或 register-*（血缘）命令，执行前必须向用户复述确切目标（地域 / 项目 / ID / 名称 / 新字段值），并获得明确确认。不得假定默认值；如果用户未预先批准完整计划，则不得在未进行中间确认的情况下连续执行多次写入。

所有 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（无模式）或 maxcompute-table:::project_name:schema_name:table_name（有模式）。

当用户提供 project.table 时，先尝试无模式格式；如果未找到，再使用 default 模式重试。

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

权限错误——读取 references/ram-policies.md，引导用户授予权限，并等待用户确认后再重试。

命令

所有命令都必须包含 --region <RegionId> 和一对超时参数 --read-timeout 60 --connect-timeout 10。用户代理已在前提条件部分通过 AI-Mode 全局设置，因此下方无需为每条命令添加 --user-agent 标志。所有列表命令均支持 --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 个版本；相册操作需要 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 | 成功验证步骤 |