Skip to main content
DocumentationLibraryReference
On this page

Developers Command-line workflows

Change a query and build it

Edit a query in your editor, build only what the change reaches, and publish your commit to Kater.

Audience
Data teams
Prerequisites
  • The Kater CLI, signed in with kater login
  • A local copy, made with kater git clone
  • kater debug passes

This is the everyday loop: change a file, build what the change reaches, commit, and publish. As in dbt, state:modified+ selects each file that you changed and everything that reads it, so a build runs only what your change could move.

The commands and their times are real. Long waits are shortened in the recording.

  1. Change a file.

    Open the query in your editor and change it. Here, a field ad_reporting.sum__clicks is added to spend_by_platform.sql.

    Terminal window
    git diff --stat
     connections/snowflake_prod_connection/workspaces/ad_reporting/query_contracts/spend_by_platform.sql | 3 ++-
     1 file changed, 2 insertions(+), 1 deletion(-)

  2. See what the change reaches.

    --state git:main compares your local copy with main: the files that you committed since main, changed and did not commit, or added. kater ls lists them and every model that reads them, and runs nothing.

    Terminal window
    kater ls --select state:modified+ --state git:main
    chart.spend_by_platform
    chart.spend_mix
    query.spend_by_platform

  3. Build it.

    kater build compiles each selected model, runs it on the warehouse through your Kater API, and runs its tests, in the order that they read each other. Each object prints a line when it starts and a line when it ends.

    Terminal window
    kater build --select state:modified+ --state git:main
    15:00:20  Running with kater=0.1.0, profile=kater, target=dev (Kater API at http://127.0.0.1:8788)
    15:00:22  Waiting for Kater to read the project. 1s
    15:00:25  Found 1 query, 2 charts (13 of 13 models reused)
    15:00:25
    15:00:26  1 of 3 START query ad_reporting/spend_by_platform ........................ [RUN]
    15:00:28  1 of 3 OK query ad_reporting/spend_by_platform ............ [OK 3 rows in 2.68s]
    15:00:28  2 of 3 START chart ad_reporting/spend_by_platform ........................ [RUN]
    15:00:28  2 of 3 OK chart ad_reporting/spend_by_platform ................... [OK in 0.10s]
    15:00:28  3 of 3 START chart ad_reporting/spend_mix ................................ [RUN]
    15:00:28  3 of 3 OK chart ad_reporting/spend_mix ........................... [OK in 0.10s]
    15:00:28
    15:00:28  Finished running 1 query, 2 charts in 0h0m3.0s.
    15:00:28
    15:00:28  Completed successfully
    15:00:28
    15:00:28  Done. PASS=3 WARN=0 ERROR=0 SKIP=0 TOTAL=3

    “13 of 13 models reused” says that Kater compiled nothing again that your change did not reach.

  4. Fix and try again.

    When an object fails, the run ends with a block for each failure: what failed, the file, and the message. Change the file, then run kater retry. It runs again only what failed and what it skipped, from target/run_results.json.

    Terminal window
    kater retry

  5. Commit and publish.

    Commit with plain git. kater git push publishes your commits to Kater, where the portal and everyone who can read the files see them.

    Terminal window
    git commit -qam "Add clicks to spend by platform"
    kater git push

    Add -m to describe the publish with your own words in place of the commit subjects.

  • kater ls --select state:modified+ --state git:main lists only what your change reaches.
  • kater build ends with ERROR=0.
  • kater git push publishes, and the portal shows your change.

If something looks wrong

You seeWhat to do
kater ls --select state:modified+ lists nothingNothing differs from main. Check git status, and check that you added --state git:main.
ERROR with Kater did not publish it, because what reads it would not work.A dashboard, chart or app that reads the model would break. The block under it names that object and its problem.
Warning in app … and Add app:NAME to --select to make its problems fail the compile.An app outside your selection has a problem that your change did not cause. The build passes. Add app:NAME when you own the app.
Your access changed while this command ran.The Kater API answered late, and your access looked different in the middle of the command. Run the command again.
Kater could not get an answer from the Kater API in time.The Kater API is busy or stopped. Run kater debug to see which check fails.

Next steps