kater build

Use it to check a change from the models it reads to the queries and tests that read it. A model, a chart and a workspace’s root compile. A query runs on the warehouse. Each test of a selected model runs right after the model, before anything that reads the model.

Examples

# Go to your local copy of Kater content
cd ~/kater-content
# Build a query and everything it reads
kater build --select +connections/snowflake_prod_connection/workspaces/ad_reporting/query_contracts/spend_by_platform.sql
# Build a shared model, its tests, and everything that reads it
kater build --select semantic.ad_reporting+
# Build what this branch changed since main, and what reads it
kater build --select state:modified+ --state git:main
# Build a query and what it reads, without the tests
kater build --select +spend_by_platform --exclude resource_type:test

Options

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

What it prints

15:20:01  Running with kater=0.1.0, profile=kater, target=dev (Kater API at http://127.0.0.1:8788)
15:20:02  Found 1 model, 1 query, 2 tests (2 of 2 models reused)
15:20:02
15:20:02  1 of 4 START model semantic.ad_reporting ................................. [RUN]
15:20:02  1 of 4 WARN model semantic.ad_reporting ........................ [WARN in 0.11s]
15:20:02  2 of 4 START test spend_needs_currency ................................... [RUN]
15:20:03  2 of 4 PASS test spend_needs_currency .......................... [PASS in 0.96s]
15:20:03  3 of 4 START test clicks_impressions_by_platform ......................... [RUN]
15:20:07  3 of 4 FAIL 4 test clicks_impressions_by_platform ............ [FAIL 4 in 4.38s]
15:20:07  4 of 4 SKIP query ad_reporting/spend_by_platform ........................ [SKIP]
15:20:07
15:20:07  Finished running 1 model, 1 query, 2 tests in 0h0m6.2s.
15:20:07
15:20:07  Completed with 1 error and 1 warning:
15:20:07
15:20:07  Failure in test clicks_impressions_by_platform (connections/snowflake_prod_connection/modeling/kater_objects/tests/ad_reporting.sql)
15:20:07    Got 4 values that differ from what the test expects.
15:20:07    picker: 4 rows expected or returned on one side only.
15:20:07
15:20:07  Done. PASS=1 WARN=1 ERROR=1 SKIP=1 TOTAL=4

• Found counts what it selected by kind, and how many of the models it read came from the compile cache.
• One line when each object starts, and one when it ends. The end says OK, PASS, WARN, ERROR, FAIL or SKIP, the rows a query returned, and the time.
• SKIP. An object that reads one that failed is skipped. So is an object that reads a model whose test failed. The model’s other tests still run.
• The end. The time of the run, a block for each error and each warning, then a count of each result.

Press Ctrl-C to stop a build. It stops after the object that it is on, and prints the same end for what finished. It exits with 130.

The run’s record

Each build in your own terminal writes target/run_results.json in your content root, as dbt does. kater compile, kater run, kater test and kater sync write it too. Git does not see the target folder, and kater git push does not send it.

• metadata has kater_version, generated_at and invocation_id, which is the request ID of the command.
• results has one entry for each object: its unique_id, status, timing, execution_time, message, failures, and in adapter_response the rows and the warehouse’s query_id. A test’s status is pass, fail, warn, error or skipped. Any other object’s is success, warn, error or skipped.
• elapsed_time is the time of the whole run, and args names the command in which, and its flags.

With --json, the answer is this record. kater retry reads it, and so does --select result:STATUS.

Exit codes

0 when nothing failed, warnings included unless you add --warn-error. 1 when an object erred or a test failed. 2 for a command that is not valid. 130 when you stop it.

See also

• All commands