Table Types

KalamDB uses four runtime table types:

• USER
• SHARED
• STREAM
• SYSTEM (internal)

Table-Type Routing Model

Quick Selection

• choose USER for tenant/user-isolated data
• choose SHARED for global application data
• choose STREAM for short-lived realtime event state
• treat SYSTEM as internal metadata tables managed by the engine

SQL Creation Patterns

Recommended unified syntax:

CREATE TABLE app.messages (
  id BIGINT PRIMARY KEY DEFAULT SNOWFLAKE_ID(),
  content TEXT NOT NULL,
  created_at TIMESTAMP DEFAULT NOW()
) WITH (TYPE = 'USER');

Also supported for compatibility:

• CREATE USER TABLE ...
• CREATE SHARED TABLE ...
• CREATE STREAM TABLE ...

USER Tables

Per-user logical isolation with user-aware routing and permissions.

CREATE TABLE chat.messages (
  id BIGINT PRIMARY KEY DEFAULT SNOWFLAKE_ID(),
  conversation_id BIGINT NOT NULL,
  content TEXT NOT NULL,
  created_at TIMESTAMP DEFAULT NOW()
) WITH (
  TYPE = 'USER',
  FLUSH_POLICY = 'rows:1000,interval:60',
  STORAGE_ID = 'local'
);

Use for: conversations, preferences, private records, tenant data.

SHARED Tables

Global shared scope for all users.

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

Use for: reference data, global settings, shared catalogs.

STREAM Tables

Ephemeral rows with TTL-based eviction. Like USER tables, STREAM tables are scoped per user tenant and are not shared across all users.

CREATE TABLE chat.typing_events (
  event_id BIGINT PRIMARY KEY DEFAULT SNOWFLAKE_ID(),
  user_id TEXT NOT NULL,
  event_type TEXT NOT NULL,
  created_at TIMESTAMP DEFAULT NOW()
) WITH (
  TYPE = 'STREAM',
  TTL_SECONDS = 30
);

Use for: typing indicators, presence, cursor events, transient signals.

Realtime Subscriptions

Today, KalamDB supports realtime subscriptions to all three primary application table types: USER, SHARED, and STREAM. This allows applications to listen for live changes (inserts, updates, deletes) as they happen, enabling reactive UIs and realtime workflows.

Subscriptions can be full-row (SELECT *) or projected (SELECT username, status FROM chat.changes ...) depending on the payload shape your client needs.

SYSTEM Tables

Internal control-plane and metadata tables (system.*).

• not intended for normal app DDL lifecycle
• role-restricted access for sensitive operations
• file upload/download flows reject SYSTEM tables

Capability Matrix

Capability Definitions

• App DDL creation: Whether application SQL can create/manage this table type directly.
• Per-user isolation: Whether data is automatically isolated by authenticated user/tenant.
• ACCESS_LEVEL option: Whether table-level access policy can be configured through ACCESS_LEVEL.
• TTL_SECONDS option: Whether the table supports TTL-based automatic row eviction.
• USE_USER_STORAGE option: Whether table storage can be explicitly pinned to user-scoped storage paths.
• Cold-tier Parquet lifecycle: Whether hot data can flush/compact into cold-tier Parquet segments.
• File APIs supported: Whether /v1/files/... upload/download flows are supported for rows in this table type.
• Live Query: Whether realtime subscriptions can stream change events from this table type.
• Cluster multi-group Raft support: Whether metadata/data operations for this table type participate in clustered Raft replication groups.

Related Docs

• Table DDL
• Storage Tiers
• FILE Datatype
• File - Upload & DataType
• Storage ID Usage