SDK guide
/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
| Language | Package | Status |
|---|---|---|
| Python | relata-sdk on PyPI | Reference implementation — fullest surface |
| TypeScript | @zysec-ai/relata-sdk on npm | At parity with Python (typed clients) |
| Go | github.com/relatadb/sdk-go/v2 | At 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())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-erasureAgent 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 deleteGraph + 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 operatorGovernance, 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 taskStreaming (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 / LangGraphSee 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)
| Feature | Python | TypeScript | Go | Notes |
|---|---|---|---|---|
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 + EmbedBatch | Server 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/Video | CLIP / 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_batch | 10 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 | ✅ both | async-native | ctx-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 | ✅ 68 | Each 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.
| Client | Surface | Python | TS | Go |
|---|---|---|---|---|
GovernanceClient | Rules, retention (holds + WORM), breakglass, alerts, DSAR | ✅ | ✅ | ✅ |
McpClient | 68 typed MCP tool wrappers + generic call_tool | ✅ | ✅ | ✅ |
A2AClient | A2A tasks + LangGraph checkpoints + agent card | ✅ | ✅ | ✅ |
AuditClient | Audit entries (filtered/paginated) + signed receipts + PDF export | ✅ | ✅ | ✅ |
IdentityClient | Identity label/uncertainty + lookup tables + ERASE SUBJECT | ✅ | ✅ | ✅ |
ObjectClient | Typed upsert + batch via /ingest?object_type= | ✅ | ✅ | ✅ |
IngestClient | Bulk NDJSON + CSV + media status | ✅ | ✅ | ✅ |
VectorClient | KNN + hybrid search + similar-to (SQL-backed) | ✅ | ✅ | ✅ |
S3Client | S3 protocol door wrapper | ✅ | ✅ | ✅ |
SystemClient | LLM config + test + jobs status | ✅ | ✅ | ✅ |
StreamingClient | NDJSON row streams + SSE consumers (watch/alerts) + Arrow IPC | ✅ | ✅ | ✅ |
TenantAdminClient | Tenant CRUD + quota + sharing agreements | ✅ | ✅ | ✅ |
BackupClient | Backup create / list / restore | — | ✅ | ✅ |
TokenClient | Token create / check / revoke / stats | — | ✅ | ✅ |
LogClient | Structured log query / tail | — | ✅ | ✅ |
RulesClient | Detection-rule CRUD + Sigma import | ✅ (on Gov) | ✅ (on Gov) | ✅ (on Gov) |
Memory cognitive-verb matrix
| Verb | HTTP | Python | TS | Go |
|---|---|---|---|---|
add | POST /memory/remember | ✅ | ✅ | ✅ |
add_batch | POST /memory/remember/batch | ✅ | ✅ | ✅ |
search (recall) | GET /memory/recall | ✅ | ✅ | ✅ |
get (recognize) | GET /memory/recognize/:id | ✅ | ✅ | ✅ |
update (consolidate) | POST /memory/consolidate | ✅ | ✅ | ✅ |
forget | DELETE /memory/forget/:id | ✅ | ✅ | ✅ |
associate | POST /memory/associate | ✅ | ✅ | ✅ |
episodes | GET /memory/episodes | ✅ | ✅ | ✅ |
justify | GET /memory/justify/:id | ✅ | ✅ | ✅ |
resolve | POST /memory/resolve/:id | ✅ | ✅ | ✅ |
summarise | POST /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 = ½.
| SDK | Coverage | Strengths |
|---|---|---|
| Python | 99.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 |
| TypeScript | 99.6% | Types, rules (all 8), ontology, links, identity helpers, 16 typed clients, 13 error classes, 3 framework adapters, SPARQL, cluster ops, sessions, OTLP ingest |
| Go | 99.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/KNNSearchemitsORDER BY <slot> <=> '[…]', a pgvector-ism the server parser rejects (ORDER BYonly 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 viarelataCLI or the admin dashboard) - Config:
GET /config(operator introspection) - Attestation:
GET /attestation(supply-chain verification, run viacosign verify-blob)
Runnable example inventory
Each SDK ships a parallel set of self-contained examples.
| Capability | Python | TypeScript | Go |
|---|---|---|---|
| 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_TOKENRoadmap
| Work item | Deliverable | Status |
|---|---|---|
| OpenAPI contract + drift gate | Server ROUTES table drives docs/.../api-reference.md via gen_api_reference.py; check_docs.sh fails on drift | ✅ Done |
| SDK contract-test suite | Shared 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 parity | check_sdk_parity.py holds Python/TypeScript/Go to the same domain modules on every PR | ✅ Done |
| 68 typed MCP wrappers per SDK | Each of Python/TS/Go ports the full union of MCP tools (22 original + 46 from Rust's 58-tool set) | ✅ Done |
| Sessions / OTLP wrappers | Wrapped 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-embedding | Awaits a server-side vector-literal grammar; hybrid search + SIMILAR TO cover the common case today | Open |
| Offline query plan cache | SDK-side cache of sha256(sql) → plan verdict | P2 |
| OpenTelemetry auto-instrumentation | Every SDK call auto-emits an OTel span | P3 |
| Java/Kotlin SDK | JVM SDK for enterprise/Spring Boot integrations (pgwire/JDBC wire-driver guides exist today) | P3 |
| C# / .NET SDK | .NET SDK for Microsoft-ecosystem customers | P3 |
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