UModel查询基础：实体检索和分析

1. 背景

在可观测性系统中，UModel定义了统一的数据模型（Schema），UModel查询专注于探索知识图谱元数据，而Entity查询则用于查询和检索具体的实体实例数据。Entity查询基于USearch引擎，提供了强大的全文检索、精确查找、条件过滤等能力，支持跨域、跨实体类型的联合查询。

与UModel查询关注Schema定义不同，Entity查询专注于运行时实体数据，帮助用户快速定位、检索和分析具体的实体实例，如服务实例、Pod实例、主机实例等。

1.1 Entity查询解决的问题

在实际的可观测性场景中，我们经常需要：

1. 快速定位实体：根据关键词、属性值快速找到相关实体
2. 跨域检索：在多个域（APM、K8s、云资源等）中联合搜索
3. 精确查询：根据已知的实体ID批量查询详细信息
4. 条件过滤：基于实体属性进行复杂的条件筛选
5. 统计分析：对实体数据进行聚合分析和计算

Entity查询通过USearch引擎的统一接口，解决了传统多系统查询的痛点，提供了高效、灵活的实体检索能力。

1.2 三种查询类型的区别

在EntityStore中，存在三种不同类型的查询：

Entity查询专注于实体实例数据，是日常运维和问题排查中最常用的查询方式。

2. Entity查询介绍

2.1 数据模型

三层存储结构

USearch采用分层存储结构，确保数据的逻辑隔离和高效查询：

1. Workspace层：最顶层隔离单位，不同workspace之间完全隔离
2. Domain层：域级别的分类，用于业务逻辑分组（如apm、k8s、acs等）
3. EntityType层：具体的实体类型，包含实际的实体数据（如apm.service、k8s.pod等）

Workspace: my-observability
├── Domain: apm
│ ├── EntityType: apm.service
│ ├── EntityType: apm.host 
│ └── EntityType: apm.instance
├── Domain: k8s
│ ├── EntityType: k8s.pod
│ ├── EntityType: k8s.node
│ └── EntityType: k8s.service
└── Domain: acs
├── EntityType: acs.ecs.instance
└── EntityType: acs.rds.instance
 

数据存储特点

• 唯一性保证：在同一EntityType下，__entity_id__保证唯一性
• 列式存储：支持多行多列的表结构数据，支持SPL进行统计分析
• 索引优化：针对检索场景进行全文索引优化，支持多关键词检索和Ranking打分
• 时序支持：支持基于时间范围的数据查询和过滤，支持回溯任意时刻的实体和关系状态

2.2 USearch核心功能

检索能力

USearch提供强大的全文检索能力，支持：

• 多类型联合检索：跨多个domain和entity_type进行联合查询，统一打分排序
• 多关键词检索打分：基于词权重、字段权重等信息计算相关性分数
• 智能分词：自动分词和相关性打分，提高检索准确性

-- 检索所有domain中包含"cart"的实体
.entity with(domain='*', name='*', query='cart')

扫描能力

除了检索模式，USearch还支持扫描模式，读取原始数据后通过SPL进行更多的过滤和计算，适用于需要复杂数据处理的场景。

-- 扫描apm域中香港区域的应用数量
.entity with(domain='apm', name='apm.service') 
| where region_id = 'cn-hongkong'
| stats count = count()

2.3 查询语法

基础语法结构

.entity with(
domain='domain_pattern', -- 域过滤模式
name='type_pattern', -- 类型过滤模式 
query='search_query', -- 查询条件
topk=10, -- 返回条数
ids=['id1','id2','id3'] -- 精确ID查询
)

参数详解

fnmatch语法说明：支持通配符匹配，如*匹配任意字符，?匹配单个字符。参考fnmatch文档

域和类型过滤模式

-- 匹配模式示例
.entity with(domain='ac*') -- ac开头的domain
.entity with(domain='a*c') -- a开头、c结尾的domain 
.entity with(name='*instance') -- 以instance结尾的类型
.entity with(name='k8s.*') -- k8s域下的所有类型
.entity with(domain='*', name='*') -- 所有domain和类型

3. 查询模式详解

3.1 精确ID查询

当知道具体的实体ID时，使用ids参数进行精确查询：

-- 查询特定ID的实体
.entity with(
domain='apm', 
name='apm.service', 
ids=['4567bd905a719d197df','973ad511dad2a3f70a']
)

适用场景：

• 根据告警中的实体ID查询详细信息
• 验证特定实体的存在性和状态
• 批量查询已知ID的实体信息

3.2 全文检索模式

基础全文搜索

-- 简单关键词搜索
.entity with(query='web application')

-- 多词OR关系（默认行为）
.entity with(query='kubernetes docker container')

搜索特性：

• 多个词之间是OR关系，出现任意一个词即满足条件
• 搜索所有字段，包括系统字段和自定义字段
• 自动分词和相关性打分

短语搜索

对于通过符号连接（-）的词，必须在同一字段下完整匹配：

-- 完整短语匹配
.entity with(query='opentelemetry.io/name-fraud-detection')

-- 普通搜索（命中任意一个词）
.entity with(query='opentelemetry.io/name cart')

字段限定搜索

指定在特定字段中搜索：

-- 在描述字段中搜索
.entity with(query='description:"error handling service"')

-- 在自定义属性中搜索
.entity with(query='cluster_name:production')

-- 在标签中搜索
.entity with(query='labels.team:backend')

逻辑条件组合

支持and、or、not逻辑运算符：

-- AND条件：同时满足两个条件
.entity with(query='service_name:web AND status:running')

-- OR条件：满足任一条件
.entity with(query='environment:prod OR environment:staging')

-- NOT条件：满足左侧、不满足右侧
.entity with(query='type:service NOT status:stopped')

