Python 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.

pip install relata-sdk — Python 3.11+. Hard deps: httpx, pydantic. Async extras: pyarrow, pandas, langgraph, boto3/aiobotocore (all optional — install only what you use). The SDK ships sync + async mirrors of every client (42 classes total) so the same code shape works in scripts and in asyncio servers.

See the SDK overview for the cross-language parity matrix. This page is the Python capability catalog.

Quickstart

pip install relata-sdk
from relata import RelataClient
from relata.ingest import IngestClient
 
with RelataClient("http://localhost:9090", purpose="analytics") as client:
    # /query is read-only (#782) — writes go through the governed ingest door.
    IngestClient.from_client(client).bulk(
        "Person", [{"id": "p1", "name": "Alice", "email": "a@x.com"}]
    )
    for row in client.query("SELECT * FROM Person LIMIT 5"):
        print(row["name"], row["email"])

Async is the same surface with an a-prefix: await client.aquery(...), await client.asearch(...), etc. Use async with RelataClient(...) for scoped lifecycles.

The query surface

PathMethodReturns
SQLquery(sql, purpose=None, dialect=None) / aqueryQueryResult (iterable)
Parameterizedquery_params(sql, params, purpose=None) / aquery_paramsQueryResult — ? auto-rewrites to $N
Arrow IPCquery_arrow(sql, purpose=None)pyarrow.Table — zero-copy
Arrow Flight (gRPC)query_flight(sql, flight_endpoint=None, ...) / aquery_flightpyarrow.Table
GraphQLgraphql(query, variables=None, operation_name=None) / agraphqldict — variables bound server-side (#3260)
SPARQLsparql(query)dict
Cypherany MATCH-prefixed string via query()auto-routed, governed
GQL (ISO 39075)query(stmt, dialect="gql")header-selected, governed (#3265)
Fluent builderclient.select(*cols).where(...).limit(10).execute() / .aexecute()QueryResult
from relata import select
 
result = (select("*").from_("Person")
          .where("age > $1").where_param("age > $1", 25)
          .order_by("name").limit(10)
          .purpose("analytics").execute())

Typed domain clients

Every domain client has sync + async mirrors and a .from_client(client) factory that inherits auth/tenant/purpose/timeout:

from relata import (
    GovernanceClient, IdentityClient, ObjectClient, IngestClient,
    VectorClient, SearchClient, StreamingClient, AuditClient,
    TenantAdminClient, BackupClient, TokenClient, LogClient,
    SystemClient, A2AClient, McpClient, Namespace,
)
ClientKey methodsCross-ref
GovernanceClientrules CRUD, Sigma import, retention/WORM/legal-holds, breakglass, alerts, DSARDetection Rules
IdentityClientlabel, record_uncertainty, register_lookup/list_lookups/invoke_lookup, erase_subjectIdentity (active learning)
ObjectClientupsert, typed_upsert, batch_upsert, get, delete—
IngestClientbulk, bulk_csv, ingest_auto, ingest_cdr, otlp_traces/logs/metrics, ingest_iterIngestion
VectorClientknn_search, hybrid_search, similar_to, embed/embed_batch + embed_image/face/audio/videoHybrid Search
SearchClienttyped /search JSON door: query(namespace, text=..., rank_by=..., filters=..., limit=...)Search reference
StreamingClientquery_rows (NDJSON), query_arrow_raw, watch/watch_stream (SSE), alerts (SSE)—
AuditClientcount, entries(...), find_by_request_id, sign_receipt, export_pdf → bytes—
TenantAdminClienttenant CRUD, quota, sharing, platform usage/licenseEnterprise edition only; the open build has one tenant
BackupClientcreate, list, restore, restore_status, compact, wait_for_restoreBackup & Restore
TokenClientremember, check, revoke, stats (dedup tokens)—
LogClientappend, head, load_leaves (integrity log)—
SystemClientLLM config/test, jobs/workflows, feeds, notifications, pipelines—
A2AClientsubmit_task, get_task, checkpoints, agent_card—
McpClientinitialize, list_tools, call_tool + 68 typed tool wrappersMCP Tools
Namespaceclient.namespace("Document") → query/write/get/delete_all/branch_fromSearch reference

Vectors & embeddings

vc = client.vector_client          # or: VectorClient.from_client(client)
 
# Pure KNN over a named slot
vc.knn_search("Document", "embedding", [0.1, ...], k=10, ef_search=200)
 
# Hybrid: BM25 + vector + graph, RRF-fused
vc.hybrid_search("Document", query_text="graph retrieval", k=10,
                 rerank=True, weights=[0.2, 0.5, 0.3])
 
# Embedding (6 modalities) — uses server's CPU lexical default or GPU sidecar
emb = vc.embed("Alice Smith")            # → {embedding, model, dim}
vc.embed_image(base64_bytes)             # CLIP
vc.embed_face(base64_bytes)              # ArcFace
vc.embed_audio(base64_bytes)             # CLAP
vc.embed_video(base64_bytes)             # CLIP keyframe

Graph & intelligence operators

All on RelataClient directly — 10 graph algorithms + 10 AML/financial + 3 maritime:

client.graph_pagerank("Person", damping=0.85, max_iter=20)
client.graph_shortest_path("alice-id", "bob-id", max_hops=5)
client.graph_community("Person")
 
# Financial intelligence
client.sanctions_screen("Acme Holdings", threshold=0.85)
client.beneficial_ownership_chain("Acme Holdings", max_depth=6)
client.crypto_trace("0xabc...", purpose="compliance")
 
# Maritime
client.vessel_track(mmsi=123456789, window_secs=86400)
client.dark_fleet_detect(max_gap_hours=48)

See Graph Analytics for the algorithm matrix and the SQL TVF / gds.* / traverse.* surfaces.

Agent memory — 10 cognitive verbs + recall-quality knobs

from relata import Memory
 
mem = Memory("http://localhost:9090", bearer_token="<token>", purpose="agent")
mid = mem.add("Alice prefers dark mode", confidence=0.9, memory_class="semantic")
 
# retrieval-quality operators — tune what comes back
results = mem.search(
    "ui preferences", top_k=10,
    min_confidence=0.6,            # CONFIDENCE floor
    recency_half_life_secs=259200,  # 3-day decay  (RECENCY)
    budget_tokens=1500,            # hard prompt budget  (BUDGET)
    cancel_threshold=0.92,         # stop on a great match  (CANCEL_WHEN)
)
detail = mem.search_detailed(...)  # exposes recall_cost_tokens + cancelled

The full verb set: add, add_batch, search, search_detailed, get, update, forget, associate, episodes, justify, resolve, summarise. See Agent memory reference (recall knobs + the 5 operators).

Ecosystem (Python-only)

ExtraInstallSurface
7 framework adaptersrelata_adapters (ships with the package)RelataMemory for LangChain / LlamaIndex / CrewAI / AutoGen(+AG2) / Pydantic-AI / smolagents — duck-typed, install only your framework
LangGraph checkpointer (the 7th adapter)pip install relata-sdk[langgraph]RelataCheckpointer + AsyncRelataCheckpointer (real BaseCheckpointSaver subclasses; persist via the governed A2A door)
IPython / Jupyter magicpip install relata-sdk[ipython]%%relata --purpose analytics cell magic → results render as a pandas DataFrame
S3 door helperpip install relata-sdk[s3]S3Client.boto3() / AsyncS3Client.aio() / S3Client.httpx() — returns a configured boto3/aiobotocore/httpx client pointed at Relata's S3 door
# Auto-detect which framework is installed and return the right adapter
from relata_adapters.registry import get_memory_adapter
Adapter = get_memory_adapter()   # LangChain/LlamaIndex/CrewAI/... or None
mem = Adapter(relata_memory_backend) if Adapter else None

Authentication & multi-tenant

client = RelataClient(
    "http://localhost:9090",
    bearer_token="<token>",
    purpose="analytics",
    tenant="org-acme",          # X-Relata-Tenant-Id on every request
    acting_as="user-42",        # X-Acting-As (delegation)
    delegated_by="admin-1",     # X-Delegated-By
    timeout=30.0,
    max_retries=3,
    admin_base_url="http://admin.internal:9090",  # /admin/* + /platform/* zero-trust split
)

Examples

The SDK ships ~25 runnable examples in sdks/python/examples/. Run any with python -m examples.<name>:

RELATA_TOKEN=secret python -m examples.basic_query        # minimal connect + SELECT
RELATA_TOKEN=secret python -m examples.ingest             # bulk + CSV ingest
RELATA_TOKEN=secret python -m examples.advanced_query     # filter + aggregate + Arrow
RELATA_TOKEN=secret python -m examples.governance         # PURPOSE + audit + types
RELATA_TOKEN=secret python -m examples.memory_quickstart  # add / search / forget
RELATA_TOKEN=secret python -m examples.multi_tenant       # org isolation
RELATA_TOKEN=secret python -m examples.intelligence       # sanctions / UBO / crypto / convoy / DNS
RELATA_TOKEN=secret python -m examples.face_search        # FACE_SEARCH operator
RELATA_TOKEN=secret python -m examples.streaming          # SSE watch + transparency log
RELATA_TOKEN=secret python -m examples.a2a                # agent-to-agent + checkpoints
RELATA_TOKEN=secret python -m examples.bitemporal         # AS OF + WITH PROVENANCE

Full set: sdks/python/examples/.

Next steps