实体查询

三层存储结构

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

1. Workspace层：最顶层隔离单位，不同workspace之间完全隔离。

2. Domain层：域级别的分类，用于业务逻辑分组。

3. EntityType层：具体的实体类型，包含实际的实体数据。

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 打分。

• 时序支持：支持基于时间范围的数据查询和过滤，支持回溯任意时刻的实体和关系状态。

1. 检索能力

-- 检索所有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')

-- 多关键词OR查询
.entity with(query='kubernetes pod error', topk=50)

-- 字段权重影响打分
.entity with(query='name:cart OR ports:8080', topk=20)

2. 扫描能力

读取原始数据，通过SPL进行更多的过滤和计算：

-- 扫描后进行SPL计算
.entity with(domain='apm', name='apm.service') 
| where cpu_usage > 0.8
| stats count() by cluster

基础语法结构

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

参数详解

域和类型过滤模式

过滤方式支持使用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和类型

1. 精确ID查询

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

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

适用场景：

• 根据告警中的实体ID查询详细信息。

• 验证特定实体的存在性和状态。

• 批量查询已知ID的实体信息。

2. 全文检索模式

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

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

-- 例如原始数据中为：`{"opentelemetry.io/name":"fraud-detection"}` `{"opentelemetry.io/name":"cart"}`，搜索 `opentelemetry.io/name-fraud-detection` 则只返回 `{"opentelemetry.io/name":"fraud-detection"}`；搜索 `opentelemetry.io/name cart` 则返回所有数据-- 完整短语匹配，只返回`{"opentelemetry.io/name":"fraud-detection"}`
.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"'。

相关性打分

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

1. 词频权重：关键词在文档中出现的频率。

2. 字段权重：不同字段的重要性权重（如名称字段权重高于描述字段）。

3. 文档长度：较短文档中的匹配通常得分更高。

4. 逆文档频率：稀有词汇获得更高权重。

排序规则

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

-- 默认相关性排序
.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