Go SDK Quickstart

The following program connects to the MOI Catalog Service and lists the catalogs visible to the current identity. It uses a bounded context and performs only a read operation, making it suitable as an initial connectivity and authentication check.

Create a module

The SDK’s current go.mod declares Go 1.24.3. After confirming that your local toolchain is compatible, create a module and add the dependency:

mkdir moi-sdk-quickstart
cd moi-sdk-quickstart
go mod init example.com/moi-sdk-quickstart
go get github.com/matrixorigin/moi-go-sdk@latest

The SDK does not currently publish semantic-version Go tags, so @latest can resolve to a commit-based pseudo-version. Production projects should retain go.mod and go.sum, and verify the newly resolved commit before upgrading.

Supply service configuration

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

These environment-variable names are conventions used by the example. Obtain the Base URL and SDK Key from your MOI deployment or administrator. The SDK sends the key in the moi-key request header. Do not substitute a Genesis model API Key, browser cookie, or database password unless the deployment explicitly accepts it for the Catalog Service.

Write and run the program

Save the following as main.go:

package main

import (
	"context"
	"errors"
	"fmt"
	"log"
	"os"
	"time"

	sdk "github.com/matrixorigin/moi-go-sdk"
)

func requiredEnv(name string) string {
	value := os.Getenv(name)
	if value == "" {
		log.Fatalf("set %s before running this program", name)
	}
	return value
}

func main() {
	client, err := sdk.NewRawClient(
		requiredEnv("MOI_BASE_URL"),
		requiredEnv("MOI_API_KEY"),
		sdk.WithHTTPTimeout(30*time.Second),
	)
	if err != nil {
		log.Fatalf("create MOI client: %v", err)
	}

	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
	defer cancel()

	response, err := client.ListCatalogs(ctx)
	if err != nil {
		var apiErr *sdk.APIError
		var httpErr *sdk.HTTPError
		switch {
		case errors.As(err, &apiErr):
			log.Fatalf(
				"MOI API error: code=%s request_id=%s message=%s",
				apiErr.Code, apiErr.RequestID, apiErr.Message,
			)
		case errors.As(err, &httpErr):
			log.Fatalf("HTTP error: status=%d", httpErr.StatusCode)
		default:
			log.Fatalf("list catalogs: %v", err)
		}
	}

	fmt.Printf("Visible catalogs: %d\n", len(response.List))
	for _, catalog := range response.List {
		fmt.Printf("- %s (id=%d)\n", catalog.CatalogName, catalog.CatalogID)
	}
}

Format, compile, and run it:

gofmt -w main.go
go run .

A successful request prints the number and names of visible catalogs. An empty list is not necessarily an error; the identity might not have any visible resources yet.

Understand clients and errors

The module path is github.com/matrixorigin/moi-go-sdk, while its package name is sdk. The example therefore uses an explicit sdk import alias.

RawClient provides typed resource operations. ListCatalogs returns *sdk.CatalogListResponse, so the application does not need to decode the service response envelope. For higher-level operations such as file imports, table-access roles, or SQL execution, reuse the raw client:

highLevelClient := sdk.NewSDKClient(client)

The SDK returns *sdk.HTTPError for a non-2xx response and *sdk.APIError when a successful HTTP response contains an application error code in its envelope. Preserve the latter’s RequestID for troubleshooting. Network failures and context timeouts are returned as other Go errors.

Integration checks

• If NewRawClient fails, confirm that the Base URL includes a scheme and host. A trailing slash is removed automatically.

• For a 401 or 403 response, verify the key type, target environment, and resource permissions. Do not print the key in logs.

• Pass a cancellable context to every operation. The example sets both an HTTP-client timeout and a per-call deadline.

• While the SDK has no semantic-version tag, review pseudo-version changes caused by go get -u and run your own integration tests in CI.

• Refer to the source and Go documentation in the official Go SDK repository for the exact methods and types in the revision your project uses.

After the first request works, continue to Data SDK topics for the available resource areas.