Compute Resources¶

The SDK does not manage compute resources directly, but SQL, ingestion, and workflow operations depend on compute in the workspace. Before submitting work, an integration should confirm the required resource type, availability, and capacity. When a call fails or remains queued, combine the SDK response with resource state in the console.

Distinguish the two resource types¶

Type	Work it runs	Typical SDK operations
Query compute resource	SQL queries and structured table reads or writes	`run_sql` / `RunSQL` and tasks that access MatrixOne tables
Task compute resource	Non-SQL work such as parsing, chunking, embedding, and file processing	File ingestion, workflows, and GenAI pipelines

The two types are not interchangeable. A pipeline that reads a structured table and processes files can depend on both query and task compute. Use the AI Studio Compute resources page as the source of truth for specifications, node ranges, auto-suspend settings, and current state.

Current SDK boundary¶

The current Python SDK source and API reference and Go SDK source do not define public compute-resource types or methods for CRUD, start, suspend, or scaling operations. Use RawClient only through its declared methods; it is not a compatibility layer for arbitrary internal APIs.

Use the console to:

inspect available specifications and current prices;
create, update, start, suspend, retry, or delete a resource;
change node ranges or auto-suspend behavior;
inspect utilization, Credit consumption, and associated workloads.

After configuration, applications can still use the SDK to execute SQL, submit processing work, and inspect task results.

Verify query compute with a SQL call¶

The following examples call the SDK’s implemented high-level SQL helper with a constant query. This checks client authentication, SQL routing, and the query execution path. It does not prove that a particular dedicated resource has scaled as expected. Use fully qualified table names, such as sales.orders, for production queries.

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() uses the NL2SQL run_sql operation exposed by the Python SDK. Do not print API keys in logs. The exact response structure is determined by the deployed service version.

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)
}

Give calls a deadline so a resource startup or query problem cannot block the caller indefinitely:

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

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

The additional snippet requires the time import.

Preflight checklist¶

Confirm that the SDK base URL and API key identify the intended workspace.
Determine the resource type for every stage; check SQL and non-SQL stages separately.
In the console, verify that the resource is not in an error state and account for a cold start after auto-suspend.
Inspect associated workloads to avoid making batch work compete with latency-sensitive work for the same capacity.
Set client deadlines. Track asynchronous work by task ID or workflow job ID instead of treating an HTTP timeout as a task failure.

The first request after auto-suspend may wait while the resource resumes. A client timeout means only that the caller did not receive a result before its deadline; it does not prove that the server canceled the task. If an operation returns a task ID, inspect its state before retrying.

Diagnose failures and queueing¶

Symptom	Check first	Next action
SQL fails immediately	API key, workspace, SQL syntax, and table permissions	Inspect query compute state and SQL history
A call takes unusually long	Whether compute is suspended, starting, or undersized	Inspect associated workloads; adjust the resource in the console if necessary
Ingestion or a workflow does not start	Task compute state, task configuration, and input-object permissions	Query the task or workflow job through the SDK, then inspect job logs
The client times out while work continues	Whether the SDK deadline is shorter than the task duration	Preserve the returned task identifier and poll status; do not submit a duplicate blindly
A resource is in an error state	Resource details and associated workloads in the console	Restore the resource, then retry only if the operation is safe to repeat

Suspending or deleting compute affects associated tasks. Before making a lifecycle change, inspect active tasks and bound workflows in the resource details. Deletion is irreversible, and product rules can prevent deletion of default resources.