SDK guide#

RelataDB ships three published consumer SDKs — Python, TypeScript, and Go — held in 3-way domain-module parity by scripts/check_sdk_parity.py and mirrored to github.com/relatadb/sdk-{python,typescript,go} on every develop push. This page routes you to the right one, shows what's covered, and tracks the roadmap.

Rust? There is an internal/reference Rust client (crates/relata-sdk-rust) used by the server binary, the tray app, the test harness, and relata-bench. It is first-party and load-bearing but not published as a consumer SDK — the three SDKs below are the supported app-facing surface.

SDK locations#

Quickstart pages: Python · TypeScript · Go.

Quick examples — what "covered" looks like#

Python is the reference implementation; TypeScript and Go mirror the same verbs (see the parity matrix below for exact identifiers, and your SDK's quickstart for the local spelling). Every call declares a purpose and runs through the governed path — ACL, cell masking, audit.

Connect & query#

from relata import RelataClient
 
with RelataClient("http://localhost:9090", purpose="analytics") as relata:
    # Raw SQL — QueryResult is iterable
    for row in relata.query("SELECT * FROM Person WHERE name LIKE 'Ahmed%' LIMIT 10"):
        print(row["name"])
 
    # Fluent builder + bi-temporal time-travel + provenance
    res = (relata.select("Person")
                .where("nationality = 'IN'")
                .as_of("2025-01-01T00:00:00Z")
                .with_provenance()
                .limit(5)
                .execute())

Hybrid search#

hits = relata.search("shell company", "IntelChunk", limit=10, highlight=True)
for h in hits.hits:
    print(h.score, h.highlights)

Ingest (bulk / CSV / streaming / OTLP / document)#

from relata import IngestClient
ing = IngestClient.from_client(relata)
 
ing.bulk("Person", [{"name": "Alice", "email": "a@x.io"}],
         on_conflict="upsert")            # upsert | skip | error
ing.ingest_csv("people.csv", "Person")    # typed CSV loader
ing.otlp_traces(payload)                  # OTLP traces / logs / metrics
ing.ingest_document(source="report.pdf", content=blob, auto_chunk=True)

Identity resolution & entity lifecycle#

from relata import IdentityClient
idc = IdentityClient.from_client(relata)
 
cluster = relata.resolve_identities("alice@x.io")        # → unified entity + aliases
relata.fuse_identities(id_a, id_b)                       # ontological merge
idc.erase_subject("alice@x.io", reason="gdpr-art17")     # governed right-to-erasure

Agent memory — 10 cognitive verbs#

from relata import Memory
 
with Memory("http://localhost:9090", purpose="agent-notes") as m:
    mid = m.add("Alice prefers dark mode")               # remember
    for hit in m.search("ui preferences", top_k=5):      # recall (hybrid + recency)
        print(hit["content"])
    m.forget(mid)                                         # governed retention retract, not a hard delete

Graph + intelligence operators#

path = relata.graph_dijkstra("Person", "p-1", "p-9")     # shortest path
ring = relata.graph_scc("Transaction")                    # fraud-ring detection
ubo  = relata.beneficial_ownership_chain("ShellCo")       # intel operator

Governance, audit & A2A (typed clients)#

from relata.audit import AuditClient
from relata.a2a  import A2AClient
 
audit = AuditClient.from_client(relata)
print(audit.count())                       # chain_valid + entry count
 
a2a = A2AClient.from_client(relata)
print(a2a.agent_card())                    # discover the agent
task = a2a.submit_task({"name": "enrich", "input": {...}})   # agent-to-agent task

Streaming (governed SSE change feed)#

from relata import StreamingClient
sc = StreamingClient.from_client(relata)
for evt in sc.watch("Person"):             # live, ACL-filtered change feed
    print(evt)

Point an agent at it (MCP + framework adapters)#

from relata import McpClient
mcp = McpClient.from_client(relata)        # 68 typed tool wrappers; also call_tool(name, args)
 
# Or drop Relata in as governed memory for an existing framework:
#   from relata_adapters.langchain import RelataMemory      # LangChain / LlamaIndex / CrewAI /
#   from relata_adapters.crewai   import RelataStorage      # AutoGen / AG2 / Pydantic-AI /
#   from relata_langgraph import RelataCheckpointer         # smolagents / LangGraph

See the Python, TypeScript, and Go quickstarts for install + run instructions, and the AI in RelataDB page for the full agent/RAG loop.

Feature parity matrix (verified against source)#

Typed v1.1 client inventory#

Each typed client wraps a server-side domain surface. Construct with <Class>.from_client(client) (Python/Go) or new <Class>(client) (TS). Every client inherits auth, tenant, purpose, and retry config.

Memory cognitive-verb matrix#

Platform capability coverage#

Coverage is computed from the capability matrix in sdks/COVERAGE.md (the CI-gated canonical tracker in the source repo, verified by scripts/check_sdk_parity.py). 1 partial = ½.

The one shared gap#

A single capability is ⚠️ partial across all three published SDKs (and Rust):

• KNN by caller-supplied embedding — knn_search/knnSearch/KNNSearch emits ORDER BY <slot> <=> '[…]', a pgvector-ism the server parser rejects (ORDER BY only takes a bare column). Hybrid search (HYBRID_SEARCH) and reference-row similarity (SIMILAR TO) are unaffected and fully ✅. Tracked pending a server-side vector-literal grammar.

The remaining differentials are minor: SIMILAR_IMAGE shipped to Python/TypeScript/Go but not yet to the internal Rust client; the ClientPool connection-pool helper is TypeScript+Rust only. Every other capability in the 22-section matrix is green across all three published SDKs.

Server-only surfaces (raw HTTP, no SDK wrapper)#

These endpoints are reachable via raw HTTP but deliberately not wrapped by the typed SDKs:

• Admin: reindex, rotate-dek, dashboard, system, logs (operator surfaces, run via relata CLI or the admin dashboard)
• Config: GET /config (operator introspection)
• Attestation: GET /attestation (supply-chain verification, run via cosign verify-blob)

Runnable example inventory#

Each SDK ships a parallel set of self-contained examples.

Each example file is self-contained — connect, run, print, exit. Run from the language's sdks/<lang>/ directory:

# Python
RELATA_TOKEN=secret python -m examples.graphql
 
# TypeScript (Node 23+ / Deno / Bun)
node --experimental-strip-types examples/graphql.ts
 
# Go
go run ./examples/graphql -url http://localhost:9090 -token $RELATA_TOKEN

Roadmap#

Minimum public SDK example shape#

Relata is the governed memory layer for AI agents, so every SDK shows the agent-memory loop, not just a SQL call: connect → remember (with purpose + provenance) → recall (hybrid retrieval, optionally AS OF) → justify (provenance/audit chain) → handle errors → close. The verbs are reached the same way in every language: POST /memory/{remember|recall|recognize|justify|consolidate|forget} (or the matching MCP tool). See the query cookbook → Part 2 for canonical request bodies.

See also#

• Python · TypeScript · Go quickstarts
• Agent Memory — the 10 cognitive verbs
• AI in RelataDB — the full agent/RAG loop
• Error reference — deep-linkable RFC 7807 error codes