Workbooks and Versions¶

A SQL Editor workbook is a saved collection of SQL associated with the interactive AI Studio experience. Workbook versions preserve changes made in that editor.

The public MOI Python SDK and MOI Go SDK do not currently publish workbook or workbook-version types and methods. They also do not expose a query-history client. The SQL method documented in this section executes a statement and returns its result; it does not save the statement to a workbook.

What this means for an integration¶

Do not call an internal or browser-observed /workbook/... route from SDK code. Such a route is not part of the published SDK contract and may have different authentication, workspace, permission, and lifecycle requirements. Likewise, do not treat a workbook ID copied from the UI as an SDK resource ID.

Choose one of these supported designs instead:

Requirement	Recommended design
Execute SQL from an application	Use `run_sql` or `RunSQL` with fully qualified table names
Keep reviewed SQL with application code	Store `.sql` files in source control and review them with the code that invokes the SDK
Let users edit and version SQL interactively	Use the AI Studio SQL editor
Keep an application audit trail	Persist an application-owned query record; see Record what your application needs
Diagnose queries in the product UI	Use SQL History, subject to the workspace feature configuration

An application-owned saved query¶

If a service needs editable or versioned SQL outside AI Studio, model it as an application resource rather than a presumed SDK workbook. A minimal record might contain:

{
  "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"
}

The field names above are an application example, not MOI API fields. Keep the database name and SQL together so reviewers can verify that referenced tables are fully qualified. If multiple services can update a record, use normal application concurrency controls such as immutable revisions or optimistic locking.

At execution time:

load the approved revision;
optionally confirm referenced objects through database and table metadata;
execute it through the SQL query helper;
write the application execution record without credentials or sensitive result rows.

This separation avoids coupling an integration to an unpublished UI API. If workbook methods are added to an official SDK later, use the public types and method documentation from that release rather than translating this application model into request fields by assumption.