How do I install the Umodel Query skill?

Run npx skillmds@latest add alibaba/umodel-query in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Umodel Query safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Umodel Query?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Umodel Query free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Umodel Query?

alibaba (@alibaba) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Umodel Query by alibaba — Agent Skill

Name: Umodel Query
Author: alibaba

Umodel Query

Read from a UModel object-graph semantic layer with the `umctl` CLI (MCP alternative noted). Three kinds of read: (1) entities & relationships / topology (`.entity`, `.topo`) and (2) the model itself (`.umodel`, and `.entity_set` methods, including entity-linked `list_skills`) return real rows; (3) metrics & logs (`get_metrics` / `get_logs`) return an executable *plan* — PromQL / Elasticsearch DSL with the entity id pre-substituted — that you run against the backend. Against a PaaS endpoint the same calls return data rows instead of a plan. Use to query or read UModel entities, relations, topology, or model metadata; to read a service's metrics or logs; to look up services and dependencies; or to discover what objects, datasets, and methods exist. For root-cause analysis on top of these reads, see the `umodel-rca` skill. Triggers: UModel, object graph, .entity / .topo / .umodel / .entity_set, query entities, read topology, read metrics / logs, get_metrics / get_logs, list services / dependencies / datasets /

alibaba be39d18 6 files · 24.2 KB Updated Sep 17, 2026

File contents

UModel Query — read entities, relationships, the model, and telemetry

UModel is an object-graph semantic layer: enterprise objects (services, Pods, deployments, config changes, promotions, …), their typed relationships (calls, depends_on, affects, …), and the datasets (metrics, logs) hanging off them — all read through one SPL surface via the umctl CLI (MCP alternative at the bottom).

