Skip to main content
DocumentationLibraryReference
On this page

Kater CLI Make and compare new

kater new kater-dataset

Makes a Kater dataset file to a connection's shared layer.

Start it over one warehouse table, from your SQL, or as a custom SQL dataset. A create needs --target-path and --name, and --dry-run shows the file first. A Kater dataset gives each column of a table a field name and a label, and holds its first measures. See Kater datasets.

Examples

Terminal window
# Go to a connection's shared layer in your local copy of Kater content
cd connections/snowflake_prod_connection/modeling
# Add a Kater dataset over a table that has a DB dataset
kater new kater-dataset --target-path kater_objects/datasets --name facebook_ads__region_report --table DEMO_DB.ANALYTICS_AD_REPORTING.FACEBOOK_ADS__REGION_REPORT
# Add a custom SQL dataset from the SQL in a file
kater new kater-dataset --target-path kater_objects/datasets/marts --name ad_reporting__region_spend --sql-file ~/region_spend.sql --custom-sql
# See the name and file it would write for a table, and write nothing
kater new kater-dataset --target-path kater_objects/datasets --table DEMO_DB.ANALYTICS_AD_REPORTING.FACEBOOK_ADS__REGION_REPORT --dry-run

Options

OptionDescription
--target-path <path>The folder for the new dataset, in the connection’s modeling/kater_objects/ folder, such as kater_objects/datasets. A create needs it. kater new options kater_dataset lists the folders that you can use.
--name <name>The dataset’s technical name, such as facebook_ads__region_report. Other models read it as kater_dataset.NAME. A create needs it. Without it, a dry run proposes the table’s name in lower case, or a name such as unnamed_dataset_1.
--label <text>The name that people see, such as Facebook Ads Region Report.
--description <text>What the dataset holds, for the people and agents that read it.
--ai-context <text>Guidance for an AI agent that uses the dataset, such as its grain and which totals not to add together.
--tags <tag>A tag for the dataset: key=value, such as source_data=facebook_ads, or key alone. See Structured model tags. You can give it more than one time.
--metadata <json>The label, description, AI context and tags as one JSON object, such as {"label": "Facebook Ads Region Report"}. A value here cannot differ from its own option.
--dry-runShows the file that the command would write, its name and its revisions, and writes nothing. With it, you can give --scope in place of --target-path, and leave out --name.
--custom-sqlMakes a custom SQL dataset: one query in your warehouse’s own SQL, which needs no DB dataset and no sync. It cannot go with --table.
--sql-file <file>A file with the dataset’s SQL, without frontmatter. Kater writes the frontmatter. Give - to read the SQL from standard input. It cannot go with --table.
--table <database.schema.table>The warehouse table that the new dataset reads, such as DEMO_DB.ANALYTICS_AD_REPORTING.FACEBOOK_ADS__REGION_REPORT, or the same as JSON. The table needs a DB dataset. Every column becomes a dimension, as sync writes one.
--reuse-existingLets you run the same create again, such as after a timeout. When the file already holds exactly this dataset, the command succeeds and writes nothing. Different content still fails.
--namespace-revision <revision>The revision of the names already taken, from the witnesses of a dry run. The create stops when a SQL file in the connection’s modeling/ folder changed after the dry run.
--source-revision <revision>With --sql-file or --table, the revision of the checked SQL, from the witnesses of a dry run. The create stops when the SQL or a model it reads changed after the dry run.

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

Three ways to start

  • Over a table. --table writes a standard dataset that reads every column of the table as a dimension. The table needs a DB dataset first. Kater refuses a table that a standard Kater dataset already reads, and names that dataset.
  • From your SQL. --sql-file gives the SQL. A standard dataset reads one DB dataset’s table, by its DATABASE.SCHEMA.TABLE address.
  • Custom SQL. --custom-sql makes a custom SQL dataset. Without --sql-file, it starts from a short query with one dimension and one measure, which you replace.
  • Empty. With none of these, the file holds only its frontmatter, and you write its SQL.

Kater checks the SQL before it writes. When the SQL has an error, Kater writes nothing and lists the problems.

After it saves

  • Columns of a custom SQL dataset. Kater reads the dataset’s columns from the warehouse. When that read fails, the file stays saved, and the answer asks you to refresh the dataset.
  • Sync and your dataset. Sync did not make this dataset. When it reads a table, kater sync --resource-type kater_dataset stops at that table until you adopt the dataset with --adopt. Sync leaves a custom SQL dataset alone.
  • The answer. It gives the new file’s path, authored_path, and the model’s id, object_id.

Names and access

  • A new name. The name must be new among the connection’s Kater datasets. Kater never adds a number to make a name new.
  • The naming rule. A name starts with a letter or _, and holds letters, digits, _, $ and -, up to 128 characters.
  • Edit access. You need edit access to the connection’s modeling/ folder.
  • In a local copy. The file is on your computer only. Commit it and run kater git push to publish it.

See Create commands.

See also