dbt.

Orchid reads your dbt project — models, tests, sources, exposures, macros, doc blocks — and surfaces them in the schema browser alongside your warehouse tables. You query the materialized models like any other table, with full context one click away.

How the connector works

Orchid doesn't run dbt for you. Instead, it parses your dbt project files (the manifest.json generated by dbt compile or dbt run) so it can:

• Show model lineage in the schema browser.
• Link cell results back to the source model definition.
• Surface test failures with the failing rows when you click a test.
• Generate ref('...')-aware autocomplete in SQL cells.
• Surface macro definitions and doc blocks alongside models.

Requirements

• A dbt project on your machine (or accessible via a checked-out git repo).
• A target/manifest.json generated by dbt — run dbt compile once at minimum.
• A separate Orchid warehouse connection to the database where your models are materialized.

Connect

1. Open Integrations → + Add connection → dbt.
2. Click Browse and pick the dbt project root (the folder with dbt_project.yml).
3. Pick the warehouse connection it should pair with (e.g. your Snowflake or BigQuery connection).
4. Click Save. Orchid reads the manifest and surfaces models in the sidebar.

Optional settings

Auto-refresh on file changes

Orchid watches target/manifest.json. When you re-run dbt compile or dbt run, the schema panel updates within a second. No need to reconnect.

Multiple targets

If your project has multiple dbt targets (dev / prod), Orchid uses the one selected in your dbt project's profiles.yml. Switch by changing the target before re-compiling. To run against both side-by-side, add two Orchid dbt connections pointing at the same project root but paired with different warehouse connections.

What Orchid surfaces from your dbt project

Models with rendered SQL

Click any dbt model in the schema panel. Orchid shows the rendered (compiled) SQL — i.e.ref('upstream') already replaced with the qualified table name — alongside the original Jinja source. Useful when you want to understand what the warehouse actually ran.

Macros

Macro inspection works the same way. Open Macros in the schema panel and click into one to see its body. Orchid pulls macro definitions from both your project and installed packages.

-- A macro in your project, e.g. macros/cents_to_dollars.sql:
{% macro cents_to_dollars(column_name, precision=2) %}
  ({{ column_name }} / 100.0)::numeric(18, {{ precision }})
{% endmacro %}

-- Compiled invocation visible in Orchid:
SELECT order_id,
       (total_cents / 100.0)::numeric(18, 2) AS total_dollars
FROM {{ ref('orders') }};
      

Source freshness

If your dbt project defines freshness on sources and you've run dbt source freshness, Orchid surfaces freshness status (pass / warn / error) directly on the source in the schema panel. Hover for the latest check timestamp.

Exposures

Exposures (dashboards, ML models, etc. that consume dbt models) appear in their own section in the schema panel. Click an exposure to jump to its ref chain — useful when you're asked "does anything break if I drop this column?".

Doc blocks

Markdown content from {% docs ... %} blocks is surfaced in the model detail view. When a column has a description: in schema.yml and that description references a doc block, Orchid renders the full markdown — including snippets, lists, and links — instead of the raw {{ doc(...) }} call.

# models/marts/schema.yml
version: 2
models:
  - name: orders
    description: "{{ doc('orders_overview') }}"
    columns:
      - name: status
        description: "{{ doc('order_status_values') }}"
        tests:
          - accepted_values:
              values: ['placed', 'shipped', 'returned']
      

Common gotchas

• "manifest.json not found" — you haven't run dbt compile or dbt run yet, or you're pointing at the wrong project folder. Verify with ls target/manifest.json.
• Models materialize to a different schema than you expect — dbt's schema generation depends on profiles.yml. Verify with dbt debug, and double-check the schema in the compiled SQL Orchid shows.
• Tests don't show — tests are present in the manifest only after they've been compiled. dbt build or dbt compile followed by dbt test is the safest sequence.
• Doc blocks render as raw Jinja — the manifest hasn't been recompiled since you edited the docs. dbt compile again.
• Freshness missing on sources — you need to run dbt source freshness at least once. Orchid reads the latest results from target/sources.json.

Example workflow

A common pattern: open the dbt schema panel, find a model that's relevant, drag it into a SQL cell. Orchid generates the compiled query — fully qualified, no Jinja — and runs it against the warehouse. Inspect the result, build a chart, share.

-- Orchid generates this when you drag the 'fct_orders' model into a cell
SELECT *
FROM analytics.marts.fct_orders
LIMIT 100;
      

Where to go next

For more on writing SQL cells, see SQL cells.