You're reading the v2.0.0 docs. View the latest (v2.2.0) →

Go SDK quickstart — first query in 5 minutes

This page walks through installing the Go SDK, connecting to a local Relata server, and running your first governed query + search + memory recall.

Prerequisites

  • Go 1.25+
  • A running Relata server (cargo run -p relata-cli -- serve)

Verify the server is up:

curl http://127.0.0.1:9090/health
# {"status":"ok",...}

1. Install

go get github.com/relatadb/sdk-go

The Go SDK is stdlib-only — no external dependencies. Just net/http, encoding/json, crypto/rand, context, and time.

2. Connect and insert a row

package main
 
import (
    "context"
    "fmt"
    "log"
 
    "github.com/relatadb/sdk-go/relata"
)
 
func main() {
    client := relata.New("http://localhost:9090", &relata.ClientOptions{
        BearerToken:    "relata-dev",   // required when server sets RELATA_BEARER_TOKEN
        DefaultPurpose: "analytics",     // required — every query must declare a purpose
    })
 
    // Insert (governed — purpose is recorded in the audit log).
    _, err := client.Query(context.Background(),
        "INSERT INTO Person (_pk, name, email) VALUES ('p1', 'Alice', 'alice@example.com')")
    if err != nil {
        log.Fatal(err)
    }
}

3. Query it back

result, err := client.Query(context.Background(), "SELECT * FROM Person LIMIT 5")
if err != nil {
    log.Fatal(err)
}
for _, row := range result.Rows {
    fmt.Println(row["name"], row["email"])
}

4. Full-text + hybrid search

hits, err := client.Search(context.Background(), "alice", "Person",
    relata.WithSearchLimit(5), relata.WithHighlight())
if err != nil {
    log.Fatal(err)
}
for _, hit := range hits.Hits {
    fmt.Println(hit.Score, hit.Fields["name"])
}

5. Agent memory

mem, err := relata.NewMemory("http://localhost:9090", "agent-notes",
    &relata.MemoryOptions{BearerToken: "relata-dev"})
id, _ := mem.Add(context.Background(), "Alice prefers dark mode")
hits, _ := mem.Search(context.Background(), "ui preferences", relata.WithTopK(3))
mem.Forget(context.Background(), id)

6. Cypher

Relata auto-detects Cypher — send a MATCH query through client.Query():

result, _ := client.Query(context.Background(),
    "MATCH (n:Person {id: 'p1'}) RETURN *",
)
// → SELECT * FROM Person WHERE id = 'p1'

Authentication & multi-tenant

client := relata.New("http://localhost:9090", &relata.ClientOptions{
    BearerToken:    "relata-dev",
    DefaultPurpose: "analytics",
    Tenant:         "org-acme",   // X-Relata-Tenant-Id (multi-tenant)
    Timeout:        15 * time.Second,
})

Context-based cancellation

Every SDK method takes a context.Context — cancel long-running queries via:

ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
 
result, err := client.Query(ctx, "SELECT * FROM HugeTable")
if errors.Is(err, context.DeadlineExceeded) {
    log.Println("query timed out")
}

Typed clients

The Go SDK ships 15 typed sub-clients mirroring the server's REST surface:

ClientPurpose
relata.NewGovernanceClient(client)ACL policies, purposes
relata.NewAuditClient(client)Audit log queries
relata.NewIdentityClient(client)Identity resolution
relata.NewMemory(url, purpose, opts)Agent cognitive verbs (standalone — owns its transport)
relata.NewMcpClient(client)MCP tool invoker
relata.NewTenantAdminClient(client)Multi-tenant config
relata.NewBackupClient(client)Backup + restore
...see the Go SDK source

Examples

The Go SDK ships a parallel set of runnable examples in sdks/go/examples/. Each is a self-contained main package — run with go run ./examples/<name>:

# Basic + ecosystem
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/advanced_query    -url http://localhost:9090 -token $RELATA_TOKEN
go run ./examples/governance        -url http://localhost:9090 -token $RELATA_TOKEN
go run ./examples/memory_quickstart -url http://localhost:9090 -token $RELATA_TOKEN
go run ./examples/multi_tenant      -url http://localhost:9090
go run ./examples/ephemeral_server
 
# Domain operators
go run ./examples/graphql           -url http://localhost:9090 -token $RELATA_TOKEN
go run ./examples/graph_algorithms  -url http://localhost:9090 -token $RELATA_TOKEN
go run ./examples/intelligence      -url http://localhost:9090 -token $RELATA_TOKEN
go run ./examples/multi_search      -url http://localhost:9090 -token $RELATA_TOKEN
go run ./examples/parameterized     -url http://localhost:9090 -token $RELATA_TOKEN
go run ./examples/lookups           -url http://localhost:9090 -token $RELATA_TOKEN
go run ./examples/streaming         -url http://localhost:9090 -token $RELATA_TOKEN
go run ./examples/a2a               -url http://localhost:9090 -token $RELATA_TOKEN
go run ./examples/tokens            -url http://localhost:9090 -token $RELATA_TOKEN
go run ./examples/tenant_admin      -url http://localhost:9090 -token $RELATA_TOKEN
go run ./examples/bitemporal        -url http://localhost:9090 -token $RELATA_TOKEN
go run ./examples/audit             -url http://localhost:9090 -token $RELATA_TOKEN
go run ./examples/analytics         -url http://localhost:9090 -token $RELATA_TOKEN
go run ./examples/jobs_workflows    -url http://localhost:9090 -token $RELATA_TOKEN
go run ./examples/face_search       -url http://localhost:9090 -token $RELATA_TOKEN
go run ./examples/investigation     -url http://localhost:9090 -token $RELATA_TOKEN

Next steps