Python SDK Quickstart

This guide creates an isolated Python environment, connects to the MOI Catalog Service, and reads the catalogs visible to the current identity. The example does not create or modify resources.

Install the SDK

The Python SDK requires Python 3.9 or later. Create a virtual environment and install the package from the official repository:

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"

On Windows PowerShell, activate the environment with .venv\Scripts\Activate.ps1.

This command follows the repository’s main branch and is convenient for evaluation. For a production project, replace main with a tag or commit SHA that you have tested, and record the resolved version in your dependency lock file.

Confirm that the package can be imported:

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

Configure the connection

The example uses MOI_BASE_URL and MOI_API_KEY as local environment-variable names. They are conventions for this example, not names required by the SDK.

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

The Base URL must include a scheme and host. RawClient removes a trailing slash and sends the key in the moi-key request header. Do not substitute a Genesis model API Key, browser cookie, or database password unless your deployment explicitly provides it as the Catalog Service credential.

Make the first request

Create 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')})")

Run it:

python quickstart.py

A successful request prints the number and names of visible catalogs. An empty list can also be a valid response: it means that the current identity has no visible catalogs, not that the connection failed.

Choose the appropriate client

RawClient returns the data value from the service response envelope. JSON objects therefore appear as Python dictionaries, so integration code should tolerate fields that are absent. For a higher-level operation, construct SDKClient from the same raw client:

from moi import RawClient, SDKClient

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

SDKClient currently includes helpers for table-access roles, file imports, and run_sql; it does not replace the complete resource-level API on RawClient. Refer to the source and API reference in the official Python SDK repository for the parameters and response fields supported by the version you installed.

Troubleshooting

  • Base URL validation fails during initialization: Include both the scheme and host, such as https://service.example.com, rather than only a hostname or path.

  • The service returns 401 or 403: Confirm that the key is accepted by the Catalog Service and that its identity has access in the target environment. Never print the key in logs.

  • The service returns an application error: Record the code, message, and request_id from APIError. These values help an administrator or support engineer trace the request.

  • A request times out: The default request timeout is 30 seconds. To change it, import with_timeout from moi.options and pass it when constructing RawClient.

  • An import fails or behavior changes: Confirm the pinned SDK commit and consult that revision’s tests and API reference. The main branch is not a fixed interface version.

For the resource areas covered by the SDK, including catalogs, databases, and files, continue to Data SDK topics.