kater compile

Compiles your saved queries, charts and shared models, and reports each error and warning.

Use it to check your work after you change a model, before you run or share it. It also formats the SQL of each file and declares any parameter that the SQL reads, unless you add --no-format. To see the rows that a query returns, use kater run.

Examples

# Go to a connection in your local copy of Kater content
cd connections/snowflake_prod_connection
# Compile the ad_reporting workspace: its root, saved queries and charts
kater compile --select workspaces/ad_reporting
# Compile one saved query
kater compile --select workspaces/ad_reporting/query_contracts/spend_by_platform.sql
# Compile one saved query and every query and chart that reads it
kater compile --select workspaces/ad_reporting/query_contracts/spend_by_platform.sql+
# Check a query and leave its file as it is
kater compile --select workspaces/ad_reporting/query_contracts/paid_media_spend_trend.sql --no-format
# Compile the shared models and every workspace of the connection, and check connection.yaml
kater compile --select .

Options

Option	Description
`-s`, `--select <selection>`	What to compile: a file, a folder, a model by its name or typed address, or a method such as `tag:team=finance`. A folder is a workspace, a connection’s `modeling` folder, a connection or the whole content root, and Kater compiles every model in it and in the folders under it. Leave it out to compile your scope, or else the workspace or modeling folder you are in. See Selecting models. You can give it more than one time.
`--exclude <selection>`	What to leave out of the selection, in the same words as `--select`. You can give it more than one time.
`--state <state>`	What `state:modified` and `state:new` compare with: a folder that holds an earlier `manifest.json`, or `git:REF`, such as `git:main`.
`--no-format`	Writes nothing to your files: no formatting and no parameter declarations. Use it to check files that you can read but not edit.

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

What a compile checks

Each model. It compiles each selected model and lists its errors and warnings. A warning also names a formula that repeats one in the workspace, and a name that the workspace uses already.
Your files. Without --no-format, it formats each selected file. It also declares each parameter that the SQL reads and that nothing declares. For this, you need edit access to every file it compiles.
connection.yaml. A compile of a connection, its modeling folder or the content root also checks connection.yaml. This occurs only when --select names that one folder, or when you give no --select.
dashboard.yaml. A compile in a workspace also checks its dashboard.yaml. So it finds a reference that a query rename broke.
Apps and dashboards that read the files. It checks each app and dashboard that the compiled files reach. When Kater’s servers check them after a change, the compile waits up to 60 seconds. A check that still runs after that is listed in downstream. See When a broken app fails the compile.
Brainstorm folders. A workspace in a brainstorm folder compiles only when you name it or a file in it. A compile of a whole connection or content root skips it.

When a broken app fails the compile

An app that does not work fails the compile only when the selection includes the app. The selection includes an app when app:NAME names it, or when a term with + after it, such as semantic.orders+, selects what reads the compiled models. A compile with no --select includes every app in its scope.

The selection includes the app. Kater publishes none of the models, and each one ends with ERROR and the app’s page, line and problem, such as Kater did not publish it, because what reads it would not work. .../apps/monday_brief/index.html:134: There is no query first_touch_returns in .... The command exits 1.
The selection does not include the app. Kater publishes the models. The app gets one Warning: line, such as Warning: The app monday_brief does not work. The selection does not include it, so the compile goes on., and its own block under Completed with N warnings, with the page and line of each problem. The warning counts in WARN=, and the command exits 0, or 1 with --warn-error.

So a compile of a shared model never fails for an app that another person broke, but it still tells you about it.

What it prints

Kater compiles the models of a workspace or a modeling folder together. So each model prints a line when the compile starts, and a line when the compile ends, with OK, WARN or ERROR. Until the first model ends, a line such as Waiting for Kater to compile 6 files. 1s shows after 1 second and every 10 seconds. The first compile on an empty compile store reads each scope that the selection reaches, which can take a minute or more. The run ends with its time, a block for each error and warning, and a summary, as kater build shows them. Then it lists each problem in connection.yaml or dashboard.yaml. It writes target/run_results.json.

With --json, the answer is the compile’s own JSON. See Output, errors and exit codes.

status is ok when every selected model compiled, and failed when one did not. no_targets means that nothing matched.
items has one entry for each model: its target, its status (built, failed or blocked) and its diagnostics. A model that compiled gives its warehouse SQL in result.sql.
source_formats says what the compile wrote to each file, such as formatted, or declared with the new parameters in declared.
connection_checks, dashboard_checks and app_validation hold the problems that those checks found.

The command exits with 0 when every model compiled and no check found an error. It exits with 1 when a model did not compile, nothing matched, or a check found an error. It exits with 2 for a command that is not valid.