A database dataset describes one warehouse table: its columns, their types and whether each is a category or a quantity. It is the source layer. You rarely write one, because schema sync writes it for you.

Nothing analyzes a database dataset directly. A Kater dataset reads it and adds field names, labels and measures. In the Shared models editor, a Kater dataset shows its database dataset as the table it reads.

Example

1
-- DDL and column classifications are generated by kater sync --resource-type db_dataset. label and description are yours to edit. name follows the warehouse table, and sync renames it when the table changes.
2
---
3
name: orders
4
model_type: db_dataset
5
database: shop
6
schema: sales
7
table: orders
8
---
9

10
CREATE TABLE shop.sales.orders (
11
  -- @categorical
12
  order_id VARCHAR NOT NULL,
13
  -- @categorical
14
  customer_id VARCHAR,
15
  -- @categorical
16
  region VARCHAR,
17
  -- @categorical
18
  currency VARCHAR,
19
  -- @continuous
20
  order_date DATE,
21
  -- @continuous
22
  amount DECIMAL(18,2),
23
  ...
24
);

Where you see them

Database datasets keep Files’ own view. In Files, select View › Modeling, then the Source tab, and open a table. The file shows its locked database, schema and table, Label and Description to add, and the generated CREATE TABLE.

Keys

Rules

• Sync owns the DDL. Do not edit the column list or the classifications by hand. Run kater sync after a table changes, or select Model › Sync DB datasets in Shared models.
• Nothing runs the DDL. The CREATE TABLE describes a table that already exists. Compiling or running Kater never changes your warehouse.
• The physical address stays the warehouse’s. Other models read the table as DATABASE.SCHEMA.TABLE, such as shop.sales.orders. db_dataset.orders is not an address.
• Quoted names stay exact. Snowflake folds an unquoted name to upper case and keeps a quoted one as written, so "Orders" and orders are different tables. DuckDB ignores case.
• Supported DDL is simple. A non-empty column list, with optional OR REPLACE and, on Snowflake, TRANSIENT. CREATE TABLE AS SELECT, defaults and unsupported constraints are refused.
• Files sit by database and schema. The path is modeling/db_objects/datasets/<DATABASE>/<SCHEMA>/<TABLE>.sql. A table name with a space is escaped in the file name, such as order%20events.sql.
• Field labels and measures go one layer up. Put them in the Kater dataset over this table. To make one for a table that has none, select New › Kater dataset in Shared models and select the table.

Add one by hand

Sync is the normal way. To describe a table yourself, open Files › Modeling, select the Source tab, then New › Physical Dataset. From a terminal, kater new db-dataset --name NAME --target-path PATH writes a blank scaffold, and --dry-run shows it first.

Common errors