Skip to main content
DocumentationLibraryReference
On this page

Kater CLI Build and check

kater run

Runs saved queries and charts on your warehouse.

Each one prints a line when it starts and a line when it ends, with the number of rows it returned. Use it to check a query before you share it. You do not need to compile first, and a run changes none of your files. To get the rows, add --json. To compile, run and test in one command, use kater build.

Examples

Terminal window
# Go to a workspace in your local copy of Kater content
cd connections/snowflake_prod_connection/workspaces/ad_reporting
# Run every saved query and chart in the workspace
kater run --select .
# Run one saved query
kater run --select query_contracts/spend_by_platform.sql
# Run the queries that have the tag team=finance, and leave out the charts
kater run --select tag:team=finance --exclude resource_type:chart
# Run a query with the parameter values and filters in inputs.json
kater run --select query_contracts/paid_media_spend_trend.sql --inputs-file inputs.json
# Run a query on the warehouse again, even when it ran in the last 15 minutes
kater run --select query_contracts/spend_by_platform.sql --fresh

Arguments

ArgumentDescription
<paths>Optional. Files to run, as --select names them. Give one or more.

Options

OptionDescription
-s, --files, --select <selection>What to run: a file or a folder, a query by its name or typed address, or a method such as tag:team=finance. A folder runs every saved query and chart in it and in the folders under it. Give a scratch file to run every statement in it. A scratch file must be all that --select names. Leave it out to run your scope. 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.
--inputs-file <file>A JSON file with the parameter values and the filters for each query. See Parameter values and filters.
--freshRuns each query on the warehouse again, even when it ran with the same inputs in the last 15 minutes. It waits for the new rows.

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

Where the rows come from

A run does not always go to the warehouse. Each run in your terminal keeps its rows in your local copy, under .kater/runtime/, for the next command. When a query ran with the same inputs, the rows come from there.

  • Rows from the last 15 minutes come back as they are, and nothing goes to the warehouse. ran_at says when the query ran.
  • Older rows do not come back. The query runs again on the warehouse, and the command waits for the new rows.
  • --fresh always runs the query again, and waits for the new rows.
  • result_id names the rows, so that kater answer can read them again.

When you change a query, a chart or a model that it reads, the next run does not use the old rows. Kater keeps at most 1 GB of rows in your local copy, and removes the oldest first. Through the Kater MCP or the portal, the rows come from your organisation’s result store, and older rows come back marked refreshing while the query runs again.

When an agent runs one saved query through the Kater MCP’s kater tool, the chat shows the query’s answer, with a link to it in Kater (app_url). A run of several queries gives each result its own link.

What it prints

Each query prints a line when it starts and a line when it ends, as kater build shows them. The run ends with its time, each error and a summary, and writes target/run_results.json. With --json, the answer is the run’s own JSON: status, and in items each query’s target, status and result, with its rows, row_count, ran_at and result_id.

Parameter values and filters

The inputs file names each query by the id that kater model list shows. Under the id, parameters gives the parameter values, and filters lists the optional filters to turn on. An optional filter is off unless you list it. This file runs paid_media_spend_trend for the last 6 complete months:

inputs.json
{"rel1_JUXnLRBC_j3VUJuk1rPawWZYLLQOrYCBOyVxIDYIrt8": {"parameters": {"is_within_last__union__date_day": 6}, "filters": ["is_within_last__union__date_day"]}}

See also