dbt setup

Adding a dbt project

Navigate to Settings → dbt and click "Add project".

Cloud mode

Cloud mode connects to dbt Cloud using the Admin API (for project/environment discovery) and the Discovery API (for manifest, catalog, and run results).

Prerequisites

• A dbt Cloud account with at least one project and environment

• A dbt Cloud personal access token or service token with read access

Creating an API token

1. Log in to dbt Cloud

2. Navigate to Account Settings → API tokens

3. Create a Service token with at least the following permissions:

   • Metadata Only - required for the Discovery API

   • Read-only - required for project and environment listing

4. Copy the generated token

Configuration

1. Enter a Name for the project

2. Select Cloud as the config type

3. Fill in your Account ID - found in the dbt Cloud console (Account settings → Account)

   

4. Enter the API Token from the previous step

5. Set Access URL

   

6. Click "Load Projects" to validate credentials and load available projects

7. Select a Project from the dropdown

8. Select an Environment - production environments are auto-selected when available

9. Set a Discovery URL

   

10. Click "Save"

Artifacts mode

Artifacts mode reads dbt artifacts directly from an S3-compatible object storage bucket. This is useful for self-hosted dbt Core setups where artifacts are uploaded to S3 after each run.

Expected bucket structure

s3://your-bucket/path/to/artifacts/ run-2024-01-01/ manifest.json run_results.json catalog.json (optional) run-2024-01-02/ manifest.json run_results.json catalog.json (optional)

Each run folder should contain at least manifest.json. The run_results.json and catalog.json files are optional but recommended.

Configuration

1. Enter a Name for the project

2. Select Artifacts as the config type

3. Set the Artifact URL - S3 path to your artifacts folder (e.g. s3://bucket-name/path/to/artifacts)

4. Enter Access Key and Secret Key for S3 authentication

5. Optionally set Region (defaults to us-east-1)

6. Optionally set a custom Endpoint for S3-compatible storage (e.g. MinIO)

7. Click "Save"

Syncing

After a project is configured, click "Sync Now" to trigger a sync. The sync process:

1. Fetches artifacts - retrieves manifest, run results, and catalog from the configured source

2. Imports metadata - creates enrichment objects for dbt models, sources, seeds, and snapshots

3. Resolves warehouse connections - matches dbt models to existing SelectZero database connections by database name

4. Builds lineage - creates column-level lineage relations between dependent models using passthrough matching

5. Imports test results - stores dbt test run results with status, execution time, and compiled SQL

6. Imports test cases - dbt tests are registered as SelectZero test cases with their source set to DBT, so they appear alongside native test cases in the Test cases library

How metadata works

How lineage works

dbt lineage is built using passthrough column matching. When a dbt model depends on another model (via depends_on), SelectZero compares the column names of both the source and target tables in the warehouse. Columns with matching names are linked as directed lineage relations.

This approach works well for models that pass columns through without renaming. The compiled SQL of each model is stored as a reference for each lineage relation, allowing users to trace the origin query.

Lineage is created between models where:

• Both the source and target models are resolved to warehouse connections

• Both models have metadata synced in SelectZero

• Matching column names exist in both models

Browsing dbt resources

The view is split into two panes:

• Left pane - a searchable tree grouped by resource type. Type the model/source/seed name into the search box at the top to filter the list. Click a group header to collapse or expand it.

• Right pane - the selected resource's full metadata.

The following resource types are listed, in this order:

• Models - dbt models (any materialization)

• Sources - declared sources backing the project

• Seeds - CSV seeds

• Snapshots - snapshot definitions

• Exposures - declared exposures (dashboards, reports, etc.)

The detail pane for a selected resource shows:

• Description, materialization, package, owner, tags, and any custom metadata from the manifest

• Last run timestamp - click to jump to the corresponding run in the Runs tab

• Test status with a data-quality bar summarizing pass/fail/error counts

• Link to the matched catalog object (when warehouse resolution succeeded)

• Raw SQL and compiled SQL, toggleable

Test results

dbt test results are imported and stored as pipeline runs. Each run contains:

• Run status - overall SUCCESS or FAILED based on individual test outcomes

• Generated timestamp - when the dbt run was executed

• Elapsed time - total run duration

• Individual results - each test/model result with status (pass, fail, error), execution time, failure message, and compiled SQL

Test results can be viewed by clicking on a project and navigating to the Runs tab. Clicking on a specific run shows detailed results with expandable test information.

Up to 50 historical runs are retained per project.

dbt and lineage

When a dbt model is matched to a SelectZero catalog object, that object is marked as dbt-enriched. In the Lineage graph, dbt-enriched nodes display a small dbt badge in the upper-right corner of the object (and column-level) tile. Clicking the badge opens the Resources browser with the matching dbt resource pre-selected, so you can review the model's SQL, tests, and metadata without leaving the lineage view.

The badge is only shown when the node has an active dbt enrichment - disabled or removed projects no longer mark their objects.