AI 助理
备案控制台
官方文档
输入文档关键字查找
首页 云监控 云监控2.0 操作指南 常驻应用 实体探索 USearch

USearch

更新时间：
产品详情
我的收藏

USearch 是云监控 2.0 中以查询实体为目的 SPL 语法，支持多种查询模式，包括全文检索、精确查找、条件过滤等。USearch 深度集成在云监控 2.0 中，包括全局快速查询、字段快捷下钻、指标下钻等。

在控制台中使用 USearch

全局快速查询

功能入口： 登录云监控2.0控制台，进入任意工作空间（WorkSpace），在左侧导航栏单击择快速查询。

  1. 在输入框中输入查询语句（USearch SPL 语法中的 query 部分），然后单击查询，查询结果会显示在下方结果区域。

  2. 在左侧选择域（Domain）和实体类型（EntitySet），然后单击查询，查询结果会显示在下方结果区域。

  3. 在左侧列表中选择查询实体结果，右边展示该实体的详细信息以及环境指标。

实体查询

功能入口： 登录云监控2.0控制台，进入任意工作空间（WorkSpace），在左侧导航栏单击择实体探索。

  • 在输入框中输入查询语句（USearch SPL 语法中的 query 部分），然后单击查询，查询结果会显示在下方结果区域。此处和快速查询的查询结果一致。

  • 切换到 SPL 查询模式，输入 SPL 查询语句（完整 USearch SPL 语法），然后单击查询，查询结果会显示在下方结果区域。

字段快捷下钻

功能入口： 登录云监控2.0控制台，进入任意实体的查询页面、仪表盘等页面，鼠标悬浮在字段上，会显示image（USearch）图标。单击 USearch 图标，弹出 USearch 查询框会自动填充字段内容并进行搜索，此处和快速查询的查询结果一致。

USearch 语法介绍

USearch 提供强大而灵活的查询语法，支持多种查询模式和条件组合。

基础语法结构

.entity with(
    domain='domain_pattern',     -- 域过滤
    type='type_pattern',         -- 类型过滤
    query='search_query',        -- 查询条件
    topk=10,                     -- 最大返回条数
    groupTopk=5                  -- 每个entity_type最大返回条数
)

参数说明：

参数

类型

必填

说明

示例

domain

string

否

域过滤，支持通配符

'apm'、'k8s*'、'*'

type

string

否

类型过滤，支持通配符

'apm.service'、'*service'

query

string

否

查询条件，支持多种语法

'error'、'name:web-app'

topk

int

否

最大返回条数，默认 100

50、200

groupTopk

int

否

每个 entity_type 最大返回条数

5、10

查询模式详解

1. 全文搜索

搜索所有字段内容，支持多关键词查询：

-- 简单关键词搜索
.entity with(query='ecs for rag')

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

特性说明：

  • 多个词之间默认为 OR 关系，出现任意一个词即满足条件。

  • 搜索所有字段，包括系统字段和自定义字段。

  • 自动分词和相关性打分排序。

2. 短语搜索

对于连字符连接的词组，必须在同一字段下完整匹配：

-- 精确短语匹配
.entity with(query='cms-cloud-d-user-sls-test-safat-tw7z5zqq-d558c')

匹配规则：

  • 连字符连接的词必须在同一字段下连续出现。

  • 完全匹配字段值，不支持部分匹配。

3. 字段限定搜索

在特定字段中进行精确搜索：

-- 基础字段搜索
.entity with(query='desc:"ecs for rag"')

-- 系统字段搜索
.entity with(query='__entity_id__:web-service-001')

-- 自定义字段搜索
.entity with(query='cluster_name:production')

4. 逻辑条件组合

支持复杂的逻辑运算符组合：

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

逻辑运算符说明：

  • AND：必须同时满足左右两个条件。

  • OR：满足左右任意一个条件即可。

  • NOT：满足左侧条件，但不能满足右侧条件。

特殊字符处理

当查询内容包含特殊字符时，必须使用双引号包围：

-- 包含冒号的查询
.entity with(query='description:"ratio is 1:2"')

-- 包含管道符的查询
.entity with(query='config:"value1|value2"')

-- 包含空格的查询
.entity with(query='name:"my service name"')

-- 包含逗号的查询
.entity with(query='list:"item1,item2,item3"')

-- 包含分号的查询
.entity with(query='command:"start; stop; restart"')

-- 包含反斜杠的查询
.entity with(query='path:"C:\\Program Files\\App"')

需要转义的特殊字符：: ( ) \ [ ] > < = , { } ; | " ' \r \n \t

重要

  • 当查询值包含上述任意特殊字符时，必须将整个值用双引号 " 包围。

  • 对于包含双引号的值，使用\转义字符。

