🖥️ System & Cluster Ops

Multi-node cluster control plus the high-throughput wire protocols and live event stream.

Cluster ops (RELATA_PROFILE=cluster)

Four methods for multi-node deployments:

client.cluster_nodes()
# [ClusterNode(id="node-7f3a", role="coordinator", addr="10.0.0.1:9090",
#              partitions=[0,1,2], state="healthy"),
#  ClusterNode(id="node-9b2c", role="reader",      addr="10.0.0.2:9090", ...)]
 
client.cluster_topology()
# {"nodes": [...], "partitions": [{"id": 0, "primary": "node-7f3a",
#                                  "replicas": ["node-9b2c"]}], "roles": {...}}
 
client.cluster_rebalance()
# {"rebalanced": True, "partitions_moved": 3, "duration_ms": 1240}
 
client.cluster_drain("node-9b2c")   # evacuate for maintenance
# {"drained": True, "node": "node-9b2c", "partitions_relocated": 3}

Observe stream (live SSE)

for event in client.observe_stream():
    print(event["kind"], event["level"], event["message"])
# query INFO  SELECT name FROM Person (rows=4, latency_ms=2.1)
# ingest INFO bulk Person rows=4
# ...

Requires RELATA_OBSERVE_STREAM=on server-side. A connection drop ends the generator cleanly rather than raising.

Webhooks

client.register_webhook(
    "https://hooks.slack.com/services/...",
    event_types=["ingest.completed", "alert.triggered"],
)
# {"id": "wh_019fe2...", "url": "https://...", "event_types": [...]}
 
client.list_webhooks()
# {"webhooks": [{"id": "wh_019fe2...", ...}]}
 
client.delete_webhook("wh_019fe2...")
# {"deleted": True}

Arrow Flight (zero-copy columnar over gRPC)

tbl = client.query_flight(
    "SELECT * FROM Transaction LIMIT 1000", purpose="analytics",
)
df = tbl.to_pandas()
# Requires RELATA_FLIGHT_ENABLE=true (port 8815); pyarrow only, no grpcio.

Plain gRPC (RelataQuery.Execute)

result = client.query_grpc("SELECT * FROM Person LIMIT 1000")
# Same QueryResult shape as query(); requires grpcio
# (pip install relata-sdk[grpc]).
 
result = client.query_grpc_stream("SELECT * FROM Transaction")
# Server-streaming variant — same shape, frame-by-frame.

Next: Audit & Provenance — the hash-chained, tamper-evident audit log and court-grade PDF export.