kater new workspace

Makes a new workspace that reads a shared model.

It goes in your own folder, or in the connection’s workspaces/ folder with --kind connection. The new workspace has no queries and no app until you add them.

Examples

# Make the spend_review workspace in your own folder, over the shared ad_reporting model
kater new workspace spend_review --connection snowflake_prod_connection --from-model semantic.ad_reporting
# Make it in the connection's workspaces/ folder in place of your own folder
kater new workspace spend_review --connection snowflake_prod_connection --kind connection --from-model semantic.ad_reporting
# See what it writes, and save nothing
kater new workspace spend_review --connection snowflake_prod_connection --from-model semantic.ad_reporting --dry-run
# Give the new workspace a label and a description
kater new workspace spend_review --connection snowflake_prod_connection --from-model semantic.ad_reporting --label "Spend review" --description "Spend and conversions by platform"
# Copy the ad_reporting workspace into your own folder as ad_reporting_review
kater new workspace ad_reporting_review --connection snowflake_prod_connection --duplicate-from connections/snowflake_prod_connection/workspaces/ad_reporting

Arguments

Argument	Description
`<name>`	Optional. The workspace’s name, which is also the name of its folder. Use lowercase letters, digits and underscores, up to 64 characters, and start with a letter. It is the same as `--name`.

Options

Option	Description
`--target-path <path>`	The folder to make the workspace in, by its path from the folder you are in. Use it in place of `--connection` and `--kind`. With `--connection` too, the folder must be in that connection.
`--name <name>`	The workspace’s name, in place of `NAME`. When you give both, they must be the same.
`--duplicate-from <path>`	Copies this workspace, by its path from the content root, such as `connections/snowflake_prod_connection/workspaces/ad_reporting`. It must be in the same connection. See Copying a workspace.
`--label <text>`	The name that Kater shows for the workspace on screen, such as `Spend review`.
`--description <text>`	What the workspace is for, in a sentence or two.
`--ai-context <text>`	Notes for an agent that works in the workspace.
`--tags <tag>`	A tag for the workspace, as `key=value` or as a `key` alone. Give the option with no values to clear the tags. You can give it more than one time.
`--business-question <business-question>`	A question the workspace answers, such as “Which campaigns bring the most conversions?”. Repeat it for each. You can give it more than one time.
`--workspace-metadata <json>`	More keys for the top of `workspace.sql`, as a JSON object. Kater merges them into what it writes there. A copy with `--duplicate-from` refuses it.
`--metadata <json>`	The label, description, AI context and tags as one JSON object, such as `{"label": "Spend review"}`. It takes only `label`, `description`, `ai_context` and `tags`. A `null` text value is written as it is. A value that differs from its own option is refused.
`--dry-run`	Shows the files the create writes, and the revisions it checks, and saves nothing.
`--from-model <model>`	The shared model that the workspace reads, by its name or its address, such as `semantic.ad_reporting`. It is a semantic model or a Kater dataset. Without it, the workspace reads nothing until `kater workspace source use` gives it a model.
`--reuse-existing`	Uses a workspace that already exists with the same name and the same content, in place of a refusal. A workspace with different content still conflicts.
`--duplicate-revision <revision>`	With `--duplicate-from`: the `duplicate_revision` that a `--dry-run` lists. The create stops when the copied workspace changed since.
`--source-revision <revision>`	With `--from-model`, or with a copy outside a brainstorm topic: the `source_revision` that a `--dry-run` lists. The create stops when the shared model changed since.
`--composition-revision <revision>`	With `--duplicate-from` of a workspace that has apps: the `composition_revision` that a `--dry-run` lists. The create stops when the apps changed since.
`--connection <name>`	The connection to make the workspace in, such as `snowflake_prod_connection`. Give it when `--target-path` names no folder.
`--kind <kind>`	Where the workspace goes. `personal` puts it in your own folder, `users/<you>/workspaces/`, and is the default. `connection` puts it in the connection’s `workspaces/` folder.
`--start <start-type>`	The type to start from: overview, operations, realtime, transactions. Left out: No template, an empty dashboard you add queries and charts to.
`--source <start-source>`	Source data. Kater selects the source data that fits what you write. Or select the one you know. A dashboard, a query, a shared model or an app, by its path from the content root. Left out, Kater finds the best fit.
`--refresh-seconds <start-refresh-seconds>`	Refresh. Takes 60 (Every minute), 300 (Every 5 minutes), 900 (Every 15 minutes). Left out: 60, unless the type sets its own. For realtime.

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

What it writes

Kater makes the workspace’s folder, with a workspace.sql file, a dashboard.yaml file and an empty query_contracts/ folder. It makes no query and no app.

With --from-model, the SQL in workspace.sql reads every field of the model. The workspace’s root keeps the workspace’s name, so a query in a workspace named sales reads FROM workspace.sales, whatever model it reads.
Without --from-model, workspace.sql has no SQL until kater workspace source use gives the workspace a model.
A name that is taken is refused. Kater never adds a number to make it different.

Copying a workspace

--duplicate-from copies every file of the workspace. The queries and charts of the copy point at the new workspace.
Each app is copied with a new id, and you are its owner. A copied app still reads the queries of the original workspace.
A copy refuses --from-model and --workspace-metadata.
A workspace in a brainstorm topic must be a copy. Make it with kater brainstorm copy.

Check that nothing changed since a dry run

A --dry-run answer lists witnesses: the revisions of what the create reads. Give each one back to the create with its option, such as --source-revision. When one changed since the dry run, the create stops and asks you to make a new dry run. An option for a revision that a workspace create never reads stops the create for any value.