Querying & DML

KalamClient.query(...) executes SQL over HTTP. For Flutter lists, prefer Kalam Sync watch() so the UI reads the local cache.

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

Parameterized queries

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

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

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.

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

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)

1if (!res.success) {2  print(res.error);3  return;4}5 6final first = res.results.first;7print(first.columns.map((c) => c.name).toList());8 9for (final row in first.rows) {10  final id = row['id']?.asInt();11  final name = row['name']?.asString();12  final active = row['active']?.asBool();13  print('id=$id name=$name active=$active');14}

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

Multiple statements

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

DML: INSERT / UPDATE / DELETE

All SQL goes through query(...):

1await client.query(2  r"INSERT INTO app.messages (conversation_id, role, content) VALUES ($1, $2, $3)",3  params: [42, 'user', 'hello'],4);5 6await client.query(7  r"UPDATE app.messages SET content = $1 WHERE message_id = $2",8  params: ['edited', 'msg_123'],9);10 11await client.query(12  r"DELETE FROM app.messages WHERE message_id = $1",13  params: ['msg_123'],14);

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:

1final ref = KalamFileRef(2  id: '1234567890123456789',3  sub: 'f0001',4  name: 'avatar.png',5  size: 20480,6  mime: 'image/png',7  sha256: 'abc123...',8);9 10await client.query(11  r'INSERT INTO app.users (id, avatar) VALUES ($1, $2)',12  params: ['user_1', ref.toMap()],13);

Read a FILE reference

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

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

1/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:

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

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

Procedures

Typed procedure clients come from kalam schema gen --languages dart, not from a generic method on KalamClient. Generated KalamFunctions wraps query('CALL ...') the same way TypeScript createKalam(client) does:

1final db = KalamFunctions(client);2final user = await db.chat.createMessage(3  ChatCreateMessageRequest(userId: 'u1', body: 'hello'),4);

JSON parameters and returns are Map<String, Object?>. Named SQL types reuse the generated row classes. REST POST /v1/functions/{namespace}/{procedure} remains a server HTTP path for non-SDK callers.

Next

• Realtime Subscriptions
• Types & Models
• SQL Reference

Generated typed remote queries

After kalam schema gen --languages dart, reuse the generated table codecs and primary key directly:

1final inventory = KalamTables.inventory.bind(client);2final query = inventory.query()3    .filter(InventoryColumns.sku.eq('sku-1'))4    .limit(20);5final rows = await query.get();6final updates = query.live();

InventoryColumns.sku is KalamColumn<String>, so passing a number fails Dart analysis. Existing .where((c) => c.col('sku').eq(value)) remains available for dynamic queries. eq(null) and neq(null) produce IS NULL and IS NOT NULL when the column type permits null. Values use bound parameters.

orderBy on a remote live query sorts the matching rows locally before applying limit. The limit controls the displayed rows, not retained memory. Use a narrow filter for large datasets. Scalar string ordering is local and does not promise server collation equivalence. Use kalam_sync for durable local projections and offline actions; bind(client) uses remote transport and does not add persistence.

Generated Dart table specs require one declared primary key. Keyless tables still get row codecs, but no sync spec or guessed key. Composite primary keys are rejected by schema compilation to match current server support. Array codecs preserve null arrays and encode/decode each supported scalar, enum, composite, and timestamp element; null array elements are not represented by the current contract.