UModel queries

Overview

UModel is a query interface in EntityStore for knowledge graph metadata. Use the .umodel syntax to explore EntitySet definitions, EntitySetLink relationships, and the complete knowledge graph structure.

Case study materials

Download the materials for this use case: umodel-enrich-dev.zip.

UModel query data model

Query target

A UModel query targets the metadata of a knowledge graph, not specific entity instances.

Query type	Target data	Example
UModel query	Knowledge graph schema	EntitySet definitions, relationship type definitions
Entity query	Specific entity instances	Specific service, pod, and host instances
Topo query	Relationships between entities	Specific call relationships, deployment relationships

Data structure

UModel queries return a fixed five-field structure.

Field	Type	Description	Example
`__type__`	string	Built-in system field	`link` (edge) or `node` (node)
`kind`	string	UModel element type	`entity_set`, `entity_set_link`, `data_link`
`metadata`	string	Metadata	Name, description, domain, etc.
`schema`	string	Schema definition	Field definitions, type constraints, etc.
`spec`	string	Specifications	Storage configurations, computing logic, etc.

The metadata, schema, and spec fields are JSON strings. Use json_extract_scalar to extract values.

Query examples

type	kind	metadata	schema	spec
node	entity_set	`{"kind":"entity_set","domain":"synthetics","name":"synthetics.task","description":{"en_us":"Synthetic Task refers to the specific endpoint or service being monitored…"}}`	`{"version":"v0.1.0","url":"umodel.aliyun.com"}`	`{"last_observed_time_field":"time","keep_alive_seconds":3600,"time_field":"time","primary_key_fields":["task_name","task_id"],"name_fields":["task_name","task_id","task_url","task_type","probe_type","task_state"]…}`
node	entity_set	`{"short_description":{"en_us":"A service name is used to identify and differentiate between various services.","zh_cn":"An application name is used in application performance management (APM) to identify and distinguish different applications."},"kind":"entity_set","domain":"apm"…}`	`{"version":"v0.1.0","url":"umodel.aliyun.com"}`	`{"last_observed_time_field":"last_observed_time","keep_alive_seconds":3600,"primary_key_fields":["service_id"],"name_fields":["service"],"dynamic":false,"ordered_fields":["service","source","language"]…}`
node	entity_set	`{"short_description":{"en_us":"Platform for AI (Elastic Algorithm Service EAS) service instances","zh_cn":"Platform for AI (Elastic Algorithm Service EAS) service instances"},"common_schema_info":{"version":"0.1.0-20250822-beta","group":"acs-learn"},"domain":"acs"...}`	`{"version":"v0.1.0","url":"umodel.aliyun.com"}`	`{"time_field":"time","primary_key_fields":["instance_id"],"name_fields":["instance_name","instance_id"],"fields":[{"filterable":true,"orderable":true,"name":"external_i_p",…}]}`

UModel query syntax

Basic query syntax

-- Basic query format
.umodel | [SPL operations...]

-- Query with conditions
.umodel | where <condition> | limit <count>

Core query modes

List queries

Query all UModel data (not recommended):

-- List all umodel data (not recommended)
.umodel

-- Query with paging
.umodel | limit 0, 10

Filter by type:

-- Query all EntitySet definitions
.umodel | where kind = 'entity_set' | limit 0, 10

-- Query all EntitySetLink definitions
.umodel | where kind = 'entity_set_link' | limit 0, 10

-- Query all edge types (relationship definitions)
.umodel | where __type__ = 'link' | limit 0, 10

-- Query all node types (entity definitions)
.umodel | where __type__ = 'node' | limit 0, 10

Filter by property:

-- Query entity definitions with a specific name
.umodel | where json_extract_scalar(metadata, '$.name') = 'acs.ecs.instance' | limit 0, 10

-- Query all definitions in a specific domain
.umodel | where json_extract_scalar(metadata, '$.domain') = 'apm' | limit 0, 10

-- Query definitions in multiple domains
.umodel | where json_extract_scalar(metadata, '$.domain') in ('acs', 'apm', 'k8s') | limit 0, 10

Multi-condition queries:

-- Query all EntitySets in the APM domain
.umodel 
| where kind = 'entity_set' 
  and json_extract_scalar(metadata, '$.domain') = 'apm' | limit 0, 10

-- Query EntitySets that contain a specific field
.umodel 
| where kind = 'entity_set'
  and spec like '%service_name%' | limit 0, 10

