Go SDK

Relata DB 3.0
SDK method names are mostly unchanged in 3.0, but the SDKs call the new /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/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",
    })
 
    // /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

PathMethodReturns
SQLQuery(ctx, sql, opts ...QueryOption)*QueryResult — WithPurpose, WithTimeout, WithDialect
ParameterizedQueryWithParams(ctx, sql, params, opts...)*QueryResult
Arrow Flight (gRPC zero-copy)QueryFlight(ctx, sql, flightEndpoint, purpose, bearer)arrow.Table
GraphQLGraphQL(ctx, query, variables, operationName)any — variables bound server-side (#3260)
SPARQLSparql(ctx, query)map[string]any
Cypherany MATCH-prefixed string via Query()auto-routed, governed
GQL (ISO 39075)Query(ctx, stmt, relata.WithDialect("gql"))header-selected, governed (#3265)
Fluent builderrelata.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
ClientKey methodsCross-ref
GovernanceClientrules CRUD, ImportSigma, retention/WORM/legal-holds, breakglass, alerts, DSARDetection Rules
IdentityClientLabel, RecordUncertainty, RegisterLookup/ListLookups/InvokeLookup, EraseSubjectIdentity
ObjectClientUpsert, BatchUpsert, UpsertTyped, Get, Delete—
IngestClientBulk, BulkCSV, IngestAuto, IngestCDR, OTLPTraces/Logs/Metrics, IngestIter (channel)Ingestion
VectorClientKNNSearch, HybridSearch, SimilarTo, Embed/EmbedBatch + EmbedImage/Face/Audio/VideoHybrid Search
SearchClienttyped /search: Query(ctx, SearchRequest)Search reference
StreamingClientQueryRows (*RowIterator), QueryArrowRaw (*BytesIterator, io.Reader), Watch/Alerts (*SSEIterator)—
AuditClientCount, Entries, FindByRequestID, SignReceipt, ExportPDF → []byte—
TenantAdminClienttenant CRUD, quota, sharing, platform usage/licenseEnterprise edition only; the open build has one tenant
BackupClientCreate, List, Restore, RestoreStatus, Compact, WaitForRestoreBackup & Restore
TokenClientRemember, Check, Revoke, Stats—
LogClientAppend, Head, LoadLeaves—
SystemClientLLM config/test, jobs/workflows, feeds, notifications, pipelines—
A2AClientSubmitTask, GetTask, checkpoints, AgentCard—
McpClientInitialize, ListTools, CallTool + 68 typed wrappersMCP Tools
S3ClientHTTP (returns configured *http.Client with bearer+tenant transport), BaseURLS3 door
Namespaceclient.Namespace("Document") → Query/Write/Get/DeleteAll/BranchFromSearch 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