> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flashduty.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 数据查询语法指南

> 掌握 Flashduty RUM 查看器的搜索语法，通过灵活的查询条件快速定位和分析用户数据。

RUM 查看器的查询由**词项**（terms）和**操作符**（operators）组成，可以组合出复杂的检索条件；不熟悉语法时也可以用自然语言查询。

## AI 自然语言查询

不熟悉查询语法时，可以直接用自然语言（中英文均可）描述要找的数据，AI 会将其转换为标准查询语句（DQL），字段与语法与手动查询完全一致。点击查询框左侧的 **AI 自然语言查询**（魔法棒）图标进入，或在普通查询模式下按 <kbd>⌘</kbd> + <kbd>Enter</kbd>（Windows 和 Linux 为 <kbd>Ctrl</kbd> + <kbd>Enter</kbd>）；进入后输入框边框会高亮。

<Steps>
  <Step title="描述查询意图">
    用自然语言描述您想查找的数据，按 <kbd>Enter</kbd> 生成预览。例如：

    ```
    来自 Chrome 浏览器、耗时超过 2 秒的 5xx 资源请求
    ```

    AI 会将其转换为：

    ```
    browser_name:Chrome resource_status_code:>=500 resource_duration:>2s
    ```

    您无需记住字段名，AI 会按当前事件类型选择可查询的字段。
  </Step>

  <Step title="查看变更预览">
    预览显示将要加入的 DQL 条件；当请求更适合其他事件类型（如提示「将切换事件类型为 错误」）或时间范围时，也会显示相应变更。结果不理想时，修改描述后再次回车即可重新生成。
  </Step>

  <Step title="应用或撤销">
    点击 **应用**、**追加到查询** 或 **切换并应用** 确认变更。应用后，提示消息中提供 **撤销**，可恢复应用前的查询、事件类型和时间范围。
  </Step>
</Steps>

### 追加而非替换

输入框中已有查询条件时，AI 生成的条件会**追加**到现有查询之后，不会覆盖，因此可以用自然语言逐步补充筛选条件；空查询时直接应用生成结果。

<Note>
  * “最近 1 小时”“昨天”“过去 7 天”等时间表达会更新查看器的时间选择器，不会被写成 `client_time` 等 DQL 条件；性能时长条件仍属于 DQL，例如 `view_loading_time:>2s`。
  * 时间范围最长 **14 天**。请求的范围更长时，预览会提示已截取最近 14 天：相对时间范围改为过去 14 天，绝对时间范围保留请求的结束时间并向前取 14 天。
</Note>

<Tip>
  在 AI 输入框中用**自然语言**描述即可，直接输入查询语法（如 `browser_name:Chrome`）反而会降低转换准确率。需要精确控制条件时，请使用下方的查询语法。
</Tip>

## 查询基础

查询支持两种类型的词项：

| 类型 | 说明 | 示例 |
| - | - | - |
| **单词项** | 单个词汇 | `test`、`hello` |
| **短语** | 用双引号包围的词汇组 | `"hello flashduty"` |

### 布尔操作符

| 操作符 | 描述 | 示例 |
| - | - | - |
| `AND` | 交集：两个词项都必须在选定的视图中（默认操作符） | `error AND timeout` |
| `OR` | 并集：任一词项包含在选定的视图中，需要使用 `()` 包裹起来 | `(error OR warning)` |
| `-` | 排除：后面的词项不在视图中 | `error -timeout` |

## 全文检索

<Warning>
  全文检索仅部分字段支持，如未查询到结果，请转为字段查询。
</Warning>

| 查询语句 | 描述 |
| - | - |
| `hello` | 精确匹配 `hello` 的字段 |
| `hello*` | 匹配以 `hello` 开头的字段 |
| `*hello` | 匹配以 `hello` 结尾的字段 |
| `*hello*` | 匹配含有 `hello` 的字段 |
| `"hello world"` | 精确匹配 `"hello world"` 的字段 |

## 转义特殊字符

检索包含特殊字符的字段值时，需要使用反斜杠 `\` 转义或者双引号。

<Note>
  以下字符被视为特殊字符：`:`, `"`, `*`, `-`, `>`, `<`, `,`, `(`, `)`, `[`, `]`, `\` 和空格
</Note>

## 属性检索

使用 `attribute:term` 语法检索特定属性：

| 查询语句 | 描述 |
| - | - |
| `browser_name:Chrome` | 检索值为 `Chrome` 的浏览器 |
| `view_name:*/detail` | 检索以 `/detail` 结尾的视图名称 |
| `-resource_status_code:0` | 检索状态码不为 `0` 的资源 |
| `os_name:"Mac OS X"` | 检索值为 `"Mac OS X"` 的系统名称 |

## 数值检索

对于数值类型的属性，可以使用比较操作符：

