zsql CLI

zsql is the command line for 0sql. It scaffolds a project (YAML files describing your warehouse tables, dimensions, measures, joins and security policies), validates and deploys it to the hosted service, and sends queries to it. The CLI generates no SQL itself: every plan runs on the service, and zsql prints what comes back.

Install

curl -fsSL https://0sql.io/install.sh | sh
zsql --version

A single static binary, no runtime. Details and the build-from-source route are in Installing zsql.

The loop

zsql init tpcds                      # project.yml, datasources.yml, security.yml, models/, tests/
cd tpcds
$EDITOR datasources.yml              # one entry per warehouse: adapter, tier, host...
zsql new table "Store Sales" --datasource tpcds --physical-name store_sales --domain store
zsql new relation --datasource tpcds --domain store
zsql auth --api-key zsk_... --server https://app.0sql.io
zsql check                           # validate on the service, keep nothing
zsql deploy                          # deploy the checked-out git branch
zsql sql --expr "item category, store net paid" --context user.json
zsql repl --context user.json
zsql test

init creates the files, new adds model files from templates, auth stores your personal key in .zsql, check validates without deploying, deploy ships the checked-out git branch, and sql, repl and test exercise the deployment. Each step has a page below.

Commands

Group	Command	Does
project	`zsql init [DIR]`	Start a project: templates, `.gitignore`, `git init -b main`
	`zsql new table NAME --datasource DS`	Write `models/<domain>/tbl.<name>.yml` from the template
	`zsql new relation --datasource DS`	Write `models/<domain>/rel.<domain>.yml`
	`zsql new test NAME`	Write `tests/<name>.yml`
service	`zsql auth --api-key KEY`	Save the key (and optionally the server) in `.zsql`
	`zsql check`	Validate the project on the service without deploying
	`zsql deploy`	Deploy the checked-out branch
	`zsql test`	Run the deployed branch’s tests on the service
	`zsql status`	The deployed branch’s summary, as JSON
	`zsql list`	Every deployment the key can see
	`zsql remove --yes`	Remove the deployed branch
	`zsql health`	Liveness of the server
querying	`zsql sql`	Plan one query and print the SQL
	`zsql explain`	SQL plus the node graph and timings
	`zsql explore`	What a query can add: dimensions to drill into, measures to join
	`zsql spec LINE`	The spec JSON a shorthand line makes, locally
	`zsql repl`	Plan interactively
	`zsql fields [Q]`	Fields of the deployed branch
	`zsql tables`	Tables of the deployed branch

Every flag is in the command reference.

Global flags

Flag	Default
`--project DIR`	The directory holding `project.yml`, here or in a parent
`--branch NAME`	The checked-out git branch of the project; `main` outside a project
`--server URL`	`ZSQL_SERVER`, else `server:` in `.zsql` or `~/.zsql/config`, else `server:` in `project.yml`
`--uid UID`	`uid` from `project.yml`

The API key comes from ZSQL_API_KEY, else api_key: in .zsql (written by zsql auth), else ~/.zsql/config. Outside a project directory, --uid is required and the branch defaults to main; that is how you query a deployment from a machine that has no checkout. Without any server setting, zsql falls back to a local development address (http://127.0.0.1:3699), so pass --server https://app.0sql.io to zsql auth once. See Authentication and configuration.

Server errors print as <class>: <message>, for example NotFound: no deployment for project tpcds branch main, and the process exits non-zero.

Install

The loop

Commands

Global flags

Pages