Catalog

Catalog 是工作区的数据资产入口。导入任务写入这里，SQL、工作流和知识库再从这里引用数据。Python 和 Go SDK 都提供 Catalog 的低层客户端方法。

Workspace
└─ Catalog
   └─ Database
      └─ Table

Volume 与 File 也位于 Database 下，文件操作见 文件与卷。

创建客户端

Python 使用 RawClient；请求体用字典传入：

import os

from moi import RawClient

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

Go 使用 NewRawClient 和强类型请求：

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

不要把 API Key 写入源码。以下示例假定客户端已经创建。

遍历资源树

调用下级资源前，先取得完整父级链路。建议应用持久化每一级的服务端 ID，并把名称只用于日志和界面展示。

资源

Python / Go 方法

用途

Catalog

list_catalogs / ListCatalogs、get_catalog_tree / GetCatalogTree

列出顶层资产或一次读取嵌套树

Database

list_databases / ListDatabases、get_database_children / GetDatabaseChildren

按 Catalog 列库，或读取库下的 Table 与 Volume

Table

get_table / GetTable、get_table_overview / GetTableOverview

读取完整 Schema 或轻量概览

Python 可直接读取资源树：

tree = client.get_catalog_tree()
catalog = client.get_catalog({"id": 101})
databases = client.list_databases({"id": 101})
children = client.get_database_children({"id": 201})

读取表元数据

在把 Table 交给查询、工作流或导出任务之前，至少确认：

  1. Table 仍属于预期的 Catalog 和 Database。

  2. 当前身份具有读取权限。

  3. Schema 中所需列存在，类型与调用方预期一致。

  4. 对象已经完成载入或处理，可以读取。

Schema 是运行时契约，不应从抽样数据推断。preview_table 返回有限行数，get_table_data 支持分页读取：

table = client.get_table({"id": 301})
sample = client.preview_table({"id": 301, "lines": 10})
page = client.get_table_data(
    {"id": 301, "database_id": 201, "page": 1, "page_size": 100}
)

创建与变更

Python 的基本创建流程如下。实际列类型必须使用目标服务支持的类型：

catalog = client.create_catalog(
    {"name": "analytics", "description": "Production analytics"}
)
database = client.create_database(
    {"catalog_id": 101, "name": "sales", "description": "Sales mart"}
)
table = client.create_table(
    {
        "database_id": 201,
        "name": "orders",
        "columns": [{"name": "id", "type": "int", "is_pk": True}],
    }
)

重试创建 Table 前，可用 check_table_exists({"database_id": ..., "name": ...}) 做确定性检查。创建 Catalog 和 Database 时应保存创建响应中的 ID，不要依赖名称重新发现对象。

Go 中对应方法为 CreateCatalog、CreateDatabase 和 CreateTable，请求类型分别为 CatalogCreateRequest、DatabaseCreateRequest 和 TableCreateRequest。UpdateCatalog 可更新名称或说明；UpdateDatabase 只更新说明，不能改名。

下载表数据

两种 SDK 都支持获取签名下载链接。Python 还提供 download_table_data，直接返回 CSV FileStream：

stream = client.download_table_data({"id": 301})
try:
    with open("orders.csv", "wb") as output:
        while chunk := stream.read(1024 * 1024):
            output.write(chunk)
finally:
    stream.close()

流必须关闭。签名链接和预览结果应视为临时数据，不要持久化为长期地址。

删除顺序

truncate_table 清空数据但保留表结构；delete_table 删除表及其数据。delete_database 会删除整个 Database，delete_catalog 会删除其下所有 Database、Table 和 Volume。调用前：

  1. 用 get_table_full_path 核对 Table 的完整路径。

  2. 用 get_table_ref_list、get_database_ref_list 或 get_catalog_ref_list 检查引用。

  3. 先移除下游引用，再删除最下层对象。

  4. 删除后再次读取或列出父级，确认对象确实不可用。