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 immediately (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

Synchronous vs Asynchronous

cz-cli sql runs synchronously by default (--sync), waiting for results before exiting. For long-running queries, submit asynchronously to get a job_id and retrieve results later:

Async submit, 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

INSERT, UPDATE, DELETE, CREATE, DROP, and other write operations require the explicit --write flag to prevent accidental changes:

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

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; reference them in SQL with %(KEY)s. Useful 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 setting the timezone:

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

Dry Run

Validate syntax and run EXPLAIN without actually executing — useful for pre-deployment checks:

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 is 100 rows):

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

Suppress column headers:

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`	Async submit, returns job_id immediately	`false`
`--write`	Allow write operations (DDL/DML)	off
`--batch` / `-B`	Execute multiple semicolon-separated statements	`false`
`--variable KEY=VALUE`	Variable substitution; use `%(KEY)s` in SQL	—
`--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 chars)	`true`
`--header` / `--no-header` / `-N`	Output column headers	`true`
`-f, --file`	Read SQL from a file	—
`-e, --execute`	SQL string (equivalent to positional argument)	—
`--stdin`	Read SQL from stdin	`false`
`--job-profile`	Retrieve execution profile for a completed job	—
`--schema-context`	Attach schema information to the 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 (columns, 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 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>

Retrieve 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 (this command only):

cz-cli -p prod workspace use analytics

Persist the switch (save to profile):

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

Common Use Cases

Case 1: Explore 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

Case 2: Debug a slow query

Submit asynchronously first:

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

Note the job_id, then check execution details:

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

Case 3: Execute 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

Case 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