工作簿¶

SQL 编辑器 Workbook 是 AI Studio 交互式体验中保存的一组 SQL，Workbook 版本用于保留编辑器中的修改过程。

目前对外发布的 MOI Python SDK 和 MOI Go SDK 没有公开 Workbook 或 Workbook 版本的类型与方法，也没有查询历史客户端。本节介绍的 SQL 方法只执行语句并返回结果，不会把语句保存到 Workbook。

集成方案应如何处理¶

不要在 SDK 代码中调用内部接口或从浏览器请求中观察到的 /workbook/... 路径。这类路径不属于对外 SDK 契约，其认证、工作区、权限和生命周期要求都可能不同。同样，不要把从界面复制的 Workbook ID 当作 SDK 资源 ID 使用。

请根据实际需求选择以下方案：

需求	推荐方案
从应用执行 SQL	使用 `run_sql` 或 `RunSQL`，并写完全限定表名
让 SQL 和应用代码一起评审	将 `.sql` 文件保存在源码仓库中，与 SDK 调用代码一同评审
由用户交互式编辑和版本化 SQL	使用 AI Studio SQL 编辑器
保留应用审计记录	持久化应用自有的查询记录，参见保存应用真正需要的记录
在产品界面诊断查询	使用 SQL 历史，入口是否可用取决于工作区功能配置

应用自有的已保存查询¶

如果服务需要在 AI Studio 之外编辑或版本化 SQL，应将其建模为应用资源，而不是假定存在 SDK Workbook。最小记录可以包含：

{
  "id": "monthly-revenue",
  "revision": 3,
  "database": "analytics",
  "sql": "SELECT month, SUM(total) FROM analytics.orders GROUP BY month",
  "state": "approved",
  "updated_at": "2026-07-29T08:30:00Z"
}

上面的字段名只是应用设计示例，不是 MOI API 字段。将数据库名和 SQL 保存在一起，便于评审者确认所有表都使用完全限定名。多个服务可能同时更新记录时，应使用不可变 Revision、乐观锁等常规并发控制。

执行时可以按以下顺序处理：

读取已批准的 Revision；
按需用元数据确认引用对象；
通过 SQL 查询辅助方法执行；
保存应用执行记录，但不写入凭证或敏感结果行。

这样可以避免集成代码依赖未公开的界面 API。以后官方 SDK 如果增加 Workbook 方法，应直接使用对应版本公开的类型和方法文档，不要根据上述应用模型猜测请求字段。