kater model edit

Proposes a change to a model, such as a new field, filter or join, and writes the SQL for it.

Without --write, it shows the plan and changes nothing. Add --write to save the change.

Examples

# Go to the ad_reporting workspace
cd connections/snowflake_prod_connection/workspaces/ad_reporting
# Propose adding the Clicks measure to the spend_by_platform query
kater model edit query.spend_by_platform --path query_contracts/spend_by_platform.sql --add-fields ad_reporting.sum__clicks
# Add it, and save the file
kater model edit query.spend_by_platform --path query_contracts/spend_by_platform.sql --add-fields ad_reporting.sum__clicks --write
# Propose the quick operations in operations.json, and keep the proposal in proposal.json
kater model edit query.spend_by_platform --path query_contracts/spend_by_platform.sql --operations-file operations.json --json > proposal.json
# Save the proposal that you kept
kater model edit query.spend_by_platform --path query_contracts/spend_by_platform.sql --apply-plan proposal.json --write

Arguments

Argument	Description
`<model>`	The model to change, by its name or typed address, such as `query.spend_by_platform`.

Options

Option	Description
`--path <file>`	The file that holds the model.
`--text-file <file>`	The file’s text in place of what is saved, such as an editor’s unsaved changes. `-` reads stdin.
`--create-projection <json>`	Makes a new field, as JSON with an `expression`, and optionally `name`, `field_type`, `label` and `description`. Without a name, Kater writes the expression with its label, and the type its formula has. You can give it more than one time.
`--duplicate-projection <json>`	Copies a field, as JSON with the exact `output` reference to copy, and optionally `name`, `expression`, `field_type`, `label` and `description`. Without a name, the copy’s name is `copy__` and the field’s name, and its label ends in `(Copy)`. You can give it more than one time.
`--add-fields <field>`	Adds a field from a model that this one reads. Give the reference that `kater model fields` lists for it, such as `ad_reporting.sum__clicks`. You can give it more than one time.
`--remove-output <output>`	Takes a field out of the model, by the exact output reference JSON that `kater model inspect` gives for it. You can give it more than one time.
`--operations <json>`	Quick operations to run, as a JSON array of objects with `target`, `operation_id` and `parameters`. `kater operation list` gives the target and the parameters of each operation.
`--operations-file <file>`	The same JSON array of quick operations, from a file. `-` reads stdin.
`--workspace-inputs <json>`	Changes to the filters and parameters of a workspace’s root, or of the query in the file, as a JSON array. Each item has a `kind`, the `model` and its `model_revision`. See Filter and parameter changes.
`--workspace-inputs-file <file>`	The same JSON array of filter and parameter changes, from a file. `-` reads stdin.
`--relationships <json>`	Changes to the joins of the model’s main SELECT, as a JSON array. See Relationship changes.
`--relationships-file <file>`	The same JSON array of relationship changes, from a file. `-` reads stdin.
`--clauses <json>`	A query’s grouping and row limit, and the filters a model always applies, as JSON with `group`, `limit` and `required_filters`.
`--extract-stage <cte>`	Moves one of the query’s CTEs, by its name, to a query of its own in the same file. The query then reads the new query. Each CTE that it reads moves first.
`--stage-name <name>`	The name of the query that `--extract-stage` makes. Leave it out to use the CTE’s name.
`--fix <id>`	Applies a fix that `kater model inspect` offers for a problem, by the fix’s id.
`--apply-plan <file>`	A plan that this command returned earlier, from a file. Give `--write` with it to save the plan.
`--write`	Saves the change. Without it, the command only shows the plan.

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

What goes together

One kind of change at a time. Give field changes, --extract-stage, --fix or --apply-plan, and only one of them.
Field changes. These are --add-fields, --remove-output, --create-projection, --duplicate-projection, the quick operations, the filter and parameter changes, the relationship changes and --clauses.
Relationship changes go on their own.
Grouping and row limit come after fields. --clauses does not go with added or removed fields. Add or remove the fields first, then change the grouping or the row limit.
New fields go apart from quick operations. Quick operations and --clauses do not go with --create-projection or --duplicate-projection.
Give each JSON value one time. Give --operations or --operations-file, not both, and so on. Only one file option can read stdin.
A plan keeps its file. --apply-plan uses the file as it was when Kater made the plan. So it does not take --text-file.

Quick operations

A quick operation is a change from a field’s menu, such as a running total or a display format. Kater writes the SQL for it. kater operation list with --field and --operation gives the exact item to send. Use the field.describe operation to change a field’s description, AI context, tags and business questions. See Quick operations.

Filter and parameter changes

Each item’s kind is remove_filter, update_filter, update_parameter, reorder_filters or add_custom_filter. An item can also have name, label, description, ai_context, order, predicate and required. See Filters and parameters.

Relationship changes

Each item’s kind is add_relationship, update_relationship, remove_relationship or rename_alias. An item can also have these keys:

name, model, alias and to.
keys, a list of objects with field and other_field.
required, cardinality, and join_type, which is left or inner.
label, description and ai_context.

update_relationship changes what a join carries, and its keys and its model too. remove_relationship also takes out the fields that read the joined model. rename_alias gives a source a new alias, and changes every column that reads it. See Relationships and joins.