| 查询语句 | 描述 |
| - | - |
| `session_error_count:>5` | 检索错误数大于 `5` 的会话 |
| `view_time_spent:>=1.00min` | 检索停留时间大于 `1min` 的视图 |
| `session_view_count:[2 TO 8]` | 检索视图访问量在 `2` 和 `8` 之间的会话 |

## 复杂检索示例

<Tabs>
  <Tab title="错误分析">
    检索钱包页面中发生的 Warning 类型的错误：

    ```
    error_message:Warning\:* view_url_path:/wallet/*
    ```
  </Tab>

  <Tab title="性能分析">
    检索加载时间超过 5 秒，且以 `/incident/detail/` 开头的视图：

    ```
    view_loading_time:>=5s view_url_path:/incident/detail/*
    ```
  </Tab>

  <Tab title="错误请求">
    检索请求类型为 `fetch` 或者 `xhr`，且状态码不为 `200` 的资源：

    ```
    -resource_status_code:200 resource_type:(fetch OR xhr)
    ```
  </Tab>

  <Tab title="页面行为">
    检索 URL 为 `/incident`，且操作数大于 `2` 或者错误数大于 `3` 的视图：

    ```
    view_url_path:/incident (view_action_count:>=2 OR view_error_count:>=3)
    ```
  </Tab>
</Tabs>

## 微信小程序专属属性

针对微信小程序平台采集的 View 事件，除通用的 `view_*` 字段外，还支持以下可查询属性，便于排查小程序页面冷启动、`setData` 调用和生命周期阶段耗时：

| 属性 | 说明 |
| - | - |
| `view_first_render` | 首屏渲染耗时 |
| `view_app_launch` | 小程序启动耗时 |
| `view_loading_time` | 页面加载耗时 |
| `view_setdata_count` | 页面 `setData` 调用次数 |
| `view_setdata_duration` | 页面 `setData` 累计耗时 |
| `view_onload_to_onshow` | `onLoad` 到 `onShow` 之间的耗时 |
| `view_onshow_to_onready` | `onShow` 到 `onReady` 之间的耗时 |

例如，检索首屏渲染超过 2 秒的小程序页面：

```
source:miniprogram view_first_render:>2s
```

## 会话属性检索

除上述示例中的字段外，会话（Session）还支持以下常用可查询属性，这些属性同样可用于列表列展示、CSV 导出和链接变量：

| 属性 | 说明 |
| - | - |
| `session_id` | 会话 ID |
| `session_view_count` | 会话内的视图访问量 |
| `session_has_replay` | 会话是否包含回放 |
| `session_sampled_for_error` | 会话是否为异常补采会话：为 `true` 时，该会话的事件在客户端被暂存、直到会话报错才上传，因此明细只从报错前的一小段开始 |
| `session_sampled_for_error_replay` | 会话回放是否因报错才保留：为 `true` 时，该回放是会话报错后才补充上传的 |
| `rc_version` | 远程配置版本，即会话上报时所使用的远程配置版本号 |

例如，检索由异常补采上传的会话：

```
session_sampled_for_error:true
```

异常补采的开关见应用管理中[远程配置](../quickstart/app-management#远程配置)的 **异常会话补采**（`sessionOnError`）与 **异常回放补采**（`sessionReplayOnError`）。

其中 `rc_version` 对应应用管理中[远程配置](../quickstart/app-management)的发布版本，可按配置版本筛选会话，评估远程配置发布（rollout）的生效情况。

## 高级检索技巧

<AccordionGroup>
  <Accordion title="时间范围检索">
    结合时间范围进行精确检索：

    ```
    view_loading_time:>2s client_time:>1758253826081
    ```
  </Accordion>

  <Accordion title="用户行为检索">
    检索结账页面的用户点击行为：

    ```
    action_type:click view_url_path:/checkout/*
    ```
  </Accordion>

  <Accordion title="设备类型检索">
    检索移动设备上加载时间超过 3 秒的视图：

    ```
    device_type:mobile view_loading_time:>3s
    ```
  </Accordion>

  <Accordion title="地理位置检索">
    检索中国地区发生错误的会话：

    ```
    geo_country:China session_error_count:>0
    ```
  </Accordion>
</AccordionGroup>

## 最佳实践

* 多词短语用双引号包围，确保精确匹配。
* 谨慎使用通配符，避免条件过于宽泛。
* 用 `AND` / `OR` 组合多个条件，构建精确查询。
* 借助自动补全减少输入错误。
* 保存常用检索条件，方便重复查询。

## 下一步

<CardGroup cols={2}>
  <Card title="RUM 查看器概览" icon="compass" href="./overview">
    了解查看器核心功能
  </Card>

  <Card title="分布式追踪" icon="diagram-project" href="../best-practices/distributed-tracing">
    了解分布式追踪最佳实践
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.