HTTP API を通して Mila を操作する Go ライブラリです。既定では KARTE API 基盤に接続します。Go 1.27.3 以上が必要です。
KARTE の SQL API と、Query Job の作成・状態取得・結果取得・キャンセルに対応します。
KARTE アプリで発行したアクセストークンを AccessToken に指定します。SDK が Authorization: Bearer <token> を設定します。SQL 実行には alpha.explore.query.execute Scope が必要です。
既定の送信先は POST https://api.karte.io/v2alpha/explore/query/execute です。 別の環境では BaseURL にその環境の URL を指定します（例: https://api.example.com）。
BaseURL と認証方式は独立して変更できます。別の API 基盤で API key を使う場合などは、AccessToken の代わりに Authenticator を指定します。
client, err := mila.New(mila.Config{
BaseURL: "https://mila.example.com/api",
Authenticator: mila.AuthenticatorFunc(func(req *http.Request) error {
req.Header.Set("X-API-Key", os.Getenv("MILA_API_KEY"))
return nil
}),
Endpoints: map[mila.Operation]string{
mila.OperationRunSQL: "/sql/query",
},
})Authenticator は Authenticate(*http.Request) error を持つインターフェースです。API key・Basic 認証・動的 token 取得・リクエスト署名などを呼び出し側で実装できます。AuthenticatorFunc は関数を渡すためのアダプターです。AccessToken と Authenticator の同時指定はエラーになります。
認証処理は送信前に毎回呼ばれ、URL・HTTP method・本文・標準 API ヘッダーが設定済みのリクエストを受け取ります。本文の参照には req.GetBody() を使うと送信する本文を消費しません。token 取得などの通信には req.Context() を渡してください。認証エラーの場合は API リクエストを送信せず、errors.Is / errors.As で元のエラーを辿れます。独自の認証処理は並行呼び出しに対応させてください。
Config.Endpoints は操作ごとのパスを上書きします。省略した操作には既定値を使い、BaseURL だけ変更した場合も SQL の既定パスを使います。パスは / で始まり、接続先ホスト・query・fragment を含めません。BaseURL にパス接頭辞がある場合はその後ろに追加します。パスを上書きしても送受信の形式は変わりません。
Query Job も KARTE の公開 API パスを既定値に使います。testdata/openapi.yaml は Mila の仕様から KARTE の入出力形式に合わせて生成した Query Job 契約です。
go get github.com/plaidev/mila-client-go@latest開発元の checkout を利用する場合は、利用先の go.mod に次を追加します。
require github.com/plaidev/mila-client-go v0.0.0
replace github.com/plaidev/mila-client-go => /path/to/mila/mila-client-goトークンだけで、既定の KARTE API に SQL を送信できます。
package example
import (
"context"
"os"
mila "github.com/plaidev/mila-client-go"
)
func Query(ctx context.Context) (*mila.RunSQLResponse, error) {
client, err := mila.New(mila.Config{
AccessToken: os.Getenv("KARTE_ACCESS_TOKEN"),
})
if err != nil {
return nil, err
}
return client.RunSQL(ctx, mila.RunSQLRequest{
SQL: "SELECT 1 AS value",
})
}RunSQLRequest.SQL は {"sql":"..."} として送信します。参照専用の API で、SQL は 1〜16,000 文字です。参照できるテーブルはトークンの対象プロジェクトで許可されたものに限定されます。
RunSQL は []map[string]any を返します。API が配列行・オブジェクト行のどちらを返しても、列名で参照できます。ネストしたオブジェクト・配列・null は JSON の形を保ちます。列の型は API が返した文字列を保持します。
ResultColumnSchema は Java・OpenAPI の ResponseColumnSchema、TypeScript の ResultColumnSchema に対応し、name・type・fields を保持します。fields は STRUCT の子フィールド、ARRAY では名前のない要素型を1件保持します。type の型である ValueType は Java の同名の型に対応する文字列識別子です。COMPLEX・KLL_SKETCH・HLL_SKETCH などの型名もそのまま保持します。
RunSQLRaw は schema の列順に揃えた二次元配列を返します。配列行では重複する列名や名前のない列も取得できます。RunSQL は map に変換する際にこれらを拒否し、値を黙って上書きしません。オブジェクト行に対しては、一意に列を対応付けられることを確認します。schema・rows が欠けた応答は UnsupportedResponseError になります。
動的な JSON 数値は、BIGINT の精度を保つため json.Number で読み込みます。必要な型への変換は呼び出し側で明示してください。
number := result.Rows[0]["count"].(json.Number)
count, err := number.Int64()Endpoints のキーは OperationRunSQL、OperationCreateQueryJob、OperationGetQueryJob など、公開メソッドに対応する定数です。RunSQL と RunSQLRaw は OperationRunSQL、GetQueryJobResults と GetQueryJobResultsRaw は OperationGetQueryJobResults を共有します。
| 操作 | メソッド | KARTE 公開パス |
|---|---|---|
| 同期 SQL | RunSQL, RunSQLRaw |
/v2alpha/explore/query/execute（既定） |
| Query Job の作成 | CreateQueryJob |
/v2alpha/explore/queryJobs/create |
| Query Job の状態 | GetQueryJob |
/v2alpha/explore/queryJobs/get |
| Query Job の結果 | GetQueryJobResults, GetQueryJobResultsRaw |
/v2alpha/explore/queryJobs/result/get |
| Query Job のキャンセル | CancelQueryJob |
/v2alpha/explore/queryJobs/cancel |
Query Job は読み取り専用 SQL を非同期で実行します。必要な Scope は alpha.explore.queryJob.execute です。対象環境でこれらの API がリリースされていることを確認してください。
CreateQueryJobRequest.SQL は同期 SQL と同じ sql として送信します。作成入力は sql と任意の jobId・labels です。実行権限は KARTE サーバが設定します。labels.queryLabel はサーバの計測値が優先されます。HTTP 200 と 202 の両方を成功として扱います。
jobID, err := mila.NewQueryJobID()
if err != nil {
return err
}
request := mila.CreateQueryJobRequest{
SQL: "SELECT * FROM events",
JobID: jobID,
}
job, err := client.CreateQueryJob(ctx, request)JobID を省略すると SDK が生成します。応答が届かない場合の手動再送に備えるなら、上記のように事前に生成し、同じ JobID・SQLを再利用してください。SDK が caller の request を書き換えることはありません。RunSQLRequest に旧 createJob フラグは持たせず、専用メソッドで作成します。
GetQueryJob で状態を確認し、SUCCEEDED になったら結果を取得します。QueryJobResponse は QUEUED・RUNNING・SUCCEEDED・FAILED・CANCELLED の状態、期限、行数などのメタデータを保持します。FAILED の実行エラーは Error に入り、HTTP 通信のエラーとは区別します。CancelQueryJob はキャンセル要求後の現在の状態を返します。
page, err := client.GetQueryJobResults(ctx, mila.QueryJobResultsRequest{
JobID: job.JobID,
PageSize: mila.Ptr(int32(100)),
})
if err != nil {
return err
}
if page.NextPageToken != "" {
// 次のページは、返された token をそのまま指定します。
next, err := client.GetQueryJobResults(ctx, mila.QueryJobResultsRequest{
JobID: job.JobID,
PageSize: mila.Ptr(int32(100)),
PageToken: page.NextPageToken,
})
// next と err を処理します。
}NextPageToken が空なら最終ページです。ページ取得と状態のポーリングは呼び出し側で行います。GetQueryJobResults はオブジェクト行・配列行のどちらも列名で参照できる形で返し、ネストしたオブジェクト・配列・null を JSON のまま保持します。GetQueryJobResultsRaw は列スキーマの順序に揃えた二次元配列を返します。配列行では重複する列名も保持できます。オブジェクト行では列と値が一意に対応することを確認します。結果に行が含まれない状態では、State と Error を確認してください。
各メソッドの末尾に、任意で一つの RequestOptions を指定できます。
result, err := client.RunSQL(ctx, request, mila.RequestOptions{
Timeout: 30 * time.Second,
})通常の API は 10 秒、SQL は API 側の 120 秒を考慮して 130 秒が既定値です。context の期限が先ならそちらを使い、独自の認証処理からレスポンス本文の読み込みまでを含めます。認証処理は req.Context() の中断・期限を尊重してください。独自の HTTPClient を指定した場合は、その Timeout も HTTP 通信に適用されます。
通信失敗・HTTP エラーの自動再試行や、標準の Bearer token の自動更新は行いません。動的な token が必要な場合は Authenticator で取得します。401・403・429 を含む非成功応答は APIError で返します。429 の Retry-After が返された場合は Headers から取得できます。
redirect は追跡しません。認証情報の転送と POST の GET への変換を避け、3xx も APIError として返します。
Client は複数の goroutine で共有できます。設定した Endpoints は構築時にコピーします。独自の HTTP client は Transport・接続プール・Timeout を共有し、元の client 自体は書き換えません。
Query Job の任意の数値はポインタ型です。mila.Ptr(int32(100)) でページサイズを指定できます。省略時は API の既定値を使います。pageSize の有効範囲は 1〜10,000 です。
SQL と Query Job の結果の動的な JSON 数値は json.Number です。行数・時刻など、型が決まった整数フィールドは int64 で保持します。
var apiErr *mila.APIError
if errors.As(err, &apiErr) {
fmt.Println(apiErr.StatusCode)
fmt.Println(apiErr.Headers.Get("Retry-After"))
}APIError は操作・パス・HTTP status・本文・ヘッダーを保持します。本文は最大 64 KiB で、切り詰めた場合は BodyTruncated が true です。Error() の文字列には本文・認証情報を含めません。
中断・期限超過は errors.Is(err, context.Canceled) / errors.Is(err, context.DeadlineExceeded) で判定できます。通信や JSON のエラーも原因を辿れます。
cd mila-client-go
gofmt -w .
go test -race -timeout 60s ./...
go vet ./...SQL・Query Job は KARTE の公開契約に合わせ、既定 URL・認証・sql 本文・ページング・配列行とオブジェクト行をテストしています。TestQueryJobOpenAPIContract は公開契約に合わせたスナップショットと Go の型・送受信を照合します。
開発元の mila-client-go/ が正本です。新しいファイルは公開許可リストにも追加します。リリース時に VERSION を更新して master にマージすると、既存 CI が検証済みスナップショットを配布先の main と同名タグに同期します。VERSION を変えない PR は公開しません。配布先だけでの開発・検証に Mila 本体や Node.js は不要です。
MIT License。詳細は LICENSE を参照してください。
結果スキーマは同期・非同期とも {name?, type, fields?} で、ARRAY / STRUCT の fields を再帰的に保持します。HTTP の結果行は配列形式です。結果データは GetQueryJobResultsRaw または GetQueryJobResults で取得します。