计算¶

SDK 不直接管理计算资源，但 SQL、数据载入和工作流等调用都依赖工作区中的计算资源。集成程序需要在提交任务前确认资源类型、状态和容量，并在调用失败或长时间排队时将 SDK 返回与控制台状态结合排查。

先区分两类资源¶

类型	承载的工作	常见 SDK 调用
SQL 计算资源	SQL 查询、结构化表读写	`run_sql` / `RunSQL`，以及会读写 MatrixOne 表的任务
通用计算资源	解析、分段、嵌入、文件处理等非 SQL 工作	文件载入、工作流和 GenAI pipeline

两类资源不能互换。一个流程如果同时读取结构化表并处理文件，可能同时依赖 SQL 与通用计算资源。资源规格、节点范围、自动暂停和当前状态以 AI Studio 的计算资源页面为准。

当前 SDK 边界¶

经核对官方 Python SDK 源码与 API reference 以及 Go SDK 源码，当前版本没有计算资源的公开类型或 CRUD、启动、暂停、扩缩容方法。RawClient 只应调用其已声明的方法；它不是任意内部 API 的兼容层。

需要完成以下操作时，请使用控制台：

查看可用规格和当前价格；
创建、修改、启动、暂停、重试或删除资源；
调整节点范围或自动暂停；
查看利用率、Credit 消耗和关联工作负载。

完成配置后，应用仍可用 SDK 执行 SQL、提交处理任务并查询任务结果。

用 SQL 调用验证查询资源¶

以下示例使用 SDK 中已实现的高级方法执行一个只返回常量的 SQL。它可以验证客户端认证、SQL 路由和查询执行链路，但不能证明某个专用资源已经按预期扩容。生产查询仍应使用全限定表名，例如 sales.orders。

Python¶

import os

from moi import RawClient, SDKClient

raw = RawClient(
    base_url=os.environ["MOI_BASE_URL"],
    api_key=os.environ["MOI_API_KEY"],
)
client = SDKClient(raw)

result = client.run_sql("SELECT 1 AS ready")
print(result)

SDKClient.run_sql() 调用 Python SDK 已公开的 NL2SQL run_sql 操作。不要在日志中输出 API Key；服务返回的结构以当前部署版本为准。

Go¶

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	sdk "github.com/matrixorigin/moi-go-sdk"
)

func main() {
	raw, err := sdk.NewRawClient(
		os.Getenv("MOI_BASE_URL"),
		os.Getenv("MOI_API_KEY"),
	)
	if err != nil {
		log.Fatal(err)
	}

	client := sdk.NewSDKClient(raw)
	result, err := client.RunSQL(context.Background(), "SELECT 1 AS ready")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%+v\n", result)
}

为调用设置超时或取消信号，避免资源启动或查询异常时无限等待：

ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()

result, err := client.RunSQL(ctx, "SELECT 1 AS ready")

这段补充代码需要导入 time。

提交任务前的检查¶

确认 SDK 的 Base URL 和 API Key 指向目标工作区。
根据工作内容确认所需资源类型；SQL 与非 SQL 阶段分别检查。
在控制台确认资源不是异常状态，并评估是否处于自动暂停后的冷启动阶段。
检查资源的关联工作负载，避免批处理与延迟敏感任务争用同一容量。
为 SDK 调用设置客户端超时；异步任务使用任务 ID 或工作流作业 ID 跟踪，不要用单次 HTTP 超时推断任务失败。

自动暂停后的首次请求可能需要等待资源恢复。调用超时只说明客户端没有在期限内收到结果，不等同于服务端已经取消任务。若调用返回任务 ID，应继续查询任务状态后再决定是否重试。

失败与排队排查¶

现象	先检查	后续动作
SQL 立即报错	API Key、工作区、SQL 语法和表权限	再查看 SQL 计算资源状态与 SQL 历史
调用等待较久	资源是否暂停、启动中或容量不足	查看关联工作负载；必要时在控制台调整资源
载入或工作流不启动	通用计算资源状态、任务配置、输入对象权限	用 SDK 查询任务或工作流作业，再查看作业日志
客户端超时但后台仍运行	SDK 超时小于实际任务时长	保留返回的任务标识，按状态查询，避免直接重复提交
资源异常	控制台中的资源详情与关联工作负载	先处理资源问题，再按任务幂等性决定是否重试

暂停或删除资源会影响关联任务。变更前先在资源详情中检查活跃任务和绑定工作流；删除不可恢复，默认资源也可能受产品限制而不能删除。