Querying & SQL

The CLI is SQL-first: if a statement works through /v1/api/sql, send it unchanged via kalam --command, kalam --file, or the interactive shell.

Execution options

1kalam --command "SELECT * FROM system.tables LIMIT 5;"2kalam --command "SELECT * FROM system.tables LIMIT 5;" --json3kalam --file ./setup.sql --csv4kalam --url kalam.masky.app --command "SELECT 1;"

Common patterns

1# Read system metadata2kalam -c "SELECT * FROM system.tables ORDER BY namespace_id, table_name LIMIT 20;"3 4# DDL / DML5kalam -c "CREATE NAMESPACE chat;"6kalam -c "CREATE TABLE chat.messages (id BIGINT PRIMARY KEY, body TEXT) WITH (TYPE='USER');"7kalam -c "INSERT INTO chat.messages (id, body) VALUES (1, 'hello');"8 9# Run a whole SQL file10kalam -f ./migrations/001-init.sql

Namespace state in interactive mode

Namespace switching is SQL, not a backslash command:

1USE NAMESPACE chat;2SELECT * FROM messages ORDER BY id DESC LIMIT 20;3\flush table messages

After USE NAMESPACE chat, SET NAMESPACE chat, or USE chat, the CLI stores chat locally and sends it as namespace_id on later requests. Unqualified table names resolve to chat.<table> until you switch again. The prompt shows the active namespace as ns:<name>.

Table footer metadata

In table format, results end with row count and footer metadata:

1(50 rows)23As: alice4Took: 2.146 ms

• As: — effective user (includes EXECUTE AS and \as)
• Took: — server-reported execution time in milliseconds

Interactive formatting

Related

• SQL reference
• Interactive Commands
• SQL Workflows