> ## Documentation Index
> Fetch the complete documentation index at: https://test-8ad8522e-feat-ai-sre.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 数据查询语法指南

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

Flashduty RUM 查看器提供了强大的检索能力，允许您通过灵活的查询语法快速定位和分析 RUM 数据。查询由**词项**（terms）和**操作符**（operators）组成，支持复杂的搜索条件组合。

## AI 自然语言查询

如果您还不熟悉查询语法，可以直接用自然语言描述想要查找的数据，AI 会自动将其转换为查询语句。

<Steps>
  <Step title="进入 AI 查询">
    点击查询输入框中的**魔法棒**图标进入 AI 自然语言查询模式。进入后输入框边框会高亮，与普通查询模式明确区分。
  </Step>

  <Step title="描述查询意图">
    用自然语言描述您想查找的数据（支持中英文），然后按**回车**转换。例如：

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

    AI 会将其转换为：

    ```
    browser_name:Chrome resource_status_code:>=500 resource_duration:>2s
    ```
  </Step>

  <Step title="预览并应用">
    AI 生成对应的查询语句并展示预览。确认无误后点击**应用**，查询立即生效；若结果不理想，可继续修改描述后再次回车重新生成，或点击**撤销**回退到应用前的状态。
  </Step>
</Steps>

<Note>
  AI 生成的是标准查询语句（DQL），使用的字段与语法与手动查询完全一致（详见下文）。您无需记住字段名称，AI 会根据当前事件类型自动选择可查询的字段。
</Note>

### 追加而非替换

当输入框中已有查询条件时，AI 生成的条件会**追加**到现有查询之后，而不会覆盖它。因此您可以在已有查询的基础上，用自然语言逐步补充筛选条件。若当前为空查询，则直接应用生成结果。

如果您的描述更适合其他事件类型，AI 会提示切换（如「将切换事件类型为 错误」），并在该事件类型的可查询字段范围内生成查询。

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

## 查询基础

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

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

### 布尔操作符

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

## AI 自然语言查询

如果你不想手写 DQL，可以让 AI 将自然语言请求转换为查询条件。在 RUM 查看器的查询框左侧点击 **AI 自然语言查询** 图标；也可以在普通查询模式下按 <kbd>⌘</kbd> + <kbd>Enter</kbd>（Windows 和 Linux 为 <kbd>Ctrl</kbd> + <kbd>Enter</kbd>）。

<Steps>
  <Step title="输入查询意图">
    用自然语言描述你想查看的数据，例如“Chrome 浏览器上的报错”“耗时超过 2 秒的资源请求”或“过去 24 小时的 checkout 页面”。按 <kbd>Enter</kbd> 生成预览。
  </Step>

  <Step title="查看变更预览">
    预览会显示将要加入的 DQL 条件；当请求更适合其他事件类型或时间范围时，也会显示事件类型或时间范围的变更。
  </Step>

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

<Note>
  “最近 1 小时”“昨天”“过去 7 天”等时间表达会更新查看器的时间选择器，不会被写成 `client_time` 等 DQL 条件。性能时长条件仍然属于 DQL，例如 `view_loading_time:>2s`。
</Note>

<Note>
  AI 自然语言查询的时间范围最长为 **14 天**。如果请求的范围更长，预览会提示已截取最近 14 天；应用后时间选择器会使用截取后的范围。相对时间范围会改为过去 14 天，绝对时间范围会保留请求的结束时间，并向前取 14 天。
</Note>

## 全文检索

<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` | 会话是否包含回放                 |
| `rc_version`         | 远程配置版本，即会话上报时所使用的远程配置版本号 |

其中 `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>

## 最佳实践

<CardGroup cols={2}>
  <Card title="使用引号包围短语" icon="quote-left">
    确保多词短语的精确匹配
  </Card>

  <Card title="合理使用通配符" icon="asterisk">
    避免过于宽泛的检索条件
  </Card>

  <Card title="组合多个条件" icon="layer-group">
    通过 AND/OR 操作符构建精确查询
  </Card>

  <Card title="利用自动补全" icon="keyboard">
    减少输入错误，提高检索准确性
  </Card>
</CardGroup>

<Tip>
  保存常用检索条件，提高重复查询的效率。
</Tip>

## 下一步

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

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