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
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.