Python client

A single-file client lives in clients/python. It uses only the standard library for HTTP, and pyarrow for Arrow results.

from curral import Client, CurralError

c = Client("https://curral.example.com", token="curral_...")   # API key or OIDC ID token
# c = Client("http://127.0.0.1:8080", user="analyst", password="...")

t = c.query("SELECT * FROM orders WHERE amount > $1", [100])   # pyarrow.Table
df = t.to_pandas()                                             # or polars.from_arrow(t)

for row in c.iter_rows("SELECT id, amount FROM orders"):       # dicts, streamed as NDJSON
    ...

print(c.dry_run("DELETE FROM orders"))   # decision, tables, targets, limits; nothing runs

Errors: a refused or failed request raises CurralError with status and request_id, the same id as in the audit log.
Row limit: when a result hits the server’s row limit, a TruncatedResultWarning is issued.
Mid-stream failures raise an exception instead of returning a short result.
Custom CA: pass cafile=.

Without the client

Any Arrow-aware tool can read the stream directly:

import pyarrow as pa, requests

r = requests.post("http://127.0.0.1:8080/v1/query",
                  auth=("analyst", "analyst-pw"),
                  json={"sql": "SELECT * FROM orders", "format": "arrow"})
table = pa.ipc.open_stream(r.content).read_all()