Go SDK
/v1 routes and some wrappers are removed or reshaped (tenant administration, cluster operations, webhooks, dedup tokens, media embedding). See the SDK changes. Python, TypeScript and Go are the only supported SDKs.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/v2package 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",
})
// /query is read-only (#782) — writes go through the governed ingest door.
ingest := relata.NewIngestClient(client)
if _, err := ingest.Bulk(ctx, "Person", []map[string]any{
{"id": "p1", "name": "Alice", "email": "a@x.com"},
}, nil); 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 | Enterprise edition only; the open build has one tenant |
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 keyframeGraph & 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' effectFull 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_TOKENFull 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