Skip to main content
DocumentationLibraryReference
On this page

Kater CLI Make and compare new

kater new query

Makes a query in a workspace: a blank query, a query from your own SQL, or a copy of another query.

The new query goes in the workspace’s query_contracts/ folder. To build a query from the fields you select, use kater query new.

Examples

Terminal window
# Go to the ad_reporting workspace in your local copy of Kater content
cd connections/snowflake_prod_connection/workspaces/ad_reporting
# Add a blank query named clicks_by_platform
kater new query --name clicks_by_platform
# Add a query from its SQL alone, and let Kater write the top of the file
echo "SELECT ad_reporting.platform, ad_reporting.sum__impressions FROM workspace.ad_reporting AS ad_reporting GROUP BY ad_reporting.platform" | kater new query --name impressions_by_platform --sql-file -
# See the file that a copy of spend_by_platform writes, and save nothing
kater new query --name spend_by_platform_review --duplicate-from spend_by_platform --dry-run
# Copy the spend_by_platform query as spend_by_platform_review
kater new query --name spend_by_platform_review --duplicate-from spend_by_platform

Arguments

ArgumentDescription
<name>Optional. Its technical name, the same as --name.

Options

OptionDescription
--target-path <path>Where the query goes: a workspace’s folder, or a query file to add the query to. A path that starts with connections/ is from the content root. Any other path is from the folder you are in. In a workspace’s folder, the new file is query_contracts/<name>.sql. Leave it out, and the query goes in the workspace you work in: the one --scope names, your saved scope, or the folder you are in. A copy goes in the workspace of the query that --duplicate-from names by its path.
--name <name>The query’s name. It wins over the name in a --query-file. A name that is taken is refused, and Kater never adds a number to make it different.
--duplicate-from <query>Copies a query of the same workspace, by its name, such as spend_by_platform, or by its file’s path. For one query of a file that holds several, add #model= and the query’s name to the path.
--label <text>The name that Kater shows for the query on screen, such as Clicks by platform.
--description <text>What the query answers, in a sentence or two.
--ai-context <text>Notes for an agent that reads or changes the query.
--tags <tag>A tag for the query, 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 query answers, such as “Which campaigns bring the most conversions?”. Repeat it for each. You can give it more than one time.
--metadata <json>The label, description, AI context and tags as one JSON object, such as {"label": "Clicks by platform"}. 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-runShows the file the create writes, and the revisions it checks, and saves nothing.
--sql-file <file>A file that holds only the query’s SQL. Kater writes the top of the file for you. - reads the SQL from standard input.
--query-file <file>A file that holds a whole query file: the top of the file and its SQL. Kater checks it before it saves anything. - reads it from standard input.
--reuse-existingUses a query that already exists with the same name and the same content, in place of a refusal. A query with different content still conflicts.
--expected-revision <revision>When you add the query to a file that exists: the expected_revision that a --dry-run lists. The create stops when the file changed since.
--duplicate-revision <revision>With --duplicate-from: the duplicate_revision that a --dry-run lists. The create stops when the copied query changed since.
--namespace-revision <revision>The namespace_revision that a --dry-run lists. The create stops when the workspace changed since.
--source-revision <revision>The source_revision that a --dry-run lists. The create stops when it changed since.
--schema-revision <revision>The schema_revision that a --dry-run lists. The create stops when it changed since.
--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.

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

What it writes

  • A blank query, with no SQL, file or copy, reads its workspace and selects nothing.
  • --sql-file gives the SQL alone, and Kater writes the top of the file. --query-file gives the whole file, which Kater checks before it saves.
  • It reads through the workspace. Kater changes SQL that reads the workspace’s shared model to read the workspace. For example, it changes FROM semantic.ad_reporting in SQL from a Definitions example.
  • --name wins over the name in a --query-file. A name that is taken is refused, never numbered.

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 --namespace-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 query create never reads stops the create for any value.

See also