Database and Table Metadata¶

SQL execution is safer when object IDs, names, and columns come from the Catalog API instead of user-entered strings. The public SDKs expose this API through RawClient.

These methods return Catalog metadata. They do not execute SHOW or DESCRIBE in a persistent SQL session. Visibility still depends on the API key and the service-side permissions of the caller.

Discover the target objects¶

Use the narrowest method for the information you need:

Operation	Python	Go	Result
List databases in a catalog	`list_databases({"id": catalog_id})`	`ListDatabases(ctx, &DatabaseListRequest{CatalogID: ...})`	Database IDs, names, descriptions, counts, and timestamps
List a database’s children	`get_database_children({"id": database_id})`	`GetDatabaseChildren(ctx, &DatabaseChildrenRequest{DatabaseID: ...})`	Child objects with their ID, name, type, size, and child count
Inspect one table	`get_table({"id": table_id})`	`GetTable(ctx, &TableInfoRequest{TableID: ...})`	Columns, row count, size, statistics, creation SQL, and descriptive metadata
Get a lightweight cross-database view	`get_table_overview()`	`GetTableOverview(ctx)`	Database name, table name, and column names

The list and child methods are useful for discovery. Pass the returned ID to a detail method rather than deriving IDs from names.

Python example¶

RawClient methods accept request dictionaries and return the decoded data object from the service response.

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

# Use an ID selected from Catalog metadata or application configuration.
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))

Do not assume optional descriptive or statistics fields are present. Use dict.get unless the field is required by the operation.

Go example¶

The Go SDK returns typed responses:

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 also contains Lines, Size, Stats, CreateSql, CreatedAt, CreatedBy, and Comment. Treat counts and statistics as descriptive metadata, not as a concurrency-safe precondition for a later write.

Before building SQL¶

Keep the database and table names returned by metadata; do not substitute an object display label for its SQL name.
Quote identifiers according to MatrixOne SQL rules when a name requires quoting.
Re-read table details when code depends on a particular schema. A cached column list can become stale.
Let the service enforce permissions. An object being known to the application does not mean the current API key may read it.

The public API surface is defined by the Python SDK and Go SDK repositories. Continue with SQL queries and results after selecting a database and table.