Skip to Content
Querying & DML

Querying & DML

KalamClient.query(...) executes SQL over the KalamDB HTTP API and returns a QueryResponse.

DART
final response = await client.query('SELECT 1');print(response.success);

Parameterized queries

Use $1, $2, … placeholders in SQL and pass params as a Dart list.

DART
final res = await client.query(  r'SELECT * FROM app.messages WHERE conversation_id = $1 AND is_deleted = $2',  params: ['conv_42', false],);

params is encoded to JSON and sent to the server, so values should be JSON-compatible (strings, numbers, booleans, null, lists, and maps).

If you need richer server-side typing (timestamps, decimals, JSON columns), keep your SQL explicit (e.g. CAST(...)) and validate the returned values.

Namespaces

KalamDB supports per-tenant namespaces. The SDK exposes this as an optional namespace argument.

DART
final res = await client.query(  'SELECT * FROM messages ORDER BY created_at DESC LIMIT 10',  namespace: 'alice',);

This is most useful when your SQL references unqualified tables (e.g. messages instead of alice.messages).

For background, see: SQL Reference: Namespaces.

Reading results

A QueryResponse can contain multiple QueryResult values (one per statement). The most common pattern is to read the first one.

Primary row access (QueryResult.rows)

DART
if (!res.success) {  print(res.error);  return;} final first = res.results.first;print(first.columns.map((c) => c.name).toList()); for (final row in first.rows) {  final id = row['id']?.asInt();  final name = row['name']?.asString();  final active = row['active']?.asBool();  print('id=$id name=$name active=$active');}

rows is List<Map<String, KalamCellValue>> (named columns), not List<List<dynamic>>.

Multiple statements

DART
final res = await client.query('SELECT 1; SELECT 2;'); for (final (i, r) in res.results.indexed) {  print('statement[$i] columns=${r.columns.length} rows=${r.rowCount}');}

DML: INSERT / UPDATE / DELETE

All SQL goes through query(...):

DART
await client.query(  r"INSERT INTO app.messages (conversation_id, role, content) VALUES ($1, $2, $3)",  params: [42, 'user', 'hello'],); await client.query(  r"UPDATE app.messages SET content = $1 WHERE message_id = $2",  params: ['edited', 'msg_123'],); await client.query(  r"DELETE FROM app.messages WHERE message_id = $1",  params: ['msg_123'],);

FILE refs: insert and read

Insert a FILE reference value

If you already have file metadata (for example from a previous read), insert it as JSON:

DART
final ref = KalamFileRef(  id: '1234567890123456789',  sub: 'f0001',  name: 'avatar.png',  size: 20480,  mime: 'image/png',  sha256: 'abc123...',); await client.query(  r'INSERT INTO app.users (id, avatar) VALUES ($1, $2)',  params: ['user_1', ref.toMap()],);

Read a FILE reference

DART
final res = await client.query('SELECT id, avatar FROM app.users WHERE id = $1', params: ['user_1']);final row = res.rows.first; final fileRef = row['avatar']?.asFile();if (fileRef != null) {  final url = fileRef.getDownloadUrl('http://localhost:18080', 'app', 'users');  print('${fileRef.name} ${fileRef.formatSize()} $url');}

getDownloadUrl(...) delegates to the shared Rust link-common FileRef model, the same source used by the TypeScript SDK. The returned path is:

TEXT
/v1/files/{namespace}/{table}/{sub}/{stored_name}

Fetch the URL with the authenticated user’s bearer token. For user tables, SDK helpers generate an owner-scoped URL: regular users can download only their own files. Service clients can upload/write through authorized EXECUTE AS USER flows, but direct cross-user FILE byte downloads require a dba or system token and an authorized user_id query parameter.

Error handling

When success is false, the server returns an error code/message:

DART
final res = await client.query('SELECT * FROM table_that_does_not_exist');if (!res.success) {  throw StateError('${res.error}');}

For user-facing apps, prefer mapping error.code to a stable UI message and logging error.details for debugging.

Next

Last updated on
Auth-Aware ClientRealtime Subscriptions