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

Python SDK quickstart — first query in 5 minutes

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

Prerequisites

  • Python 3.11+
  • A running Relata server (cargo run -p relata-cli -- serve or ./target/debug/relata serve)

Verify the server is up:

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

1. Install

pip install relata-sdk
# or with uv
uv add relata-sdk

2. Connect and insert a row

from relata import RelataClient
 
with RelataClient("http://localhost:9090", purpose="analytics") as client:
    # Insert a row (governed — purpose is recorded in the audit log).
    client.query(
        "INSERT INTO Person (_pk, name, email) VALUES ('p1', 'Alice', 'alice@example.com')"
    )

3. Query it back

result = client.query("SELECT * FROM Person LIMIT 5")
for row in result:
    print(row["name"], row["email"])

4. Full-text + hybrid search

hits = client.search("alice", "Person", limit=5, highlight=True)
for hit in hits.hits:
    print(hit.score, hit.fields.get("name"), hit.highlights)

5. Agent memory

from relata import Memory
 
with Memory("http://localhost:9090", purpose="agent-notes") as mem:
    mid = mem.add("Alice prefers dark mode")          # governed store
    results = mem.search("ui preferences", top_k=3)    # confidence × recency × relevance
    mem.forget(mid)                                    # governed retract

6. Cypher

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

result = client.query("MATCH (n:Person {id: 'p1'}) RETURN *")
# → SELECT * FROM Person WHERE id = 'p1'

7. Jupyter notebook

%load_ext relata.ipython
 
%%relata --purpose analytics
SELECT * FROM Person LIMIT 10

Results render as a pandas DataFrame automatically.

Authentication

If the server sets RELATA_BEARER_TOKEN, pass it to the client:

client = RelataClient(
    "http://localhost:9090",
    bearer_token="relata-dev",
    purpose="analytics",
)

Multi-tenant

client = RelataClient(
    "http://localhost:9090",
    bearer_token="...",
    purpose="analytics",
    organization="org-acme",   # X-Organization-Id
)

Examples

The Python SDK ships a parallel set of runnable examples in sdks/python/examples/. Run any of them 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.ephemeral_server   # spawn + health check
RELATA_TOKEN=secret python -m examples.graphql            # GraphQL introspection + selection
RELATA_TOKEN=secret python -m examples.graph_traversal    # PATHS_BETWEEN multi-hop
RELATA_TOKEN=secret python -m examples.intelligence       # sanctions / UBO / crypto / convoy / DNS
RELATA_TOKEN=secret python -m examples.multi_search       # federated multi-query
RELATA_TOKEN=secret python -m examples.parameterized      # server-side $N binding
RELATA_TOKEN=secret python -m examples.lookups            # CSV enrichment at query time
RELATA_TOKEN=secret python -m examples.streaming          # SSE watch + transparency log
RELATA_TOKEN=secret python -m examples.a2a                # agent-to-agent tasks + checkpoints
RELATA_TOKEN=secret python -m examples.tokens             # dedup-token replay defence
RELATA_TOKEN=secret python -m examples.tenant_admin       # tenant CRUD + suspend / reactivate
RELATA_TOKEN=secret python -m examples.bitemporal         # AS OF + WITH PROVENANCE
RELATA_TOKEN=secret python -m examples.audit              # audit chain + signed/PDF reports
RELATA_TOKEN=secret python -m examples.analytics          # group-by / histogram / window funcs
RELATA_TOKEN=secret python -m examples.jobs_workflows     # detection jobs + DAG workflows
RELATA_TOKEN=secret python -m examples.face_search        # FACE_SEARCH operator
RELATA_TOKEN=secret python -m examples.investigation      # PATHS_BETWEEN forensic link analysis

Next steps