Skip to main content
DocumentationLibraryReference
On this page

Kater CLI Make and compare new

kater new db-dataset

Makes the DB dataset file for one warehouse table, from the table's CREATE TABLE statement.

kater sync --resource-type db_dataset usually writes these files for you, so use this command for a table that sync has not written yet. The next sync takes the file over. It does not read or change your warehouse. See DB datasets.

Examples

Terminal window
# Go to a connection's folder in your local copy of Kater content
cd connections/snowflake_prod_connection
# See the name and the file that the returns table would get, and write nothing
kater new db-dataset --target-path modeling/db_objects/datasets --sql-file returns.sql --dry-run
# Add the DB dataset for the returns table
kater new db-dataset --target-path modeling/db_objects/datasets --name returns --label Returns --sql-file returns.sql
# Let sync take the file over and profile its columns
kater sync --resource-type db_dataset --scope modeling

Options

OptionDescription
--target-path <path>The connection’s modeling/db_objects/datasets/ folder, or a folder in it on the way to the table’s file, such as modeling/db_objects/datasets/shop/sales. A create needs it.
--active-path <path>The file you have open. With --dry-run and --scope, when it is a DB dataset, the dry run proposes its folder. A create that writes refuses it.
--name <name>The DB dataset’s technical name. A create needs it. Without it, a dry run proposes the name that sync would give the table.
--label <text>The name that people see. Sync keeps it.
--description <text>What the table holds, for the people and agents that read it. Sync keeps it.
--metadata <json>The label and the description as one JSON object, such as {"label": "Returns"}. 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 and --sql-file.
--sql-file <file>A file with the table’s CREATE TABLE statement, without frontmatter. The statement names the table in full, as DATABASE.SCHEMA.TABLE, and lists its columns. A create needs it. Give - to read it from standard input.
--reuse-existingLets you run the same create again, such as after a timeout. When the file already holds exactly this DB 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, the revision of the checked SQL, from the witnesses of a dry run. The create stops when the SQL changed after the dry run.

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

The statement

The examples read the table’s statement from returns.sql. It names the table in full and lists its columns:

returns.sql
CREATE TABLE shop.sales.returns (order_id INTEGER, returned_at TIMESTAMP, amount DECIMAL(10, 2));

What it writes

  • The file that sync keeps for the table. The file is modeling/db_objects/datasets/DATABASE/SCHEMA/TABLE.sql, whatever its name, such as modeling/db_objects/datasets/shop/sales/returns.sql.
  • The frontmatter. Kater writes the name, the label and the description that you give, and the table’s database, schema and table keys. The first line is the header that sync writes. See DB datasets.
  • Your statement. Kater checks it before it writes. When it has an error, Kater writes nothing.
  • The answer. It gives the new file’s path, authored_path, and the model’s id, object_id.

When Kater refuses it

  • The SQL is not one CREATE TABLE statement that names the table in full.
  • connection.yaml does not select the table. Add the table to connection.yaml first.
  • Another DB dataset already describes the table. Open that file instead.
  • --target-path is not on the way to the table’s file. The message names the folder to give.

After you create it

The next kater sync --resource-type db_dataset takes the file over and lists it under Adopted. It writes the DDL from the warehouse, profiles the columns, and keeps the name, the label and the description. When the warehouse has no such table, sync keeps the file, gives a warning, and never deletes it. See Files that sync did not write.

Names and access

  • A new name. The name must be new among the connection’s DB 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