For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /features/query-workspace.md.
  • 简体中文
  • 受控只读查询、脱敏与流式导出

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

    受控只读查询工作台(/query):左侧库表结构浏览器、Monaco 自动补全、服务端敏感列脱敏与流式分页
    受控只读查询工作台(/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 收到实时撤销事件,编辑器立即锁定,禁止继续翻页、导出或发起新查询。
    • 界面会清晰展示 撤销原因、操作人及撤销时间,如需继续排查请重新发起申请。