Querying & DML

Raw SQL execution

1const res = await client.query('SELECT * FROM app.messages LIMIT 10');2console.log(res.status, res.results?.[0]?.named_rows);

With parameters:

1const res = await client.query(2  'SELECT * FROM app.messages WHERE conversation_id = $1',3  ['conv_42'],4);

From client.ts, params are sent through queryWithParams(sql, JSON.stringify(params)).

Vector search queries

Vector search uses the same query() and helper APIs as any other SQL workflow.

1const matches = await client.queryAll(2  `SELECT d.id, d.title3   FROM rag.documents AS d4   JOIN rag.documents_vectors AS v ON v.id = d.id5   ORDER BY COSINE_DISTANCE(v.doc_embedding, $1)6   LIMIT 5`,7  [JSON.stringify(queryEmbedding)],8);

Typical SQL setup:

1CREATE TABLE rag.documents_vectors (2  id BIGINT PRIMARY KEY,3  doc_embedding EMBEDDING(384)4) WITH (TYPE = 'USER');5 6ALTER TABLE rag.documents_vectors7  CREATE INDEX doc_embedding USING COSINE;

See /docs/server/architecture/vector-search for the full schema and retrieval pattern.

Row helpers (named_rows)

query() returns a raw QueryResponse. Results are exposed via results?.[0]?.named_rows as plain named-column maps from the server.

For ergonomic access, use:

• queryOne(sql, params?) → RowData | null
• queryAll(sql, params?) → RowData[]
• queryRows<T>(sql, tableName, params?) → KalamRow<T>[]

queryOne() and queryAll() are intentionally not generic. They return RowData with KalamCellValue wrappers. Use queryRows<T>() when you want typed application objects plus FILE-aware row helpers.

1const one = await client.queryOne('SELECT id, name FROM app.users WHERE id = $1', ['u1']);2console.log(one?.id.asString(), one?.name.asString());3 4const many = await client.queryAll('SELECT id, active FROM app.users');5for (const row of many) {6  console.log(row.id.asString(), row.active.asBool());7}

For FILE-aware row wrappers (.file() / .downloadUrl()):

1interface MessageRow {2  id: string;3  sender: string;4  content: string;5}6 7const rows = await client.queryRows<MessageRow>(8  'SELECT id, sender, content, avatar FROM app.messages',9  'app.messages',10);11console.log(rows[0]?.data.sender);

The helper methods above wrap each value as KalamCellValue (.asString(), .asInt(), .asFile(), etc.). See /docs/ts-sdk/cell-values for the full API.

executeAsUser

1await client.executeAsUser(2  'SELECT * FROM app.messages LIMIT 1',3  'alice',4);

Source behavior:

• wraps SQL as EXECUTE AS '<user_id>' ( <statement> )
• strips trailing semicolons in inner SQL
• escapes ' in the target user id
• requires one non-empty statement and a non-empty user id
• is valid for USER and STREAM tables; SHARED tables use their table policy directly
• KalamDB authorizes cross-user targets with its role matrix: system can target any role, DBA can target DBA/service/user, service can target service/user, and regular users can only target themselves

For the underlying table policy and role matrix, see /docs/server/architecture/table-types and /docs/server/sql-reference/impersonation.

Convenience DML methods

1await client.insert('app.messages', {2  id: 1,3  sender: 'alice',4  content: 'hello',5});6 7await client.update('app.messages', 1, { content: 'updated' });8await client.delete('app.messages', 1);

Important caveat

update() builds SQL string values directly (with quote escaping for strings). For complex/untrusted inputs, prefer query() with parameter placeholders where possible.

Type shape notes from generated declarations

Generated SDK types mark some fields optional:

1interface QueryResponse {2  status: 'success' | 'error';3  results?: QueryResult[];4  took?: number;5  error?: ErrorDetail;6}7 8interface QueryResult {9  schema?: SchemaField[];10  rows?: unknown[][];11  named_rows?: Record<string, unknown>[];12  row_count: number;13  message?: string;14}

Handle missing results/schema defensively in generic tooling; prefer named_rows when present.