Understand dbt project objects

A DBT PROJECT is a schema-level object that contains versioned source files for your dbt project in Snowflake. A dbt project object is a deployed directory that contains a dbt_project.yml file at its root and model files representing your data pipeline. When you deploy (create) a dbt project object, you usually do so by copying workspace, git stage, or internal stage files directly into a dbt project object. Workspaces, on the other hand, are a development environment that allow you to edit and debug your dbt code before deploying a production-ready version via Snowsight or CI/CD integration.

dbt project objects support role-based access control (RBAC). You can CREATE, ALTER, and DROP dbt project objects like other schema-level objects in Snowflake. You can use the EXECUTE DBT PROJECT command from a Snowflake warehouse to execute dbt commands like test and run. You can also use tasks to schedule execution of these commands.

Benefits of creating a dbt project object

  • Run from any orchestrator: Use EXECUTE DBT PROJECT from any SQL client, Snowflake task, or external orchestrator such as Apache Airflow.

  • Monitoring and observability: Each dbt project object execution sends OpenTelemetry-compatible logs and traces to the Snowflake Event Table. Users get programmatic access to query history details using DBT_PROJECT_EXECUTION_HISTORY and SYSTEM$GET_DBT_LOG. For more information, see Monitor dbt Projects on Snowflake.

  • CI/CD integration: Use Snowflake CLI (snow dbt deploy) to deploy a new project version automatically on every merge. For a full walkthrough, see Tutorial: Set up CI/CD integrations on dbt Projects on Snowflake.

  • AI-assisted debugging with Cortex: Cortex AI can inspect your deployed project files and lineage. When an execution fails, ask Cortex natural-language questions to diagnose the issue directly with the deployed object files.

  • Real-time project documentation: The project details page is an in-product replacement for dbt docs, with an interactive DAG, column-level lineage, compiled SQL, and full run history. For more information, see View and manage information for existing dbt Projects.

How dbt project objects get updated

dbt project objects don’t automatically update as you edit the workspace. You must execute ALTER DBT PROJECT … ADD VERSION each time you want to redeploy and update the files of the dbt project object.

To create a production pipeline, we recommend creating a dbt project object and scheduling its execution with a task. Because each dbt project object version is immutable, doing so ensures nothing changes between runs unless someone explicitly adds a new version.

To update the files of a dbt project object, you must add a new version each time. For example:

ALTER DBT PROJECT testdbt.public.my_dbt_project_object
  ADD VERSION FROM 'snow://workspace/user$.public."all_my_dbt_projects"/versions/last';

For teams using Git-based workflows, Snowflake recommends using the Snowflake CLI to deploy directly from within a CI/CD pipeline such as GitHub Actions. For example:

snow dbt deploy my_dbt_project_object --source ./path/to/dbt/project --force

--force enables you to add a version; without it, it would be the equivalent of running CREATE DBT PROJECT on an already created object, which would fail. For a full CI/CD walkthrough on using the Snowflake CLI with GitHub Actions, see Tutorial: Set up CI/CD integrations on dbt Projects on Snowflake.

For more information about versioning, see Versions for dbt project objects and files.