SDK guide

Relata DB 3.0
The SDK surface below is partly the 2.x surface. In 3.0 the SDKs follow the new /v1 routes and some wrappers are removed or reshaped; see the route restructure. Python, TypeScript and Go are the only supported SDKs; no Rust consumer SDK is supported, and a client generated from the OpenAPI document is not an officially supported SDK.

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? The Rust SDK crate is removed from the 3.0 workspace and is not a support or qualification target. The three SDKs below are the supported app-facing surface; other languages use HTTP and the OpenAPI document.

SDK locations

LanguagePackageStatus
Pythonrelata-sdk on PyPIReference implementation — fullest surface
TypeScript@zysec-ai/relata-sdk on npmAt parity with Python (typed clients)
Gogithub.com/relatadb/sdk-go/v2At parity with Python (typed clients)

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())
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)

FeaturePythonTypeScriptGoNotes
Core client (query/health/status)✅✅✅HTTP
Parameterized queries ($N server-side binding)✅ query_params + aquery_params✅ queryWithParams✅ QueryWithParams? placeholders auto-rewritten in Python
Text embedding (/embed, /embed/batch)✅ VectorClient.embed + embed_batch✅ VectorClient.embed + embedBatch✅ VectorClient.Embed + EmbedBatchServer endpoint always available (CPU fallback); GPU sidecar via RELATA_ACCEL_ENDPOINT
Media embedding (/embed/{image,face,audio,video})✅ embed_image/face/audio/video✅ embedImage/Face/Audio/Video✅ EmbedImage/Face/Audio/VideoCLIP / ArcFace / CLAP; 503 when active embedder doesn't support media
Fluent QueryBuilder✅✅✅
SearchBuilder (/search)✅✅✅Facets, highlight, filter, fuzzy preset
Memory cognitive verbs✅ 10 + add_batch✅ 10 + add_batch✅ 10 + add_batch10 cognitive verbs + add_batch (batch convenience wrapper). See the verb matrix below.
Typed v1.1 clients (fromClient)✅ 16✅ 16✅ 16
Typed response models✅ Pydantic✅ interfaces✅ structs
RFC 7807 ProblemDetails errors✅✅ 13 classes✅
X-Request-ID per attempt✅✅✅UUIDv7
Retry on 502/503/504✅ configurable✅ configurable✅ configurable + Retry-After
Multi-tenant (X-Organization-Id)✅✅✅
Delegation (X-Acting-As / X-Delegated-By)✅✅✅
Sync + async mirrors✅ bothasync-nativectx-based
Streaming (SSE watch/alerts)✅ StreamingClient✅ StreamingClient✅ StreamingClient
Arrow RecordBatch / Table✅ query_arrow + query_flight (pyarrow)✅ ArrowFlightTransport (apache-arrow optional peer)✅ QueryFlight (arrow/go)Arrow IPC + Flight DoGet in all three
Agent-framework adapters✅ 7✅ 3—Python: LangChain/LlamaIndex/CrewAI/AutoGen(AG2)/Pydantic-AI/smolagents/LangGraph. TS: LangChain/LlamaIndex/LangGraph. Go/Rust: legitimately — (no idiomatic ecosystem to adapt).
Typed MCP tool wrappers✅ 68✅ 68✅ 68Each SDK ports the full union of MCP tools; Rust (internal) ships 58. See MCP tools reference.
Bi-temporal travel helper (as_of + with_provenance)✅✅✅
Graph traversal DSL✅ paths_between + graph_*✅ graph() + graph_*✅ PathsBetween + Graph*All 3 ship 10+ graph operators; TS adds a fluent graph() DSL helper. See Graph analytics
Bulk ingest streaming (ingest_iter)✅✅✅

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.

ClientSurfacePythonTSGo
GovernanceClientRules, retention (holds + WORM), breakglass, alerts, DSAR✅✅✅
McpClient68 typed MCP tool wrappers + generic call_tool✅✅✅
A2AClientA2A tasks + LangGraph checkpoints + agent card✅✅✅
AuditClientAudit entries (filtered/paginated) + signed receipts + PDF export✅✅✅
IdentityClientIdentity label/uncertainty + lookup tables + ERASE SUBJECT✅✅✅
ObjectClientTyped upsert + batch via /ingest?object_type=✅✅✅
IngestClientBulk NDJSON + CSV + media status✅✅✅
VectorClientKNN + hybrid search + similar-to (SQL-backed)✅✅✅
S3ClientS3 protocol door wrapper✅✅✅
SystemClientLLM config + test + jobs status✅✅✅
StreamingClientNDJSON row streams + SSE consumers (watch/alerts) + Arrow IPC✅✅✅
TenantAdminClientTenant CRUD + quota + sharing agreements✅✅✅
BackupClientBackup create / list / restore—✅✅
TokenClientToken create / check / revoke / stats—✅✅
LogClientStructured log query / tail—✅✅
RulesClientDetection-rule CRUD + Sigma import✅ (on Gov)✅ (on Gov)✅ (on Gov)

