Python¶

本指南创建一个隔离的 Python 环境，连接 MOI Catalog Service，并读取当前身份可见的 Catalog 列表。示例只执行查询，不创建或修改资源。

安装¶

Python SDK 要求 Python 3.9 或更高版本。建议在虚拟环境中从官方仓库安装：

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install "moi-python-sdk @ git+https://github.com/matrixorigin/moi-python-sdk.git@main"

Windows PowerShell 使用 .venv\Scripts\Activate.ps1 激活环境。

上面的命令跟随官方仓库 main 分支，适合快速试用。生产项目应将 main 替换为已经验证的 tag 或 commit SHA，并把解析后的版本记录在依赖锁文件中。

确认包可导入：

python -c "from moi import RawClient; print('MOI Python SDK is ready')"

配置连接¶

示例约定使用 MOI_BASE_URL 和 MOI_API_KEY 两个环境变量；它们只是本地变量名，不是 SDK 强制的配置名称。

export MOI_BASE_URL="https://<catalog-service-host>"
export MOI_API_KEY="<sdk-api-key>"

Base URL 必须包含协议和主机名。RawClient 会去除末尾的 /，并自动通过 moi-key 请求头发送密钥。不要把 Genesis 模型 API Key、浏览器 Cookie 或数据库连接密码混作 SDK Key；应使用部署方明确提供给 Catalog Service 的凭据。

发起第一次请求¶

新建 quickstart.py：

import os
import sys

from moi import APIError, HTTPError, RawClient


def required_env(name: str) -> str:
    value = os.getenv(name, "").strip()
    if not value:
        raise RuntimeError(f"Set {name} before running this program")
    return value


client = RawClient(
    base_url=required_env("MOI_BASE_URL"),
    api_key=required_env("MOI_API_KEY"),
)

try:
    response = client.list_catalogs()
except APIError as exc:
    print(
        f"MOI API error: code={exc.code}, "
        f"request_id={exc.request_id}, message={exc.message}",
        file=sys.stderr,
    )
    raise SystemExit(1) from exc
except HTTPError as exc:
    print(f"HTTP error: status={exc.status_code}", file=sys.stderr)
    raise SystemExit(1) from exc

catalogs = response.get("list", []) if isinstance(response, dict) else []
print(f"Visible catalogs: {len(catalogs)}")
for catalog in catalogs:
    print(f"- {catalog.get('name')} (id={catalog.get('id')})")

运行：

python quickstart.py

成功后会打印可见 Catalog 的数量和名称。列表为空也可能是正常结果，表示当前身份没有可见 Catalog；它与连接失败不同。

客户端怎么选¶

RawClient 直接返回响应包络中的 data。JSON 对象在 Python 中表现为字典，因此首次接入时应对缺失字段保持容错。需要执行高级操作时，再基于同一个底层客户端创建 SDKClient：

from moi import RawClient, SDKClient

raw = RawClient(base_url=base_url, api_key=api_key)
sdk = SDKClient(raw)

SDKClient 当前提供表权限角色、文件导入和 run_sql 等便捷方法；它不会替代 RawClient 的完整资源接口。方法参数和返回字段以官方 Python SDK 仓库中的源码及 API reference 为准。

常见问题¶

初始化时报 Base URL 错误：检查值是否同时包含协议和主机名，例如 https://service.example.com；不要只填写域名或路径。
返回 401 或 403：确认使用的是 Catalog Service 接受的 SDK Key，并检查该身份在目标环境中的权限。不要在日志中打印密钥。
返回业务错误：APIError 中的 code、message 和 request_id 可用于定位服务端请求；向管理员或支持人员反馈时一并提供这些值。
连接超时：默认请求超时为 30 秒。需要调整时，可从 moi.options 导入 with_timeout 并在创建 RawClient 时传入。
导入失败或行为变化：确认锁定的 SDK commit，并对照该版本仓库中的测试和 API reference；main 分支不承诺固定接口。

继续了解 Catalog、数据库和文件等资源的调用范围，可查看 SDK 数据主题。