UModel 查询_云监控(CMS)-阿里云帮助中心

概述

UModel 查询是 EntityStore 中用于查询知识图谱元数据的专用查询接口。通过.umodel查询语法，可以探索 EntitySet 定义、EntitySetLink 关系以及完整的知识图谱结构，为数据建模分析和Schema管理提供强大支持。

应用案例

当前应用案例相关素材，请参考：umodel.zip

UModel查询数据模型

查询目标

UModel 查询的目标是知识图谱的元数据，而非具体的实体实例：

查询类型	目标数据	示例
UModel 查询	知识图谱Schema	EntitySet定义、关系类型定义
Entity 查询	具体实体实例	具体的服务、Pod、主机实例
Topo 查询	实体间关系	具体的调用关系、部署关系

数据结构

UModel 查询返回的数据具有固定的五字段结构：

字段	类型	说明	示例
`__type__`	string	内置系统字段	`link`（边）或 `node`（节点）
`kind`	string	UModel元素类型	`entity_set`, `entity_set_link`, `data_link`
`metadata`	string	元数据信息	名称、描述、域信息等
`schema`	string	Schema定义	字段定义、类型约束等
`spec`	string	具体规范	存储配置、计算逻辑等

注意：metadata、schema、spec 是 JSON 格式的 string，需要使用 json_extract_scalar 函数进行提取。

查询示例

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":"应用名是在应用性能管理（APM）领域中用于标识和区分不同应用的名称。"},"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) Instances","zh_cn":"人工智能平台PAI(模型在线服务 EAS)服务实例"},"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查询语法

基础查询语法

-- 基础查询格式
.umodel | [SPL操作...]

-- 带限制条件的查询
.umodel | where <condition> | limit <count>

核心查询模式

1. List场景 - 列表查询

查询所有UModel数据（不建议使用）：

-- 列出所有umodel数据（不建议使用）
.umodel

-- 带分页的查询
.umodel | limit 0, 10

按类型过滤：

-- 查询所有EntitySet定义
.umodel | where kind = 'entity_set' | limit 0, 10

-- 查询所有EntitySetLink定义
.umodel | where kind = 'entity_set_link' | limit 0, 10

-- 查询所有边类型（关系定义）
.umodel | where __type__ = 'link' | limit 0, 10

-- 查询所有节点类型（实体定义）
.umodel | where __type__ = 'node' | limit 0, 10

按属性过滤：

-- 查询特定名称的实体定义
.umodel | where json_extract_scalar(metadata, '$.name') = 'acs.ecs.instance' | limit 0, 10

-- 查询特定域的所有定义
.umodel | where json_extract_scalar(metadata, '$.domain') = 'apm' | limit 0, 10

-- 查询多个域的定义
.umodel | where json_extract_scalar(metadata, '$.domain') in ('acs', 'apm', 'k8s') | limit 0, 10

复合条件查询：

-- 查询APM域下的所有EntitySet
.umodel 
| where kind = 'entity_set' 
  and json_extract_scalar(metadata, '$.domain') = 'apm' | limit 0, 10

-- 查询包含特定字段的EntitySet
.umodel 
| where kind = 'entity_set'
  and spec like '%service_name%' | limit 0, 10

2. 图计算场景 - 关系分析

UModel 支持基于元数据的图计算，用于分析 EntitySet 之间的关系：

基础图查询语法：

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

基础概念：

在图查询中，有两个关键性的图概念：

节点类型，即 label 信息，在 UModel 的元数据图查询中，为 <domain>@<kind>，例如 apm@entity_set。
节点 ID，即 __entity_id__ 信息，在 UModel 的元数据图查询中，为 kind::domain::name，例如 entity_set::apm::apm.service。

查询 EntitySet 的邻居关系：

-- 查询特定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

方向性关系查询：

-- 查询指向某个EntitySet的关系
.umodel 
| graph-match (s:"acs@entity_set" {__entity_id__: 'entity_set::acs::acs.ecs.instance'})
              <--(d) 
  project s, d | limit 0, 10

-- 查询从某个EntitySet出发的关系  
.umodel 
| graph-match (s:"acs@entity_set" {__entity_id__: 'entity_set::acs::acs.ack.cluster'})
              --(d) 
  project s, d | limit 0, 10

高级查询功能

JSON路径提取

由于 UModel 数据采用 JSON 结构存储，需要使用 JSON 函数进行字段提取：

-- 提取基础信息
.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


#### 复杂条件筛选

```sql
-- 多条件组合查询
.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

聚合分析

-- 按域统计EntitySet数量
.umodel 
| where kind = 'entity_set'
| extend domain = json_extract_scalar(metadata, '$.domain')
| stats entity_count = count() by domain
| sort entity_count desc

-- 分析字段复杂度
.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

性能优化建议

1. 查询优化

使用精确过滤

-- 优化前：范围过大
.umodel | where json_extract_scalar(metadata, '$.name') like '%service%'

-- 优化后：精确匹配
.umodel | where kind = 'entity_set' 
  and json_extract_scalar(metadata, '$.domain') = 'apm'
  and json_extract_scalar(metadata, '$.name') = 'apm.service'

过滤前置

-- 优化前：后期过滤
.umodel 
| extend name = json_extract_scalar(metadata, '$.name')
| where name = 'apm.service'

-- 优化后：过滤前置
.umodel 
| where json_extract_scalar(metadata, '$.name') = 'apm.service'
| extend name = json_extract_scalar(metadata, '$.name')

3. 图查询优化

明确查询范围

-- 优化前：全图搜索
.umodel | graph-match (s)-[e]-(d) project s, e, d

-- 优化后：指定起始点
.umodel 
| graph-match (s:"apm@entity_set" {__entity_id__: 'entity_set::apm::apm.service'})
              -[e]-(d) 
  project s, e, d

注意事项

1. 数据理解

UModel 查询返回的是 Schema 定义，不是具体实例数据。
查询结果反映的是数据建模的结构，而非运行时状态。
需要理解 UModel ID 的特殊格式，避免与实体 ID 混淆。

2. 查询限制

图查询功能相对基础，不支持复杂的多级跳跃。
JSON 路径操作相对复杂，需要熟悉 JSON 函数。

3. 性能考虑

UModel 数据量相对较小，但 JSON 操作可能影响性能。
避免过于复杂的 JSON 路径表达式。
合理使用过滤前置和性能友好的查询条件。