Client and Workspace

An MOI SDK client connects to the Catalog Service. Its constructor accepts a Base URL, API Key, and optional HTTP configuration; it has no separate workspace ID argument. The identity associated with the Key and server-side permissions determine which resources calls can see and modify.

Consequently, switching a workspace in an application is not a client-side UI change alone. Obtain a credential valid for the intended workspace, and keep clients for separate environments or identities clearly separated.

RawClient and SDKClient

RawClient is the foundation for all calls, with each public method representing a service capability. SDKClient wraps a RawClient and supplies helpers that require multiple calls or client-side logic.

Need	Choose
Create, inspect, or delete one Catalog, Database, Table, or other resource	RawClient
Control the request type, CallOptions, and response structure precisely	RawClient
Create or reuse a table role, import local files, or wait for a workflow job	SDKClient
Use both layers in one application	Keep the RawClient and construct SDKClient from it

Python:

import os
from moi import RawClient, SDKClient
from moi.options import with_timeout, with_user_agent

raw = RawClient(
    os.environ["MOI_BASE_URL"],
    os.environ["MOI_API_KEY"],
    with_timeout(60.0),
    with_user_agent("catalog-sync/1.0"),
)
client = SDKClient(raw)

catalogs = raw.list_catalogs()

Go:

raw, err := sdk.NewRawClient(
	os.Getenv("MOI_BASE_URL"),
	os.Getenv("MOI_API_KEY"),
	sdk.WithHTTPTimeout(60*time.Second),
	sdk.WithUserAgent("catalog-sync/1.0"),
)
if err != nil {
	log.Fatal(err)
}
client := sdk.NewSDKClient(raw)

catalogs, err := raw.ListCatalogs(ctx)

The example timeout is not a service guarantee. Non-streaming HTTP requests default to 30 seconds; adjust the value for file size, operation duration, and the caller’s deadline.

Client lifetime

Create clients during process startup and reuse their connection pools. Go RawClient and SDKClient instances can be used concurrently across goroutines. Python RawClient holds a requests.Session by default. Reuse it, but for complex multithreaded sharing, follow the concurrency constraints of requests.Session or provide separate Sessions for independent execution units.

Separate clients at these boundaries:

Boundary	Approach
Development, staging, and production	Create a client for each Base URL and Key pair; never fall back across environments
Different workspaces or tenants	Use independently authorized Keys and clients; do not rewrite identity on a global instance
Key rotation	Construct and health-check a new client before retiring the old one
A call under a special identity	Use the new instance returned by with_special_user / WithSpecialUser

A custom HTTP client is useful for consistent proxy, TLS, pool, or telemetry settings. Python provides with_http_client(requests.Session), and Go provides WithHTTPClient(*http.Client). Once supplied, its transport and lifetime settings are the application’s responsibility.

Control an individual call

ClientOptions affect all calls from a client; CallOptions affect one operation.

Setting	Python	Go
Overall HTTP timeout	with_timeout	WithHTTPTimeout
Custom HTTP client	with_http_client	WithHTTPClient
User-Agent	with_user_agent	WithUserAgent
Default headers	with_default_header(s)	WithDefaultHeader(s)
Request ID	with_request_id	WithRequestID
Per-call headers	with_header(s)	WithHeader(s)
Query parameters	with_query_param / with_query	WithQueryParam / WithQuery

Every Go method accepts context.Context. Give external operations a deadline, and let upstream cancellation stop the SDK call:

ctx, cancel := context.WithTimeout(parentCtx, 20*time.Second)
defer cancel()

catalogs, err := raw.ListCatalogs(ctx, sdk.WithRequestID(requestID))

Python does not have a per-call context. Use client timeouts, streaming read timeouts, and application-level cancellation.

For workspace membership and role configuration, see User Permissions. Continue with the SDK’s resource-specific sections for individual methods.