Skip to main content
DocumentationLibraryReference
On this page

Kater CLI Make and compare new

kater new semantic-model

Makes a semantic model file to a connection's shared layer.

Start it from your SQL, from one shared dataset or model, or as a copy of another semantic model. A create needs --target-path and --name, and --dry-run shows the file first. A semantic model joins Kater datasets, and other semantic models, into one place to analyze. See Semantic models.

Examples

Terminal window
# Go to a connection's shared layer in your local copy of Kater content
cd connections/snowflake_prod_connection/modeling
# Start a semantic model from the google_ads__campaign_report dataset, with all its fields
kater new semantic-model --target-path kater_objects/semantic_models/marketing --name google_ads_campaigns --base kater_dataset.google_ads__campaign_report
# Add a semantic model from the SQL in a file
kater new semantic-model --target-path kater_objects/semantic_models/marketing --name google_ads_campaigns --sql-file ~/google_ads_campaigns.sql
# Copy the ad_reporting model under a new name
kater new semantic-model --target-path kater_objects/semantic_models/marts --name ad_reporting_finance --duplicate-from ad_reporting
# See the file it would write, and write nothing
kater new semantic-model --target-path kater_objects/semantic_models/marketing --name google_ads_campaigns --base kater_dataset.google_ads__campaign_report --dry-run

Options

OptionDescription
--target-path <path>The folder for the new model, in the connection’s modeling/kater_objects/ folder, such as kater_objects/semantic_models/marketing. A create needs it. kater new options semantic_model lists the folders that you can use.
--name <name>The model’s technical name, such as google_ads_campaigns. Other models read it as semantic.NAME. A create needs it. Without it, a dry run proposes a name such as unnamed_semantic_model_1.
--duplicate-from <model>Copies a semantic model of the same connection. Give its name, its id, or PATH#model=NAME. The copy keeps the model’s SQL and frontmatter, with the new name and the metadata you give.
--label <text>The name that people see, such as Google Ads Campaigns.
--description <text>What the model holds, for the people and agents that read it.
--ai-context <text>Guidance for an AI agent that uses the model, such as its grain and which totals not to add together.
--tags <tag>A tag for the model: key=value, such as team=marketing/paid_media, 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": "Google Ads Campaigns"}. A null text, or {} for tags, clears a value that --duplicate-from copies. 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.
--sql-file <file>A file with the model’s SQL, without frontmatter. Kater writes the frontmatter. Give - to read the SQL from standard input. It cannot go with --base or --duplicate-from.
--base <model>The shared Kater dataset or semantic model to start from. Give its name, its typed address such as kater_dataset.google_ads__campaign_report, or identity JSON. The new model passes every field of it through. It cannot go with --sql-file or --duplicate-from.
--reuse-existingLets you run the same create again, such as after a timeout. When the file already holds exactly this model, the command succeeds and writes nothing. Different content still fails.
--duplicate-revision <revision>With --duplicate-from, the copied model’s revision from the witnesses of a dry run. The create stops when that model changed after the dry run.
--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 --base, 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.

What it writes

  • One file. The file is NAME.sql in the target folder, such as kater_objects/semantic_models/marketing/google_ads_campaigns.sql. Kater writes its frontmatter.
  • From a base. With --base, the SQL reads the base under a short name, and passes every field that the base publishes through. The base must compile now, and it must publish fields.
  • From your SQL. With --sql-file, Kater checks the SQL before it writes. When the SQL has an error, Kater writes nothing and lists the problems.
  • Empty. With none of --sql-file, --base or --duplicate-from, the file holds only its frontmatter, and you write its SQL.
  • 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 semantic models. 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.
  • Readable files. To check the name, Kater reads every SQL file in modeling/. It stops when one has frontmatter that it cannot read.
  • In a local copy. The file is on your computer only. Commit it and run kater git push to publish it.

Check a dry run, then create

  1. Run the create with --dry-run --json. It writes nothing.
  2. Read the file path and the name that it proposes, and the revisions in witnesses.
  3. Run the create without --dry-run, with those revisions, such as --namespace-revision. The create stops when something changed after the dry run.

The revision options work only on a create that writes, not with --dry-run. See Create commands.

See also