kater show

Runs one model, a statement of a scratch file, or SQL on your warehouse, and shows its first rows, as dbt show does.

Use it to see what a model returns, or to try SQL before you save it as a query. It saves nothing. With --dry-run, it shows the SQL and runs nothing.

Examples

# Go to the ad_reporting workspace in your local copy of Kater content
cd connections/snowflake_prod_connection/workspaces/ad_reporting
# Show 5 rows of the spend_by_platform query
kater show --select query.spend_by_platform
# Show 10 values of the platform field of the workspace's root
kater show --select workspace.ad_reporting --field platform --limit 10
# Show the warehouse SQL that the spend_by_platform query compiles to, and run nothing
kater show --select query_contracts/spend_by_platform.sql --dry-run
# Show the warehouse SQL of the workspace's root
kater show --select workspace.sql --dry-run
# Compile the unsaved text in draft.sql as the spend_by_platform query
kater show --select query_contracts/spend_by_platform.sql --text-file draft.sql --dry-run
# Run the SQL body of the spend_by_platform query, lines 6 to 13, and show up to 20 rows
kater show --select query_contracts/spend_by_platform.sql --selection 5:0-12:30 --limit 20
# Run SQL on the workspace and show the first 5 rows
kater show --inline "SELECT ad_reporting.platform, ad_reporting.sum__clicks FROM workspace.ad_reporting AS ad_reporting GROUP BY ad_reporting.platform"
# Go to the snowflake_prod_connection connection
cd ../..
# Run the first statement in your scratch file spend_checks.sql
kater show --select users/you@example.com/brainstorm/spend_checks.sql --statement 0
# Run every statement in the scratch file, in order
kater show --select users/you@example.com/brainstorm/spend_checks.sql --all
# Compile the statement at line 4, character 11, and show it without running it
kater show --select users/you@example.com/brainstorm/spend_checks.sql --at 3:10 --dry-run

Options

Option	Description
`-s`, `--select <selection>`	The one thing to show. Give a model by its name or typed address, such as `query.spend_by_platform`. Or give a file by its path, such as a scratch file with `--statement`. For one model of a file that declares several, give both as `path:FILE,TYPE.NAME`, as `kater ls` writes it.
`--inline <sql>`	The SQL to run, in quotes, in place of `--select`. It runs in your scope, so give `--scope` to name the workspace.
`--inline-file <file>`	A file that holds the SQL to run, as `--inline` does. `-` reads the SQL from standard input.
`--field <field>`	Shows only the values of this field of the model.
`--statement <n>`	With a scratch file: runs the statement at this zero-based index. `0` is the first statement.
`--at <line>:<character>`	With a scratch file: runs the statement at this place, as a zero-based line and character, such as `3:10`. A place just after a semicolon is in the next statement. Characters count in UTF-16 units.
`--all`	With a scratch file: runs every statement, in order. A statement that fails does not stop the others.
`-j`, `--jobs <number>`	With `--all`: how many statements run at one time, from 1 to 8. The results still print in the file’s order. The default is `1`.
`--selection <range>`	With a SQL file: runs only this part of the file, as one statement. Give its start and end as zero-based `LINE:CHARACTER-LINE:CHARACTER`, such as `5:0-12:30`. Characters count in UTF-16 units.
`--text-file <file>`	Text to use in place of the saved file, such as an editor’s unsaved changes. Kater still reads it as the file in `--select`. `-` reads it from standard input.
`--limit <n>`	The most rows to show, from 1 to 10,000. Without it, a model or SQL shows up to 5 rows, and a scratch statement up to 1,000.
`--dry-run`	Shows the SQL that it would run, and runs nothing. For a model, that is the warehouse SQL that the model compiles to, or each error with its line when it does not compile.

It also takes the global options --json, --kater-root, --scope and --help.

What to give it

Give --select, --inline or --inline-file, and only one of them. --select names one thing. Name a model one time, and add its file as path:FILE only when you need it, such as --select path:query_contracts/spend_by_platform.sql,query.spend_by_platform.

A model, by its name or typed address, shows its rows. Add --field to see the values of one field.
A model’s file shows the model that the file declares.
A scratch file needs --statement, --at or --all.
Any SQL file takes --selection to run one part of it.

Kater finds a model that you name in the whole project, so you need no --scope. When a query and its chart have the same name, it shows the query. When two models of other kinds have the name, such as a DB dataset and the Kater dataset over it, the command stops and lists them: name one as TYPE.NAME, such as kater_dataset.facebook_ads__ad_report.

SQL from --inline or --inline-file runs in your scope. Name the workspace with --scope, or else Kater uses the scope that kater scope use saved, or the folder you are in.

What it prints

It prints Previewing node 'NAME':, then the rows as a table, one line for each row. Each column has the name the warehouse gives it, as in dbt show, such as | PLATFORM | SUM__CLICKS | on Snowflake. SQL from --inline prints Previewing inline node:. When the model has more rows than --limit, the last line says so. A scratch file with --all prints one block for each statement. With --dry-run, it prints only the SQL.

Statements in a scratch file

A scratch file holds statements in your brainstorm folder. What a statement reads decides where it runs: one shared model, several shared models joined, or warehouse tables. A statement that reads warehouse tables needs edit access to the shared models.

Lines and characters count from 0, so line 4 in an editor is line 3.