Skip to main content
DocumentationLibraryReference
On this page

Kater CLI Find and understand model

kater model promote

Moves a field from one query to its workspace's root, so that every query in the workspace can read it.

Every other place in the workspace that computes the same formula then reads the root’s field. Run it with --dry-run first to see the change, which writes nothing. See Promotion and verification.

Examples

Terminal window
# Go to the ad_reporting workspace
cd connections/snowflake_prod_connection/workspaces/ad_reporting
# Propose moving a query's field to the workspace's root, and write nothing
kater model promote previous_month_percent_change__sum__conversions --relation conversions_last_month_vs_the_month_before --dry-run
# Move the field, with a name and a label of your own
kater model promote previous_month_percent_change__sum__conversions --relation conversions_last_month_vs_the_month_before --name conversions_change_vs_previous_month --label "Conversions change vs previous month"
# Propose moving a query's filter to the workspace's root
kater model promote --filter is_within_last__union__date_day --relation paid_media_spend_trend --dry-run

Arguments

ArgumentDescription
<field>Optional. The field to move, by its name in the query. Kater compares names as your warehouse compares them. Leave it out when you give --filter.

Options

OptionDescription
--filter <filter>Moves one of the query’s filters in place of a field, by its name, such as is_within_last__union__date_day. See Moving a filter.
--relation <query>Required. The query that holds the field or the filter, by its name, such as paid_media_spend_trend, or as query.paid_media_spend_trend. The query’s file path also works.
--path <file>The query’s file. It names the workspace in place of --scope.
--name <name>The name of the root’s new field. Leave it out to keep the field’s own name. When another field in the workspace has that name, Kater uses the name of the column the field is computed in. Kater refuses a name that another field has.
--label <text>The label of the root’s new field. Leave it out to keep the field’s own label.
--promote-as <kind>For a formula column, makes the root’s field a measure or a dimension with the same formula. See Formula columns.
--dry-runShows the change and writes nothing. The dry run ends with the command that writes this proposal.
--revision <revision>Writes the change only while it is still the proposal of a dry run, by that dry run’s revision. The command at the end of the dry run gives it.
--confirm-unverifiedWrites the change even when the check on the warehouse could not verify it. A check that finds different rows always stops the change.

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

Where it works

It works in one workspace. Kater takes it from --scope, from the file in --path, or from the folder you are in. Only the workspace’s root, its workspace.sql, gets the field.

What moves to the root

  • The places that compute it. A place is an expression in a query’s own SELECT, or in one of its CTEs. It reads the workspace’s fields and computes the same formula. The compiler decides this, not the text.
  • Columns passed on. A query’s field that computes the formula from columns its CTEs pass on also counts. Those CTEs then pass the root’s field on instead.
  • The numbers stay the same. Each place keeps its formula, and every query keeps its fields. One compile of the workspace proves it.
  • Other fields stay. A field over the same inputs that computes something else stays as it is. The output says why for each one.

The check on the warehouse

Before it writes, Kater runs each query that the change reaches on your warehouse, before and after the change. When the rows differ, it writes nothing. When the check cannot verify the change, it also writes nothing, unless you give --confirm-unverified.

Formula columns

A formula column is a custom calculation that a query writes as an Excel formula. With --promote-as measure, the root gets MEASURE(EXCEL('=…')) with the same formula. With --promote-as dimension, it gets DIMENSION(EXCEL('=…')). The query then reads that field.

  • A formula that reads a measure or a total on its own row can be a measure.
  • A formula that reads only values on its own row can be a dimension.
  • A formula that reads other rows, a range, a whole column or a custom calculation cannot be either. Kater refuses it and says why.

Moving a filter

With --filter, Kater moves one of the query’s filters to the root, as it is, with the parameter it reads. Every query that has the same filter then reads the root’s filter. When the check finds that a query with the filter returns other rows, Kater writes nothing.

Brainstorm copies

Kater promotes nothing from a brainstorm copy. Apply the copy to its workspace with kater workspace apply first. Then promote the field there.

Through an agent

When an agent promotes a field through the Kater MCP, the result’s app_url opens the field in its workspace. A proposal opens on the workspace’s Promote dialog, with the same name and label. A written promotion opens at the line of the root that declares the field. --json returns the model.promote answer, with the promotion card’s data in card.

See also