sqb query

Execute ad hoc SQL against the active project connection. Useful for inspecting data, debugging models, or running one-off queries without leaving the SQLBuild CLI.

Usage

sqb --project-dir <path> query "SELECT * FROM dev.fact_orders LIMIT 5"

Or from a file:

sqb --project-dir <path> query --file my_query.sql

File paths are resolved from the current working directory.

sqb query reads only sqlbuild_project.toml and sqlbuild_local.toml to connect. It does not parse models or import project Python, so it starts quickly in large projects and still runs when a model or Python file is broken. The SQL runs as written: SQLBuild does not resolve model names in it.

Flags

Flag	Description
sql	SQL to execute (positional argument)
--file	Read SQL from a file instead of the command line
--format	long prints one record per row; json prints a JSON array. Without it, the default output applies
--json	Shorthand for --format json
--limit	Maximum rows to return (default: 20)
--no-limit	Disable the row limit
--warehouse <name>	Snowflake warehouse for this invocation; overrides the target’s query warehouse group and the connection warehouse

Output

By default sqb query prints a table with each column’s name and warehouse type:

┌──────────┬─────────────┬───────────┐
│ order_id │ customer_id │  status   │
│ INTEGER  │   INTEGER   │  VARCHAR  │
├──────────┼─────────────┼───────────┤
│        1 │         100 │ completed │
│        2 │         200 │ completed │
└──────────┴─────────────┴───────────┘

2 rows

The table must fit the terminal width, or 120 characters when output is redirected. When it is wider, or a value spans several lines, sqb query prints one record per row instead, so no column or value is ever cut. Numbers are right-aligned. Types show where the adapter reports them.

The last line counts the rows. When the limit cut rows off, it says so and how to see more:

20 rows shown (limit 20; use --limit or --no-limit)

Above 50 rows it suggests reading fewer: 60 rows; to read fewer, aggregate with GROUP BY or add a LIMIT.

long

--format long always prints one record per row:

-[ RECORD 1 ]---------------------------+
order_id    | 1
customer_id | 100
status      | completed

2 rows

json

--format json, or --json, prints a JSON array of objects for programs:

[{"order_id": 1, "customer_id": 100, "status": "completed"}]

--format table and --format csv are not accepted. The default output already prints a table when the result fits; use --json for programs.

Errors

When the warehouse rejects the SQL, sqb query prints the warehouse message as error[C108]: ... on stderr and exits with code 2. Nothing is written to stdout, so redirected json output is never partial. Invalid command input, such as a missing query file, exits with code 1.

Examples

# Quick inspection with default format
sqb query "SELECT * FROM dev.fact_orders"

# One record per row with a higher limit
sqb query "SELECT * FROM dev.dim_customers" --format long --limit 50

# Export to JSON
sqb query "SELECT * FROM dev.daily_revenue" --json --no-limit

# Run SQL from a file
sqb query --file debug_query.sql