SQL Execution and Data Exploration

This page covers cz-cli commands for SQL execution, schema and table management, job diagnostics, and workspace switching.

cz-cli sql — Execute SQL

Basic Usage

Synchronous execution, returns results directly (default):

cz-cli -p prod sql "SELECT current_timestamp()"

Pass SQL with -e:

cz-cli -p prod sql -e "SELECT * FROM public.orders LIMIT 10"

Read SQL from a file:

cz-cli -p prod sql -f query.sql

Sync vs Async

cz-cli sql executes synchronously by default (--sync), waiting for results before exiting. For long-running queries, you can submit asynchronously, get the job_id, and then retrieve results:

Submit asynchronously, returns job_id immediately:

cz-cli -p prod sql "SELECT * FROM huge_table" --async

Check job status:

cz-cli -p prod sql status <job_id>

Or use the job command:

cz-cli -p prod job status <job_id> cz-cli -p prod job result <job_id>

Write Protection

Write operations such as INSERT, UPDATE, DELETE, CREATE, and DROP require the explicit --write flag to prevent accidental modifications:

cz-cli -p prod sql --write -e "CREATE TABLE IF NOT EXISTS public.demo (id INT, name STRING)" cz-cli -p prod sql --write -e "INSERT INTO public.demo VALUES (1, 'test')" cz-cli -p prod sql --write -e "DROP TABLE public.demo"

Batch Execution of Multiple Statements

Use --batch to execute multiple semicolon-separated statements in sequence:

cz-cli -p prod sql --write --batch -e " CREATE TABLE IF NOT EXISTS ods.events (id INT, ts TIMESTAMP, type STRING); INSERT INTO ods.events VALUES (1, current_timestamp(), 'click'); INSERT INTO ods.events VALUES (2, current_timestamp(), 'view'); "

Variable Substitution

Use --variable KEY=VALUE to inject variables, referenced in SQL with %(KEY)s, suitable for templated queries:

cz-cli -p prod sql "SELECT %(col)s FROM public.orders LIMIT 10" \ --variable col=order_id cz-cli -p prod sql "SELECT * FROM public.orders WHERE dt = '%(dt)s'" \ --variable dt=2026-05-26

Query Hints

Use --set KEY=VALUE to pass query-level hints, such as specifying a timezone:

cz-cli -p prod sql "SELECT current_timestamp()" \ --set cz.sql.timezone=UTC

Pre-execution Validation (dry-run)

Performs only syntax checking and EXPLAIN without actually executing, suitable for pre-deployment validation:

cz-cli -p prod sql --dry-run -f deploy.sql

Output Control

Do not truncate long fields:

cz-cli -p prod sql "SELECT * FROM public.orders" --no-truncate

Remove row limit (default 100 rows):

cz-cli -p prod sql "SELECT * FROM public.orders" --no-limit

Do not output column names:

cz-cli -p prod sql "SELECT id, name FROM public.orders" --no-header

Specify output format:

cz-cli -p prod sql "SELECT * FROM public.orders LIMIT 5" -o table cz-cli -p prod sql "SELECT * FROM public.orders LIMIT 5" -o csv

Full Parameter Reference

Parameter	Description	Default
`--sync` / `--no-sync`	Wait synchronously for results	`true`
`--async`	Submit asynchronously, returns job_id immediately	`false`
`--write`	Allow write operations (DDL/DML)	Off
`--batch` / `-B`	Execute multiple semicolon-separated statements in batch	`false`
`--variable KEY=VALUE`	Variable substitution, referenced in SQL with `%(KEY)s`	—
`--set KEY=VALUE`	Query hint	—
`--dry-run`	EXPLAIN only, no actual execution	`false`
`--timeout`	Job timeout in seconds	`300`
`--limit` / `--no-limit`	Auto-truncate to 100 rows	`true`
`--truncate` / `--no-truncate`	Truncate long fields (3000 characters)	`true`
`--header` / `--no-header` / `-N`	Whether to output column names	`true`
`-f, --file`	Read SQL from file	—
`-e, --execute`	SQL string (equivalent to positional argument)	—
`--stdin`	Read SQL from stdin	`false`
`--job-profile`	Query execution profile of a completed job	—
`--schema-context`	Attach schema information to response (for Agent use)	`false`

cz-cli schema — Schema Management

List all schemas:

cz-cli -p prod schema list

View schema details (including table list):

cz-cli -p prod schema describe public

Create a schema:

cz-cli -p prod schema create dwd

Drop a schema (requires confirmation):

cz-cli -p prod schema drop old_schema

cz-cli table — Table Management and Data Exploration

List all tables in the current schema:

cz-cli -p prod table list

List tables in a specific schema:

cz-cli -p prod -s dwd table list

View table structure (column names, types, comments):

cz-cli -p prod table describe public.orders

Preview table data (default 10 rows):

cz-cli -p prod table preview public.orders

View table row count and recent job statistics:

cz-cli -p prod table stats public.orders

View table version history (Time Travel support):

cz-cli -p prod table history public.orders

Create a table from DDL:

cz-cli -p prod table create --write "CREATE TABLE public.test (id INT, name STRING)"

Drop a table (requires confirmation):

cz-cli -p prod table drop public.test

cz-cli job — SQL Job Diagnostics

Asynchronously submitted queries return a job_id; use the job command to track them:

View job status and execution summary:

cz-cli -p prod job status <job_id>

Get job query results (waits if still running):

cz-cli -p prod job result <job_id>

View job execution profile (analyze performance bottlenecks):

cz-cli -p prod sql --job-profile <job_id>

cz-cli workspace — Workspace Switching

View current workspace:

cz-cli -p prod workspace current

List all available workspaces:

cz-cli -p prod workspace list

Temporarily switch workspace (current command only):

cz-cli -p prod workspace use analytics

Persistent switch (saved to profile):

cz-cli -p prod workspace use analytics --persist

Common Use Cases

Scenario 1: Exploring a new table

cz-cli -p prod table describe public.orders cz-cli -p prod table preview public.orders cz-cli -p prod table stats public.orders

Scenario 2: Debugging a slow query

Submit asynchronously first:

cz-cli -p prod sql "SELECT * FROM huge_table GROUP BY ..." --async

Note the job_id and view execution details:

cz-cli -p prod job status <job_id> cz-cli -p prod sql --job-profile <job_id>

Scenario 3: Executing DDL in CI/CD

Validate syntax with dry-run first:

cz-cli -p prod sql --dry-run -f migrations/v2.sql

Execute after confirming no issues:

cz-cli -p prod sql --write --batch -f migrations/v2.sql

Scenario 4: Templated queries (Agent scenario)

cz-cli -p prod sql \ "SELECT COUNT(*) FROM public.orders WHERE dt = '%(dt)s' AND status = '%(status)s'" \ --variable dt=2026-05-26 \ --variable status=completed