元数据¶

先从 Catalog API 获取对象 ID、名称和列，再构造 SQL，可以避免依赖用户手工输入的对象信息。对外发布的 Python 和 Go SDK 都通过 RawClient 提供这组接口。

这些接口返回的是 Catalog 元数据，不会在一个持久 SQL 会话中执行 SHOW 或 DESCRIBE。调用者能看到哪些对象，仍由 API Key 对应身份及服务端权限决定。

定位目标对象¶

按所需信息选择粒度最小的接口：

操作	Python	Go	主要返回内容
列出 Catalog 中的数据库	`list_databases({"id": catalog_id})`	`ListDatabases(ctx, &DatabaseListRequest{CatalogID: ...})`	数据库 ID、名称、描述、对象数量和时间信息
列出数据库子对象	`get_database_children({"id": database_id})`	`GetDatabaseChildren(ctx, &DatabaseChildrenRequest{DatabaseID: ...})`	子对象 ID、名称、类型、大小和子项数量
查看单表详情	`get_table({"id": table_id})`	`GetTable(ctx, &TableInfoRequest{TableID: ...})`	列、行数、大小、统计信息、建表 SQL 和描述信息
获取跨数据库的轻量表概览	`get_table_overview()`	`GetTableOverview(ctx)`	数据库名、表名和列名

列表和子对象接口适合发现资源。后续读取详情时应传递返回的 ID，不要根据名称推算或拼接 ID。

Python 示例¶

RawClient 方法接收请求字典，并返回服务响应中已经解码的 data 对象：

import os

from moi import RawClient

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

catalog_id = int(os.environ["MOI_CATALOG_ID"])
database_result = raw.list_databases({"id": catalog_id})

for database in database_result.get("list", []):
    print(
        database["id"],
        database["name"],
        database.get("table_count", 0),
    )

# 从 Catalog 元数据或应用配置中取得表 ID。
table_id = int(os.environ["MOI_TABLE_ID"])
table = raw.get_table({"id": table_id})

print(table["name"])
for column in table.get("columns", []):
    print(column["name"], column["type"], column.get("is_pk", False))

描述和统计类字段不一定都有值。除非接口明确要求某字段存在，否则应使用 dict.get 读取。

Go 示例¶

Go SDK 使用类型化请求和响应：

package main

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

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

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

	catalogID, err := strconv.ParseInt(os.Getenv("MOI_CATALOG_ID"), 10, 64)
	if err != nil {
		log.Fatal(err)
	}
	databases, err := client.ListDatabases(ctx, &sdk.DatabaseListRequest{
		CatalogID: sdk.CatalogID(catalogID),
	})
	if err != nil {
		log.Fatal(err)
	}
	for _, database := range databases.List {
		fmt.Printf("%d\t%s\t%d tables\n",
			database.DatabaseID, database.DatabaseName, database.TableCount)
	}

	tableID, err := strconv.ParseInt(os.Getenv("MOI_TABLE_ID"), 10, 64)
	if err != nil {
		log.Fatal(err)
	}
	table, err := client.GetTable(ctx, &sdk.TableInfoRequest{
		TableID: sdk.TableID(tableID),
	})
	if err != nil {
		log.Fatal(err)
	}
	for _, column := range table.Columns {
		fmt.Printf("%s\t%s\tprimary-key=%t\n",
			column.Name, column.Type, column.IsPk)
	}
}

TableInfoResponse 还包含 Lines、Size、Stats、CreateSql、 CreatedAt、CreatedBy 和 Comment。行数和统计信息适合用于展示和判断数据概况，不应作为后续写操作的并发安全前置条件。

构造 SQL 前的检查¶

使用元数据返回的数据库名和表名，不要用对象展示名称替代 SQL 名称。
名称需要转义时，按照 MatrixOne SQL 的标识符规则处理。
业务代码依赖固定表结构时，应重新读取表详情；缓存的列清单可能已经过期。
让服务端执行权限判断。应用知道某个对象存在，不代表当前 API Key 有权读取。

公开接口以 Python SDK 和 Go SDK 仓库为准。选定数据库和表后，继续阅读 SQL 查询与结果。