Transport & Endpoints
The Dart SDK is a high-level wrapper over the same public endpoints described in the API reference.
SQL execution (HTTP)
query(...) executes SQL over the HTTP SQL endpoint.
- See: HTTP API Reference
- See: SQL Reference
The SDK passes params as JSON (for $1, $2, … placeholders).
Related auth endpoints used by the SDK:
login(...)→POST /v1/api/auth/loginrefreshToken(...)→POST /v1/api/auth/refreshexchangeOidcToken(...)→POST /v1/api/auth/oidc/exchange-token
FILE download helpers use the shared KalamDB file endpoint:
| Method | Endpoint | Dart helpers |
|---|---|---|
GET | /v1/files/{namespace}/{table}/{sub}/{stored_name} | KalamFileRef.getDownloadUrl(...), KalamCellValue.asFileUrl(...) |
The last path segment is the stored filename generated by the shared
link-common FileRef model. It is not the raw file id by itself.
For user tables, these helpers generate owner-scoped URLs. A regular user can
download only their own files; service tokens can write through authorized
EXECUTE AS USER flows, but direct cross-user FILE byte downloads require a
dba or system token with an authorized user_id query parameter.
Live subscriptions (WebSocket)
live(), liveTable(), and liveEvents() use the WebSocket realtime endpoint.
- See: WebSocket Protocol
- See: Architecture: Live Query
On native Dart and Flutter targets, the shared subscription connection defaults The 0.8 client uses the shared KDOM binary codec. Legacy MessagePack connections are rejected; keep the SDK and server on the same release cohort.
Debugging compression
By default, the server may send gzip-compressed frames. For local debugging, disable compression:
This appends ?compress=false to the WS URL so you can more easily inspect frames.
Do not enable in production. Compression reduces bandwidth and improves performance.
Timeouts and retries
timeoutcontrols HTTP request timeout for queries.maxRetriescontrols retry count for idempotent queries (typicallySELECT).