查询历史¶

对外 SDK 通过同步辅助方法执行 SQL：

Python：SDKClient.run_sql(statement)
Go：(*SDKClient).RunSQL(ctx, statement)

两者都会调用 Catalog 服务的 NL2SQL run_sql 操作。SQL 必须使用 analytics.orders 这样的完全限定表名，服务据此确定目标数据库。

使用 Python 执行查询¶

先用已认证的 RawClient 创建高层客户端：

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)

response = client.run_sql(
    "SELECT order_id, total "
    "FROM analytics.orders "
    "ORDER BY order_id DESC "
    "LIMIT 20"
)

for result in response.get("results", []):
    print(result.get("columns", []))
    for row in result.get("rows", []):
        print(row)

Python 客户端把响应数据解码为字典和列表。不要让应用逻辑依赖文档未说明的响应 Envelope 字段。

对应的底层调用如下：

response = raw.run_nl2sql(
    {
        "operation": "run_sql",
        "statement": "SELECT COUNT(*) FROM analytics.orders",
    }
)

直接执行 SQL 时优先使用 SDKClient.run_sql：该方法会拒绝空语句，并自动设置操作类型。

使用 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)

	response, err := client.RunSQL(
		context.Background(),
		"SELECT order_id, total "+
			"FROM analytics.orders "+
			"ORDER BY order_id DESC LIMIT 20",
	)
	if err != nil {
		log.Fatal(err)
	}

	for _, result := range response.Results {
		fmt.Println(result.Columns)
		for _, row := range result.Rows {
			fmt.Println(row)
		}
	}
}

Go 返回 *NL2SQLRunSQLResponse。每个 NL2SQLResult 包含 Columns []string 和 Rows []NL2SQLRow，其中一行是字符串切片。

按已发布的接口契约设计¶

Python 和 Go 对外仓库中的 run_sql 当前都不返回查询 Handle 或 Statement ID，也没有公开以下 SDK 方法：

异步查询轮询或结果流式读取；
结果分页或下载；
取消或终止正在运行的语句；
读取 SQL 历史或执行计划。

因此，重试策略由应用负责。网络错误不能证明服务端从未接收语句。对于可能修改数据的 SQL，除非语句及其所在流程明确具备幂等性，否则不要自动重试。

官方示例每次只提交一条语句；对外 SDK 文档没有承诺多语句或事务语义。应将语句拆开调用；如果应用必须控制会话或事务，请使用数据库 Driver。

保存应用真正需要的记录¶

调用方如果需要自己的查询记录，应在调用 SDK 前准备并保存：

应用生成的请求 ID；
完整 SQL 或脱敏后的 SQL；
所选数据库和表的元数据 ID；
开始和结束时间；
成功或失败状态，以及脱敏后的错误；
允许持久化的结果摘要。

不要记录 API Key 或不受限制的结果行。错误分类和请求 ID 的处理方式见响应、错误与分页。AI Studio 运维人员可以在 SQL 历史中查看界面侧记录，但该功能不会为对外 SDK 增加查询历史方法。

保存 SQL 和记录查询历史是两个不同问题。设计持久化方案前，请先阅读工作簿能力边界。