kater chart

Lists, reads, checks, saves and runs the saved charts of a workspace.

A chart draws the rows of one query, and a dashboard shows saved charts as tiles. Each command here takes its request as a JSON file. kater new chart makes a chart, with options. See Charts.

Commands

Command	What it does
`kater chart list`	List the saved charts that read a query.
`kater chart read`	Read a saved chart’s spec, SQL and title.
`kater chart describe`	Show a query’s columns and what each chart kind takes, as a chart builder reads them. To change a chart, kater chart draw is shorter.
`kater chart plan`	Check a chart without saving it.
`kater chart prompt`	Write a prompt asking an agent to finish a chart.
`kater chart create`	Make a chart from its exact request. kater new chart makes one from options.
`kater chart save`	Save your changes to an existing chart.
`kater chart draw`	Draw a saved chart again from its kind and the columns each role reads.
`kater chart duplicate`	Copy a saved chart under a new name.
`kater chart reorder`	Change the order of a query’s charts.
`kater chart destination`	Check whether a workspace can take a chart.
`kater chart snapshot`	Get the rows kept from your last run of a query.
`kater chart preview`	Draw an unsaved chart from its query’s kept rows.
`kater chart execute`	Run a chart on the warehouse, as a dashboard tile does.

The request file

Each command reads one JSON object from the file that --request-file names. Give - to read the request from standard input. The CLI’s help does not show the fields, so each command’s page lists them.

Name a workspace by its full path from the content root, such as connections/snowflake_prod_connection/workspaces/ad_reporting.
Name a query or a chart by its name, such as spend_by_platform or spend_mix.
Run it from any folder in your local copy of Kater content. Kater finds the content root by walking up from that folder.
The answer is JSON. With --json, it is on one line. Keep it in a file to read it with jq.

Many commands take one of these two files as they are. The first names the spend_by_platform query, and the second names the spend_mix chart, a pie chart over that query:

{"source": {"name": "spend_by_platform", "namespace": {"path": "connections/snowflake_prod_connection/workspaces/ad_reporting"}}}

{"chart": {"name": "spend_mix", "namespace": {"path": "connections/snowflake_prod_connection/workspaces/ad_reporting"}}}

Revisions

A command that changes a saved chart takes its expected_revision: the revision that kater chart read or kater chart list gave. When the chart changed after you read it, Kater refuses the change. Read the chart again, and try again. The examples use jq to copy the revision and the chart from one answer into the next request.

Command names

Each command sends one operation, and a dot in the operation’s name is a space here: chart.read is kater chart read. kater invoke sends the same requests by the operation’s name.

Examples

# List the saved charts that read the spend_by_platform query
kater chart list --request-file spend_by_platform.json
# Show the spend_mix chart: its spec, its SQL and its revision
kater chart read --request-file spend_mix.json
# Make a table chart over spend_by_platform in the ad_reporting workspace
kater new chart --target-path connections/snowflake_prod_connection/workspaces/ad_reporting --name spend_by_platform_table --source-query spend_by_platform
# Show the columns of spend_by_platform and what each chart kind takes
kater chart describe --request-file spend_by_platform.json