Memory cognitive-verb matrix

VerbHTTPPythonTSGo
addPOST /memory/remember✅✅✅
add_batchPOST /memory/remember/batch✅✅✅
search (recall)GET /memory/recall✅✅✅
get (recognize)GET /memory/recognize/:id✅✅✅
update (consolidate)POST /memory/consolidate✅✅✅
forgetDELETE /memory/forget/:id✅✅✅
associatePOST /memory/associate✅✅✅
episodesGET /memory/episodes✅✅✅
justifyGET /memory/justify/:id✅✅✅
resolvePOST /memory/resolve/:id✅✅✅
summarisePOST /memory/summarise✅✅✅

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 = ½.

SDKCoverageStrengths
Python99.6%Reference implementation; governance, identity, 76 canonical types, detection rules (all 8), ontology, streaming, all typed clients, 7 framework adapters, SPARQL, cluster ops, sessions, OTLP ingest
TypeScript99.6%Types, rules (all 8), ontology, links, identity helpers, 16 typed clients, 13 error classes, 3 framework adapters, SPARQL, cluster ops, sessions, OTLP ingest
Go99.6%Types, rules (all 8), ontology, links, identity helpers, SSE streaming, SPARQL, cluster ops, sessions, OTLP ingest

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.

CapabilityPythonTypeScriptGo
Basic query / quickstart✅ basic_query.py✅ basic-query.ts✅ basic/
Ingest✅ ingest.py✅ ingest.ts✅ ingest/
Advanced query / Arrow✅ advanced_query.py✅ advanced-query.ts✅ advanced_query/
Governance✅ governance.py✅ governance.ts✅ governance/
Memory (cognitive verbs)✅ memory_quickstart.py✅ memory-quickstart.ts✅ memory_quickstart/
Multi-tenant✅ multi_tenant.py✅ multi-tenant.ts✅ multi_tenant/
Ephemeral server✅ ephemeral_server.py✅ ephemeral-server.ts✅ ephemeral_server/
GraphQL✅ graphql.py✅ graphql.ts✅ graphql/
Graph algorithms✅ graph_traversal.py✅ graph-algorithms.ts✅ graph_algorithms/
Intelligence operators✅ intelligence.py✅ intelligence.ts✅ intelligence/
Multi-search✅ multi_search.py✅ multi-search.ts✅ multi_search/
Parameterized queries✅ parameterized.py✅ parameterized.ts✅ parameterized/
Lookup tables✅ lookups.py✅ lookups.ts✅ lookups/
Streaming (SSE watch + log)✅ streaming.py✅ streaming.ts✅ streaming/
A2A (tasks + checkpoints)✅ a2a.py✅ a2a.ts✅ a2a/
Dedup tokens (replay defence)2.5.8: ✅. 3.0: dedup-token methods removed; the token client wraps tenant self-service routes instead
Tenant admin (lifecycle)2.5.8: ✅ in all three. 3.0: only me remains in the open SDKs (tenant administration is Enterprise)
Bi-temporal (AS OF + WITH PROVENANCE)✅ bitemporal.py✅ bitemporal.ts✅ bitemporal/
Audit✅ audit.py✅ audit.ts✅ audit/
Analytics (SQL exploration)✅ analytics.py✅ analytics.ts✅ analytics/
Jobs & workflows✅ jobs_workflows.py✅ jobs-workflows.ts✅ jobs_workflows/
Face search (multimodal)✅ face_search.py✅ face-search.ts✅ face_search/
Investigation (paths_between)✅ investigation.py✅ investigation.ts✅ investigation/

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

Work itemDeliverableStatus
OpenAPI contract + drift gateServer ROUTES table drives docs/.../api-reference.md via gen_api_reference.py; check_docs.sh fails on drift✅ Done
SDK contract-test suiteShared fixtures.yaml wire contract consumed by sdks/contract-tests/{python,typescript,go}/ (hermetic, no live server) + run_sdk_contract_tests.py (live-server, all 4 SDKs)✅ Done
3-way domain-module paritycheck_sdk_parity.py holds Python/TypeScript/Go to the same domain modules on every PR✅ Done
68 typed MCP wrappers per SDKEach of Python/TS/Go ports the full union of MCP tools (22 original + 46 from Rust's 58-tool set)✅ Done
Sessions / OTLP wrappersWrapped across all three published SDKs. In 3.0 the cluster-operation wrappers and SPARQL are removed (Enterprise / retired)2.5.8; changed in 3.0
KNN caller-supplied-embeddingAwaits a server-side vector-literal grammar; hybrid search + SIMILAR TO cover the common case todayOpen
Offline query plan cacheSDK-side cache of sha256(sql) → plan verdictP2
OpenTelemetry auto-instrumentationEvery SDK call auto-emits an OTel spanP3
Java/Kotlin SDKJVM SDK for enterprise/Spring Boot integrations (pgwire/JDBC wire-driver guides exist today)P3
C# / .NET SDK.NET SDK for Microsoft-ecosystem customersP3

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