SQL API

The SQL Product API mirrors the AI Studio SQL editor: it manages workbooks, reads MatrixOne metadata, starts queries, obtains results and profiles, and lists query history. AI Studio workspace permission grants access to the product surface; MatrixOne database roles still decide whether the SQL itself is allowed.

Workbooks and versions

Method and route	Purpose
POST /newmoi/workbook/create	Create a workbook
POST /newmoi/workbook/list	List workbooks
POST /newmoi/workbook/detail	Read workbook detail
POST /newmoi/workbook/update	Update workbook metadata
POST /newmoi/workbook/delete	Delete a workbook
POST /newmoi/workbook/version/list	List workbook versions
POST /newmoi/workbook/version/create	Create a version
POST /newmoi/workbook/version/update	Update a version
POST /newmoi/workbook/version/save	Save a version

A workbook stores editor state; creating or saving it does not execute SQL. Keep the workbook and version IDs returned by the service. Before overwriting shared work, read the latest version and handle a conflict rather than assuming the copy in memory is current.

Database metadata

Metadata routes under /newmoi/meta cover database lists and trees, tables, table detail, columns, column statistics, and DDL. Use these calls to select an existing database/table and construct editor assistance from server-returned names.

The drop operations /newmoi/meta/db/drop, /newmoi/meta/table/drop, and /newmoi/meta/view/drop are destructive SQL actions. Show the fully qualified object, current workspace/database connection, and known dependencies to the caller before submitting one. Product API success does not provide recovery; backup and restore remain database responsibilities.

Execute and follow a query

Start a query through:

POST /newmoi/query/execute

Use the identifier returned by that call for subsequent operations:

Route	Use
/newmoi/query/describe	Read query or statement state
/newmoi/query/result	Read paginated/limited result data
/newmoi/query/result/download	Download result data
/newmoi/query/profile	Inspect the execution profile
/newmoi/query/detail	Read query detail
/newmoi/query/kill	Request cancellation
GET /newmoi/query/ws	Obtain the query WebSocket entry when enabled

Execution can outlive the initial HTTP request. Poll the query or statement state, or use the documented WebSocket protocol, until a terminal state. Canceling is complete only when state confirms it. Apply an explicit row limit for interactive results and use the download operation for larger output.

SQL text and returned rows can contain sensitive data. Avoid placing full queries or results in application logs. Parameterization behavior is defined by the deployed execute schema; do not emulate parameters with unsafe string concatenation.

Query history

POST /newmoi/query/history lists query records and POST /newmoi/query/history/overview returns aggregates. History is workspace/product context, while SQL execution authorization remains in the database. Preserve server timestamps and IDs when correlating history with database logs.

On failure, report the query/statement ID, state, database, server request ID, and a redacted error. Retry only transient transport/service failures. Syntax errors, permission denials, missing objects, and deterministic data errors require a corrected request.

Catalog asset operations are documented in Data, files, and connectors.