Go SDK

go get github.com/relatadb/sdk-go/v2 — Go 1.25+. The core is stdlib-only (net/http, encoding/json, crypto/rand, context, time); google.golang.org/grpc + github.com/apache/arrow/go/v15 are pulled only for Arrow Flight. Every method takes ctx context.Context first and returns (..., error).

See the SDK overview for the cross-language parity matrix. This page is the Go capability catalog.

Quickstart

go get github.com/relatadb/sdk-go/v2

package main
 
import (
    "context"
    "fmt"
    "log"
    "github.com/relatadb/sdk-go/v2/relata"
)
 
func main() {
    ctx := context.Background()
    client := relata.New("http://localhost:9090", &relata.ClientOptions{
        BearerToken:    "relata-dev",
        DefaultPurpose: "analytics",
    })
 
    _, err := client.Query(ctx,
        "INSERT INTO Person (_pk, name, email) VALUES ('p1', 'Alice', 'a@x.com')")
    if err != nil { log.Fatal(err) }
 
    res, _ := client.Query(ctx, "SELECT * FROM Person LIMIT 5")
    for _, row := range res.Rows { fmt.Println(row["name"], row["email"]) }
}

Idiomatic context.Context everywhere — cancel long queries via context.WithTimeout / context.WithCancel.

The query surface

