Skip to Content
SQL ReferenceTable DDL

Table DDL

KalamDB supports three table types: USER, SHARED, and STREAM. See Table Types for detailed descriptions.

CREATE TABLE

Syntax

sql snippetSQL
CREATE [USER|SHARED|STREAM] TABLE [IF NOT EXISTS] [<namespace>.]<table_name> (  <column_name> <data_type> [NOT NULL|NULL] [DEFAULT <expr>] [PRIMARY KEY],  ...,  [CONSTRAINT <name> PRIMARY KEY (<column_name>)])[WITH (  TYPE = '<USER|SHARED|STREAM>',  STORAGE_ID = '<storage_id>',  USE_USER_STORAGE = <TRUE|FALSE>,  FLUSH_POLICY = '<rows:N|interval:N|rows:N,interval:N>',  DELETED_RETENTION_HOURS = <hours>,  TTL_SECONDS = <seconds>,  ACCESS_LEVEL = '<PUBLIC|PRIVATE|RESTRICTED>')];

WITH Options

OptionApplies ToDescription
TYPEAllTable type when not using prefix syntax
STORAGE_IDAllTarget storage backend
USE_USER_STORAGEUSERUse per-user storage directory
FLUSH_POLICYUSER, SHAREDWhen to flush hot → cold tier
DELETED_RETENTION_HOURSAllSoft-delete retention period
TTL_SECONDSSTREAMAuto-eviction time for stream data
ACCESS_LEVELSHAREDPUBLIC, PRIVATE, or RESTRICTED

Examples

User table (per-user isolated):

sql snippetSQL
CREATE TABLE app.messages (  id BIGINT PRIMARY KEY DEFAULT SNOWFLAKE_ID(),  conversation_id BIGINT NOT NULL,  sender TEXT NOT NULL,  role TEXT NOT NULL DEFAULT 'user',  content TEXT NOT NULL,  created_at TIMESTAMP NOT NULL DEFAULT NOW()) WITH (  TYPE = 'USER',  FLUSH_POLICY = 'rows:1000,interval:60');

Shared table (global access):

sql snippetSQL
CREATE SHARED TABLE app.config (  key TEXT PRIMARY KEY,  value TEXT NOT NULL,  updated_at TIMESTAMP DEFAULT NOW()) WITH (  ACCESS_LEVEL = 'PUBLIC');

Stream table (ephemeral with TTL):

sql snippetSQL
CREATE STREAM TABLE app.events (  event_id TEXT PRIMARY KEY,  payload TEXT,  created_at TIMESTAMP DEFAULT NOW()) WITH (  TTL_SECONDS = 30);

ALTER TABLE

sql snippetSQL
-- Add a columnALTER TABLE [<namespace>.]<table_name>  ADD COLUMN <name> <type> [NOT NULL|NULL] [DEFAULT <value>]; -- Drop a columnALTER TABLE [<namespace>.]<table_name>  DROP COLUMN <name>; -- Modify a column typeALTER TABLE [<namespace>.]<table_name>  MODIFY COLUMN <name> <type> [NOT NULL|NULL]; -- Change table propertiesALTER TABLE [<namespace>.]<table_name>  SET TBLPROPERTIES (ACCESS_LEVEL = '<PUBLIC|PRIVATE|RESTRICTED>'); -- Create a vector index on an embedding columnALTER TABLE [<namespace>.]<table_name>  CREATE INDEX <embedding_column> USING COSINE;

Vector index example

sql snippetSQL
CREATE TABLE rag.documents_vectors (  id BIGINT PRIMARY KEY,  embedding EMBEDDING(384)) WITH (TYPE = 'USER'); ALTER TABLE rag.documents_vectors  CREATE INDEX embedding USING COSINE;

After the index exists, rank nearest rows with:

sql snippetSQL
SELECT idFROM rag.documents_vectorsORDER BY COSINE_DISTANCE(embedding, '[0.12,0.03,0.98]')LIMIT 10;

DROP TABLE

sql snippetSQL
DROP TABLE [IF EXISTS] [<namespace>.]<table_name>;DROP USER TABLE [IF EXISTS] [<namespace>.]<table_name>;DROP SHARED TABLE [IF EXISTS] [<namespace>.]<table_name>;DROP STREAM TABLE [IF EXISTS] [<namespace>.]<table_name>;

CREATE VIEW

sql snippetSQL
CREATE VIEW [<namespace>.]<view_name> AS <select_query>;CREATE VIEW [<namespace>.]<view_name> (<column1>, <column2>, ...) AS <select_query>;

Example:

sql snippetSQL
CREATE VIEW chat.recent_messages AS  SELECT id, sender, content, created_at  FROM chat.messages  WHERE created_at > NOW() - INTERVAL '1 hour'  ORDER BY created_at DESC;

SHOW TABLES

sql snippetSQL
SHOW TABLES;SHOW TABLES IN <namespace>;SHOW TABLES IN NAMESPACE <namespace>;

DESCRIBE TABLE

sql snippetSQL
DESCRIBE TABLE [<namespace>.]<table_name>;DESC TABLE [<namespace>.]<table_name>; -- Show table historyDESCRIBE TABLE [<namespace>.]<table_name> HISTORY;

SHOW STATS

sql snippetSQL
SHOW STATS FOR TABLE [<namespace>.]<table_name>;
Last updated on