kater new chart

Makes a new saved chart over a query in a workspace.

Without a definition, the chart is a table of every column the query returns, and Kater runs no query to make it. Give --definition-file to make another kind of chart, such as a bar chart or a pie chart.

Examples

# Go to the ad_reporting workspace in your local copy of Kater content
cd connections/snowflake_prod_connection/workspaces/ad_reporting
# Make a table chart of every column that spend_by_platform returns
kater new chart --name spend_by_platform_table --source-query spend_by_platform
# Show the chart it would make, and save nothing
kater new chart --name spend_by_platform_table --source-query spend_by_platform --dry-run
# Make the table chart with a title of its own
kater new chart --name spend_by_platform_table --source-query spend_by_platform --label "Spend by platform table"
# Make a chart from a chart definition in spend_share.json
kater new chart --name spend_share --source-query spend_by_platform --definition-file spend_share.json
# Make the chart from the content root, in the workspace that has the query
cd ../../../..
kater new chart --name spend_by_platform_table --source-query spend_by_platform --target-path connections/snowflake_prod_connection/workspaces/ad_reporting

Arguments

Argument	Description
`<name>`	Optional. Its technical name, the same as `--name`.

Options

Option	Description
`--target-path <path>`	The workspace to put the chart in, or its `charts` folder. A path that starts with `connections/` is from the content root. Any other path is from the folder you are in. Leave it out, and the chart goes in the workspace you work in: the one `--scope` names, your saved scope, or the folder you are in. When none is a workspace with the query that `--source-query` names, the chart goes in the one workspace that has a query of that name.
`--active-path <path>`	The file open in your editor, which helps a dry run find where the chart goes. Use it only with `--dry-run` and `--scope`. Kater refuses it when it makes the chart.
`--name <name>`	The chart’s name, such as `spend_by_platform_table`. It is also the name of the chart’s file. You must give it to make the chart. A dry run can leave it out.
`--duplicate-from <path>`	A chart to copy, by its file from the content root, such as connections/<connection>/workspaces/<workspace>/charts/spend_by_week.yaml. The copy goes in the same workspace and reads the same query.
`--label <text>`	The title the chart shows, such as `"Spend by platform table"`. Without it, the title says what the chart shows.
`--metadata <json>`	The chart’s label as a JSON object, such as `{"label": "Spend share"}`. A chart takes no other key. Do not give it with `--label`.
`--dry-run`	Shows the chart it would save, with its revisions, and saves nothing.
`--source-query <name>`	The query the chart reads, by its exact name in the workspace, such as `spend_by_platform`. Without `--target-path`, it also selects the workspace. When several workspaces have a query of that name, give `--target-path`. Leave it out when the workspace has one query, or when the definition names the query.
`--definition-file <file>`	The chart as JSON: its `spec`, and its `sql` or its `plan`. Give `-` to read it from standard input. See The chart definition.
`--reuse-existing`	When the same chart is already saved under this name, Kater gives it back and writes nothing. Kater refuses a saved chart with other content.
`--namespace-revision <revision>`	The workspace’s revision, as a dry run gives it. Kater refuses to make the chart when the workspace changed after the dry run.
`--source-revision <revision>`	The query’s revision, as a dry run gives it. Kater refuses to make the chart when the query changed after the dry run.
`--duplicate-revision <revision>`	With `--duplicate-from`: the duplicate_revision in the witnesses of kater new chart `--dry-run` `--json`. The create stops when the copied chart changed since.
`--schema-revision <revision>`	The revision of the query’s columns, as a dry run gives it. Kater refuses to make the chart when the columns changed after the dry run.
`--start <start-type>`	The type to start from: line, bar, table, stats, pie, ranked. Left out: No template, the chart builder suggests a kind from the query.
`--source <start-source>`	Source data. The query whose rows the chart draws. Kater selects one that fits what you write, or you select it. A dashboard, a query, a shared model or an app, by its path from the content root. Left out, Kater finds the best fit.

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

What Kater makes

The chart goes in the workspace’s charts folder, such as charts/spend_by_platform_table.sql.
Without a definition, the chart is a table of every column the query returns. Kater runs no query to make it.
A name the workspace already has is refused, unless --reuse-existing finds the same chart.
To run the new chart, use kater run, such as kater run --select charts/spend_by_platform_table.sql.

The chart definition

The definition file holds the chart’s spec, and exactly one of sql or plan. It is the request of kater chart plan, without expected_revision. The spec names the chart by the name in --name, and its query by the name in --source-query.

Options a chart does not take

A chart takes only a name and a label. Its description, guidance and tags belong to its query. To send the create request as JSON, use kater chart create --request-file. For what the create commands have in common, see Create commands.