Path	Method	Returns
SQL	`Query(ctx, sql, opts ...QueryOption)`	`*QueryResult` — `WithPurpose`, `WithTimeout`, `WithDialect`
Parameterized	`QueryWithParams(ctx, sql, params, opts...)`	`*QueryResult`
Arrow Flight (gRPC zero-copy)	`QueryFlight(ctx, sql, flightEndpoint, purpose, bearer)`	`arrow.Table`
GraphQL	`GraphQL(ctx, query, variables, operationName)`	`any` — `variables` bound server-side (#3260)
SPARQL	`Sparql(ctx, query)`	`map[string]any`
Cypher	any `MATCH`-prefixed string via `Query()`	auto-routed, governed
GQL (ISO 39075)	`Query(ctx, stmt, relata.WithDialect("gql"))`	header-selected, governed (#3265)
Fluent builder	`relata.NewQuery(sql).Purpose(p).Where(...).Limit(10).Execute(ctx, client)`	`*QueryResult`

Free constructors: relata.PathsBetween(from, to, maxHops), relata.MatchFace(img, topK), relata.LookupIdentity(id), relata.HybridSearch(type, query, topK) — for typed-query IR compilation.

Typed domain clients

18 typed sub-clients (68 MCP wrappers, at parity with Python/TypeScript). Each takes the parent *Client:

ingest := relata.NewIngestClient(client)
objs   := relata.NewObjectClient(client)
gov    := relata.NewGovernanceClient(client)
mcp    := relata.NewMcpClient(client)
vc     := relata.NewVectorClient(client)
// + IdentityClient, SearchClient, StreamingClient, AuditClient,
//   TenantAdminClient, BackupClient, TokenClient, LogClient,
//   SystemClient, A2AClient, S3Client, Namespace, Memory

Client	Key methods	Cross-ref
`GovernanceClient`	rules CRUD, `ImportSigma`, retention/WORM/legal-holds, breakglass, alerts, DSAR	Detection Rules
`IdentityClient`	`Label`, `RecordUncertainty`, `RegisterLookup`/`ListLookups`/`InvokeLookup`, `EraseSubject`	Identity
`ObjectClient`	`Upsert`, `BatchUpsert`, `UpsertTyped`, `Get`, `Delete`	—
`IngestClient`	`Bulk`, `BulkCSV`, `IngestAuto`, `IngestCDR`, `OTLPTraces/Logs/Metrics`, `IngestIter` (channel)	Ingestion
`VectorClient`	`KNNSearch`, `HybridSearch`, `SimilarTo`, `Embed`/`EmbedBatch` + `EmbedImage/Face/Audio/Video`	Hybrid Search
`SearchClient`	typed `/search`: `Query(ctx, SearchRequest)`	Search reference
`StreamingClient`	`QueryRows` (RowIterator), `QueryArrowRaw` (BytesIterator, `io.Reader`), `Watch`/`Alerts` (*SSEIterator)	—
`AuditClient`	`Count`, `Entries`, `FindByRequestID`, `SignReceipt`, `ExportPDF` → `[]byte`	—
`TenantAdminClient`	tenant CRUD, quota, sharing, platform usage/license	Multi-Tenancy
`BackupClient`	`Create`, `List`, `Restore`, `RestoreStatus`, `Compact`, `WaitForRestore`	Backup & Restore
`TokenClient`	`Remember`, `Check`, `Revoke`, `Stats`	—
`LogClient`	`Append`, `Head`, `LoadLeaves`	—
`SystemClient`	LLM config/test, jobs/workflows, feeds, notifications, pipelines	—
`A2AClient`	`SubmitTask`, `GetTask`, checkpoints, `AgentCard`	—
`McpClient`	`Initialize`, `ListTools`, `CallTool` + 68 typed wrappers	MCP Tools
`S3Client`	`HTTP` (returns configured `*http.Client` with bearer+tenant transport), `BaseURL`	S3 door
`Namespace`	`client.Namespace("Document")` → `Query/Write/Get/DeleteAll/BranchFrom`	Search reference

Functional options — every per-call override

Go-idiomatic variadic options for every knob (no builder boilerplate):

hits, _ := client.Search(ctx, "alice", "Person",
    relata.WithSearchLimit(50),
    relata.WithSearchFacets("status", "city"),
    relata.WithHighlight(),
    relata.WithMatchingStrategy("all"),
    relata.WithTypoTolerance(map[string]any{"enabled": true, "minWordSize": 4}),
    relata.WithWeights(0.2, 0.5, 0.3),  // graph, bm25, vector
)
 
pr, _ := client.GraphPageRank(ctx, "analytics", "Person",
    &relata.GraphPageRankOptions{Damping: 0.85, MaxIter: 20})

Vectors & embeddings

vc := relata.NewVectorClient(client)
 
knn, _ := vc.KNNSearch(ctx, "Document", "embedding", []float64{0.1,...}, 10,
    &relata.KNNOptions{EFSearch: 200})
 
hybrid, _ := vc.HybridSearch(ctx, "Document", "graph retrieval",
    &relata.HybridSearchOptions{K: 10, Rerank: true, Weights: &[3]float64{0.2,0.5,0.3}})
 
e, _   := vc.Embed(ctx, "Alice Smith", "")         // → *EmbedResponse
eimg, _ := vc.EmbedImage(ctx, b64, "")             // CLIP
vc.EmbedFace(ctx, b64, "")                         // ArcFace
vc.EmbedAudio(ctx, b64, "")                        // CLAP
vc.EmbedVideo(ctx, b64, "")                        // CLIP keyframe

Graph & intelligence operators

All on *Client — 10 graph algorithms + 10 AML/financial + 3 maritime:

client.GraphPageRank(ctx, "analytics", "Person", &relata.GraphPageRankOptions{...})
client.GraphShortestPath(ctx, "alice-id", "bob-id", &relata.GraphShortestPathOptions{MaxHops: 5})
client.GraphCommunity(ctx, "analytics", "Person", nil)
 
client.SanctionsScreen(ctx, "compliance", "Acme Holdings",
    &relata.SanctionsScreenOptions{Threshold: 0.85})
client.BeneficialOwnershipChain(ctx, "compliance", "Acme Holdings", 6)
client.CryptoTrace(ctx, "compliance", "0xabc...")
 
client.VesselTrack(ctx, "analytics", 123456789, 86400)
client.DarkFleetDetect(ctx, "analytics", 48)

See Graph Analytics.

Agent memory — 10 cognitive verbs + recall-quality knobs

Memory is a standalone client (owns its own *Client via New(...)):

mem, _ := relata.NewMemory("http://localhost:9090", "agent",
    &relata.MemoryOptions{BearerToken: "relata-dev"})
 
id, _ := mem.Add(ctx, "Alice prefers dark mode")
 
// retrieval-quality operators (functional options)
results, _ := mem.Search(ctx, "ui preferences",
    relata.WithTopK(10),
    relata.WithMinConfidence(0.6),
    relata.WithRecencyHalfLife(259200),
    relata.WithBudgetTokens(1500),
    relata.WithCancelThreshold(0.92),
)
 
detail, _ := mem.SearchDetailed(ctx, "ui preferences", /* same opts */)
// detail.RecallCostTokens + detail.Cancelled — observe the knobs' effect

Full verb set: Add, AddBatch, Search, SearchDetailed, Get, Update, Forget, Associate, Episodes, Justify, Resolve, Summarise. See Agent memory reference.

Authentication & multi-tenant

client := relata.New("http://localhost:9090", &relata.ClientOptions{
    BearerToken:    "relata-dev",
    DefaultPurpose: "analytics",
    Tenant:         "org-acme",   // X-Relata-Tenant-Id on every request
    ActingAs:       "user-42",    // X-Acting-As (delegation)
    DelegatedBy:    "admin-1",    // X-Delegated-By
    Timeout:        15 * time.Second,
    MaxRetries:     3,
    RetryBackoff:   500 * time.Millisecond,
    AdminBaseURL:   "http://admin.internal:9090", // /admin/* + /platform/* split
})

Examples

~25 runnable examples in sdks/go/examples/. Each is a self-contained main package — go run ./examples/<name>:

go run ./examples/basic             -url http://localhost:9090 -token $RELATA_TOKEN
go run ./examples/ingest            -url http://localhost:9090 -token $RELATA_TOKEN
go run ./examples/memory_quickstart -url http://localhost:9090 -token $RELATA_TOKEN
go run ./examples/intelligence      -url http://localhost:9090 -token $RELATA_TOKEN
go run ./examples/graph_algorithms  -url http://localhost:9090 -token $RELATA_TOKEN
go run ./examples/streaming         -url http://localhost:9090 -token $RELATA_TOKEN
go run ./examples/face_search       -url http://localhost:9090 -token $RELATA_TOKEN

Full set: sdks/go/examples/.

Next steps

Search and retrieval — typed /search, multi-query batch + RRF
Agent memory reference — 10 verbs + recall-quality knobs
Graph analytics — 10+ algorithms, gds.* portability
Query cookbook
Full Go SDK source

Go SDK#

Quickstart#

The query surface#

Typed domain clients#

Functional options — every per-call override#

Vectors & embeddings#

Graph & intelligence operators#

Agent memory — 10 cognitive verbs + recall-quality knobs#

Authentication & multi-tenant#

Examples#

Next steps#