This file is the overview + setup. Each query surface has a focused guide under references/ — read the one your task needs (don't load them all).

Setup (CLI-first)

1. Ensure umctl is on PATH — UModel's read CLI:

command -v umctl || go install github.com/alibaba/UnifiedModel/cmd/umctl@latest   # needs Go 1.22+

No Go toolchain? Download a prebuilt umctl from the repo's Releases, or build from a clone (make build-cli → ./bin/umctl). Verify with umctl version.

2. Point umctl at your UModel server — set the address explicitly (flag, env, or a saved profile):

umctl --addr http://<host>:8080 query run <workspace> "<SPL>" -o json   # per call
export UMCTL_ADDR=http://<host>:8080                                    # or for the session
umctl configure                                                         # or save a profile

3. Pick the workspace — every read takes a workspace name. List what the server has and use the one your data lives in (the bundled demo is demo):

umctl workspace list -o json

No server yet? The bundled demo serves one with sample data on :8080: make quickstart QUICKSTART_SAMPLE=examples/incident-investigation (needs a repo clone + Go).

Always pass -o json. Plain reads put column names in data.header and rows in data.data (a matrix) — zip them to read records. (Entity-call results wrap differently; see the entity-set guide.)

Query surfaces — open the reference you need

Your goal	SPL surface	Guide
Read objects (services, deployments, config changes…) by type / search / id	`.entity`	references/entity.md
Traverse relationships, dependencies, topology	`.topo`	references/topology.md
List what object types / datasets / links / runbooks exist	`.umodel`	references/model.md
Call an EntitySet's methods (discover via `__list_method__`, list datasets or Skills)	`.entity_set \| entity-call`	references/entity-set.md
Read a service's metrics / logs (fetch a plan, then run it)	`get_metrics` / `get_logs`	references/metrics-logs.md

How they relate: .umodel defines the types. The domain + name you pass everywhere names one of those definitions — for .entity / .entity_set it's an EntitySet (.umodel with(kind='entity_set')); for get_metrics / get_logs it's a MetricSet / LogSet. .entity reads the runtime instances of an EntitySet; .entity_set calls methods on the EntitySet itself; the same domain/name join them.

Typical flow: .umodel to learn the types → .entity to find an object and grab its __entity_id__ → .topo / .entity_set / telemetry build on that id.

Notes

Stay read-only.
.entity / .topo / .umodel reads return real rows in open source. get_metrics / get_logs return an executable plan you run against Prometheus / Elasticsearch (or, against a PaaS endpoint with mode='data', rows directly) — see references/metrics-logs.md.
MCP alternative (instead of the CLI): connect umodel-mcp and call the query_spl_execute tool with { "workspace": "demo", "query": "<the same SPL>" } (arg key is query, not spl). Same SPL, same results.

---name: umodel-querydescription: Read from a UModel object-graph semantic layer with the `umctl` CLI (MCP alternative noted). Three kinds of read: (1) entities & relationships / topology (`.entity`, `.topo`) and (2) the model itself (`.umodel`, and `.entity_set` methods, including entity-linked `list_skills`) return real rows; (3) metrics & logs (`get_metrics` / `get_logs`) return an executable *plan* — PromQL / Elasticsearch DSL with the entity id pre-substituted — that you run against the backend. Against a PaaS endpoint the same calls return data rows instead of a plan. Use to query or read UModel entities, relations, topology, or model metadata; to read a service's metrics or logs; to look up services and dependencies; or to discover what objects, datasets, and methods exist. For root-cause analysis on top of these reads, see the `umodel-rca` skill. Triggers: UModel, object graph, .entity / .topo / .umodel / .entity_set, query entities, read topology, read metrics / logs, get_metrics / get_logs, list services / dependencies / datasets / ---# UModel Query — read entities, relationships, the model, and telemetryUModel is an **object-graph semantic layer**: enterprise objects (services, Pods,deployments, config changes, promotions, …), their typed relationships (`calls`,`depends_on`, `affects`, …), and the datasets (metrics, logs) hanging off them — all readthrough one SPL surface via the `umctl` CLI (MCP alternative at the bottom).This file is the **overview + setup**. Each query surface has a focused guide under[`references/`](references/) — **read the one your task needs** (don't load them all).## Setup (CLI-first)**1. Ensure `umctl` is on PATH** — UModel's read CLI:```bashcommand -v umctl || go install github.com/alibaba/UnifiedModel/cmd/umctl@latest # needs Go 1.22+```No Go toolchain? Download a prebuilt `umctl` from the repo's Releases, or build from a clone(`make build-cli` → `./bin/umctl`). Verify with `umctl version`.**2. Point `umctl` at your UModel server** — set the address explicitly (flag, env, or asaved profile):```bashumctl --addr http://<host>:8080 query run <workspace> "<SPL>" -o json # per callexport UMCTL_ADDR=http://<host>:8080 # or for the sessionumctl configure # or save a profile```**3. Pick the workspace** — every read takes a workspace name. List what the server has anduse the one your data lives in (the bundled demo is `demo`):```bashumctl workspace list -o json```> No server yet? The bundled demo serves one with sample data on `:8080`:> `make quickstart QUICKSTART_SAMPLE=examples/incident-investigation` (needs a repo clone + Go).**Always pass `-o json`.** Plain reads put column names in `data.header` and rows in`data.data` (a matrix) — zip them to read records. (Entity-call results wrap differently; seethe entity-set guide.)## Query surfaces — open the reference you need| Your goal | SPL surface | Guide ||---|---|---|| Read objects (services, deployments, config changes…) by type / search / id | `.entity` | [references/entity.md](references/entity.md) || Traverse relationships, dependencies, topology | `.topo` | [references/topology.md](references/topology.md) || List what object types / datasets / links / runbooks exist | `.umodel` | [references/model.md](references/model.md) || Call an EntitySet's methods (discover via `__list_method__`, list datasets or Skills) | `.entity_set \| entity-call` | [references/entity-set.md](references/entity-set.md) || Read a service's **metrics / logs** (fetch a plan, then run it) | `get_metrics` / `get_logs` | [references/metrics-logs.md](references/metrics-logs.md) |**How they relate:** `.umodel` defines the **types**. The `domain` + `name` you passeverywhere names one of those definitions — for `.entity` / `.entity_set` it's an**EntitySet** (`.umodel with(kind='entity_set')`); for `get_metrics` / `get_logs` it's a**MetricSet** / **LogSet**. `.entity` reads the runtime **instances** of an EntitySet;`.entity_set` calls **methods** on the EntitySet itself; the same `domain`/`name` join them.Typical flow: `.umodel` to learn the types → `.entity` to find an object and grab its`__entity_id__` → `.topo` / `.entity_set` / telemetry build on that id.## Notes- Stay **read-only**.- `.entity` / `.topo` / `.umodel` reads return **real rows** in open source. `get_metrics` / `get_logs` return an executable *plan* you run against Prometheus / Elasticsearch (or, against a PaaS endpoint with `mode='data'`, rows directly) — see [references/metrics-logs.md](references/metrics-logs.md).- **MCP alternative** (instead of the CLI): connect `umodel-mcp` and call the `query_spl_execute` tool with `{ "workspace": "demo", "query": "<the same SPL>" }` (arg key is `query`, not `spl`). Same SPL, same results.

Frequently asked questions