Entity 查询：可观测性系统中的“实体搜索引擎”，实战指南！

作者：路遥

点击此处，查看视频演示！

背景

在可观测性系统中，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 中，存在三种不同类型的查询：

EntityStore 是 UModel 系统中的统一存储引擎，负责存储和管理可观测性领域的核心 Metadata 数据，包括 UModel 元数据、实体数据和实体关系数据。它为可观测性分析提供高性能的数据存储和查询能力。

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

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 文档：docs.python.org/3/library/f...

域和类型过滤模式

-- 匹配模式示例
.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.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.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

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

总结

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

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

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

点击此处查看视频演示。