背景
Cloud Native
在可观测性系统中，UModel 定义了统一的数据模型（Schema），UModel 查询专注于探索知识图谱元数据，而 Entity 查询则用于查询和检索具体的实体实例数据。Entity 查询基于 USearch 引擎，提供了强大的全文检索、精确查找、条件过滤等能力，支持跨域、跨实体类型的联合查询。
与 UModel 查询关注 Schema 定义不同，Entity 查询专注于运行时实体数据，帮助用户快速定位、检索和分析具体的实体实例，如服务实例、Pod 实例、主机实例等。
在实际的可观测性场景中，我们经常需要：
快速定位实体：根据关键词、属性值快速找到相关实体
跨域检索：在多个域（APM、K8s、云资源等）中联合搜索
精确查询：根据已知的实体 ID 批量查询详细信息
条件过滤：基于实体属性进行复杂的条件筛选
统计分析：对实体数据进行聚合分析和计算
Entity 查询通过 USearch 引擎的统一接口，解决了传统多系统查询的痛点，提供了高效、灵活的实体检索能力。
在 EntityStore 中，存在三种不同类型的查询：
Entity 查询专注于实体实例数据，是日常运维和问题排查中最常用的查询方式。
Entity 查询介绍
Cloud Native
三层存储结构
USearch 采用分层存储结构，确保数据的逻辑隔离和高效查询：
Workspace 层：最顶层隔离单位，不同 workspace 之间完全隔离
Domain 层：域级别的分类，用于业务逻辑分组（如 apm、k8s、acs 等）
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 打分
时序支持：支持基于时间范围的数据查询和过滤，支持回溯任意时刻的实体和关系状态
检索能力
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()
基础语法结构
.entity with(domain='domain_pattern', -- 域过滤模式name='type_pattern', -- 类型过滤模式query='search_query', -- 查询条件topk=10, -- 返回条数ids=['id1','id2','id3'] -- 精确ID查询)
参数详解
fnmatch 语法说明：支持通配符匹配，如 * 匹配任意字符，? 匹配单个字符。参考 fnmatch 文档：https://docs.python.org/3/library/fnmatch.html。
域和类型过滤模式
-- 匹配模式示例.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和类型
查询模式详解
Cloud Native
当知道具体的实体 ID 时，使用 ids 参数进行精确查询：
-- 查询特定ID的实体.entity with(domain='apm',name='apm.service',ids=['4567bd905a719d197df','973ad511dad2a3f70a'])
适用场景：
根据告警中的实体 ID 查询详细信息
验证特定实体的存在性和状态
批量查询已知 ID 的实体信息
基础全文搜索
-- 简单关键词搜索.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"'
支持跨多个 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')
无论检索模式还是扫描模式，都可以结合 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
打分和排序机制
Cloud Native
USearch 使用多因素综合打分算法：
词频权重：关键词在文档中出现的频率
字段权重：不同字段的重要性权重（如名称字段权重高于描述字段）
文档长度：较短文档中的匹配通常得分更高
逆文档频率：稀有词汇获得更高权重
默认按相关性分数降序排列，分数相同时按时间戳排序：
-- 默认相关性排序.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 查询具体应用场景
Cloud Native
问题描述：线上出现告警或需要查找特定实体时，需要快速定位相关实体实例。
解决方案：根据场景选择不同的查询方式。
-- 方式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')
效果：快速获取问题实体的完整信息，包括状态、属性、标签等，支持多种查询方式满足不同场景需求。问题描述：需要在多个域（APM、K8s、云资源等）中搜索包含特定关键词的实体，避免在多系统间切换。
解决方案：使用多类型联合检索。
-- 在所有域中搜索包含"error"的实体.entity with(domain='*', name='*', query='error', topk=50)-- 检索特定前缀domain下的多种实体类型.entity with(domain='apm*', name='*', query='error', topk=50)
效果：统一接口检索跨域实体，打破数据孤岛，提高查询效率。
问题描述：需要找出满足特定条件的实体，并进行统计分析，识别问题模式或进行数据洞察。
解决方案：结合 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
效果：快速识别问题实体，进行数据聚合分析，发现数据模式。
性能优化建议
Cloud Native
字段限定查询比全文搜索更高效：
-- ❌ 全文搜索（较慢）.entity with(query='production')-- ✅ 字段限定（更快）.entity with(query='environment:production')
后缀通配符比前缀通配符性能更好：
-- ❌ 前缀通配符（较慢）.entity with(name='*service')-- ✅ 后缀通配符（更快）.entity with(name='service*')
简单的 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')
根据实际需求设置 topk 值，避免返回过多不必要的数据：
-- 只需要前10条结果.entity with(query='error', topk=10)-- 需要更多结果时再增加.entity with(query='error', topk=100)
总结
Cloud Native
Entity 查询作为 EntityStore 中用于查询实体实例的核心接口，为可观测性场景提供了强大的检索和分析能力。通过 Entity 查询，用户可以：
快速定位：通过关键词、ID、条件快速找到目标实体
跨域检索：统一接口查询多个域的实体数据
精确查询：支持字段限定、逻辑组合等精确查询方式
数据分析：结合 SPL 进行复杂的数据过滤和统计分析
这些能力使得 Entity 查询成为日常运维、问题排查、数据分析等场景中不可或缺的工具，为可观测性数据的有效利用提供了坚实的基础。
点击阅读原文查看视频演示。