Schema & Query Diagnostics

Use these commands to inspect table schemas and query execution plans. They are intended for operators, DBAs, and developers tuning SQL against KalamDB tables.

For storage-tier background on plan metrics, see /docs/server/architecture/storage-tiers.

DESCRIBE — table schema

KalamDB supports two DESCRIBE styles. Both answer “what columns does this table have?”, but they use different syntax, authorization, and result shapes.

`DESCRIBE TABLE` (KalamDB native)

SQL

1DESCRIBE TABLE [<namespace>.]<table_name>;2DESC TABLE [<namespace>.]<table_name>;3 4-- Schema version history5DESCRIBE TABLE [<namespace>.]<table_name> HISTORY;

Access: authenticated users with an elevated role (DBA or System). Regular User role statements are rejected at execution time.

Returns: rich column metadata from the schema registry:

Column	Description
`column_name`	Column name
`ordinal_position`	1-based position in the table
`column_id`	Parquet field id
`data_type`	Kalam SQL type name (for example `TEXT`, `BIGINT`, `TIMESTAMP`)
`is_nullable`	Whether the column allows `NULL`
`is_primary_key`	Whether the column is part of the primary key
`column_default`	Default expression, if any
`column_comment`	Column comment, if any
`schema_version`	Schema version when the column was added

Example:

SQL

1DESCRIBE TABLE dba.notifications;

`DESCRIBE <table>` / `DESC <table>` (DataFusion shorthand)

SQL

1DESCRIBE [<namespace>.]<table_name>;2DESC [<namespace>.]<table_name>;

Access: DBA or System only (admin meta command).

Behavior: KalamDB rewrites the statement to query information_schema.columns and returns Kalam SQL type names (kdb_data_type) instead of Arrow physical types:

Column	Description
`column_name`	Column name
`data_type`	Kalam SQL type (`kdb_data_type`)
`is_nullable`	`YES` / `NO`

Unqualified table names resolve against the session’s current namespace (USE NAMESPACE, CLI ns:<name> context, or API namespace_id).

Example:

SQL

1USE NAMESPACE dba;2DESCRIBE notifications;

CLI shortcut

In the interactive shell, \d <table> and \describe <table> run an information_schema.columns query with Kalam type names — the same columns as the shorthand above, plus namespace, column_default, and position:

SQL

1\d dba.notifications2\describe notifications

See CLI querying for output formats.

EXPLAIN — query plans

EXPLAIN shows how DataFusion plans a query without executing it (unless ANALYZE is present).

Access: DBA or System only.

Syntax (keyword order matters)

DataFusion expects this order:

SQL

1EXPLAIN [ANALYZE] [VERBOSE] [FORMAT <indent|tree|pgjson>] <query>;

Keyword	Position	Effect
`EXPLAIN`	required	Start the diagnostic command
`ANALYZE`	optional, before `VERBOSE`	Execute the query and attach runtime metrics
`VERBOSE`	optional, after `ANALYZE`	Add extra result rows (full metrics, row count, duration) when combined with `ANALYZE`
`FORMAT`	optional	Plan rendering style (`indent` default, `tree`, `pgjson`)

Common mistake: EXPLAIN VERBOSE ANALYZE is not valid. Use EXPLAIN ANALYZE VERBOSE instead. With the wrong order, the parser treats ANALYZE as a separate statement and fails.

`EXPLAIN` (plan only)

Returns two rows — logical plan and physical plan — without running the query:

SQL

1EXPLAIN2SELECT id, user_id3FROM dba.notifications4WHERE user_id = 'test'5LIMIT 3;

Example output columns:

plan_type	plan
`logical_plan`	Optimized logical plan tree
`physical_plan`	Physical operators (`FilterExec`, `GlobalLimitExec`, `DeferredBatchExec`, …)

`EXPLAIN ANALYZE` (plan + runtime metrics)

Executes the query, discards result rows to the client, and returns an annotated physical plan with per-operator metrics:

SQL

1EXPLAIN ANALYZE2SELECT id, user_id, _deleted3FROM dba.notifications4WHERE user_id = 'test'5LIMIT 3;

Returns one primary row:

plan_type	plan
`Plan with Metrics`	Physical plan tree with timing and counter metrics

On USER and SHARED tables, KalamDB enables scan diagnostics for EXPLAIN ANALYZE. Look for DeferredBatchExec nodes and metrics such as:

Metric	Meaning
`hot_rows_scanned`	Rows read from the hot tier (RocksDB)
`cold_rows_scanned`	Rows read from cold Parquet files
`cold_files_total`	Cold files considered by manifest pruning
`cold_files_skipped`	Cold files skipped by pruning
`cold_files_scanned`	Cold files actually read
`cold_file_visited{file=…}`	Individual Parquet files touched (up to 16 recorded)

Plan text also includes static scan context on deferred MVCC sources, for example: storage_tiers=[hot=rocksdb,cold=parquet], mvcc=true.

`EXPLAIN ANALYZE VERBOSE` (full metrics + summary)

Adds extra rows after the annotated plan:

SQL

1EXPLAIN ANALYZE VERBOSE2SELECT id, user_id, _deleted3FROM dba.notifications4WHERE user_id = 'test'5LIMIT 3;

plan_type	plan
`Plan with Metrics`	Annotated plan with standard metrics
`Plan with Full Metrics`	Plan with all available metric detail
`Output Rows`	Rows produced by the query
`Duration`	Total execution time

Reading plans for KalamDB tables

Typical physical plans on application tables include:

DeferredBatchExec — deferred MVCC scan (hot RocksDB + cold Parquet merge)
FilterExec — predicate evaluation (pushdown where possible)
ProjectionExec — column selection
GlobalLimitExec / LocalLimitExec — LIMIT handling
CooperativeExec — stream table scans

Use plain EXPLAIN to compare logical vs physical shape without execution cost. Use EXPLAIN ANALYZE when you need to see whether filters hit the hot tier, how many cold files were scanned, and operator timings.

CLI output tips

In default table format, the CLI renders plan_type / plan result sets specially:

Multi-line plan text is expanded across table rows (continuation lines leave plan_type blank)
The plan column uses the full terminal width instead of the generic 32-character cap

For machine-readable output, use JSON:

BASH

1kalam --json -c "EXPLAIN ANALYZE SELECT 1;"

Or in the interactive shell:

SQL

1\format json2EXPLAIN ANALYZE VERBOSE SELECT id FROM dba.notifications LIMIT 3;

Schema & Query Diagnostics

DESCRIBE — table schema

DESCRIBE TABLE (KalamDB native)

DESCRIBE <table> / DESC <table> (DataFusion shorthand)