> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# 受控只读查询、脱敏与流式导出

本手册面向研发、测试与数据分析人员，介绍如何在不接触数据库明文账号的情况下，通过 `/query` 安全查询生产只读数据并按权导出。


![受控只读查询工作台（/query）：左侧库表结构浏览器、Monaco 自动补全、服务端敏感列脱敏与流式分页](/screenshots/query-zh-CN-dark.png)

受控只读查询工作台（/query）：左侧库表结构浏览器、Monaco 自动补全、服务端敏感列脱敏与流式分页

## 1. 第 1 步：获取查询授权（Query Grant / Session）

进入左侧菜单 **查询（`/query`）**：

- **如果团队开启了查询审批**（默认）：
  1. 点击 **申请查询权限**，选择权限组已获授的 `query_access` 流程。
  2. 勾选本次需要查询的 **目标数据源**（支持多选子集）、申请有效时长（最长可达 525,600 分钟）以及是否需要 **导出权限（`can_export`）**。
  3. 填写申请理由后提交，审批人在 `/approvals/query-access` 通过后即刻生成限时 **Query Grant**，工作台通过 SSE 自动解锁无需手动刷新。
- **如果管理员关闭了查询审批**：直接选择授权的查询流程即可立即进入受控 **Query Session**。

## 2. 第 2 步：浏览表结构并执行只读 SQL

1. 在左侧 **Schema 树** 展开数据源 → 数据库/Schema → 表，点击表名即可查看全部列类型、主键与索引定义，右侧 Monaco 编辑器同步开启库表列自动补全。
2. 编写单条只读语句并点击 **运行**：
   - **允许执行的语句**：`SELECT`、只读 `WITH ... SELECT`（CTE）、`SHOW`、`DESCRIBE` / `DESC`、`EXPLAIN`。
   - **会被服务端 AST 直接拦截的语句（`4007` / `4011`）**：
     - 任何 `INSERT` / `UPDATE` / `DELETE` / `DDL`（请走变更工单 `/changes/new`）
     - 加锁读（`SELECT ... FOR UPDATE`、`LOCK IN SHARE MODE`）
     - 分号拼接多语句注入或读写文件函数

### 必须了解的 4 个查询运行限制

| 限制项      | 默认值                                              | 说明与报错排查                                      |
| :------- | :----------------------------------------------- | :------------------------------------------- |
| 单页展示行数   | 可选 `1` – `5,000` 行/页                             | 服务端游标按页拉取，前端内存无卡顿                            |
| 在线查询最大行数 | 默认 **`1,000` 行**（管理员可调至 `100,000`）               | 达到上限后服务端立即停止读取并释放目标库连接                       |
| 单语句执行超时  | 默认 **`5,000 ms` / `30,000 ms`**（最大 `300,000 ms`） | 报 `4009 QUERY_TIMEOUT` 时请补全索引过滤条件或减小 `LIMIT` |
| 分页游标有效期  | **`6 小时`（`21,600 秒`）**                           | 绑定当前登录用户的 HMAC 签名游标；超时报 `4010` 重新点击运行即可      |

## 3. 查看脱敏结果与流式导出

- **敏感字段脱敏**：若管理员在 `query_access` 流程中对 `phone`、`email`、`id_card` 等列配置了脱敏规则，数据在**离开 Yearning 服务端前即完成脱敏**，你在表格和浏览器开发者工具中看到的均已是脱敏值。
- **受控数据导出**：
  - 仅当你的有效授权包含对应数据源的 **`can_export = true`** 时，结果栏才开放导出按钮（无权或过期返回 `4003`）。
  - 支持 **CSV**、**JSONL** 与浏览器增量生成 **XLSX**（服务端不落地保存任何导出文件），所有导出行为均写入审计日志。

## 4. 授权被提前撤销或过期时的现象

任意该流程的冻结审批人或管理员均可在任何时刻一键撤销你的 Query Grant。撤销发生的瞬间：

- 前端通过 `GET /api/v4/events/stream` 收到实时撤销事件，**编辑器立即锁定**，禁止继续翻页、导出或发起新查询。
- 界面会清晰展示 **撤销原因、操作人及撤销时间**，如需继续排查请重新发起申请。
