Using dbt models

If you manage your warehouse models with dbt, you can keep your dbt project as the source of truth for Supersimple data models too.

The Supersimple CLI converts dbt's generated manifest.json and catalog.json artifacts into a Supersimple YAML file. Supersimple-specific metadata lives alongside each model and column under config.meta.supersimple, so the generated file does not need to be edited manually.

From your dbt project, generate the dbt artifacts and convert them with:

dbt docs generate
supersimple dbt convert

1. Add Supersimple annotations to dbt

Enable each dbt model that you want to expose in Supersimple under config.meta.supersimple:

version: 2

models:
  - name: customers
    description: Customer accounts, excluding test accounts and administrators.
    config:
      meta:
        supersimple:
          enabled: true
          model_id: customers
          primary_key: [customer_id]
          relations:
            transactions:
              name: Transactions
              type: hasMany
              model_id: transactions
              join_strategy:
                join_key: customer_id

    columns:
      - name: customer_id
        description: Unique customer ID.
        data_tests: [not_null, unique]

      - name: status
        description: Current customer status.
        config:
          meta:
            supersimple:
              type: Enum
              enum_options:
                load: distinct_values

Models without enabled: true are ignored.

Model annotations

Field	Purpose
enabled	Include this dbt model in the generated Supersimple configuration. Must be true.
model_id	Stable Supersimple model ID. Defaults to the dbt model name.
name	User-facing model name. Defaults to the dbt model name.
description	Overrides the native dbt model description.
primary_key	One or more property keys that uniquely identify a row. Strongly recommended, but not required.
relations	Relations to other Supersimple models.
operations	Operations that should always be applied to the model.
labels	Model labels, including sidebar organization.
semantics	Semantic model kind and its property mappings.
access	Model access-control configuration.
connection	Database connection to use when the account has more than one.

Except for enabled and model_id, these fields use the same shapes as the corresponding fields in Supersimple data model YAML.

Column annotations

Add column-level annotations under columns[].config.meta.supersimple:

Field	Purpose
name	User-facing property name. Defaults to the physical column name.
description	Overrides the native dbt column description.
type	Overrides the type inferred from catalog.json.
format	Display format, such as usd or percentage.
column_type	Physical temporal type for a Date property: date, datetime, timestamp, or time.
precision	Semantic granularity for a Date property, such as month or day.
enum_options	Static or dynamically loaded options for an Enum property.
sql	Custom SQL expression for the property.

Native dbt model and column descriptions are carried over automatically. Physical column types come from catalog.json, while explicit type annotations take precedence.

dbt tests are not interpreted as Supersimple metadata. For example, unique and not_null tests do not automatically define a primary key, and accepted_values does not automatically create an enum. Annotate primary_key and enum properties explicitly when needed.

2. Generate the dbt artifacts

Run this from the dbt project directory after materializing the enabled models:

dbt docs generate

Use the same dbt profile and target that contain the models you want to expose in Supersimple.

3. Convert to Supersimple YAML

Run the converter from the dbt project directory:

supersimple dbt convert

With dbt's default target/ directory, no flags are needed. The command writes supersimple-models.yml in the current directory.

If your artifacts are stored elsewhere, specify their directory:

supersimple dbt convert --artifacts-dir build/dbt

To use a different output path:

supersimple dbt convert -o generated/supersimple-models.yml

The output is marked as generated and can be safely refreshed by rerunning the command. The converter refuses to replace an existing hand-written file unless you explicitly pass --force.

TIP

Treat the generated Supersimple file as a build artifact: do not edit it manually. Put Supersimple-specific changes in the dbt annotations, then regenerate the file. You can add supersimple-models.yml to .gitignore when it is generated during CI.

Run supersimple dbt convert --help for the complete list of supported annotations, adapters, and command options.

4. Validate and import

Validate the generated models before importing them:

supersimple validate supersimple-models.yml --validate-sql

Then import them into Supersimple:

supersimple import supersimple-models.yml --validate-sql

If your account also has hand-written metrics or other configuration files, pass all related files to the same validation and import command:

supersimple validate supersimple-models.yml metrics/
supersimple import supersimple-models.yml metrics/

See Using the CLI for installation and authentication instructions.

Current limitations

• PostgreSQL, ClickHouse, and BigQuery dbt adapters are currently supported.
• Ephemeral models are not supported. Materialize a model before converting it.

Keeping models in sync

Run the artifact generation, conversion, and import steps after deploying dbt models:

dbt docs generate
supersimple dbt convert
supersimple import supersimple-models.yml --validate-sql

This can run locally or in CI. The environment needs dbt warehouse credentials for dbt docs generate and Supersimple CLI credentials for the import. See Syncing data models from Git for the Supersimple authentication variables used in GitHub Actions.

Avoid --delete-dangling unless the files passed to supersimple import represent the complete model configuration for the account.