Graph queries

UModel supports graph queries to analyze relationships between EntitySets.

Basic graph query syntax:

.umodel | graph-match <path> project <output>

Basic concepts:

Graph queries use two key concepts:

Node type: The label value. In UModel graph queries, the format is <domain>@<kind>, such as apm@entity_set.
Node ID: The __entity_id__ value. In UModel graph queries, the format is kind::domain::name, such as entity_set::apm::apm.service.

Querying the neighbor relationships of an EntitySet:

-- Query all relationships associated with a specific EntitySet
.umodel 
| graph-match (s:"acs@entity_set" {__entity_id__: 'entity_set::acs::acs.ecs.instance'})
              -[e]-(d) 
  project s, e, d | limit 0, 10

Querying directional relationships:

-- Query relationships that point to an EntitySet
.umodel 
| graph-match (s:"acs@entity_set" {__entity_id__: 'entity_set::acs::acs.ecs.instance'})
              <--(d) 
  project s, d | limit 0, 10

-- Query relationships that originate from an EntitySet  
.umodel 
| graph-match (s:"acs@entity_set" {__entity_id__: 'entity_set::acs::acs.ack.cluster'})
              -->(d) 
  project s, d | limit 0, 10

Advanced query features

JSON path extraction

Use JSON functions to extract fields from UModel data.

-- Extract basic information
.umodel 
| extend 
    entity_name = json_extract_scalar(metadata, '$.name'),
    entity_domain = json_extract_scalar(metadata, '$.domain'),
    entity_description = json_extract_scalar(metadata, '$.description.zh_cn')
| project entity_name, entity_domain, entity_description | limit 0, 100


#### Complex conditional filtering

```sql
-- Multi-condition query
.umodel 
| where kind = 'entity_set'
  and json_extract_scalar(metadata, '$.domain') in ('apm', 'k8s')
  and json_array_length(json_extract(spec, '$.fields')) > 5
| extend 
    entity_name = json_extract_scalar(metadata, '$.name'),
    field_count = json_array_length(json_extract(spec, '$.fields'))
| sort field_count desc
| limit 20

Aggregation analysis

-- Count the number of EntitySets by domain
.umodel 
| where kind = 'entity_set'
| extend domain = json_extract_scalar(metadata, '$.domain')
| stats entity_count = count() by domain
| sort entity_count desc

-- Analyze field complexity
.umodel 
| where kind = 'entity_set'
| extend 
    domain = json_extract_scalar(metadata, '$.domain'),
    field_count = json_array_length(json_extract(spec, '$.fields'))
| stats 
    avg_fields = avg(field_count),
    max_fields = max(field_count),
    entity_count = count()
  by domain
| sort entity_count desc | limit 0, 10

Performance optimization

1. Query optimization

Use exact filters

-- Before optimization: Scope is too broad
.umodel | where json_extract_scalar(metadata, '$.name') like '%service%'

-- After optimization: Exact match
.umodel | where kind = 'entity_set' 
  and json_extract_scalar(metadata, '$.domain') = 'apm'
  and json_extract_scalar(metadata, '$.name') = 'apm.service'

Pre-filtering

-- Before optimization: Late filtering
.umodel 
| extend name = json_extract_scalar(metadata, '$.name')
| where name = 'apm.service'

-- After optimization: Early filtering
.umodel 
| where json_extract_scalar(metadata, '$.name') = 'apm.service'
| extend name = json_extract_scalar(metadata, '$.name')

3. Graph query optimization

Specify the query scope

-- Before optimization: Full graph search. This query is prohibited and returns an error due to high performance overhead.
.umodel | graph-match (s)-[e]-(d) project s, e, d

-- After optimization: Specify a starting point
.umodel 
| graph-match (s:"apm@entity_set" {__entity_id__: 'entity_set::apm::apm.service'})
              -[e]-(d) 
  project s, e, d

Considerations

1. Understanding results

UModel queries return schema definitions, not specific instance data.
Results reflect the data model structure, not runtime status.
Understand UModel ID formats to avoid confusing them with entity IDs.

2. Query limitations

Graph queries do not support complex multi-hop traversals.
JSON path operations require familiarity with JSON functions.

3. Performance considerations

UModel data volumes are small, but JSON operations can affect performance.
Avoid overly complex JSON path expressions.
Apply filters early and use performance-friendly query conditions.