-- 复杂组合
.entity with(query='(cluster:prod OR cluster:staging) AND NOT status:maintenance')

特殊字符处理：

• 包含特殊字符（如|、:）的查询必须用双引号包含
• 示例：query='description:"ratio is 1:2"'

3.3 多类型联合检索

支持跨多个domain和entity_type进行联合查询，统一打分排序：

-- 检索所有domain中包含"cart"的实体
.entity with(domain='*', name='*', query='cart') 

-- 检索所有domain中包含"service"的实体类型，属性中存在"production"的实体
.entity with(domain='*', name='*service*', query='production')

-- 检索特定domain下的多种实体类型，属性中存在"error"或"rate"的实体
.entity with(domain='apm', name='apm.*', query='error rate')

3.4 结合SPL进行数据计算分析

无论检索模式还是扫描模式，都可以结合SPL进行更深入的数据计算：

-- 检索apm域中在香港区域的不同语言的应用数量，按照应用数量降序排列
.entity with(domain='apm', name='apm.service') 
| where region_id = 'cn-hongkong'
| stats count = count() by language 
| project language, count 
| sort count desc

4. 打分和排序机制

4.1 相关性打分

USearch使用多因素综合打分算法：

1. 词频权重：关键词在文档中出现的频率
2. 字段权重：不同字段的重要性权重（如名称字段权重高于描述字段）
3. 文档长度：较短文档中的匹配通常得分更高
4. 逆文档频率：稀有词汇获得更高权重

4.2 排序规则

默认按相关性分数降序排列，分数相同时按时间戳排序：

-- 默认相关性排序
.entity with(query='web service error', topk=20)

-- 结合SPL自定义排序
.entity with(query='kubernetes pod')
| sort __last_observed_time__ desc
| limit 50

-- 多字段排序
.entity with(domain='apm', name='apm.service')
| sort cluster asc, service_name asc

5. Entity查询具体应用场景

5.1 场景一：快速定位和检索实体

问题描述：线上出现告警或需要查找特定实体时，需要快速定位相关实体实例。

解决方案：根据场景选择不同的查询方式

-- 方式1：根据告警中的实体ID精确查询
.entity with(
domain='apm', 
name='apm.service', 
ids=['4567bd905a719d197df','973ad511dad2a3f70a']
)

-- 方式2：根据关键词全文检索
.entity with(query='user-service error', topk=10)

-- 方式3：字段限定精确查询
.entity with(query='service_name:user-service')

-- 方式4：通过标签查找特定团队的服务
.entity with(
domain='apm', 
name='apm.service', 
query='labels.team:backend AND labels.language:java AND status:running'
)

效果：快速获取问题实体的完整信息，包括状态、属性、标签等，支持多种查询方式满足不同场景需求。

5.2 场景二：跨域联合检索

问题描述：需要在多个域（APM、K8s、云资源等）中搜索包含特定关键词的实体，避免在多系统间切换。

解决方案：使用多类型联合检索

-- 在所有域中搜索包含"error"的实体
.entity with(domain='*', name='*', query='error', topk=50)

-- 检索特定前缀domain下的多种实体类型
.entity with(domain='apm*', name='*', query='error', topk=50)

效果：统一接口检索跨域实体，打破数据孤岛，提高查询效率。

5.3 场景三：条件过滤和数据分析

问题描述：需要找出满足特定条件的实体，并进行统计分析，识别问题模式或进行数据洞察。

解决方案：结合SPL进行条件过滤和聚合分析

-- 找出java语言的apm服务，按集群统计
.entity with(domain='apm', name='apm.service') 
| where language='java'
| stats count=count() by cluster

-- 查询生产环境或预发环境中运行的服务
.entity with(query='(environment:prod OR environment:staging) AND status:running')
| stats count=count() by environment, cluster

-- 检索apm域中ARMS生产应用在不同区域的数量，按照应用数量降序排列
.entity with(domain='apm', query='environment:prod') 
| where telemetry_client='ARMS' 
| stats service_count = count() by service, region_id 
| project region_id, service, service_count 
| sort service_count desc

效果：快速识别问题实体，进行数据聚合分析，发现数据模式。

6. 性能优化建议

6.1 使用精确匹配

字段限定查询比全文搜索更高效：

-- ❌ 全文搜索（较慢）
.entity with(query='production')

-- ✅ 字段限定（更快）
.entity with(query='environment:production')

6.2 避免前缀通配符

后缀通配符比前缀通配符性能更好：

-- ❌ 前缀通配符（较慢）
.entity with(name='*service')

-- ✅ 后缀通配符（更快）
.entity with(name='service*')

6.3 合理使用逻辑运算符

简单的AND条件比复杂的OR条件更高效：

-- ✅ 简单AND条件
.entity with(query='status:running AND cluster:prod')

-- ⚠️ 复杂OR条件（性能较差）
.entity with(query='name:a OR name:b OR name:c OR name:d')

6.4 合理设置topk

根据实际需求设置topk值，避免返回过多不必要的数据：

-- 只需要前10条结果
.entity with(query='error', topk=10)

-- 需要更多结果时再增加
.entity with(query='error', topk=100)

7. 总结

Entity查询作为EntityStore中用于查询实体实例的核心接口，为可观测性场景提供了强大的检索和分析能力。通过Entity查询，用户可以：

1. 快速定位：通过关键词、ID、条件快速找到目标实体
2. 跨域检索：统一接口查询多个域的实体数据
3. 精确查询：支持字段限定、逻辑组合等精确查询方式
4. 数据分析：结合SPL进行复杂的数据过滤和统计分析

这些能力使得Entity查询成为日常运维、问题排查、数据分析等场景中不可或缺的工具，为可观测性数据的有效利用提供了坚实的基础。