/alibabacloud-dataworks-semantic

name: alibabacloud-dataworks-semantic
description: |
  Always use this Skill for any Alibaba Cloud DataWorks semantic analysis job or run request, including read-only and preflight requests that intentionally make no API call, such as checking whether the public DataWorks semantic OpenAPI or dataworks-public plugin commands (for example create-semantic-job) are ready. It also applies when the requested outcome is only a refusal or a user choice with no API call. This includes comparing or disambiguating supplied semantic job candidates, validating or refusing an unsafe, path-traversal, or non-writable semantic result directory before any download, and inspecting artifacts for an exact run. Use it to create, run, stop, monitor, diagnose, or download results for semantic jobs backed by MaxCompute, Hologres, StarRocks, or an already uploaded CSV/XLSX reference. Do not use it for ordinary metadata lookup, lineage analysis, SQL development, workflow scheduling, file upload, published semantic model/version management, or semantic job deletion.
license: Apache-2.0
metadata:
  domain: data
  owner: dataworks

DataWorks Semantic Analysis

Use only Alibaba Cloud DataWorks public OpenAPI operations exposed by the `aliyun dataworks-public` plugin to create a reusable semantic analysis job, submit or stop a run, monitor execution, and retrieve generated result files.

Prerequisites

Perform these checks once, in this order. Install or update the public DataWorks plugin before probing any product API command; do not first probe every command, discover the plugin is missing, and then repeat the same probes.

aliyun version
aliyun plugin install --names dataworks-public
aliyun plugin update

Never pipe a remote installer into a shell. If the CLI is missing or older than 3.3.3, direct the user to the official Aliyun CLI installation documentation.

Check credentials without printing secrets:

aliyun configure list

The only allowed `aliyun configure` operation in this Skill is `configure list`. Never run `aliyun configure set`, including auto-plugin-install variants.

Observability

Session-id rules

• **Generation**: Generate the session-id exactly once at the start of each user or agent session:

SEMANTIC_SESSION_ID="$(python3 -c 'import secrets; print(secrets.token_hex(16))')"

• **Format**: The session-id must be exactly 32 lowercase hexadecimal characters.
• **Consistency across CLI/SDK/Terraform**: Reuse the same session-id for every CLI command, SDK request, and Terraform operation in the session, including retries, polling, and downloads. Never regenerate it per command or when switching tools. Generate a new value only for a new user or agent session.

UA template declaration

Use this canonical CLI flag template:

--user-agent "AlibabaCloud-Agent-Skills/{SKILL_NAME}/{session-id}"

For this Skill, every Aliyun CLI product API command must explicitly include its concrete form:

--user-agent "AlibabaCloud-Agent-Skills/alibabacloud-dataworks-semantic/${SEMANTIC_SESSION_ID}"

Do not persist the User-Agent in Aliyun CLI configuration or an environment variable. Local management commands such as `aliyun version`, `aliyun plugin ...`, and `aliyun configure list` do not support the product API User-Agent flag; do not add it to them.

Public API readiness gate

After the prerequisite plugin install/update, confirm only the commands needed by the selected workflow before collecting parameters; do not probe unrelated operations or repeat a successful readiness check. For create, run, monitor, or download workflows, check the applicable commands from this public set:

aliyun dataworks-public create-semantic-job --help \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-dataworks-semantic/${SEMANTIC_SESSION_ID}"
aliyun dataworks-public run-semantic-job --help \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-dataworks-semantic/${SEMANTIC_SESSION_ID}"
aliyun dataworks-public list-semantic-job-runs --help \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-dataworks-semantic/${SEMANTIC_SESSION_ID}"
aliyun dataworks-public download-semantic-results --help \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-dataworks-semantic/${SEMANTIC_SESSION_ID}"

For an explicit stop workflow, confirm the stop and verification commands below. Also check `list-semantic-job-runs` only when identifiers must be resolved. Do not probe or call the stop command for unrelated workflows:

aliyun dataworks-public kill-semantic-job --help \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-dataworks-semantic/${SEMANTIC_SESSION_ID}"
aliyun dataworks-public get-semantic-job-detail --help \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-dataworks-semantic/${SEMANTIC_SESSION_ID}"

Probe `kill-semantic-job --help` only when you will actually issue a new kill. When a kill was already accepted and you only need to poll or report its final state, confirm just `get-semantic-job-detail`; do not probe or invoke `kill-semantic-job` again.

For an explicit diagnosis workflow, confirm only the executor detail and log commands. Do not probe the log command for a normal successful run:

aliyun dataworks-public get-semantic-job-detail --help \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-dataworks-semantic/${SEMANTIC_SESSION_ID}"
aliyun dataworks-public get-semantic-job-log --help \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-dataworks-semantic/${SEMANTIC_SESSION_ID}"

If a command is absent after one plugin update, stop and report the installed CLI and plugin versions.

Public authentication must derive the caller's tenant and user identity from the active Aliyun CLI profile. If command help requires `tenant-id` or `user-id`, stop and report that the public identity contract is not ready; never ask a customer to discover or override internal identities.

Safety rules

-