域和类型过滤

通配符支持

支持使用通配符进行模糊匹配：

-- 域过滤示例
.entity with(domain='apm')          -- 精确匹配apm域
.entity with(domain='a*')           -- 匹配以a开头的域
.entity with(domain='*cs')          -- 匹配以cs结尾的域
.entity with(domain='*')            -- 匹配所有域-- 类型过滤示例
.entity with(type='apm.service')    -- 精确匹配
.entity with(type='*.service')      -- 匹配所有以service结尾的类型
.entity with(type='apm.*')          -- 匹配apm域下的所有类型

组合过滤

可以同时使用域过滤和类型过滤：

-- 查询特定域下的特定类型
.entity with(domain='apm', type='apm.service', query='production')

-- 使用通配符组合
.entity with(domain='k8s', type='*.pod', query='error')

查询优化建议

性能优化

  • 使用字段限定：field:value 比全文搜索更高效。

  • 添加 domain/type 过滤：缩小查询范围。

  • 合理设置 topk：避免返回过多结果。

查询精度

  • 使用精确匹配：字段限定查询提供更准确的结果。

  • 组合多个条件：使用 AND 条件进行精确过滤。

  • 善用 NOT 条件：排除不需要的结果。

常用查询模式

-- 查找异常服务
.entity with(domain='apm', type='apm.service', query='status:error OR status:warning')

-- 查找生产环境实体
.entity with(query='environment:prod AND cluster:production')

打分和排序机制

相关性打分

USearch 使用多因素综合打分算法计算 query 和每行数据之间的相关度，分数越高表明相似度越高。

单个搜索词打分

单个搜索词的打分会考虑以下维度：

  1. 词的 IDF 权重（逆文档频率）

    • 包含搜索词的数据越多，表明词的重要程度越低。

    • 包含搜索词的数据越少，词的重要程度越高。

    例如：entity_id 在所有数据中只出现一次，那么 entity_id 的 IDF 分数是最高的；而高频词如 “the” 在很多数据中都出现，IDF 分数就会较低。

  2. 列的权重

    • 一个词出现在不同的列下，权重不一样。

    • PK 列、Name 列等具备比较高的权重。

    • 长度较长的文本列具备较低的权重。

    • 权重计算采用信息熵的计算方法，这是 SLS 特有的打分方法。

多词打分策略

  • 多个搜索词会把各自的分数累加。

  • 支持词频权重和字段权重的综合计算。

  • 较短文档中的匹配通常得分更高。

排序规则

输出控制参数

在 with 语法中，可以使用以下参数控制输出：

.entity with(
    query='search_term',
    topk=100,           -- 控制输出的总数据量
    groupTopk=10        -- 控制每个 entity_type 下的最大数据量
)

参数说明：

  • topk：控制输出的总数据量，默认 100。

  • groupTopk：控制每个 entity_type 下的最大数据量。

默认排序规则

  • 默认按相关性分数降序排列。

  • 分数相同时按时间戳排序。

  • 支持结合 SPL 进行自定义排序。

输出结果格式

查询结果除了原始数据外，会额外附加两列：

字段

说明

示例

__score__

搜索的相关性分数

1.0, 0.9

__query__

查询的条件

query1

输出示例
| __score__ | __query__ | __domain__ | __entity_type__ | ... |
|-----------|-----------|------------|-----------------|-----|
| 1.0       | query1    | domain1    | type1           | ... |
| 0.9       | query1    | domain2    | type2           | ... |

排序控制

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

-- 使用 groupTopk 控制每个类型的数量
.entity with(query='kubernetes pod', topk=100, groupTopk=5)

-- 结合SPL进行自定义排序
.entity with(query='kubernetes pod')
| sort __last_observed_time__ desc| limit 50-- 按分数排序查看最相关的结果
.entity with(query='web service')
| sort __score__ desc| limit 10

常见错误和解决方法

语法错误

  1. 括号不匹配。

    -- 错误示例
.entity with(query='(status:error OR status:warning')

-- 正确示例
.entity with(query='(status:error OR status:warning)')

  2. 引号不匹配。

    -- 错误示例
.entity with(query='name:"service name')

-- 正确示例
.entity with(query='name:"service name"')

查询无结果

  1. 检查特殊字符是否正确转义。

  2. 确认域和类型过滤条件是否正确。

  3. 验证字段名称拼写是否正确。

性能问题

  1. 避免过于宽泛的通配符查询。

  2. 合理使用 topk 限制结果数量。

  3. 优先使用字段限定查询而非全文搜索。

上一篇：实体拓扑下一篇：应用中心