# Table of Contents - [About the dbt VS Code extension | dbt Developer Hub](#about-the-dbt-vs-code-extension-dbt-developer-hub) - [About dbt setup | dbt Developer Hub](#about-dbt-setup-dbt-developer-hub) - [About dbt installation | dbt Developer Hub](#about-dbt-installation-dbt-developer-hub) - [About MetricFlow | dbt Developer Hub](#about-metricflow-dbt-developer-hub) - [Advanced data modeling | dbt Developer Hub](#advanced-data-modeling-dbt-developer-hub) - [Analyses | dbt Developer Hub](#analyses-dbt-developer-hub) - [Build your metrics | dbt Developer Hub](#build-your-metrics-dbt-developer-hub) - [Custom databases | dbt Developer Hub](#custom-databases-dbt-developer-hub) - [Conversion metrics | dbt Developer Hub](#conversion-metrics-dbt-developer-hub) - [Custom aliases | dbt Developer Hub](#custom-aliases-dbt-developer-hub) - [dbt tips and tricks | dbt Developer Hub](#dbt-tips-and-tricks-dbt-developer-hub) - [Custom target names | dbt Developer Hub](#custom-target-names-dbt-developer-hub) - [About the empty flag | dbt Developer Hub](#about-the-empty-flag-dbt-developer-hub) - [Enhance your code | dbt Developer Hub](#enhance-your-code-dbt-developer-hub) - [Integrate Cursor with dbt MCP | dbt Developer Hub](#integrate-cursor-with-dbt-mcp-dbt-developer-hub) - [dbt Administrative API | dbt Developer Hub](#dbt-administrative-api-dbt-developer-hub) - [Integrate VS Code with MCP | dbt Developer Hub](#integrate-vs-code-with-mcp-dbt-developer-hub) - [Integrate Claude with dbt MCP | dbt Developer Hub](#integrate-claude-with-dbt-mcp-dbt-developer-hub) - [Set up local MCP | dbt Developer Hub](#set-up-local-mcp-dbt-developer-hub) - [Set up remote MCP | dbt Developer Hub](#set-up-remote-mcp-dbt-developer-hub) - [dbt Model Context Protocol | dbt Developer Hub](#dbt-model-context-protocol-dbt-developer-hub) - [Authentication tokens | dbt Developer Hub](#authentication-tokens-dbt-developer-hub) - [Query the Discovery API | dbt Developer Hub](#query-the-discovery-api-dbt-developer-hub) - [About the Discovery API schema | dbt Developer Hub](#about-the-discovery-api-schema-dbt-developer-hub) - [Environment object schema | dbt Developer Hub](#environment-object-schema-dbt-developer-hub) - [Tags object schema | dbt Developer Hub](#tags-object-schema-dbt-developer-hub) - [Resources object schema | dbt Developer Hub](#resources-object-schema-dbt-developer-hub) - [Snapshots object schema | dbt Developer Hub](#snapshots-object-schema-dbt-developer-hub) - [Seeds object schema | dbt Developer Hub](#seeds-object-schema-dbt-developer-hub) - [Sources object schema | dbt Developer Hub](#sources-object-schema-dbt-developer-hub) - [Owners object schema | dbt Developer Hub](#owners-object-schema-dbt-developer-hub) - [What is dbt? | dbt Developer Hub](#what-is-dbt-dbt-developer-hub) - [Explore your data | dbt Developer Hub](#explore-your-data-dbt-developer-hub) - [dbt Semantic Layer | dbt Developer Hub](#dbt-semantic-layer-dbt-developer-hub) - [Frequently asked questions | dbt Developer Hub](#frequently-asked-questions-dbt-developer-hub) - [Deploy dbt | dbt Developer Hub](#deploy-dbt-dbt-developer-hub) - [Job scheduler | dbt Developer Hub](#job-scheduler-dbt-developer-hub) - [Build and view your docs with dbt | dbt Developer Hub](#build-and-view-your-docs-with-dbt-dbt-developer-hub) - [About dbt Insights | dbt Developer Hub](#about-dbt-insights-dbt-developer-hub) - [Continuous integration in dbt | dbt Developer Hub](#continuous-integration-in-dbt-dbt-developer-hub) - [docs-paths | dbt Developer Hub](#docs-paths-dbt-developer-hub) - [Python SDK | dbt Developer Hub](#python-sdk-dbt-developer-hub) - [GraphQL | dbt Developer Hub](#graphql-dbt-developer-hub) - [Advanced CI | dbt Developer Hub](#advanced-ci-dbt-developer-hub) - [dbt support | dbt Developer Hub](#dbt-support-dbt-developer-hub) - [Install Fusion | dbt Developer Hub](#install-fusion-dbt-developer-hub) - [Access the dbt Insights interface | dbt Developer Hub](#access-the-dbt-insights-interface-dbt-developer-hub) - [Source freshness | dbt Developer Hub](#source-freshness-dbt-developer-hub) - [Service account tokens | dbt Developer Hub](#service-account-tokens-dbt-developer-hub) - [Using threads | dbt Developer Hub](#using-threads-dbt-developer-hub) - [Model access | dbt Developer Hub](#model-access-dbt-developer-hub) - [About dbt Mesh | dbt Developer Hub](#about-dbt-mesh-dbt-developer-hub) - [About the dbt Fusion engine | dbt Developer Hub](#about-the-dbt-fusion-engine-dbt-developer-hub) - [dbt Product lifecycles | dbt Developer Hub](#dbt-product-lifecycles-dbt-developer-hub) - [Project dependencies | dbt Developer Hub](#project-dependencies-dbt-developer-hub) - [User tokens | dbt Developer Hub](#user-tokens-dbt-developer-hub) - [Consume metrics from your Semantic Layer | dbt Developer Hub](#consume-metrics-from-your-semantic-layer-dbt-developer-hub) - [dbt Quickstarts | dbt Developer Hub](#dbt-quickstarts-dbt-developer-hub) - [About environments | dbt Developer Hub](#about-environments-dbt-developer-hub) - [Model contracts | dbt Developer Hub](#model-contracts-dbt-developer-hub) - [APIs Overview | dbt Developer Hub](#apis-overview-dbt-developer-hub) - [Definition object schema | dbt Developer Hub](#definition-object-schema-dbt-developer-hub) - [Supported data platforms | dbt Developer Hub](#supported-data-platforms-dbt-developer-hub) - [Deployment environments | dbt Developer Hub](#deployment-environments-dbt-developer-hub) - [Release tracks in dbt platform | dbt Developer Hub](#release-tracks-in-dbt-platform-dbt-developer-hub) - [Install the dbt VS Code extension | dbt Developer Hub](#install-the-dbt-vs-code-extension-dbt-developer-hub) - [Run your dbt projects | dbt Developer Hub](#run-your-dbt-projects-dbt-developer-hub) - [dbt Semantic Layer FAQs | dbt Developer Hub](#dbt-semantic-layer-faqs-dbt-developer-hub) - [Semantic Layer APIs | dbt Developer Hub](#semantic-layer-apis-dbt-developer-hub) - [JDBC | dbt Developer Hub](#jdbc-dbt-developer-hub) - [Version upgrade guides | dbt Developer Hub](#version-upgrade-guides-dbt-developer-hub) - [Run visibility | dbt Developer Hub](#run-visibility-dbt-developer-hub) - [Webhooks for your jobs | dbt Developer Hub](#webhooks-for-your-jobs-dbt-developer-hub) - [Job notifications | dbt Developer Hub](#job-notifications-dbt-developer-hub) - [Administer the Semantic Layer | dbt Developer Hub](#administer-the-semantic-layer-dbt-developer-hub) - [Artifacts | dbt Developer Hub](#artifacts-dbt-developer-hub) - [Project state in dbt | dbt Developer Hub](#project-state-in-dbt-dbt-developer-hub) - [Tests object schema | dbt Developer Hub](#tests-object-schema-dbt-developer-hub) - [dbt environments | dbt Developer Hub](#dbt-environments-dbt-developer-hub) - [Jobs in the dbt platform | dbt Developer Hub](#jobs-in-the-dbt-platform-dbt-developer-hub) - [Use cases and examples for the Discovery API | dbt Developer Hub](#use-cases-and-examples-for-the-discovery-api-dbt-developer-hub) - [About installing Fusion | dbt Developer Hub](#about-installing-fusion-dbt-developer-hub) - [Continuous integration jobs in dbt | dbt Developer Hub](#continuous-integration-jobs-in-dbt-dbt-developer-hub) - [Deploy jobs | dbt Developer Hub](#deploy-jobs-dbt-developer-hub) - [External metadata ingestion | dbt Developer Hub](#external-metadata-ingestion-dbt-developer-hub) - [Data health tile | dbt Developer Hub](#data-health-tile-dbt-developer-hub) - [Upgrade dbt version in Cloud | dbt Developer Hub](#upgrade-dbt-version-in-cloud-dbt-developer-hub) - [About dbt Core versions | dbt Developer Hub](#about-dbt-core-versions-dbt-developer-hub) - [Discover data with Catalog | dbt Developer Hub](#discover-data-with-catalog-dbt-developer-hub) - [Job object schema | dbt Developer Hub](#job-object-schema-dbt-developer-hub) - [dbt release notes | dbt Developer Hub](#dbt-release-notes-dbt-developer-hub) - [Integrate with other orchestration tools | dbt Developer Hub](#integrate-with-other-orchestration-tools-dbt-developer-hub) - [Deploy your metrics | dbt Developer Hub](#deploy-your-metrics-dbt-developer-hub) - [dbt Semantic Layer architecture | dbt Developer Hub](#dbt-semantic-layer-architecture-dbt-developer-hub) - [Write queries with exports | dbt Developer Hub](#write-queries-with-exports-dbt-developer-hub) - [Cache common queries | dbt Developer Hub](#cache-common-queries-dbt-developer-hub) - [About state-aware orchestration | dbt Developer Hub](#about-state-aware-orchestration-dbt-developer-hub) - [Continuous deployment in dbt | dbt Developer Hub](#continuous-deployment-in-dbt-dbt-developer-hub) - [About continuous integration (CI) in dbt | dbt Developer Hub](#about-continuous-integration-ci-in-dbt-dbt-developer-hub) - [Monitor jobs and alerts | dbt Developer Hub](#monitor-jobs-and-alerts-dbt-developer-hub) - [About Hybrid projects | dbt Developer Hub](#about-hybrid-projects-dbt-developer-hub) - [Job commands | dbt Developer Hub](#job-commands-dbt-developer-hub) - [Visualize and orchestrate exposures | dbt Developer Hub](#visualize-and-orchestrate-exposures-dbt-developer-hub) - [Model notifications | dbt Developer Hub](#model-notifications-dbt-developer-hub) - [Retry your dbt jobs | dbt Developer Hub](#retry-your-dbt-jobs-dbt-developer-hub) - [Navigate the dbt Insights interface | dbt Developer Hub](#navigate-the-dbt-insights-interface-dbt-developer-hub) - [Model query history | dbt Developer Hub](#model-query-history-dbt-developer-hub) - [Merge jobs in dbt | dbt Developer Hub](#merge-jobs-in-dbt-dbt-developer-hub) - [New concepts in the dbt Fusion engine | dbt Developer Hub](#new-concepts-in-the-dbt-fusion-engine-dbt-developer-hub) - [Supported features | dbt Developer Hub](#supported-features-dbt-developer-hub) - [About model governance | dbt Developer Hub](#about-model-governance-dbt-developer-hub) - [Preview new and experimental features in the dbt platform | dbt Developer Hub](#preview-new-and-experimental-features-in-the-dbt-platform-dbt-developer-hub) - [Column-level lineage | dbt Developer Hub](#column-level-lineage-dbt-developer-hub) - [Access Catalog from dbt platform features | dbt Developer Hub](#access-catalog-from-dbt-platform-features-dbt-developer-hub) - [Model versions | dbt Developer Hub](#model-versions-dbt-developer-hub) - [Upgrading to the dbt Fusion engine (v2.0) | dbt Developer Hub](#upgrading-to-the-dbt-fusion-engine-v2-0-dbt-developer-hub) - [Data health signals | dbt Developer Hub](#data-health-signals-dbt-developer-hub) - [Explore multiple projects | dbt Developer Hub](#explore-multiple-projects-dbt-developer-hub) - [Changelog 2019 and 2020 | dbt Developer Hub](#changelog-2019-and-2020-dbt-developer-hub) - [Changelog 2021 | dbt Developer Hub](#changelog-2021-dbt-developer-hub) - [Hybrid setup | dbt Developer Hub](#hybrid-setup-dbt-developer-hub) - [Seeds object schema | dbt Developer Hub](#seeds-object-schema-dbt-developer-hub) - [Tests object schema | dbt Developer Hub](#tests-object-schema-dbt-developer-hub) - [dbt platform compatible track - changelog | dbt Developer Hub](#dbt-platform-compatible-track-changelog-dbt-developer-hub) - [Upgrading to v1.5 | dbt Developer Hub](#upgrading-to-v1-5-dbt-developer-hub) - [Global navigation | dbt Developer Hub](#global-navigation-dbt-developer-hub) - [Model performance | dbt Developer Hub](#model-performance-dbt-developer-hub) - [Setting up state-aware orchestration | dbt Developer Hub](#setting-up-state-aware-orchestration-dbt-developer-hub) - [Upgrading to v1.9 | dbt Developer Hub](#upgrading-to-v1-9-dbt-developer-hub) - [Install the dbt VS Code extension | dbt Developer Hub](#install-the-dbt-vs-code-extension-dbt-developer-hub) - [Upgrading to v1.1 | dbt Developer Hub](#upgrading-to-v1-1-dbt-developer-hub) - [Exposure object schema | dbt Developer Hub](#exposure-object-schema-dbt-developer-hub) - [Project recommendations | dbt Developer Hub](#project-recommendations-dbt-developer-hub) - [dbt Catalog FAQs | dbt Developer Hub](#dbt-catalog-faqs-dbt-developer-hub) - [Upgrading to v1.7 | dbt Developer Hub](#upgrading-to-v1-7-dbt-developer-hub) - [Upgrading to v1.10 | dbt Developer Hub](#upgrading-to-v1-10-dbt-developer-hub) - [Upgrading to v1.0 | dbt Developer Hub](#upgrading-to-v1-0-dbt-developer-hub) - [Test object schema | dbt Developer Hub](#test-object-schema-dbt-developer-hub) - [Snapshots object schema | dbt Developer Hub](#snapshots-object-schema-dbt-developer-hub) - [2022 dbt Cloud release notes | dbt Developer Hub](#2022-dbt-cloud-release-notes-dbt-developer-hub) - [Install Fusion from the CLI | dbt Developer Hub](#install-fusion-from-the-cli-dbt-developer-hub) - [Seed object schema | dbt Developer Hub](#seed-object-schema-dbt-developer-hub) - [Upgrading to v1.8 | dbt Developer Hub](#upgrading-to-v1-8-dbt-developer-hub) - [Upgrading to v1.2 | dbt Developer Hub](#upgrading-to-v1-2-dbt-developer-hub) - [Sources object schema | dbt Developer Hub](#sources-object-schema-dbt-developer-hub) - [Apache Iceberg Support | dbt Developer Hub](#apache-iceberg-support-dbt-developer-hub) - [Trusted adapters | dbt Developer Hub](#trusted-adapters-dbt-developer-hub) - [Model object schema | dbt Developer Hub](#model-object-schema-dbt-developer-hub) - [Upgrading to v1.4 | dbt Developer Hub](#upgrading-to-v1-4-dbt-developer-hub) - [Visualize downstream exposures | dbt Developer Hub](#visualize-downstream-exposures-dbt-developer-hub) - [Upgrading to v1.3 | dbt Developer Hub](#upgrading-to-v1-3-dbt-developer-hub) - [Models object schema | dbt Developer Hub](#models-object-schema-dbt-developer-hub) - [Source object schema | dbt Developer Hub](#source-object-schema-dbt-developer-hub) - [Upgrading to v1.6 | dbt Developer Hub](#upgrading-to-v1-6-dbt-developer-hub) - [Exposures object schema | dbt Developer Hub](#exposures-object-schema-dbt-developer-hub) - [2023 dbt Cloud release notes | dbt Developer Hub](#2023-dbt-cloud-release-notes-dbt-developer-hub) - [2024 dbt Cloud release notes | dbt Developer Hub](#2024-dbt-cloud-release-notes-dbt-developer-hub) - [About Iceberg catalogs | dbt Developer Hub](#about-iceberg-catalogs-dbt-developer-hub) - [BigQuery and Apache Iceberg | dbt Developer Hub](#bigquery-and-apache-iceberg-dbt-developer-hub) - [Snowflake and Apache Iceberg | dbt Developer Hub](#snowflake-and-apache-iceberg-dbt-developer-hub) - [Upgrading to dbt utils v1.0 | dbt Developer Hub](#upgrading-to-dbt-utils-v1-0-dbt-developer-hub) - [docs | dbt Developer Hub](#docs-dbt-developer-hub) --- # About the dbt VS Code extension | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/about-dbt-extension#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page The dbt extension brings a hyper-fast, intelligent, and cost-efficient dbt development experience to VS Code. This is the only way to enjoy all the power of the new dbt Fusion engine while developing locally. _Save time and resources_ with near-instant parsing, live error detection, powerful IntelliSense capabilities, and more. _Stay in flow_ with a seamless, end-to-end dbt development experience designed from scratch for local dbt development. _This is a public beta release. Behavior may change ahead of the broader generally available (GA) release._ Productivity features[​](https://docs.getdbt.com/docs/about-dbt-extension#productivity-features "Direct link to Productivity features") ---------------------------------------------------------------------------------------------------------------------------------------- The following extension features help you get more done, fast: * **[Live error detection](https://docs.getdbt.com/docs/about-dbt-extension#live-error-detection) :** Automatically validate your SQL code to detect errors and surface warnings, without hitting the warehouse. This includes both dbt errors (like invalid `ref`) and SQL errors (like invalid column name or SQL syntax). * **[Lightning-fast parse times](https://docs.getdbt.com/docs/about-dbt-extension#lightning-fast-parse-times) :** Parse even the largest projects up to 30x faster than dbt Core. * **[Powerful IntelliSense](https://docs.getdbt.com/docs/about-dbt-extension#powerful-intellisense) :** Autocomplete SQL functions, model names, columns, macros, and more. * **[Instant refactoring](https://docs.getdbt.com/docs/about-dbt-extension#instant-refactoring) :** Rename models or columns and see references update project-wide. * **[Go-to-definition](https://docs.getdbt.com/docs/about-dbt-extension#go-to-definition-and-reference) :** Jump to the definition of any `ref`, macro, model, or column with a single click. Particularly useful in large projects with many models and macros. * **[Hover insights](https://docs.getdbt.com/docs/about-dbt-extension#hover-insights) :** See context on tables, columns, and functions without leaving your code. Simply hover over any SQL element to see details like column names and data types. * **[Live CTE previews](https://docs.getdbt.com/docs/about-dbt-extension#live-preview-for-models-and-ctes) :** Preview a CTE’s output directly from inside your dbt model for faster validation and debugging. * **[Rich lineage in context](https://docs.getdbt.com/docs/about-dbt-extension#rich-lineage-in-context) :** See lineage at the column or table level as you develop with no context switching or breaking the flow. * **[View compiled code](https://docs.getdbt.com/docs/about-dbt-extension#view-compiled-code) :** Get a live view of the SQL code your models will build alongside your dbt code. * **[Build flexibly](https://docs.getdbt.com/docs/about-dbt-extension#build-flexibly) :** Use the command palette to build models with complex selectors. ### Live error detection[​](https://docs.getdbt.com/docs/about-dbt-extension#live-error-detection "Direct link to Live error detection") Automatically validate your SQL code to detect errors and surface warnings without hitting the warehouse. * Displays diagnostics (red squiggles) for: * Syntax errors (missing commas, misspelled keywords, etc). * Invalid / missing column names (for example, `select not_a_column from {{ ref('real_model') }}`). * Missing `group by` clauses, or columns that are neither grouped nor aggregated. * Invalid function names or arguments * Hover over red squiggles to display errors. * Full diagnostic information is available in the “Problems”. ### Lightning-fast parse times[​](https://docs.getdbt.com/docs/about-dbt-extension#lightning-fast-parse-times "Direct link to Lightning-fast parse times") Parse even the largest projects up to 30x faster than with dbt Core. ### Powerful IntelliSense[​](https://docs.getdbt.com/docs/about-dbt-extension#powerful-intellisense "Direct link to Powerful IntelliSense") Autocomplete SQL functions, model names, columns, macros and more. Usage: * Autocomplete `ref`s and `source` calls. For example, type `{{ ref(` or `{{ source(` and you will see a list of available resources and their type complete the function call. * Autocomplete dialect-specific function names. ### Instant refactoring[​](https://docs.getdbt.com/docs/about-dbt-extension#instant-refactoring "Direct link to Instant refactoring") Renaming models: * Right-click on a file in the file tree and select **Rename**. * After renaming the file, you'll get a prompt asking if you want to make refactoring changes. * Select **OK** to apply the changes, or **Show Preview** to display a preview of refactorings. * After applying your changes, `ref`s should be updated to use the updated model name. Renaming columns: * Right-click on a column alias and select **Rename Symbol**. * After renaming the column, you'll get a prompt asking if you want to make refactoring changes. * Select **OK** to apply the changes, or **Show Preview** to show a preview of refactorings. * After applying your changes, downstream references to the column should be updated to use the new column name. Note: Renaming models and columns is not yet supported for snapshots, or any resources defined in a .yml file. ### Go-to-definition and reference[​](https://docs.getdbt.com/docs/about-dbt-extension#go-to-definition-and-reference "Direct link to Go-to-definition and reference") Jump to the definition of any `ref`, macro, model, or column with a single click. Particularly useful in large projects with many models and macros. Usage: * Command or Ctrl-click to go to the definition for an identifier. * You can also right-click an identifier or and select **Go to Definition** or **Go to References**. * Supports CTE names, column names, `*`, macro names, and dbt `ref()` and `source()` call. ### Hover insights[​](https://docs.getdbt.com/docs/about-dbt-extension#hover-insights "Direct link to Hover insights") See context on tables, columns, and functions without leaving your code. Simply hover over any SQL element to see details like column names and data types. Usage: * Hover over `*` to see expanded list of columns and their types. * Hover over column name or alias to see its type. ### Live preview for models and CTEs[​](https://docs.getdbt.com/docs/about-dbt-extension#live-preview-for-models-and-ctes "Direct link to Live preview for models and CTEs") Preview a CTE’s output, or an entire model, directly from inside your editor for faster validation and debugging. Usage: * Click the **table icon** or use keyboard shortcut `cmd+enter` (macOS) / `ctrl+enter` (Linux) to preview query results. * Click the **Preview CTE** codelens to preview CTE results. * Results will be displayed in the **Query Results** tab in the bottom panel. * The preview table is sortable and results are stored until the tab is closed. * You can also select a range of SQL to preview the results of a specific SQL snippet. ### Rich lineage in context[​](https://docs.getdbt.com/docs/about-dbt-extension#rich-lineage-in-context "Direct link to Rich lineage in context") See lineage at the column or table level as you develop — no context switching or breaking flow. View table lineage: * Open the **Lineage** tab in your editor. It will reflect table lineage focused on the currently-open file. * Double-click nodes to open the files in your editor. * The lineage pane updates as you navigate the files in your dbt project. * Right-click on a node to update the DAG, or view column lineage for a node. View column lineage: * Right-click on a filename, or in the SQL contents of a model file. * Select **dbt: View Lineage** --> **Show column lineage**. * Select the column to view lineage for. * Double-click on a node to update the DAG selector. * You can also use column selectors in the lineage window by adding the `column:` prefix and appending the column name. * For example, if you want the lineage for the `AMOUNT` column of your `stg_payments` model, edit the `+model.jaffle_shop.stg_payments+` to `+column:model.jaffle_shop.stg_payments.AMOUNT+`. ### View compiled code[​](https://docs.getdbt.com/docs/about-dbt-extension#view-compiled-code "Direct link to View compiled code") Get a live view of the SQL code your models will build — right alongside your dbt code. Usage: * Click the **code icon** to view compiled code side-by-side with source code. * Compiled code will update as you save your source code. * Clicking on a dbt macro will focus the corresponding compiled code. * Clicking on a compiled code block will focus the corresponding source code. ### Build flexibly[​](https://docs.getdbt.com/docs/about-dbt-extension#build-flexibly "Direct link to Build flexibly") Use the command palette to quickly build models using complex selectors. Usage: * Click the **dbt icon** or use keyboard shortcut `cmd+shift+enter` (macOS) / `ctrl+shift+enter` (Linux) to launch a quickpick menu. * Select a command to run. Using the extension[​](https://docs.getdbt.com/docs/about-dbt-extension#using-the-extension "Direct link to Using the extension") ---------------------------------------------------------------------------------------------------------------------------------- Your dbt environment must be using the dbt Fusion engine in order to use this extension. See [the Fusion documentation](https://docs.getdbt.com/docs/fusion/about-fusion) for more on eligibility and upgrading. Once installed, the dbt extension automatically activates when you open any `.sql` or `.yml` file inside of a dbt project directory. Configuration[​](https://docs.getdbt.com/docs/about-dbt-extension#configuration "Direct link to Configuration") ---------------------------------------------------------------------------------------------------------------- After installation, you may want to configure the extension to better fit your development workflow: 1. Open the VS Code settings by pressing `Ctrl+,` (Linux) or `Cmd+,` (Mac). 2. Search for `dbt`. On this page, you can adjust the extension’s configuration options as to fit your needs. Known limitations[​](https://docs.getdbt.com/docs/about-dbt-extension#known-limitations "Direct link to Known limitations") ---------------------------------------------------------------------------------------------------------------------------- The following are currently known limitations of the dbt extension: * **Remote development:** The dbt extension does not yet support remote development sessions over SSH. Support will be added in a future release. For more information on remote development, refer to [Supporting Remote Development and GitHub Codespaces](https://code.visualstudio.com/api/advanced-topics/remote-extensions) and [Visual Studio Code Server](https://code.visualstudio.com/docs/remote/vscode-server) . * **Working with YAML files:** Today, the dbt extension has the following limitations with operating on YAML files: * Go-to-definition is not supported for nodes defined in YAML files (like snapshots). * Renaming models and columns will not update references in YAML files. * Future releases of the dbt extension will address these limitations * **Renaming models:** When a model file is renamed, the dbt extension will apply edits to update all `ref()` calls that reference the renamed model. Due to limitations of VS Code's Language Server Client, we are not able to auto-save these edit files. As a result, you may see that renaming a model file results in compiler errors in your project. To fix these errors, you must either manually save each file that was edited by the dbt extension, or click **File** --> **Save All** to save all edited files. Support[​](https://docs.getdbt.com/docs/about-dbt-extension#support "Direct link to Support") ---------------------------------------------------------------------------------------------- dbt platform customers can contact dbt Labs support at [support@getdbt.com](mailto:support@getdbt.com) . You can also get in touch with us by reaching out to your Account Manager directly. For organizations that are not customers of the dbt platform, the best place for questions and discussion is the [dbt Community Slack](https://www.getdbt.com/community/join-the-community) . We welcome feedback as we work to continuously improve the extension, and would love to hear from you! For more information regarding support and acceptable use of the dbt VS Code extension, refer to our [Acceptable Use Policy](https://www.getdbt.com/dbt-assets/vscode-plugin-aup) . More information about Fusion[​](https://docs.getdbt.com/docs/about-dbt-extension#more-information-about-fusion "Direct link to More information about Fusion") ---------------------------------------------------------------------------------------------------------------------------------------------------------------- Fusion marks a significant update to dbt. While many of the workflows you've grown accustomed to remain unchanged, there are a lot of new ideas, and a lot of old ones going away. The following is a list of the full scope of our current release of the Fusion engine, including implementation, installation, deprecations, and limitations: * [About the dbt Fusion engine](https://docs.getdbt.com/docs/fusion/about-fusion) * [About the dbt extension](https://docs.getdbt.com/docs/about-dbt-extension) * [New concepts in Fusion](https://docs.getdbt.com/docs/fusion/new-concepts) * [Supported features matrix](https://docs.getdbt.com/docs/fusion/supported-features) * [Installing Fusion CLI](https://docs.getdbt.com/docs/fusion/install-fusion) * [Installing VS Code extension](https://docs.getdbt.com/docs/install-dbt-extension) * [Fusion release track](https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-version-in-cloud#dbt-fusion-engine) * [Quickstart for Fusion](https://docs.getdbt.com/guides/fusion?step=1) * [Upgrade guide](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-fusion) * [Fusion licensing](http://www.getdbt.com/licenses-faq) Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Productivity features](https://docs.getdbt.com/docs/about-dbt-extension#productivity-features) * [Live error detection](https://docs.getdbt.com/docs/about-dbt-extension#live-error-detection) * [Lightning-fast parse times](https://docs.getdbt.com/docs/about-dbt-extension#lightning-fast-parse-times) * [Powerful IntelliSense](https://docs.getdbt.com/docs/about-dbt-extension#powerful-intellisense) * [Instant refactoring](https://docs.getdbt.com/docs/about-dbt-extension#instant-refactoring) * [Go-to-definition and reference](https://docs.getdbt.com/docs/about-dbt-extension#go-to-definition-and-reference) * [Hover insights](https://docs.getdbt.com/docs/about-dbt-extension#hover-insights) * [Live preview for models and CTEs](https://docs.getdbt.com/docs/about-dbt-extension#live-preview-for-models-and-ctes) * [Rich lineage in context](https://docs.getdbt.com/docs/about-dbt-extension#rich-lineage-in-context) * [View compiled code](https://docs.getdbt.com/docs/about-dbt-extension#view-compiled-code) * [Build flexibly](https://docs.getdbt.com/docs/about-dbt-extension#build-flexibly) * [Using the extension](https://docs.getdbt.com/docs/about-dbt-extension#using-the-extension) * [Configuration](https://docs.getdbt.com/docs/about-dbt-extension#configuration) * [Known limitations](https://docs.getdbt.com/docs/about-dbt-extension#known-limitations) * [Support](https://docs.getdbt.com/docs/about-dbt-extension#support) * [More information about Fusion](https://docs.getdbt.com/docs/about-dbt-extension#more-information-about-fusion) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/about-dbt-extension.md) --- # About dbt setup | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/about-setup#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) dbt compiles and runs your analytics code against your data platform, enabling you and your team to collaborate on a single source of truth for metrics, insights, and business definitions. There are two options for deploying dbt: * **dbt** runs the dbt Fusion Engine or dbt Core in a hosted (single or multi-tenant) environment with a browser-based interface. The intuitive user interface aids you in setting up the various components. dbt comes equipped with turnkey support for scheduling jobs, CI/CD, hosting documentation, monitoring, and alerting. It also offers an integrated development environment (Studio IDE) and allows you to develop and run dbt commands from your local command line (CLI) or code editor. * **dbt Core** is an open-source command line tool that you can install locally in your environment, and communication with databases is facilitated through adapters. If you're not sure which is the right solution for you, read our [What is dbt?](https://docs.getdbt.com/docs/introduction) and our [dbt features](https://docs.getdbt.com/docs/cloud/about-cloud/dbt-cloud-features) articles to help you decide. If you still have questions, don't hesitate to [contact us](https://www.getdbt.com/contact/) . To begin configuring dbt now, select the option that is right for you. [![](https://docs.getdbt.com/img/icons/dbt-bit.svg)\ \ #### dbt platform setup\ \ Learn how to connect to a data platform, integrate with secure authentication methods, and configure a sync with a git repo.](https://docs.getdbt.com/docs/cloud/about-cloud-setup) [![](https://docs.getdbt.com/img/icons/dbt-bit.svg)\ \ #### dbt local setup\ \ Learn how to set up dbt locally using the dbt VS Code extension or CLI.](https://docs.getdbt.com/docs/about-dbt-install) Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 --- # About dbt installation | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/about-dbt-install#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) dbt enables data teams to transform data using analytics engineering best practices. Choose your local development experience from these tools: * Local command line interface (CLI) tools leveraging the speed and scale of the dbt Fusion Engine or using our legacy Core product * VS Code or Cursor with the dbt extension If you're interested in using the dbt platform, our feature-rich, browser-based UI, you can learn more in [About dbt set up](https://docs.getdbt.com/docs/cloud/about-cloud-setup) . After choosing and installing your local development experience, you can get started: * Explore a detailed first-time setup guide for [dbt Fusion engine](https://docs.getdbt.com/guides/fusion?step=1) . * [Connect to a data platform](https://docs.getdbt.com/docs/core/connect-data-platform/about-core-connections) . * Learn [how to run your dbt projects](https://docs.getdbt.com/docs/running-a-dbt-project/run-your-dbt-projects) . Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 --- # About MetricFlow | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/build/about-metricflow#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page This guide introduces MetricFlow's fundamental ideas for people new to this feature. MetricFlow, which powers the Semantic Layer, helps you define and manage the logic for your company's metrics. It's an opinionated set of abstractions and helps data consumers retrieve metric datasets from a data platform quickly and efficiently. MetricFlow handles SQL query construction and defines the specification for dbt semantic models and metrics. It allows you to define metrics in your dbt project and query them with [MetricFlow commands](https://docs.getdbt.com/docs/build/metricflow-commands) whether in dbt or dbt Core. Before you start, consider the following guidelines: * Define metrics in YAML and query them using these [new metric specifications](https://github.com/dbt-labs/dbt-core/discussions/7456) . * You must be on [dbt version](https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-version-in-cloud) 1.6 or higher to use MetricFlow. * Use MetricFlow with Snowflake, BigQuery, Databricks, Postgres (dbt Core only), or Redshift. * Discover insights and query your metrics using the [Semantic Layer](https://docs.getdbt.com/docs/use-dbt-semantic-layer/dbt-sl) and its diverse range of [available integrations](https://docs.getdbt.com/docs/cloud-integrations/avail-sl-integrations) . MetricFlow[​](https://docs.getdbt.com/docs/build/about-metricflow#metricflow "Direct link to MetricFlow") ---------------------------------------------------------------------------------------------------------- MetricFlow is a SQL query generation tool designed to streamline metric creation across different data dimensions for diverse business needs. * It operates through YAML files, where a semantic graph links language to data. This graph comprises [semantic models](https://docs.getdbt.com/docs/build/semantic-models) (data entry points) and [metrics](https://docs.getdbt.com/docs/build/metrics-overview) (functions for creating quantitative indicators). * MetricFlow is a [BSL package](https://github.com/dbt-labs/metricflow) with code source available, and compatible with dbt version 1.6 and higher. Data practitioners and enthusiasts are highly encouraged to contribute. * As a part of the Semantic Layer, MetricFlow empowers organizations to define metrics using YAML abstractions. * To query metric dimensions, dimension values, and validate configurations, use [MetricFlow commands](https://docs.getdbt.com/docs/build/metricflow-commands) . **Note** — MetricFlow doesn't support dbt [builtin functions or packages](https://docs.getdbt.com/reference/dbt-jinja-functions/builtins) at this time, however, support is planned for the future. MetricFlow abides by these principles: * **Flexibility with completeness**: Define metric logic using flexible abstractions on any data model. * **DRY (Don't Repeat Yourself)**: Minimize redundancy by enabling metric definitions whenever possible. * **Simplicity with gradual complexity:** Approach MetricFlow using familiar data modeling concepts. * **Performance and efficiency**: Optimize performance while supporting centralized data engineering and distributed logic ownership. ### Semantic graph[​](https://docs.getdbt.com/docs/build/about-metricflow#semantic-graph "Direct link to Semantic graph") We're introducing a new concept: a "semantic graph". It's the relationship between semantic models and YAML configurations that creates a data landscape for building metrics. You can think of it like a map, where tables are like locations, and the connections between them (edges) are like roads. Although it's under the hood, the semantic graph is a subset of the DAG, and you can see the semantic models as nodes on the DAG. The semantic graph helps us decide which information is available to use for consumption and which is not. The connections between tables in the semantic graph are more about relationships between the information. This is different from the DAG, where the connections show dependencies between tasks. When MetricFlow generates a metric, it uses its SQL engine to figure out the best path between tables using the framework defined in YAML files for semantic models and metrics. When these models and metrics are correctly defined, they can be used downstream with Semantic Layer's integrations. ### Semantic models[​](https://docs.getdbt.com/docs/build/about-metricflow#semantic-models "Direct link to Semantic models") Semantic models are the starting points of data and correspond to models in your dbt project. You can create multiple semantic models from each model. Semantic models have metadata, like a data table, that define important information such as the table name and primary keys for the graph to be navigated correctly. For a semantic model, there are three main pieces of metadata: * [Entities](https://docs.getdbt.com/docs/build/entities) — The join keys of your semantic model (think of these as the traversal paths, or edges between semantic models). * [Dimensions](https://docs.getdbt.com/docs/build/dimensions) — These are the ways you want to group or slice/dice your metrics. * [Measures](https://docs.getdbt.com/docs/build/measures) — The aggregation functions that give you a numeric result and can be used to create your metrics. [![A semantic model is made up of different components: Entities, Measures, and Dimensions.](https://docs.getdbt.com/img/docs/dbt-cloud/semantic-layer/semantic_foundation.jpg?v=2 "A semantic model is made up of different components: Entities, Measures, and Dimensions.")](https://docs.getdbt.com/docs/build/about-metricflow#) A semantic model is made up of different components: Entities, Measures, and Dimensions. ### Metrics[​](https://docs.getdbt.com/docs/build/about-metricflow#metrics "Direct link to Metrics") Metrics, which is a key concept, are functions that combine measures, constraints, or other mathematical functions to define new quantitative indicators. MetricFlow uses measures and various aggregation types, such as average, sum, and count distinct, to create metrics. Dimensions add context to metrics and without them, a metric is simply a number for all time. You can define metrics in the same YAML files as your semantic models, or create a new file. MetricFlow supports different metric types: * [Conversion](https://docs.getdbt.com/docs/build/conversion) — Helps you track when a base event and a subsequent conversion event occurs for an entity within a set time period. * [Cumulative](https://docs.getdbt.com/docs/build/cumulative) — Aggregates a measure over a given window. * [Derived](https://docs.getdbt.com/docs/build/derived) — An expression of other metrics, which allows you to do calculations on top of metrics. * [Ratio](https://docs.getdbt.com/docs/build/ratio) — Create a ratio out of two measures, like revenue per customer. * [Simple](https://docs.getdbt.com/docs/build/simple) — Metrics that refer directly to one measure. Use case[​](https://docs.getdbt.com/docs/build/about-metricflow#use-case "Direct link to Use case") ---------------------------------------------------------------------------------------------------- In the upcoming sections, we'll show how data practitioners currently calculate metrics and compare it to how MetricFlow makes defining metrics easier and more flexible. The following example data is based on the Jaffle Shop repo. You can view the complete [dbt project](https://github.com/dbt-labs/jaffle-sl-template) . The tables we're using in our example model are: * `orders` is a production data platform export that has been cleaned up and organized for analytical consumption * `customers` is a partially denormalized table in this case with a column derived from the orders table through some upstream process To make this more concrete, consider the metric `order_total`, which is defined using the SQL expression: `select sum(order_total) as order_total from orders` This expression calculates the total revenue for all orders by summing the order\_total column in the orders table. In a business setting, the metric order\_total is often calculated according to different categories, such as" * Time, for example `date_trunc(ordered_at, 'day')` * Order Type, using `is_food_order` dimension from the `orders` table. ### Calculate metrics[​](https://docs.getdbt.com/docs/build/about-metricflow#calculate-metrics "Direct link to Calculate metrics") Next, we'll compare how data practitioners currently calculate metrics with multiple queries versus how MetricFlow simplifies and streamlines the process. * Calculate with multiple queries * Calculate with MetricFlow The following example displays how data practitioners typically would calculate the `order_total` metric aggregated. It's also likely that analysts are asked for more details on a metric, like how much revenue came from new customers. Using the following query creates a situation where multiple analysts working on the same data, each using their own query method — this can lead to confusion, inconsistencies, and a headache for data management. select date_trunc('day',orders.ordered_at) as day, case when customers.first_ordered_at is not null then true else false end as is_new_customer, sum(orders.order_total) as order_totalfrom ordersleft join customerson orders.customer_id = customers.customer_idgroup by 1, 2 In the following three example tabs, use MetricFlow to define a semantic model that uses order\_total as a metric and a sample schema to create consistent and accurate results — eliminating confusion, code duplication, and streamlining your workflow. * Revenue example * More dimensions example * Advanced example In this example, a measure named `order_total` is defined based on the order\_total column in the `orders` table. The time dimension `metric_time` provides daily granularity and can be aggregated into weekly or monthly time periods. Additionally, a categorical dimension called `is_new_customer` is specified in the `customers` semantic model. semantic_models: - name: orders # The name of the semantic model description: | A model containing order data. The grain of the table is the order id. model: ref('orders') #The name of the dbt model and schema defaults: agg_time_dimension: metric_time entities: # Entities, which usually correspond to keys in the table. - name: order_id type: primary - name: customer type: foreign expr: customer_id measures: # Measures, which are the aggregations on the columns in the table. - name: order_total agg: sum dimensions: # Dimensions are either categorical or time. They add additional context to metrics and the typical querying pattern is Metric by Dimension. - name: metric_time expr: cast(ordered_at as date) type: time type_params: time_granularity: day - name: customers # The name of the second semantic model description: > Customer dimension table. The grain of the table is one row per customer. model: ref('customers') #The name of the dbt model and schema defaults: agg_time_dimension: first_ordered_at entities: # Entities, which usually correspond to keys in the table. - name: customer type: primary expr: customer_id dimensions: # Dimensions are either categorical or time. They add additional context to metrics and the typical querying pattern is Metric by Dimension. - name: is_new_customer type: categorical expr: case when first_ordered_at is not null then true else false end - name: first_ordered_at type: time type_params: time_granularity: day Similarly, you could then add additional dimensions like `is_food_order` to your semantic models to incorporate even more dimensions to slice and dice your revenue order\_total. semantic_models: - name: orders description: | A model containing order data. The grain of the table is the order id. model: ref('orders') #The name of the dbt model and schema defaults: agg_time_dimension: metric_time entities: # Entities, which usually correspond to keys in the table - name: order_id type: primary - name: customer type: foreign expr: customer_id measures: # Measures, which are the aggregations on the columns in the table. - name: order_total agg: sum dimensions: # Dimensions are either categorical or time. They add additional context to metrics and the typical querying pattern is Metric by Dimension. - name: metric_time expr: cast(ordered_at as date) type: time type_params: time_granularity: day - name: is_food_order type: categorical Imagine an even more complex metric is needed, like the amount of money earned each day from food orders from returning customers. Without MetricFlow the data practitioner's original SQL might look like this: select date_trunc('day',orders.ordered_at) as day, sum(case when is_food_order = true then order_total else null end) as food_order, sum(orders.order_total) as sum_order_total, food_order/sum_order_totalfrom ordersleft join customerson orders.customer_id = customers.customer_idwhere case when customers.first_ordered_at is not null then true else false end = truegroup by 1 MetricFlow simplifies the SQL process via metric YAML configurations as seen below. You can also commit them to your git repository to ensure everyone on the data and business teams can see and approve them as the true and only source of information. metrics: - name: food_order_pct_of_order_total_returning description: Revenue from food orders from returning customers label: "Food % of Order Total" type: ratio type_params: numerator: food_order denominator: order_total filter: | {{ Dimension('customer__is_new_customer') }} = false FAQs[​](https://docs.getdbt.com/docs/build/about-metricflow#faqs "Direct link to FAQs") ----------------------------------------------------------------------------------------  Do my datasets need to be normalized? Not at all! While a cleaned and well-modeled data set can be extraordinarily powerful and is the ideal input, you can use any dataset from raw to fully denormalized datasets. It's recommended that you apply quality data consistency, such as filtering bad data, normalizing common objects, and data modeling of keys and tables, in upstream applications. The Semantic Layer is more efficient at doing data denormalization instead of normalization. If you have not invested in data consistency, that is okay. The Semantic Layer can take SQL queries or expressions to define consistent datasets.  Why is normalized data the ideal input? MetricFlow is built to do denormalization efficiently. There are better tools to take raw datasets and accomplish the various tasks required to build data consistency and organized data models. On the other end, by putting in denormalized data you are potentially creating redundancy which is technically challenging to manage, and you are reducing the potential granularity that MetricFlow can use to aggregate metrics.  Why not just make metrics the same as measures? One principle of MetricFlow is to reduce the duplication of logic sometimes referred to as Don't Repeat Yourself(DRY). Many metrics are constructed from reused measures and in some cases constructed from measures from different semantic models. This allows for metrics to be built breadth-first (metrics that can stand alone) instead of depth-first (where you have multiple metrics acting as functions of each other). Additionally, not all metrics are constructed off of measures. As an example, a conversion metric is likely defined as the presence or absence of an event record after some other event record.  How does the dbt Semantic Layer handle joins? The dbt Semantic Layer, powered by MetricFlow, builds joins based on the types of keys and parameters that are passed to entities. To better understand how joins are constructed see our documentation on join types. Rather than capturing arbitrary join logic, MetricFlow captures the types of each identifier and then helps the user to navigate to appropriate joins. This allows us to avoid the construction of fan out and chasm joins as well as generate legible SQL.  Are entities and join keys the same thing? If it helps you to think of entities as join keys, that is very reasonable. Entities in MetricFlow have applications beyond joining two tables, such as acting as a dimension.  Can a table without a primary or unique entities have dimensions? Yes, but because a dimension is considered an attribute of the primary or unique ent of the table, they are only usable by the metrics that are defined in that table. They cannot be joined to metrics from other tables. This is common in event logs. Related docs[​](https://docs.getdbt.com/docs/build/about-metricflow#related-docs "Direct link to Related docs") ---------------------------------------------------------------------------------------------------------------- * [Joins](https://docs.getdbt.com/docs/build/join-logic) * [Validations](https://docs.getdbt.com/docs/build/validation) Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [MetricFlow](https://docs.getdbt.com/docs/build/about-metricflow#metricflow) * [Semantic graph](https://docs.getdbt.com/docs/build/about-metricflow#semantic-graph) * [Semantic models](https://docs.getdbt.com/docs/build/about-metricflow#semantic-models) * [Metrics](https://docs.getdbt.com/docs/build/about-metricflow#metrics) * [Use case](https://docs.getdbt.com/docs/build/about-metricflow#use-case) * [Calculate metrics](https://docs.getdbt.com/docs/build/about-metricflow#calculate-metrics) * [FAQs](https://docs.getdbt.com/docs/build/about-metricflow#faqs) * [Related docs](https://docs.getdbt.com/docs/build/about-metricflow#related-docs) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/build/about-metricflow.md) --- # Advanced data modeling | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/build/advanced-topics#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) The Semantic Layer and MetricFlow are powerful tools that allow you to define metrics and semantic models in your dbt project. This section covers advanced topics for the Semantic Layer and MetricFlow, such as data modeling workflows, and more. [![](https://docs.getdbt.com/img/icons/dbt-bit.svg)\ \ #### Fill null values for metrics\ \ Use `fill_nulls_with` to set null metric values to zero, ensuring numeric values for every data row.](https://docs.getdbt.com/docs/build/fill-nulls-advanced) [![](https://docs.getdbt.com/img/icons/dbt-bit.svg)\ \ #### Metrics as dimensions with metric filters\ \ Add metrics as dimensions to your metric filters to create more complex metrics and gain more insights.](https://docs.getdbt.com/docs/build/ref-metrics-in-filters) Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 --- # Analyses | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/build/analyses#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page Overview[​](https://docs.getdbt.com/docs/build/analyses#overview "Direct link to Overview") -------------------------------------------------------------------------------------------- dbt's notion of `models` makes it easy for data teams to version control and collaborate on data transformations. Sometimes though, a certain SQL statement doesn't quite fit into the mold of a dbt model. These more "analytical" SQL files can be versioned inside of your dbt project using the `analysis` functionality of dbt. Any `.sql` files found in the `analyses/` directory of a dbt project will be compiled, but not executed. This means that analysts can use dbt functionality like `{{ ref(...) }}` to select from models in an environment-agnostic way. In practice, an analysis file might look like this (via the [open source Quickbooks models](https://github.com/dbt-labs/quickbooks) ): analyses/running\_total\_by\_account.sql -- analyses/running_total_by_account.sqlwith journal_entries as ( select * from {{ ref('quickbooks_adjusted_journal_entries') }}), accounts as ( select * from {{ ref('quickbooks_accounts_transformed') }})select txn_date, account_id, adjusted_amount, description, account_name, sum(adjusted_amount) over (partition by account_id order by id rows unbounded preceding)from journal_entriesorder by account_id, id To compile this analysis into runnable sql, run: dbt compile Then, look for the compiled SQL file in `target/compiled/{project name}/analyses/running_total_by_account.sql`. This SQL can then be pasted into a data visualization tool, for instance. Note that no `running_total_by_account` relation will be materialized in the database as this is an `analysis`, not a `model`. Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Overview](https://docs.getdbt.com/docs/build/analyses#overview) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/build/analyses.md) --- # Build your metrics | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/build/build-metrics-intro#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) Use MetricFlow in dbt to centrally define your metrics. As a key component of the [Semantic Layer](https://docs.getdbt.com/docs/use-dbt-semantic-layer/dbt-sl) , MetricFlow is responsible for SQL query construction and defining specifications for dbt semantic models and metrics. It uses familiar constructs like semantic models and metrics to avoid duplicative coding, optimize your development workflow, ensure data governance for company metrics, and guarantee consistency for data consumers. [![This diagram shows how the dbt Semantic Layer works with your data stack.](https://docs.getdbt.com/img/docs/dbt-cloud/semantic-layer/sl-concept.png?v=2 "This diagram shows how the dbt Semantic Layer works with your data stack.")](https://docs.getdbt.com/docs/build/build-metrics-intro#) This diagram shows how the dbt Semantic Layer works with your data stack. MetricFlow allows you to: * Intuitively define metrics in your dbt project * Develop from your preferred environment, whether that's the [dbt CLI](https://docs.getdbt.com/docs/cloud/cloud-cli-installation) , [Studio IDE](https://docs.getdbt.com/docs/cloud/dbt-cloud-ide/develop-in-the-cloud) , or [dbt Core](https://docs.getdbt.com/docs/core/installation-overview) * Use [MetricFlow commands](https://docs.getdbt.com/docs/build/metricflow-commands) to query and test those metrics in your development environment * Harness the true magic of the universal Semantic Layer and dynamically query these metrics in downstream tools (Available for dbt [Starter, Enterprise, or Enterprise+](https://www.getdbt.com/pricing/) accounts only). [![](https://docs.getdbt.com/img/icons/dbt-bit.svg)\ \ #### Quickstart for the dbt Semantic Layer\ \ Use this guide to build and define metrics, set up the dbt Semantic Layer, and query them using downstream tools.](https://docs.getdbt.com/guides/sl-snowflake-qs) [![](https://docs.getdbt.com/img/icons/dbt-bit.svg)\ \ #### About MetricFlow\ \ Understand MetricFlow's core concepts, how to use joins, how to save commonly used queries, and what commands are available.](https://docs.getdbt.com/docs/build/about-metricflow) [![](https://docs.getdbt.com/img/icons/dbt-bit.svg)\ \ #### Semantic model\ \ Use semantic models as the basis for defining data. They act as nodes in the semantic graph, with entities connecting them.](https://docs.getdbt.com/docs/build/semantic-models) [![](https://docs.getdbt.com/img/icons/dbt-bit.svg)\ \ #### Metrics\ \ Define metrics through the powerful combination of measures, constraints, or functions, effortlessly organized in either YAML files or separate files.](https://docs.getdbt.com/docs/build/metrics-overview) [![](https://docs.getdbt.com/img/icons/dbt-bit.svg)\ \ #### Advanced topics\ \ Learn about advanced topics for dbt Semantic Layer and MetricFlow, such as data modeling workflows, and more.](https://docs.getdbt.com/docs/build/advanced-topics) [![](https://docs.getdbt.com/img/icons/dbt-bit.svg)\ \ #### About the dbt Semantic Layer\ \ Introducing the dbt Semantic Layer, the universal process that allows data teams to centrally define and query metrics](https://docs.getdbt.com/docs/use-dbt-semantic-layer/dbt-sl) [![](https://docs.getdbt.com/img/icons/dbt-bit.svg)\ \ #### Available integrations\ \ Discover the diverse range of partners that seamlessly integrate with the powerful dbt Semantic Layer, allowing you to query and unlock valuable insights from your data ecosystem.](https://docs.getdbt.com/docs/cloud-integrations/avail-sl-integrations) Related docs[​](https://docs.getdbt.com/docs/build/build-metrics-intro#related-docs "Direct link to Related docs") ------------------------------------------------------------------------------------------------------------------- * [Quickstart guide with the Semantic Layer](https://docs.getdbt.com/guides/sl-snowflake-qs) * [The Semantic Layer: what's next](https://www.getdbt.com/blog/dbt-semantic-layer-whats-next/) blog * [Semantic Layer on-demand course](https://learn.getdbt.com/courses/semantic-layer) * [Semantic Layer FAQs](https://docs.getdbt.com/docs/use-dbt-semantic-layer/sl-faqs) Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 --- # Custom databases | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/build/custom-databases#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page A word on naming Different warehouses have different names for _logical databases_. The information in this document covers "databases" on Snowflake, Redshift, and Postgres; "projects" on BigQuery; and "catalogs" on Databricks Unity Catalog. The values `project` and `database` are interchangeable in BigQuery project configurations. Configuring custom databases[​](https://docs.getdbt.com/docs/build/custom-databases#configuring-custom-databases "Direct link to Configuring custom databases") ---------------------------------------------------------------------------------------------------------------------------------------------------------------- The logical database that dbt models are built into can be configured using the `database` model configuration. If this configuration is not supplied to a model, then dbt will use the database configured in the active target from your `profiles.yml` file. If the `database` configuration _is_ supplied for a model, then dbt will build the model into the configured database. The `database` configuration can be supplied for groups of models in the `dbt_project.yml` file, or for individual models in model SQL files. ### Configuring database overrides in `dbt_project.yml`:[​](https://docs.getdbt.com/docs/build/custom-databases#configuring-database-overrides-in-dbt_projectyml "Direct link to configuring-database-overrides-in-dbt_projectyml") This config changes all models in the `jaffle_shop` project to be built into a database called `jaffle_shop`. dbt\_project.yml name: jaffle_shopmodels: jaffle_shop: +database: jaffle_shop # For BigQuery users: # project: jaffle_shop ### Configuring database overrides in a model file[​](https://docs.getdbt.com/docs/build/custom-databases#configuring-database-overrides-in-a-model-file "Direct link to Configuring database overrides in a model file") This config changes a specific model to be built into a database called `jaffle_shop`. models/my\_model.sql {{ config(database="jaffle_shop") }}select * from ... ### generate\_database\_name[​](https://docs.getdbt.com/docs/build/custom-databases#generate_database_name "Direct link to generate_database_name") The database name generated for a model is controlled by a macro called `generate_database_name`. This macro can be overridden in a dbt project to change how dbt generates model database names. This macro works similarly to the [generate\_schema\_name](https://docs.getdbt.com/docs/build/custom-schemas#advanced-custom-schema-configuration) macro. To override dbt's database name generation, create a macro named `generate_database_name` in your own dbt project. The `generate_database_name` macro accepts two arguments: 1. The custom database supplied in the model config 2. The node that a custom database is being generated for The default implementation of `generate_database_name` simply uses the supplied `database` config if one is present, otherwise the database configured in the active `target` is used. This implementation looks like this: get\_custom\_database.sql {% macro generate_database_name(custom_database_name=none, node=none) -%} {%- set default_database = target.database -%} {%- if custom_database_name is none -%} {{ default_database }} {%- else -%} {{ custom_database_name | trim }} {%- endif -%}{%- endmacro %} 💡 Use Jinja's whitespace control to tidy your macros! When you're modifying macros in your project, you might notice extra white space in your code in the `target/compiled` folder. You can remove unwanted spaces and lines with Jinja's [whitespace control](https://docs.getdbt.com/faqs/Jinja/jinja-whitespace) by using a minus sign. For example, use `{{- ... -}}` or `{%- ... %}` around your macro definitions (such as `{%- macro generate_schema_name(...) -%} ... {%- endmacro -%}`). ### Managing different behaviors across packages[​](https://docs.getdbt.com/docs/build/custom-databases#managing-different-behaviors-across-packages "Direct link to Managing different behaviors across packages") See docs on macro `dispatch`: ["Managing different global overrides across packages"](https://docs.getdbt.com/reference/dbt-jinja-functions/dispatch) Considerations[​](https://docs.getdbt.com/docs/build/custom-databases#considerations "Direct link to Considerations") ---------------------------------------------------------------------------------------------------------------------- ### BigQuery[​](https://docs.getdbt.com/docs/build/custom-databases#bigquery "Direct link to BigQuery") When dbt opens a BigQuery connection, it will do so using the `project_id` defined in your active `profiles.yml` target. This `project_id` will be billed for the queries that are executed in the dbt run, even if some models are configured to be built in other projects. Related docs[​](https://docs.getdbt.com/docs/build/custom-databases#related-docs "Direct link to Related docs") ---------------------------------------------------------------------------------------------------------------- * [Customize dbt models database, schema, and alias](https://docs.getdbt.com/guides/customize-schema-alias?step=1) to learn how to customize dbt models database, schema, and alias * [Custom schema](https://docs.getdbt.com/docs/build/custom-schemas) to learn how to customize dbt model schema * [Custom aliases](https://docs.getdbt.com/docs/build/custom-aliases) to learn how to customize dbt model alias name Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Configuring custom databases](https://docs.getdbt.com/docs/build/custom-databases#configuring-custom-databases) * [Configuring database overrides in `dbt_project.yml`:](https://docs.getdbt.com/docs/build/custom-databases#configuring-database-overrides-in-dbt_projectyml) * [Configuring database overrides in a model file](https://docs.getdbt.com/docs/build/custom-databases#configuring-database-overrides-in-a-model-file) * [generate\_database\_name](https://docs.getdbt.com/docs/build/custom-databases#generate_database_name) * [Managing different behaviors across packages](https://docs.getdbt.com/docs/build/custom-databases#managing-different-behaviors-across-packages) * [Considerations](https://docs.getdbt.com/docs/build/custom-databases#considerations) * [BigQuery](https://docs.getdbt.com/docs/build/custom-databases#bigquery) * [Related docs](https://docs.getdbt.com/docs/build/custom-databases#related-docs) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/build/custom-databases.md) --- # Conversion metrics | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/build/conversion#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page Conversion metrics allow you to define when a base event and a subsequent conversion event happen for a specific entity within some time range. For example, using conversion metrics allows you to track how often a user (entity) completes a visit (base event) and then makes a purchase (conversion event) within 7 days (time window). You would need to add a time range and an entity to join. Conversion metrics are different from [ratio metrics](https://docs.getdbt.com/docs/build/ratio) because you need to include an entity in the pre-aggregated join. Parameters[​](https://docs.getdbt.com/docs/build/conversion#parameters "Direct link to Parameters") ---------------------------------------------------------------------------------------------------- The specification for conversion metrics is as follows: tip Note that we use the double colon (::) to indicate whether a parameter is nested within another parameter. So for example, `query_params::metrics` means the `metrics` parameter is nested under `query_params`. | Parameter | Description | Required | Type | | --- | --- | --- | --- | | `name` | The name of the metric. | Required | String | | `description` | The description of the metric. | Optional | String | | `type` | The type of metric (such as derived, ratio, and so on.). In this case, set as 'conversion'. | Required | String | | `label` | Required string that defines the display value in downstream tools. Accepts plain text, spaces, and quotes (such as `orders_total` or `"orders_total"`). | Required | String | | `type_params` | Specific configurations for each metric type. | Required | Dict | | `conversion_type_params` | Additional configuration specific to conversion metrics. | Required | Dict | | `entity` | The entity for each conversion event. | Required | String | | `calculation` | Method of calculation. Either `conversion_rate` or `conversions`. Defaults to `conversion_rate`. | Optional | String | | `base_measure` | A list of base measure inputs. | Required | Dict | | `base_measure:name` | The base conversion event measure. | Required | String | | `base_measure:fill_nulls_with` | Set the value in your metric definition instead of null (such as zero). | Optional | Integer | | `base_measure:join_to_timespine` | Boolean that indicates if the aggregated measure should be joined to the time spine table to fill in missing dates. Default `false`. | Optional | Boolean | | `base_measure:filter` | Optional `filter` used to apply to the base measure. | Optional | String | | `conversion_measure` | A list of conversion measure inputs. | Required | Dict | | `conversion_measure:name` | The base conversion event measure. | Required | String | | `conversion_measure:fill_nulls_with` | Set the value in your metric definition instead of null (such as zero). | Optional | Integer | | `conversion_measure:join_to_timespine` | Boolean that indicates if the aggregated measure should be joined to the time spine table to fill in missing dates. Default `false`. | Optional | Boolean | | `window` | The time window for the conversion event, such as 7 days, 1 week, 3 months. Defaults to infinity. | Optional | String | | `constant_properties` | List of constant properties. | Optional | List | | `base_property` | The property from the base semantic model that you want to hold constant. | Optional | String | | `conversion_property` | The property from the conversion semantic model that you want to hold constant. | Optional | String | Refer to [additional settings](https://docs.getdbt.com/docs/build/conversion#additional-settings) to learn how to customize conversion metrics with settings for null values, calculation type, and constant properties. The following code example displays the complete specification for conversion metrics and details how they're applied: metrics: - name: The metric name # Required description: The metric description # Optional type: conversion # Required label: YOUR_LABEL # Required type_params: # Required conversion_type_params: # Required entity: ENTITY # Required calculation: CALCULATION_TYPE # Optional. default: conversion_rate. options: conversions(buys) or conversion_rate (buys/visits), and more to come. base_measure: name: The name of the measure # Required fill_nulls_with: Set the value in your metric definition instead of null (such as zero) # Optional join_to_timespine: true/false # Boolean that indicates if the aggregated measure should be joined to the time spine table to fill in missing dates. Default `false`. # Optional filter: The filter used to apply to the base measure. # Optional conversion_measure: name: The name of the measure # Required fill_nulls_with: Set the value in your metric definition instead of null (such as zero) # Optional join_to_timespine: true/false # Boolean that indicates if the aggregated measure should be joined to the time spine table to fill in missing dates. Default `false`. # Optional window: TIME_WINDOW # Optional. default: infinity. window to join the two events. Follows a similar format as time windows elsewhere (such as 7 days) constant_properties: # Optional. List of constant properties default: None - base_property: DIMENSION or ENTITY # Required. A reference to a dimension/entity of the semantic model linked to the base_measure conversion_property: DIMENSION or ENTITY # Same as base above, but to the semantic model of the conversion_measure Conversion metric example[​](https://docs.getdbt.com/docs/build/conversion#conversion-metric-example "Direct link to Conversion metric example") ------------------------------------------------------------------------------------------------------------------------------------------------- The following example will measure conversions from website visits (`VISITS` table) to order completions (`BUYS` table) and calculate a conversion metric for this scenario step by step. Suppose you have two semantic models, `VISITS` and `BUYS`: * The `VISITS` table represents visits to an e-commerce site. * The `BUYS` table represents someone completing an order on that site. The underlying tables look like the following: `VISITS` Contains user visits with `USER_ID` and `REFERRER_ID`. | DS | USER\_ID | REFERRER\_ID | | --- | --- | --- | | 2020-01-01 | bob | facebook | | 2020-01-04 | bob | google | | 2020-01-07 | bob | amazon | `BUYS` Records completed orders with `USER_ID` and `REFERRER_ID`. | DS | USER\_ID | REFERRER\_ID | | --- | --- | --- | | 2020-01-02 | bob | facebook | | 2020-01-07 | bob | amazon | Next, define a conversion metric as follows: - name: visit_to_buy_conversion_rate_7d description: "Conversion rate from visiting to transaction in 7 days" type: conversion label: Visit to buy conversion rate (7-day window) type_params: conversion_type_params: base_measure: name: visits fill_nulls_with: 0 filter: {{ Dimension('visits__referrer_id') }} = 'facebook' conversion_measure: name: sellers entity: user window: 7 days To calculate the conversion, link the `BUYS` event to the nearest `VISITS` event (or closest base event). The following steps explain this process in more detail: ### Step 1: Join `VISITS` and `BUYS`[​](https://docs.getdbt.com/docs/build/conversion#step-1-join-visits-and-buys "Direct link to step-1-join-visits-and-buys") This step joins the `BUYS` table to the `VISITS` table and gets all combinations of visits-buys events that match the join condition where buys occur within 7 days of the visit (any rows that have the same user and a buy happened at most 7 days after the visit). The SQL generated in these steps looks like the following: select v.ds, v.user_id, v.referrer_id, b.ds, b.uuid, 1 as buysfrom visits vinner join ( select *, uuid_string() as uuid from buys -- Adds a uuid column to uniquely identify the different rows) bonv.user_id = b.user_id and v.ds <= b.ds and v.ds > b.ds - interval '7 days' The dataset returns the following (note that there are two potential conversion events for the first visit): | V.DS | V.USER\_ID | V.REFERRER\_ID | B.DS | UUID | BUYS | | --- | --- | --- | --- | --- | --- | | 2020-01-01 | bob | facebook | 2020-01-02 | uuid1 | 1 | | 2020-01-01 | bob | facebook | 2020-01-07 | uuid2 | 1 | | 2020-01-04 | bob | google | 2020-01-07 | uuid2 | 1 | | 2020-01-07 | bob | amazon | 2020-01-07 | uuid2 | 1 | ### Step 2: Refine with window function[​](https://docs.getdbt.com/docs/build/conversion#step-2-refine-with-window-function "Direct link to Step 2: Refine with window function") Instead of returning the raw visit values, use window functions to link conversions to the closest base event. You can partition by the conversion source and get the `first_value` ordered by `visit ds`, descending to get the closest base event from the conversion event: select first_value(v.ds) over (partition by b.ds, b.user_id, b.uuid order by v.ds desc) as v_ds, first_value(v.user_id) over (partition by b.ds, b.user_id, b.uuid order by v.ds desc) as user_id, first_value(v.referrer_id) over (partition by b.ds, b.user_id, b.uuid order by v.ds desc) as referrer_id, b.ds, b.uuid, 1 as buysfrom visits vinner join ( select *, uuid_string() as uuid from buys) bonv.user_id = b.user_id and v.ds <= b.ds and v.ds > b.ds - interval '7 day' The dataset returns the following: | V.DS | V.USER\_ID | V.REFERRER\_ID | B.DS | UUID | BUYS | | --- | --- | --- | --- | --- | --- | | 2020-01-01 | bob | facebook | 2020-01-02 | uuid1 | 1 | | 2020-01-07 | bob | amazon | 2020-01-07 | uuid2 | 1 | | 2020-01-07 | bob | amazon | 2020-01-07 | uuid2 | 1 | | 2020-01-07 | bob | amazon | 2020-01-07 | uuid2 | 1 | This workflow links the two conversions to the correct visit events. Due to the join, you end up with multiple combinations, leading to fanout results. After applying the window function, duplicates appear. To resolve this and eliminate duplicates, use a distinct select. The UUID also helps identify which conversion is unique. The next steps provide more detail on how to do this. ### Step 3: Remove duplicates[​](https://docs.getdbt.com/docs/build/conversion#step-3-remove-duplicates "Direct link to Step 3: Remove duplicates") Instead of regular select used in the [Step 2](https://docs.getdbt.com/docs/build/conversion#step-2-refine-with-window-function) , use a distinct select to remove the duplicates: select distinct first_value(v.ds) over (partition by b.ds, b.user_id, b.uuid order by v.ds desc) as v_ds, first_value(v.user_id) over (partition by b.ds, b.user_id, b.uuid order by v.ds desc) as user_id, first_value(v.referrer_id) over (partition by b.ds, b.user_id, b.uuid order by v.ds desc) as referrer_id, b.ds, b.uuid, 1 as buysfrom visits vinner join ( select *, uuid_string() as uuid from buys) bonv.user_id = b.user_id and v.ds <= b.ds and v.ds > b.ds - interval '7 day'; The dataset returns the following: | V.DS | V.USER\_ID | V.REFERRER\_ID | B.DS | UUID | BUYS | | --- | --- | --- | --- | --- | --- | | 2020-01-01 | bob | facebook | 2020-01-02 | uuid1 | 1 | | 2020-01-07 | bob | amazon | 2020-01-07 | uuid2 | 1 | You now have a dataset where every conversion is connected to a visit event. To proceed: 1. Sum up the total conversions in the "conversions" table. 2. Combine this table with the "opportunities" table, matching them based on group keys. 3. Calculate the conversion rate. ### Step 4: Aggregate and calculate[​](https://docs.getdbt.com/docs/build/conversion#step-4-aggregate-and-calculate "Direct link to Step 4: Aggregate and calculate") Now that you’ve tied each conversion event to a visit, you can calculate the aggregated conversions and opportunities measures. Then, you can join them to calculate the actual conversion rate. The SQL to calculate the conversion rate is as follows: select coalesce(subq_3.metric_time__day, subq_13.metric_time__day) as metric_time__day, cast(max(subq_13.buys) as double) / cast(nullif(max(subq_3.visits), 0) as double) as visit_to_buy_conversion_rate_7dfrom ( -- base measure select metric_time__day, sum(visits) as mqls from ( select date_trunc('day', first_contact_date) as metric_time__day, 1 as visits from visits ) subq_2 group by metric_time__day) subq_3full outer join ( -- conversion measure select metric_time__day, sum(buys) as sellers from ( -- ... -- The output of this subquery is the table produced in Step 3. The SQL is hidden for legibility. -- To see the full SQL output, add --explain to your conversion metric query. ) subq_10 group by metric_time__day) subq_13on subq_3.metric_time__day = subq_13.metric_time__daygroup by metric_time__day ### Additional settings[​](https://docs.getdbt.com/docs/build/conversion#additional-settings "Direct link to Additional settings") Use the following additional settings to customize your conversion metrics: * **Null conversion values:** Set null conversions to zero using `fill_nulls_with`. Refer to [Fill null values for metrics](https://docs.getdbt.com/docs/build/fill-nulls-advanced) for more info. * **Calculation type:** Choose between showing raw conversions or conversion rate. * **Constant property:** Add conditions for specific scenarios to join conversions on constant properties. * Set null conversion events to zero * Set calculation type parameter * Set constant property To return zero in the final data set, you can set the value of a null conversion event to zero instead of null. You can add the `fill_nulls_with` parameter to your conversion metric definition like this: - name: visit_to_buy_conversion_rate_7_day_window description: "Conversion rate from viewing a page to making a purchase" type: conversion label: Visit to Seller Conversion Rate (7 day window) type_params: conversion_type_params: calculation: conversions base_measure: name: visits conversion_measure: name: buys fill_nulls_with: 0 entity: user window: 7 days This will return the following results: [![Conversion metric with fill nulls with parameter](https://docs.getdbt.com/img/docs/dbt-cloud/semantic-layer/conversion-metrics-fill-null.png?v=2 "Conversion metric with fill nulls with parameter")](https://docs.getdbt.com/docs/build/conversion#) Conversion metric with fill nulls with parameter Refer to [Fill null values for metrics](https://docs.getdbt.com/docs/build/fill-nulls-advanced) for more info. Use the conversion calculation parameter to either show the raw number of conversions or the conversion rate. The default value is the conversion rate. You can change the default to display the number of conversions by setting the `calculation: conversion` parameter: - name: visit_to_buy_conversions_1_week_window description: "Visit to Buy Conversions" type: conversion label: Visit to Buy Conversions (1 week window) type_params: conversion_type_params: calculation: conversions base_measure: name: visits conversion_measure: name: buys fill_nulls_with: 0 entity: user window: 1 week _Refer to [Amplitude's blog posts on constant properties](https://amplitude.com/blog/holding-constant) to learn about this concept._ You can add a constant property to a conversion metric to count only those conversions where a specific dimension or entity matches in both the base and conversion events. For example, if you're at an e-commerce company and want to answer the following question: * _How often did visitors convert from `View Item Details` to `Complete Purchase` with the same product in each step?_ * This question is tricky to answer because users could have completed these two conversion milestones across many products. For example, they may have viewed a pair of shoes, then a T-shirt, and eventually checked out with a bow tie. This would still count as a conversion, even though the conversion event only happened for the bow tie. Back to the initial questions, you want to see how many customers viewed an item detail page and then completed a purchase for the _same_ product. In this case, you want to set `product_id` as the constant property. You can specify this in the configs as follows: - name: view_item_detail_to_purchase_with_same_item description: "Conversion rate for users who viewed the item detail page and purchased the item" type: Conversion label: View Item Detail > Purchase type_params: conversion_type_params: calculation: conversions base_measure: name: view_item_detail conversion_measure: purchase entity: user window: 1 week constant_properties: - base_property: product conversion_property: product You will add an additional condition to the join to make sure the constant property is the same across conversions. select distinct first_value(v.ds) over (partition by buy_source.ds, buy_source.user_id, buy_source.session_id order by v.ds desc rows between unbounded preceding and unbounded following) as ds, first_value(v.user_id) over (partition by buy_source.ds, buy_source.user_id, buy_source.session_id order by v.ds desc rows between unbounded preceding and unbounded following) as user_id, first_value(v.referrer_id) over (partition by buy_source.ds, buy_source.user_id, buy_source.session_id order by v.ds desc rows between unbounded preceding and unbounded following) as referrer_id, buy_source.uuid, 1 as buysfrom {{ source_schema }}.fct_view_item_details vinner join ( select *, {{ generate_random_uuid() }} as uuid from {{ source_schema }}.fct_purchases ) buy_sourceon v.user_id = buy_source.user_id and v.ds <= buy_source.ds and v.ds > buy_source.ds - interval '7 day' and buy_source.product_id = v.product_id --Joining on the constant property product_id Related docs[​](https://docs.getdbt.com/docs/build/conversion#related-docs "Direct link to Related docs") ---------------------------------------------------------------------------------------------------------- * [Fill null values for metrics](https://docs.getdbt.com/docs/build/fill-nulls-advanced) Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Parameters](https://docs.getdbt.com/docs/build/conversion#parameters) * [Conversion metric example](https://docs.getdbt.com/docs/build/conversion#conversion-metric-example) * [Step 1: Join `VISITS` and `BUYS`](https://docs.getdbt.com/docs/build/conversion#step-1-join-visits-and-buys) * [Step 2: Refine with window function](https://docs.getdbt.com/docs/build/conversion#step-2-refine-with-window-function) * [Step 3: Remove duplicates](https://docs.getdbt.com/docs/build/conversion#step-3-remove-duplicates) * [Step 4: Aggregate and calculate](https://docs.getdbt.com/docs/build/conversion#step-4-aggregate-and-calculate) * [Additional settings](https://docs.getdbt.com/docs/build/conversion#additional-settings) * [Related docs](https://docs.getdbt.com/docs/build/conversion#related-docs) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/build/conversion-metrics.md) --- # Custom aliases | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/build/custom-aliases#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page Overview[​](https://docs.getdbt.com/docs/build/custom-aliases#overview "Direct link to Overview") -------------------------------------------------------------------------------------------------- When dbt runs a model, it will generally create a relation (either a table or a view ) in the database, except in the case of an [ephemeral model](https://docs.getdbt.com/docs/build/materializations) , when it will create a CTE for use in another model. By default, dbt uses the model's filename as the identifier for the relation or CTE it creates. This identifier can be overridden using the [`alias`](https://docs.getdbt.com/reference/resource-configs/alias) model configuration. ### Why alias model names?[​](https://docs.getdbt.com/docs/build/custom-aliases#why-alias-model-names "Direct link to Why alias model names?") The names of schemas and tables are effectively the "user interface" of your data warehouse. Well-named schemas and tables can help provide clarity and direction for consumers of this data. In combination with [custom schemas](https://docs.getdbt.com/docs/build/custom-schemas) , model aliasing is a powerful mechanism for designing your warehouse. The file naming scheme that you use to organize your models may also interfere with your data platform's requirements for identifiers. For example, you might wish to namespace your files using a period (`.`), but your data platform's SQL dialect may interpret periods to indicate a separation between schema names and table names in identifiers, or it may forbid periods from being used at all in CTE identifiers. In cases like these, model aliasing can allow you to retain flexibility in the way you name your model files without violating your data platform's identifier requirements. ### Usage[​](https://docs.getdbt.com/docs/build/custom-aliases#usage "Direct link to Usage") The `alias` config can be used to change the name of a model's identifier in the database. The following table shows examples of database identifiers for models both with and without a supplied `alias`, and with different materializations. | Model | Config | Relation Type | Database Identifier | | --- | --- | --- | --- | | ga\_sessions.sql | {{ config(materialization='view') }} | view | "analytics"."ga\_sessions" | | ga\_sessions.sql | {{ config(materialization='view', alias='sessions') }} | view | "analytics"."sessions" | | ga\_sessions.sql | {{ config(materialization='ephemeral') }} | CTE | "\_\_dbt\_\_cte\_\_ga\_sessions" | | ga\_sessions.sql | {{ config(materialization='ephemeral', alias='sessions') }} | CTE | "\_\_dbt\_\_cte\_\_sessions" | To configure an alias for a model, supply a value for the model's `alias` configuration parameter. For example: models/google\_analytics/ga\_sessions.sql -- This model will be created in the database with the identifier `sessions`-- Note that in this example, `alias` is used along with a custom schema{{ config(alias='sessions', schema='google_analytics') }}select * from ... Or in a `schema.yml` file. models/google\_analytics/schema.yml models: - name: ga_sessions config: alias: sessions When referencing the `ga_sessions` model above from a different model, use the `ref()` function with the model's _filename_ as usual. For example: models/combined\_sessions.sql -- Use the model's filename in ref's, regardless of any aliasing configsselect * from {{ ref('ga_sessions') }}union allselect * from {{ ref('snowplow_sessions') }} ### generate\_alias\_name[​](https://docs.getdbt.com/docs/build/custom-aliases#generate_alias_name "Direct link to generate_alias_name") The alias generated for a model is controlled by a macro called `generate_alias_name`. This macro can be overridden in a dbt project to change how dbt aliases models. This macro works similarly to the [generate\_schema\_name](https://docs.getdbt.com/docs/build/custom-schemas#advanced-custom-schema-configuration) macro. To override dbt's alias name generation, create a macro named `generate_alias_name` in your own dbt project. The `generate_alias_name` macro accepts two arguments: 1. The custom alias supplied in the model config 2. The node that a custom alias is being generated for The default implementation of `generate_alias_name` simply uses the supplied `alias` config (if present) as the model alias, otherwise falling back to the model name. This implementation looks like this: get\_custom\_alias.sql {% macro generate_alias_name(custom_alias_name=none, node=none) -%} {%- if custom_alias_name -%} {{ custom_alias_name | trim }} {%- elif node.version -%} {{ return(node.name ~ "_v" ~ (node.version | replace(".", "_"))) }} {%- else -%} {{ node.name }} {%- endif -%}{%- endmacro %} 💡 Use Jinja's whitespace control to tidy your macros! When you're modifying macros in your project, you might notice extra white space in your code in the `target/compiled` folder. You can remove unwanted spaces and lines with Jinja's [whitespace control](https://docs.getdbt.com/faqs/Jinja/jinja-whitespace) by using a minus sign. For example, use `{{- ... -}}` or `{%- ... %}` around your macro definitions (such as `{%- macro generate_schema_name(...) -%} ... {%- endmacro -%}`). ### Dispatch macro - SQL alias management for databases and dbt packages[​](https://docs.getdbt.com/docs/build/custom-aliases#dispatch-macro---sql-alias-management-for-databases-and-dbt-packages "Direct link to Dispatch macro - SQL alias management for databases and dbt packages") See docs on macro `dispatch`: ["Managing different global overrides across packages"](https://docs.getdbt.com/reference/dbt-jinja-functions/dispatch#managing-different-global-overrides-across-packages) ### Caveats[​](https://docs.getdbt.com/docs/build/custom-aliases#caveats "Direct link to Caveats") #### Ambiguous database identifiers[​](https://docs.getdbt.com/docs/build/custom-aliases#ambiguous-database-identifiers "Direct link to Ambiguous database identifiers") Using aliases, it's possible to accidentally create models with ambiguous identifiers. Given the following two models, dbt would attempt to create two views with _exactly_ the same names in the database (ie. `sessions`): models/snowplow\_sessions.sql {{ config(alias='sessions') }}select * from ... models/sessions.sql select * from ... Whichever one of these models runs second would "win", and generally, the output of dbt would not be what you would expect. To avoid this failure mode, dbt will check if your model names and aliases are ambiguous in nature. If they are, you will be presented with an error message like this: $ dbt compileEncountered an error:Compilation Error dbt found two resources with the database representation "analytics.sessions". dbt cannot create two resources with identical database representations. To fix this, change the "schema" or "alias" configuration of one of these resources: - model.my_project.snowplow_sessions (models/snowplow_sessions.sql) - model.my_project.sessions (models/sessions.sql) If these models should indeed have the same database identifier, you can work around this error by configuring a [custom schema](https://docs.getdbt.com/docs/build/custom-schemas) for one of the models. #### Model versions[​](https://docs.getdbt.com/docs/build/custom-aliases#model-versions "Direct link to Model versions") **Related documentation:** * [Model versions](https://docs.getdbt.com/docs/mesh/govern/model-versions) * [`versions`](https://docs.getdbt.com/reference/resource-properties/versions#alias) By default, dbt will create versioned models with the alias `_v`, where `` is that version's unique identifier. You can customize this behavior just like for non-versioned models by configuring a custom `alias` or re-implementing the `generate_alias_name` macro. Related docs[​](https://docs.getdbt.com/docs/build/custom-aliases#related-docs "Direct link to Related docs") -------------------------------------------------------------------------------------------------------------- * [Customize dbt models database, schema, and alias](https://docs.getdbt.com/guides/customize-schema-alias?step=1) to learn how to customize dbt models database, schema, and alias * [Custom schema](https://docs.getdbt.com/docs/build/custom-schemas) to learn how to customize dbt schema * [Custom database](https://docs.getdbt.com/docs/build/custom-databases) to learn how to customize dbt database Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Overview](https://docs.getdbt.com/docs/build/custom-aliases#overview) * [Why alias model names?](https://docs.getdbt.com/docs/build/custom-aliases#why-alias-model-names) * [Usage](https://docs.getdbt.com/docs/build/custom-aliases#usage) * [generate\_alias\_name](https://docs.getdbt.com/docs/build/custom-aliases#generate_alias_name) * [Dispatch macro - SQL alias management for databases and dbt packages](https://docs.getdbt.com/docs/build/custom-aliases#dispatch-macro---sql-alias-management-for-databases-and-dbt-packages) * [Caveats](https://docs.getdbt.com/docs/build/custom-aliases#caveats) * [Related docs](https://docs.getdbt.com/docs/build/custom-aliases#related-docs) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/build/custom-aliases.md) --- # dbt tips and tricks | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/build/dbt-tips#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page Use this page for valuable insights and practical advice to enhance your dbt experience. Whether you're new to dbt or an experienced user, these tips are designed to help you work more efficiently and effectively. The following tips are organized into the following categories: * [Package tips](https://docs.getdbt.com/docs/build/dbt-tips#package-tips) to help you streamline your workflow. * [Advanced tips and techniques](https://docs.getdbt.com/docs/build/dbt-tips#advanced-tips-and-techniques) to help you get the most out of dbt. If you're developing with the Studio IDE, you can refer to the [keyboard shortcuts](https://docs.getdbt.com/docs/cloud/dbt-cloud-ide/keyboard-shortcuts) page to help make development more productive and easier for everyone. YAML tips[​](https://docs.getdbt.com/docs/build/dbt-tips#yaml-tips "Direct link to YAML tips") ----------------------------------------------------------------------------------------------- This section clarifies where you can use [Jinja](https://docs.getdbt.com/docs/build/jinja-macros) , nest [vars](https://docs.getdbt.com/reference/dbt-jinja-functions/var) and [`env_var`](https://docs.getdbt.com/reference/dbt-jinja-functions/env_var) in your YAML files. * You can use Jinja in almost every YAML file in dbt _except_ the [`dependencies.yml` file](https://docs.getdbt.com/docs/build/packages#use-cases) . This is because the `dependencies.yml` file doesn't support Jinja. * Use `vars` in any YAML file that supports Jinja (like `schema.yml`, `snapshots.yml`). However, note that: * In `dbt_project.yml`, `packages.yml`, and `profiles.yml` files, you must pass `vars` through the CLI using `--vars`, not defined inside the `vars:` block in the YAML file. This is because these files are parsed before Jinja is rendered. * You can use `env_var()` in all YAML files that support Jinja. Only `profiles.yml` and `packages.yml` support environment variables for secure values (using the `DBT_ENV_SECRET_` prefix). These are masked in logs and intended for credentials or secrets. For additional information, check out [dbt Core's context docs](https://github.com/dbt-labs/dbt-core/blob/main/core/dbt/context/README.md) . Package tips[​](https://docs.getdbt.com/docs/build/dbt-tips#package-tips "Direct link to Package tips") -------------------------------------------------------------------------------------------------------- Leverage these dbt packages to streamline your workflow: | Package | Description | | --- | --- | | [`dbt_codegen`](https://hub.getdbt.com/dbt-labs/codegen/latest/) | Use the package to help you generate YML files for your models and sources and SQL files for your staging models. | | [`dbt_utils`](https://hub.getdbt.com/dbt-labs/dbt_utils/latest/) | The package contains macros useful for daily development. For example, `date_spine` generates a table with all dates between the ones provided as parameters. | | [`dbt_project_evaluator`](https://hub.getdbt.com/dbt-labs/dbt_project_evaluator/latest) | The package compares your dbt project against a list of our best practices and provides suggestions and guidelines on how to update your models. | | [`dbt_expectations`](https://hub.getdbt.com/metaplane/dbt_expectations/latest/) | The package contains many tests beyond those built into dbt. | | [`dbt_audit_helper`](https://hub.getdbt.com/#:~:text=adwords-,audit_helper,-codegen) | The package lets you compare the output of 2 queries. Use it when refactoring existing logic to ensure that the new results are identical. | | [`dbt_artifacts`](https://hub.getdbt.com/brooklyn-data/dbt_artifacts/latest) | The package saves information about your dbt runs directly to your data platform so that you can track the performance of models over time. | | [`dbt_meta_testing`](https://hub.getdbt.com/tnightengale/dbt_meta_testing/latest) | This package checks that your dbt project is sufficiently tested and documented. | Advanced tips and techniques[​](https://docs.getdbt.com/docs/build/dbt-tips#advanced-tips-and-techniques "Direct link to Advanced tips and techniques") -------------------------------------------------------------------------------------------------------------------------------------------------------- * Use your folder structure as your primary selector method. `dbt build --select marts.marketing` is simpler and more resilient than relying on tagging every model. * Think about jobs in terms of build cadences and SLAs. Run models that have hourly, daily, or weekly build cadences together. * Use the [where config](https://docs.getdbt.com/reference/resource-configs/where) for tests to test an assertion on a subset of records. * [store\_failures](https://docs.getdbt.com/reference/resource-configs/store_failures) lets you examine records that cause tests to fail, so you can either repair the data or change the test as needed. * Use [severity](https://docs.getdbt.com/reference/resource-configs/severity) thresholds to set an acceptable number of failures for a test. * Use [incremental\_strategy](https://docs.getdbt.com/docs/build/incremental-strategy) in your incremental model config to implement the most effective behavior depending on the volume of your data and reliability of your unique keys. * Set `vars` in your `dbt_project.yml` to define global defaults for certain conditions, which you can then override using the `--vars` flag in your commands. * Use [for loops](https://docs.getdbt.com/guides/using-jinja?step=3) in Jinja to DRY up repetitive logic, such as selecting a series of columns that all require the same transformations and naming patterns to be applied. * Instead of relying on post-hooks, use the [grants config](https://docs.getdbt.com/reference/resource-configs/grants) to apply permission grants in the warehouse resiliently. * Define [source-freshness](https://docs.getdbt.com/docs/build/sources#source-data-freshness) thresholds on your sources to avoid running transformations on data that has already been processed. * Use the `+` operator on the left of a model `dbt build --select +model_name` to run a model and all of its upstream dependencies. Use the `+` operator on the right of the model `dbt build --select model_name+` to run a model and everything downstream that depends on it. * Use `dir_name` to run all models in a package or directory. * Use the `@` operator on the left of a model in a non-state-aware CI setup to test it. This operator runs all of a selection’s parents and children, and also runs the parents of its children, which in a fresh CI schema will likely not exist yet. * Use the [\--exclude flag](https://docs.getdbt.com/reference/node-selection/exclude) to remove a subset of models out of a selection. * Use the [\--full-refresh](https://docs.getdbt.com/reference/commands/run#refresh-incremental-models) flag to rebuild an incremental model from scratch. * Use [seeds](https://docs.getdbt.com/docs/build/seeds) to create manual lookup tables, like zip codes to states or marketing UTMs to campaigns. `dbt seed` will build these from CSVs into your warehouse and make them `ref` able in your models. * Use [target.name](https://docs.getdbt.com/docs/build/custom-schemas#an-alternative-pattern-for-generating-schema-names) to pivot logic based on what environment you’re using. For example, to build into a single development schema while developing, but use multiple schemas in production. Related docs[​](https://docs.getdbt.com/docs/build/dbt-tips#related-docs "Direct link to Related docs") -------------------------------------------------------------------------------------------------------- * [Quickstart guide](https://docs.getdbt.com/guides) * [About dbt](https://docs.getdbt.com/docs/cloud/about-cloud/dbt-cloud-features) * [Develop in the Cloud](https://docs.getdbt.com/docs/cloud/about-develop-dbt) Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [YAML tips](https://docs.getdbt.com/docs/build/dbt-tips#yaml-tips) * [Package tips](https://docs.getdbt.com/docs/build/dbt-tips#package-tips) * [Advanced tips and techniques](https://docs.getdbt.com/docs/build/dbt-tips#advanced-tips-and-techniques) * [Related docs](https://docs.getdbt.com/docs/build/dbt-tips#related-docs) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/build/dbt-tips.md) --- # Custom target names | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/build/custom-target-names#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page dbt Scheduler[​](https://docs.getdbt.com/docs/build/custom-target-names#dbt-scheduler "Direct link to dbt Scheduler") ---------------------------------------------------------------------------------------------------------------------- You can define a custom target name for any dbt job to correspond to settings in your dbt project. This is helpful if you have logic in your dbt project that behaves differently depending on the specified target, for example: select *from a_big_table-- limit the amount of data queried in dev{% if target.name != 'prod' %}where created_at > date_trunc('month', current_date){% endif %} To set a custom target name for a job in dbt, configure the **Target Name** field for your job in the Job Settings page. [![Overriding the target name to 'prod'](https://docs.getdbt.com/img/docs/dbt-cloud/using-dbt-cloud/jobs-settings-target-name.png?v=2 "Overriding the target name to 'prod'")](https://docs.getdbt.com/docs/build/custom-target-names#) Overriding the target name to 'prod' dbt Studio IDE[​](https://docs.getdbt.com/docs/build/custom-target-names#dbt-studio-ide "Direct link to dbt Studio IDE") ------------------------------------------------------------------------------------------------------------------------- When developing in dbt, you can set a custom target name in your development credentials. Click your account name above the profile icon in the left panel, select **Account settings**, then go to **Credentials**. Choose the project to update the target name. [![Overriding the target name to 'dev'](https://docs.getdbt.com/img/docs/dbt-cloud/using-dbt-cloud/development-credentials.png?v=2 "Overriding the target name to 'dev'")](https://docs.getdbt.com/docs/build/custom-target-names#) Overriding the target name to 'dev' Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [dbt Scheduler](https://docs.getdbt.com/docs/build/custom-target-names#dbt-scheduler) * [dbt Studio IDE](https://docs.getdbt.com/docs/build/custom-target-names#dbt-studio-ide) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/build/custom-target-names.md) --- # About the empty flag | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/build/empty-flag#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page note The `--empty` flag is not currently available for Python models. If the flag is used with a Python model, it will be ignored. During dbt development, you might want to validate that your models are semantically correct without the time-consuming cost of building the entire model in the data warehouse. The [`run`](https://docs.getdbt.com/reference/commands/run) and [`build`](https://docs.getdbt.com/reference/commands/build) commands support the `--empty` flag for building schema-only dry runs. The `--empty` flag limits the refs and sources to zero rows. dbt will still execute the model SQL against the target data warehouse but will avoid expensive reads of input data. This validates dependencies and ensures your models will build properly. ### Examples[​](https://docs.getdbt.com/docs/build/empty-flag#examples "Direct link to Examples") Run all models in a project while building only the schemas in your development environment: dbt --empty Run a specific model: dbt --select path/to/your_model --empty dbt will build and execute the SQL, resulting in an empty schema in the data warehouse. Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Examples](https://docs.getdbt.com/docs/build/empty-flag#examples) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/build/empty-flag.md) --- # Enhance your code | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/build/enhance-your-code#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) [![](https://docs.getdbt.com/img/icons/dbt-bit.svg)\ \ #### Environment variables\ \ Learn how you can use environment variables to customize the behavior of a dbt project.](https://docs.getdbt.com/docs/build/environment-variables) [![](https://docs.getdbt.com/img/icons/dbt-bit.svg)\ \ #### Hooks and operations\ \ Learn how to use hooks to trigger actions and operations to invoke macros.](https://docs.getdbt.com/docs/build/hooks-operations) [![](https://docs.getdbt.com/img/icons/dbt-bit.svg)\ \ #### Packages\ \ Learn how you can leverage code reuse through packages (libraries).](https://docs.getdbt.com/docs/build/packages) [![](https://docs.getdbt.com/img/icons/dbt-bit.svg)\ \ #### Project variables\ \ Learn how to use project variables to provide data to models for compilation.](https://docs.getdbt.com/docs/build/project-variables) Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 --- # Integrate Cursor with dbt MCP | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/dbt-ai/integrate-mcp-cursor#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page [Cursor](https://docs.cursor.com/context/model-context-protocol) is an AI-powered code editor, powered by Microsoft Visual Studio Code (VS Code). After setting up your MCP server, you connect it to Cursor. Log in to Cursor and follow the steps that align with your hosting method. Set up with local dbt MCP server[​](https://docs.getdbt.com/docs/dbt-ai/integrate-mcp-cursor#set-up-with-local-dbt-mcp-server "Direct link to Set up with local dbt MCP server") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- 1. Configure your environment variables in an `.env` file locally. 2. Click the following application link with Cursor open: [Add to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=dbt-mcp&config=eyJjb21tYW5kIjoidXZ4IC0tZW52LWZpbGUgPGVudi1maWxlLXBhdGg%252BIGRidC1tY3AifQ%3D%3D) 3. Update inputs in the template. 4. Save, and now you have access to the dbt-mcp! Set up with remote dbt MCP server[​](https://docs.getdbt.com/docs/dbt-ai/integrate-mcp-cursor#set-up-with-remote-dbt-mcp-server "Direct link to Set up with remote dbt MCP server") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ 1. Click the following application link with Cursor open: [Add to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=dbt&config=eyJ1cmwiOiJodHRwczovLzxob3N0Pi9hcGkvYWkvdjEvbWNwLyIsImhlYWRlcnMiOnsiQXV0aG9yaXphdGlvbiI6InRva2VuIDx0b2tlbj4iLCJ4LWRidC1wcm9kLWVudmlyb25tZW50LWlkIjoiPHByb2QtaWQ%252BIn19) 2. Provide your URL/headers by updating the **host**, **production environment ID**, and **service token** in the template. 3. Save, and now you have access to the dbt MCP server! Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Set up with local dbt MCP server](https://docs.getdbt.com/docs/dbt-ai/integrate-mcp-cursor#set-up-with-local-dbt-mcp-server) * [Set up with remote dbt MCP server](https://docs.getdbt.com/docs/dbt-ai/integrate-mcp-cursor#set-up-with-remote-dbt-mcp-server) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/dbt-ai/integrate-mcp-cursor.md) --- # dbt Administrative API | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/dbt-cloud-apis/admin-cloud-api#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) The dbt Administrative API is enabled by default for [Enterprise and Enterprise+ plans](https://www.getdbt.com/pricing/) . It can be used to: * Download artifacts after a job has completed * Kick off a job run from an orchestration tool * Manage your dbt account * and more dbt currently supports two versions of the Administrative API: v2 and v3. In general, v3 is the recommended version to use, but we don't yet have all our v2 routes upgraded to v3. We're currently working on this. If you can't find something in our v3 docs, check out the shorter list of v2 endpoints because you might find it there. Many endpoints of the Administrative API can also be called through the [dbt Terraform provider](https://registry.terraform.io/providers/dbt-labs/dbtcloud/latest) . The built-in documentation on the Terraform registry contains [a guide on how to get started with the provider](https://registry.terraform.io/providers/dbt-labs/dbtcloud/latest/docs/guides/1_getting_started) as well as [a page showing all the Terraform resources available](https://registry.terraform.io/providers/dbt-labs/dbtcloud/latest/docs/guides/99_list_resources) to configure. [![](https://docs.getdbt.com/img/icons/pencil-paper.svg)\ \ #### API v2\ \ Our legacy API version, with limited endpoints and features. Contains information not available in v3.](https://docs.getdbt.com/dbt-cloud/api-v2) [![](https://docs.getdbt.com/img/icons/pencil-paper.svg)\ \ #### API v3\ \ Our latest API version, with new endpoints and features.](https://docs.getdbt.com/dbt-cloud/api-v3) [![](https://docs.getdbt.com/img/icons/pencil-paper.svg)\ \ #### dbt Terraform provider\ \ The Terraform provider maintained by dbt Labs which can be used to manage a dbt account.](https://registry.terraform.io/providers/dbt-labs/dbtcloud/latest) [](https://registry.terraform.io/providers/dbt-labs/dbtcloud/latest) Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 --- # Integrate VS Code with MCP | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/dbt-ai/integrate-mcp-vscode#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page [Microsoft Visual Studio Code (VS Code)](https://code.visualstudio.com/mcp) is a powerful and popular integrated development environment (IDE). These instructions are for integrating dbt MCP and VS Code. To get started, in VS Code: 1. Open the **Settings** menu and select the correct tab atop the page for your use case * **Workspace**: Configures the server in the context of your workspace * **User**: Configures the server in the context of your user **Note for WSL users**: If you're using VS Code with Windows Subsystem for Linux (WSL), you'll need to configure WSL-specific settings. Run the **Preferences: Open Remote Settings** command from the **Command Palette** (F1) or select the **Remote** tab in the **Settings** editor. Local user settings are reused in WSL but can be overridden with WSL-specific settings. Configuring MCP servers in the local user settings will not work properly in a WSL environment. 2. Select **Features** --> **Chat** 3. Ensure that **MCP** is **Enabled** [![mcp-vscode-settings](https://docs.getdbt.com/img/mcp/vscode_mcp_enabled_image.png?v=2 "mcp-vscode-settings")](https://docs.getdbt.com/docs/dbt-ai/integrate-mcp-vscode#) mcp-vscode-settings 4. Open the command palette `Control/Command + Shift + P`, and select either **MCP: Open Workspace Folder MCP Configuration** or **MCP: Open User Configuration**, depending on whether you want to install the MCP server for this workspace or all workspaces for the user. 5. Add your server configuration (`dbt`) to the provided `mcp.json` file as one of the servers: * Local MCP server * Remote MCP server { "servers": { "dbt": { "command": "uvx", "args": [ "--env-file", "", "dbt-mcp" ] } }} `` is where you saved the `.env` file from the Setup step { "mcpServers": { "dbt": { "url": "https:///api/ai/v1/mcp/", "headers": { "Authorization": "token ", "x-dbt-prod-environment-id": "", } } }} 6. You can start, stop, and configure your MCP servers by: * Running the `MCP: List Servers` command from the Command Palette (Control/Command + Shift + P) and selecting the server. * Utilizing the keywords inline within the `mcp.json` file. [![VS Code inline management](https://docs.getdbt.com/docs/dbt-ai/img/mcp/vscode_run_server_keywords_inline.png?v=2 "VS Code inline management")](https://docs.getdbt.com/docs/dbt-ai/integrate-mcp-vscode#) VS Code inline management Now you will be able to access the local dbt MCP server on VS Code through interfaces like GitHub Copilot. Resources[​](https://docs.getdbt.com/docs/dbt-ai/integrate-mcp-vscode#resources "Direct link to Resources") ------------------------------------------------------------------------------------------------------------ * Microsoft VS Code MCP [docs](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) . Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Resources](https://docs.getdbt.com/docs/dbt-ai/integrate-mcp-vscode#resources) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/dbt-ai/integrate-mcp-vscode.md) --- # Integrate Claude with dbt MCP | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/dbt-ai/integrate-mcp-claude#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page Claude is an AI assistant from Anthropic with two primary interfaces: * [Claude Code](https://www.anthropic.com/claude-code) : a terminal/IDE tool for development * [Claude for desktop](https://claude.ai/download) : a GUI with MCP support for file access and commands as well as basic coding features Claude Code[​](https://docs.getdbt.com/docs/dbt-ai/integrate-mcp-claude#claude-code "Direct link to Claude Code") ------------------------------------------------------------------------------------------------------------------ You can set up Claude Code with both the local and remote `dbt-mcp` server. We recommend using the local `dbt-mcp` for more developer-focused workloads. ### Setup with local dbt MCP server[​](https://docs.getdbt.com/docs/dbt-ai/integrate-mcp-claude#setup-with-local-dbt-mcp-server "Direct link to Setup with local dbt MCP server") Prerequisites: * Have an .env file with your environment variables * Local dbt-mcp setup 1. Run the following command to add the MCP server to Claude Code: claude mcp add dbt -- uvx --env-file dbt-mcp Remember to update the file path. ### Claude Code scopes[​](https://docs.getdbt.com/docs/dbt-ai/integrate-mcp-claude#claude-code-scopes "Direct link to Claude Code scopes") By default, the MCP server is installed in the "local" scope, meaning that it will be active for Claude Code sessions in the current directory for the user who installed it. It is also possible to install the MCP server: * In the "user" scope, to have it installed for all Claude Code sessions, independently of the directory used * In the "project" scope, to create a config file that can be version controlled so that all developers of the same project can have the MCP server already installed To install it in the project scope, run the following and commit the `.mcp.json` file. Be sure to use an env var file path that is the same for all users. claude mcp add dbt -s project -- uvx --env-file dbt-mcp More info on scopes [here](https://docs.anthropic.com/en/docs/claude-code/mcp#understanding-mcp-server-scopes) Claude for desktop[​](https://docs.getdbt.com/docs/dbt-ai/integrate-mcp-claude#claude-for-desktop "Direct link to Claude for desktop") --------------------------------------------------------------------------------------------------------------------------------------- 1. Go to the Claude settings. Click on the Claude menu in your system’s menu bar (not the settings within the Claude window itself) and select **Settings…** 2. In the Settings window, navigate to the **Developer** tab in the left sidebar. This section contains options for configuring MCP servers and other developer features. 3. Click the **Edit Config** button and open the configuration file with a text editor. 4. Replace the contents of the configuration file with [your correct JSON structure](https://modelcontextprotocol.io/quickstart/user#installing-the-filesystem-server) : For local MCP: { "mcpServers": { "dbt-mcp": { "command": "uvx", "args": [ "--env-file", ". If you're using Multi-cell, exclude the `ACCOUNT_PREFIX` from the hostname. The default is `cloud.getdbt.com` | | MULTICELL\_ACCOUNT\_PREFIX | Only required for Multi-cell instances | Set your Multi-cell `ACCOUNT_PREFIX`. If you are not using Multi-cell, don't set this value. You can learn more about regions and hosting [here](https://docs.getdbt.com/docs/cloud/about-cloud/access-regions-ip-addresses)
. | | DBT\_TOKEN | Required | Your personal access token or service token from the dbt platform.
**Note**: When using the Semantic Layer, it is recommended to use a personal access token. If you're using a service token, make sure that it has at least `Semantic Layer Only`, `Metadata Only`, and `Developer` permissions. | | DBT\_ACCOUNT\_ID | Required for Admininstrative API tools | Your [dbt account ID](https://docs.getdbt.com/faqs/Accounts/find-user-id) | | DBT\_PROD\_ENV\_ID | Required | Your dbt Cloud production environment ID | #### Additional configuration for SQL tools[​](https://docs.getdbt.com/docs/dbt-ai/setup-local-mcp#additional-configuration-for-sql-tools "Direct link to Additional configuration for SQL tools") | Environment Variable | Required | Description | | --- | --- | --- | | DBT\_DEV\_ENV\_ID | Optional | Your dbt Cloud development environment ID | | DBT\_USER\_ID | Optional | Your dbt Cloud user ID ([docs](https://docs.getdbt.com/faqs/Accounts/find-user-id)
) | #### Configuration for dbt CLI[​](https://docs.getdbt.com/docs/dbt-ai/setup-local-mcp#configuration-for-dbt-cli "Direct link to Configuration for dbt CLI") The local dbt-mcp supports all flavors of the dbt Engine, including dbt Core and dbt Fusion. | Environment Variable | Required | Description | Example | | --- | --- | --- | --- | | DBT\_PROJECT\_DIR | Required | The path to where the repository of your dbt project is hosted locally. | /Users/myname/reponame | | DBT\_PATH | Required | The path to your dbt executable (Core/Fusion/Cloud CLI). You can find your dbt executable by running `which dbt` | /opt/homebrew/bin/dbt | | DBT\_CLI\_TIMEOUT | Optional | Configure the number of seconds before your agent will timeout dbt CLI commands. | Defaults to 10 seconds. | You can set any environment variable supported by your dbt executable, like [for the ones supported in dbt Core](https://docs.getdbt.com/reference/global-configs/about-global-configs#available-flags) . We automatically set `DBT_WARN_ERROR_OPTIONS='{"error": ["NoNodesForSelectionCriteria"]}'` so that the MCP server knows if no node is selected when running a dbt command. You can overwrite it if needed, but it provides a better experience when calling dbt from the MCP server, ensuring the tool selects valid nodes. #### Disabling tools[​](https://docs.getdbt.com/docs/dbt-ai/setup-local-mcp#disabling-tools "Direct link to Disabling tools") We support disabling tool access on the local dbt-mcp. | Name | Default | Description | | --- | --- | --- | | `DISABLE_DBT_CLI` | `false` | Set this to `true` to disable dbt Core, dbt Cloud CLI, and dbt Fusion MCP tools | | `DISABLE_SEMANTIC_LAYER` | `false` | Set this to `true` to disable dbt Semantic Layer MCP tools | | `DISABLE_DISCOVERY` | `false` | Set this to `true` to disable dbt Discovery API MCP tools | | `DISABLE_ADMIN_API` | `false` | Set this to `true` to disable dbt Admininistrative API MCP tools | | `DISABLE_SQL` | `true` | Set this to `false` to enable SQL MCP tools | | `DISABLE_TOOLS` | "" | Set this to a list of tool names delimited by a `,` to disable specific tools | 3. After creating your .env file, you can move on to our guides on connecting dbt-mcp to tools like Claude Desktop or Cursor or to creating a configuration file. This is dependent on what tools you want to integrate with. ### Example configuration[​](https://docs.getdbt.com/docs/dbt-ai/setup-local-mcp#example-configuration "Direct link to Example configuration") For some tools, you may need an additional configuration file to upload to connect to dbt-mcp. Here is a sample configuration JSON file that you can use to connect to the MCP tools. Be sure to replace the sections within `<>`: { "mcpServers": { "dbt-mcp": { "command": "uvx", "args": [ "--env-file", "", "dbt-mcp" ] }, }} `` is where you saved the `.env` file from the Setup step. Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Setting environment variables](https://docs.getdbt.com/docs/dbt-ai/setup-local-mcp#setting-environment-variables) * [Example configuration](https://docs.getdbt.com/docs/dbt-ai/setup-local-mcp#example-configuration) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/dbt-ai/setup-local-mcp.md) --- # Set up remote MCP | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/dbt-ai/setup-remote-mcp#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) The remote server uses an HTTP connection and makes calls to dbt-mcp hosted on the cloud-based dbt platform. 1. Ensure that you have [AI Features](https://docs.getdbt.com/docs/cloud/enable-dbt-copilot) turned on. 2. Obtain the following information from dbt Platform: * **dbt Cloud host**: Use this to form the full URL. For example, replace `` here: `https:///api/ai/v1/mcp/`. It may look like: `https://cloud.getdbt.com/api/ai/v1/mcp/`. If you have a multi-cell account, the host URL will be in the `.us1.dbt.com` format. For more information, [check out our docs.](https://docs.getdbt.com/docs/cloud/about-cloud/access-regions-ip-addresses) * **Production environment ID**: This can be found on the `Orchestration` page of dbt Cloud. Use this to set an `x-dbt-prod-environment-id` header. * **Token**: Please generate either a personal access token or a service token. In terms of permissions, to fully utilize remote MCP, it must be configured with Semantic Layer and Developer permissions. 3. For the remote MCP, you will pass on headers through the JSON blob to configure required fields: **Configuration for APIs and SQL tools** | Header | Required | Description | | --- | --- | --- | | Token | Required | Your personal access token or service token from the dbt platform.
**Note**: When using the Semantic Layer, it is recommended to use a personal access token. If you're using a service token, make sure that it has at least `Semantic Layer Only`, `Metadata Only`, and `Developer` permissions. | | x-dbt-prod-environment-id | Required | Your dbt Cloud production environment ID | **Additional configuration for SQL tools** | Header | Required | Description | | --- | --- | --- | | x-dbt-dev-environment-id | Required for `execute_sql` | Your dbt Cloud development environment ID | | x-dbt-user-id | Required for `execute_sql` | Your dbt Cloud user ID ([docs](https://docs.getdbt.com/faqs/Accounts/find-user-id)
) | **Configuration to disable tools** | Header | Required | Description | | --- | --- | --- | | x-dbt-disable-tools | Optional | A comma-separated list of tools to disable. For instance: `get_all_models,text_to_sql,list_entities` | | x-dbt-disable-toolsets | Optional | A comma-separated list of toolsets to disable. For instance: `semantic_layer,sql,discovery` | 4. After establishing which headers you need, you can follow the examples [here](https://github.com/dbt-labs/dbt-mcp/tree/main/examples) to create your own agent. The MCP protocol is programming language and framework agnostic, so use whatever helps you build agents. Alternatively, you can connect the remote dbt MCP server to MCP clients that support header-based authentication. You can use this example Cursor configuration, replacing ``, ``, ``, ``, and `` with your information: { "mcpServers": { "dbt": { "url": "https:///api/ai/v1/mcp/", "headers": { "Authorization": "token ", "x-dbt-prod-environment-id": "", "x-dbt-user-id": "", "x-dbt-dev-environment-id": "" } } }} Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 --- # dbt Model Context Protocol | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/dbt-ai/about-mcp#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page As AI becomes more deeply integrated into data workflows, dbt users need a seamless way to access and integrate dbt's structured metadata and execution context effectively. This page provides an overview of dbt's MCP Server, which exposes this context, supporting use cases such as conversational access to data, agent-driven automation of dbt workflows, and AI-assisted development. The [dbt Model Context Protocol (MCP) server](https://github.com/dbt-labs/dbt-mcp) provides a standardized framework that enables users to seamlessly integrate AI applications with dbt-managed data assets regardless of the underlying data platforms. This ensures consistent, governed access to models, metrics, lineage, and freshness across various AI tools. The MCP server provides access to the dbt CLI, [API](https://docs.getdbt.com/docs/dbt-cloud-apis/overview) , the [Discovery API](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-api) , and [Semantic Layer](https://docs.getdbt.com/docs/use-dbt-semantic-layer/dbt-sl) . It provides access to private APIs, text-to-SQL, and SQL execution. For more information on MCP, have a look at [Get started with the Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) . Server Access[​](https://docs.getdbt.com/docs/dbt-ai/about-mcp#server-access "Direct link to Server Access") ------------------------------------------------------------------------------------------------------------- You can install dbt MCP locally or remotely: * [Local MCP server setup guide](https://docs.getdbt.com/docs/dbt-ai/setup-local-mcp) * [Remote MCP server setup guide](https://docs.getdbt.com/docs/dbt-ai/setup-remote-mcp) Available Tools[​](https://docs.getdbt.com/docs/dbt-ai/about-mcp#available-tools "Direct link to Available Tools") ------------------------------------------------------------------------------------------------------------------- ### Supported[​](https://docs.getdbt.com/docs/dbt-ai/about-mcp#supported "Direct link to Supported") The dbt MCP server has access to many parts of the dbt experience related to development, deployment, and discovery. Here are the categories of tools supported based on what form of the MCP Server you connect to as well as detailed information on exact commands or queries available to the LLM. | Tools | Local | Remote | | --- | --- | --- | | dbt CLI | ✅ | ❌ | | Semantic Layer | ✅ | ✅ | | SQL | ✅ | ✅ | | Metadata Discovery | ✅ | ✅ | | Administrative API | ✅ | ❌ | | Disable tools | ✅ | ✅ | Note that access to the Discovery API and the Semantic Layer API is limited depending on your [plan type](https://www.getdbt.com/pricing) . ### dbt CLI commands[​](https://docs.getdbt.com/docs/dbt-ai/about-mcp#dbt-cli-commands "Direct link to dbt CLI commands") * `build`: Executes models, tests, snapshots, and seeds in dependency order * `compile`: Generates executable SQL from models, tests, and analyses without running them * `docs`: Generates documentation for the dbt project * `ls` (list): Lists resources in the dbt project, such as models and tests * `parse`: Parses and validates the project’s files for syntax correctness * `run`: Executes models to materialize them in the database * `test`: Runs tests to validate data and model integrity * `show`: Runs a query against the data warehouse Allowing your client to utilize dbt commands through the MCP tooling could modify your data models, sources, and warehouse objects. Proceed only if you trust the client and understand the potential impact. ### Semantic Layer[​](https://docs.getdbt.com/docs/dbt-ai/about-mcp#semantic-layer "Direct link to Semantic Layer") To learn more about the dbt Semantic layer, click [here](https://docs.getdbt.com/docs/use-dbt-semantic-layer/dbt-sl) . * `list_metrics`: Retrieves all defined metrics * `get_dimensions`: Gets dimensions associated with specified metrics * `get_entities`: Gets entities associated with specified metrics * `query_metrics`: Query metrics with optional grouping, ordering, filtering, and limiting * `get_metrics_compiled_sql`: Returns the compiled SQL generated for specified metrics and groupings without executing the query ### Metadata Discovery[​](https://docs.getdbt.com/docs/dbt-ai/about-mcp#metadata-discovery "Direct link to Metadata Discovery") To learn more about the dbt Discovery API, click [here](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-api) . * `get_mart_models`: Gets all mart models * `get_all_models`: Gets all models * `get_model_details`: Gets details for a specific model * `get_model_parents`: Gets the parent nodes of a specific model * `get_model_children`: Gets the children models of a specific model * `get_model_health`: Gets health signals for a specific model * `get_exposures`: Gets all exposures * `get_exposure_details`: Gets details for a specific exposure or a list of exposures ### Administrative API[​](https://docs.getdbt.com/docs/dbt-ai/about-mcp#administrative-api "Direct link to Administrative API") To learn more about the dbt Administrative API, click [here](https://docs.getdbt.com/docs/dbt-cloud-apis/admin-cloud-api) . * `list_jobs`: List all jobs in a dbt account * `get_job_details`: Get detailed information for a specific job including configuration and settings * `trigger_job_run`: Trigger a job run with optional parameter overrides like Git branch, schema, or execution parameters * `list_jobs_runs`: List runs in an account with optional filtering by job, status, or other criteria * `get_job_run_details`: Get comprehensive run information including execution details, steps, artifacts, and debug logs * `cancel_job_run`: Cancel a running job to stop execution * `retry_job_run`: Retry a failed job run to attempt execution again * `list_job_run_artifacts`: List all available artifacts for a job run (manifest.json, catalog.json, logs, etc.) * `get_job_run_artifact`: Download specific artifact files from job runs for analysis or integration ### SQL[​](https://docs.getdbt.com/docs/dbt-ai/about-mcp#sql "Direct link to SQL") ⚠️ The SQL tools access the dbt platform endpoints. While MCP usage of the tools doesn't consume dbt Copilot credits, access to the tools is impacted by dbt Copilot credit overages from direct usage of Copilot in dbt. * `text_to_sql`: Generate SQL from natural language requests * `execute_sql`: Execute SQL on the dbt platform's backend infrastructure with support for Semantic Layer SQL syntax. Note: using a PAT instead of a service token for `DBT_TOKEN` is required for this tool. MCP integrations[​](https://docs.getdbt.com/docs/dbt-ai/about-mcp#mcp-integrations "Direct link to MCP integrations") ---------------------------------------------------------------------------------------------------------------------- The dbt MCP server integrates with any [MCP client](https://modelcontextprotocol.io/clients) that supports token authentication and tool use capabilities. We have also created integration guides for the following clients: * [Claude](https://docs.getdbt.com/docs/dbt-ai/integrate-mcp-claude) * [Cursor](https://docs.getdbt.com/docs/dbt-ai/integrate-mcp-cursor) * [VS Code](https://docs.getdbt.com/docs/dbt-ai/integrate-mcp-vscode) Troubleshooting[​](https://docs.getdbt.com/docs/dbt-ai/about-mcp#troubleshooting "Direct link to Troubleshooting") ------------------------------------------------------------------------------------------------------------------- * Some MCP clients may be unable to find `uvx` from the JSON config. This will result in error messages like `Could not connect to MCP server dbt-mcp`. If this happens, try finding the full path to `uvx` with `which uvx` on Unix systems and placing this full path in the JSON. For instance: `"command": "/the/full/path/to/uvx"`. Resources[​](https://docs.getdbt.com/docs/dbt-ai/about-mcp#resources "Direct link to Resources") ------------------------------------------------------------------------------------------------- * Refer to our blog on [Introducing the dbt MCP Server](https://docs.getdbt.com/blog/introducing-dbt-mcp-server#getting-started) for more information. Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Server Access](https://docs.getdbt.com/docs/dbt-ai/about-mcp#server-access) * [Available Tools](https://docs.getdbt.com/docs/dbt-ai/about-mcp#available-tools) * [Supported](https://docs.getdbt.com/docs/dbt-ai/about-mcp#supported) * [dbt CLI commands](https://docs.getdbt.com/docs/dbt-ai/about-mcp#dbt-cli-commands) * [Semantic Layer](https://docs.getdbt.com/docs/dbt-ai/about-mcp#semantic-layer) * [Metadata Discovery](https://docs.getdbt.com/docs/dbt-ai/about-mcp#metadata-discovery) * [Administrative API](https://docs.getdbt.com/docs/dbt-ai/about-mcp#administrative-api) * [SQL](https://docs.getdbt.com/docs/dbt-ai/about-mcp#sql) * [MCP integrations](https://docs.getdbt.com/docs/dbt-ai/about-mcp#mcp-integrations) * [Troubleshooting](https://docs.getdbt.com/docs/dbt-ai/about-mcp#troubleshooting) * [Resources](https://docs.getdbt.com/docs/dbt-ai/about-mcp#resources) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/dbt-ai/about-mcp.md) --- # Authentication tokens | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/dbt-cloud-apis/authentication#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page [![](https://docs.getdbt.com/img/icons/dbt-bit.svg)\ \ #### Personal access tokens\ \ Learn about user tokens and how to use them to execute queries against the dbt API.](https://docs.getdbt.com/docs/dbt-cloud-apis/user-tokens) [![](https://docs.getdbt.com/img/icons/dbt-bit.svg)\ \ #### Service account tokens\ \ Learn how to use service account tokens to securely authenticate with dbt APIs for system-level integrations.](https://docs.getdbt.com/docs/dbt-cloud-apis/service-tokens) Types of API access tokens[​](https://docs.getdbt.com/docs/dbt-cloud-apis/authentication#types-of-api-access-tokens "Direct link to Types of API access tokens") ----------------------------------------------------------------------------------------------------------------------------------------------------------------- **Personal access tokens:** Preferred and secure way of accessing dbt APIs on behalf of a user. PATs are scoped to an account and can be enhanced with more granularity and control. **Service tokens:** Service tokens are similar to service accounts and are the preferred method to enable access on behalf of the dbt account. ### Which token type should you use[​](https://docs.getdbt.com/docs/dbt-cloud-apis/authentication#which-token-type-should-you-use "Direct link to Which token type should you use") You should use service tokens broadly for any production workflow where you need a service account. You should use PATs only for developmental workflows _or_ dbt client workflows that require user context. The following examples show you when to use a personal access token (PAT) or a service token: * **Connecting a partner integration to dbt** — Some examples include the [Semantic Layer Google Sheets integration](https://docs.getdbt.com/docs/cloud-integrations/avail-sl-integrations) , Hightouch, Datafold, a custom app you’ve created, etc. These types of integrations should use a service token instead of a PAT because service tokens give you visibility, and you can scope them to only what the integration needs and ensure the least privilege. We highly recommend switching to a service token if you’re using a personal access token for these integrations today. * **Production Terraform** — Use a service token since this is a production workflow and is acting as a service account and not a user account. * **Cloud CLI** — Use a PAT since the Cloud CLI works within the context of a user (the user is making the requests and has to operate within the context of their user account). * **Testing a custom script and staging Terraform or Postman** — We recommend using a PAT as this is a developmental workflow and is scoped to the user making the changes. When you push this script or Terraform into production, use a service token instead. * **API endpoints requiring user context** — Use PATs to authenticate to any API endpoint that requires user context (for example, endpoints to create and update user credentials). Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Types of API access tokens](https://docs.getdbt.com/docs/dbt-cloud-apis/authentication#types-of-api-access-tokens) * [Which token type should you use](https://docs.getdbt.com/docs/dbt-cloud-apis/authentication#which-token-type-should-you-use) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/dbt-cloud-apis/authentication.md) --- # Query the Discovery API | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-querying#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page The Discovery API supports ad-hoc queries and integrations. If you are new to the API, refer to [About the Discovery API](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-api) for an introduction. Use the Discovery API to evaluate data pipeline health and project state across runs or at a moment in time. dbt Labs provide a default [GraphQL explorer](https://metadata.cloud.getdbt.com/graphql) for this API, enabling you to run queries and browse the schema. However, you can also use any GraphQL client of your choice to query the API. Since GraphQL describes the data in the API, the schema displayed in the GraphQL explorer accurately represents the graph and fields available to query. Prerequisites[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-querying#prerequisites "Direct link to Prerequisites") ------------------------------------------------------------------------------------------------------------------------------ * dbt [multi-tenant](https://docs.getdbt.com/docs/cloud/about-cloud/tenancy#multi-tenant) or [single tenant](https://docs.getdbt.com/docs/cloud/about-cloud/tenancy#single-tenant) account * You must be on an [Enterprise or Enterprise+ plan](https://www.getdbt.com/pricing/) * Your projects must be on a dbt [release tracks](https://docs.getdbt.com/docs/dbt-versions/cloud-release-tracks) or dbt version 1.0 or later. Refer to [Upgrade dbt version in Cloud](https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-version-in-cloud) to upgrade. Authorization[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-querying#authorization "Direct link to Authorization") ------------------------------------------------------------------------------------------------------------------------------ Currently, authorization of requests takes place [using a service token](https://docs.getdbt.com/docs/dbt-cloud-apis/service-tokens) . dbt admin users can generate a Metadata Only service token that is authorized to execute a specific query against the Discovery API. Once you've created a token, you can use it in the Authorization header of requests to the dbt Discovery API. Be sure to include the Token prefix in the Authorization header, or the request will fail with a `401 Unauthorized` error. Note that `Bearer` can be used instead of `Token` in the Authorization header. Both syntaxes are equivalent. Access the Discovery API[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-querying#access-the-discovery-api "Direct link to Access the Discovery API") --------------------------------------------------------------------------------------------------------------------------------------------------------------- 1. Create a [service account token](https://docs.getdbt.com/docs/dbt-cloud-apis/service-tokens) to authorize requests. dbt Admin users can generate a _Metadata Only_ service token, which can be used to execute a specific query against the Discovery API to authorize requests. 2. Find the API URL to use from the [Discovery API endpoints](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-querying#discovery-api-endpoints) table. 3. For specific query points, refer to the [schema documentation](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job) . Run queries using HTTP requests[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-querying#run-queries-using-http-requests "Direct link to Run queries using HTTP requests") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ You can run queries by sending a `POST` request to the Discovery API, making sure to replace: * `YOUR_API_URL` with the appropriate [Discovery API endpoint](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-querying#discovery-api-endpoints) for your region and plan. * `YOUR_TOKEN` in the Authorization header with your actual API token. Be sure to include the Token prefix. * `QUERY_BODY` with a GraphQL query, for example `{ "query": "", "variables": "" }` * `VARIABLES` with a dictionary of your GraphQL query variables, such as a job ID or a filter. * `ENDPOINT` with the endpoint you're querying, such as environment. curl 'YOUR_API_URL' \ -H 'authorization: Bearer YOUR_TOKEN' \ -H 'content-type: application/json' -X POST --data QUERY_BODY Python example: response = requests.post( 'YOUR_API_URL', headers={"authorization": "Bearer "+YOUR_TOKEN, "content-type": "application/json"}, json={"query": QUERY_BODY, "variables": VARIABLES})metadata = response.json()['data'][ENDPOINT] Every query will require an environment ID or job ID. You can get the ID from a dbt URL or using the Admin API. There are several illustrative example queries on this page. For more examples, refer to [Use cases and examples for the Discovery API](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-use-cases-and-examples) . Discovery API endpoints[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-querying#discovery-api-endpoints "Direct link to Discovery API endpoints") ------------------------------------------------------------------------------------------------------------------------------------------------------------ The following are the endpoints for accessing the Discovery API. Use the one that's appropriate for your region and plan. | Deployment type | Discovery API URL | | --- | --- | | North America multi-tenant | [https://metadata.cloud.getdbt.com/graphql](https://metadata.cloud.getdbt.com/graphql) | | EMEA multi-tenant | [https://metadata.emea.dbt.com/graphql](https://metadata.emea.dbt.com/graphql) | | APAC multi-tenant | [https://metadata.au.dbt.com/graphql](https://metadata.au.dbt.com/graphql) | | Multi-cell | `https://YOUR_ACCOUNT_PREFIX.metadata.REGION.dbt.com/graphql`

Replace `YOUR_ACCOUNT_PREFIX` with your specific account identifier and `REGION` with your location, which could be `us1.dbt.com`. | | Single-tenant | `https://metadata.YOUR_ACCESS_URL/graphql`

Replace `YOUR_ACCESS_URL` with your specific account prefix with the appropriate [Access URL](https://docs.getdbt.com/docs/cloud/about-cloud/access-regions-ip-addresses)
for your region and plan. | Reasonable use[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-querying#reasonable-use "Direct link to Reasonable use") --------------------------------------------------------------------------------------------------------------------------------- Discovery (GraphQL) API usage is subject to request rate and response size limits to maintain the performance and stability of the metadata platform and prevent abuse. Job-level endpoints are subject to query complexity limits. Nested nodes (like parents), code (like rawCode), and catalog columns are considered as most complex. Overly complex queries should be broken up into separate queries with only necessary fields included. dbt Labs recommends using the environment endpoint instead for most use cases to get the latest descriptive and result metadata for a dbt project. Retention limits[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-querying#retention-limits "Direct link to Retention limits") --------------------------------------------------------------------------------------------------------------------------------------- You can use the Discovery API to query data from the previous two months. For example, if today was April 1st, you could query data back to February 1st. Run queries with the GraphQL explorer[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-querying#run-queries-with-the-graphql-explorer "Direct link to Run queries with the GraphQL explorer") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ You can run ad-hoc queries directly in the [GraphQL API explorer](https://metadata.cloud.getdbt.com/graphql) and use the document explorer on the left-hand side to see all possible nodes and fields. Refer to the [Apollo explorer documentation](https://www.apollographql.com/docs/graphos/explorer/explorer) for setup and authorization information for GraphQL. 1. Access the [GraphQL API explorer](https://metadata.cloud.getdbt.com/graphql) and select fields you want to query. 2. Select **Variables** at the bottom of the explorer and replace any `null` fields with your unique values. 3. [Authenticate](https://www.apollographql.com/docs/graphos/explorer/connecting-authenticating#authentication) using Bearer auth with `YOUR_TOKEN`. Select **Headers** at the bottom of the explorer and select **+New header**. 4. Select **Authorization** in the **header key** dropdown list and enter your Bearer auth token in the **value** field. Remember to include the Token prefix. Your header key should be in this format: `{"Authorization": "Bearer }`. [![Enter the header key and Bearer auth token values](https://docs.getdbt.com/img/docs/dbt-cloud/discovery-api/graphql_header.jpg?v=2 "Enter the header key and Bearer auth token values")](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-querying#) Enter the header key and Bearer auth token values 1. Run your query by clicking the blue query button in the top right of the **Operation** editor (to the right of the query). You should see a successful query response on the right side of the explorer. [![Run queries using the Apollo Server GraphQL explorer](https://docs.getdbt.com/img/docs/dbt-cloud/discovery-api/graphql.jpg?v=2 "Run queries using the Apollo Server GraphQL explorer")](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-querying#) Run queries using the Apollo Server GraphQL explorer ### Fragments[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-querying#fragments "Direct link to Fragments") Use the [`... on`](https://www.apollographql.com/docs/react/data/fragments/) notation to query across lineage and retrieve results from specific node types. query ($environmentId: BigInt!, $first: Int!) { environment(id: $environmentId) { applied { models(first: $first, filter: { uniqueIds: "MODEL.PROJECT.MODEL_NAME" }) { edges { node { name ancestors(types: [Model, Source, Seed, Snapshot]) { ... on ModelAppliedStateNestedNode { name resourceType materializedType executionInfo { executeCompletedAt } } ... on SourceAppliedStateNestedNode { sourceName name resourceType freshness { maxLoadedAt } } ... on SnapshotAppliedStateNestedNode { name resourceType executionInfo { executeCompletedAt } } ... on SeedAppliedStateNestedNode { name resourceType executionInfo { executeCompletedAt } } } } } } } }} ### Pagination[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-querying#pagination "Direct link to Pagination") Querying large datasets can impact performance on multiple functions in the API pipeline. Pagination eases the burden by returning smaller data sets one page at a time. This is useful for returning a particular portion of the dataset or the entire dataset piece-by-piece to enhance performance. dbt utilizes cursor-based pagination, which makes it easy to return pages of constantly changing data. Use the `PageInfo` object to return information about the page. The available fields are: * `startCursor` string type — Corresponds to the first `node` in the `edge`. * `endCursor` string type — Corresponds to the last `node` in the `edge`. * `hasNextPage` boolean type — Whether or not there are more `nodes` after the returned results. There are connection variables available when making the query: * `first` integer type — Returns the first n `nodes` for each page, up to 500. * `after` string type — Sets the cursor to retrieve `nodes` after. It's best practice to set the `after` variable with the object ID defined in the `endCursor` of the previous page. Below is an example that returns the `first` 500 models `after` the specified Object ID in the variables. The `PageInfo` object returns where the object ID where the cursor starts, where it ends, and whether there is a next page. [![Example of pagination](https://docs.getdbt.com/img/Paginate.png?v=2 "Example of pagination")](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-querying#) Example of pagination Below is a code example of the `PageInfo` object: pageInfo { startCursor endCursor hasNextPage}totalCount # Total number of records across all pages ### Filters[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-querying#filters "Direct link to Filters") Filtering helps to narrow down the results of an API query. If you want to query and return only models and tests that are failing or find models that are taking too long to run, you can fetch execution details such as [`executionTime`](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-models#fields) , [`runElapsedTime`](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-models#fields) , or [`status`](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-models#fields) . This helps data teams monitor the performance of their models, identify bottlenecks, and optimize the overall data pipeline. Below is an example that filters for results of models that have succeeded on their `lastRunStatus`: [![Example of filtering](https://docs.getdbt.com/img/Filtering.png?v=2 "Example of filtering")](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-querying#) Example of filtering Below is an example that filters for models that have an error on their last run and tests that have failed: query ModelsAndTests($environmentId: BigInt!, $first: Int!) { environment(id: $environmentId) { applied { models(first: $first, filter: { lastRunStatus: error }) { edges { node { name executionInfo { lastRunId } } } } tests(first: $first, filter: { status: "fail" }) { edges { node { name executionInfo { lastRunId } } } } } }} Related content[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-querying#related-content "Direct link to Related content") ------------------------------------------------------------------------------------------------------------------------------------ * [Use cases and examples for the Discovery API](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-use-cases-and-examples) * [Schema](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job) Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Authorization](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-querying#authorization) * [Access the Discovery API](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-querying#access-the-discovery-api) * [Run queries using HTTP requests](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-querying#run-queries-using-http-requests) * [Discovery API endpoints](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-querying#discovery-api-endpoints) * [Reasonable use](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-querying#reasonable-use) * [Retention limits](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-querying#retention-limits) * [Run queries with the GraphQL explorer](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-querying#run-queries-with-the-graphql-explorer) * [Fragments](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-querying#fragments) * [Pagination](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-querying#pagination) * [Filters](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-querying#filters) * [Related content](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-querying#related-content) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/dbt-cloud-apis/discovery-querying.md) --- # About the Discovery API schema | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-about#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) With the Discovery API, you can query the metadata in dbt to learn more about your dbt deployments and the data they generate. You can analyze the data to make improvements. If you are new to the API, refer to [About the Discovery API](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-api) for an introduction. You might also find the [use cases and examples](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-use-cases-and-examples) helpful. The Discovery API _schema_ provides all the pieces necessary to query and interact with the Discovery API. The most common queries use the `environment` endpoint: [![](https://docs.getdbt.com/img/icons/dbt-bit.svg)\ \ #### Environment schema\ \ Query and compare a model’s definition (intended) and its applied (actual) state.](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment) [![](https://docs.getdbt.com/img/icons/dbt-bit.svg)\ \ #### Applied schema\ \ Query the actual state of objects and metadata in the warehouse after a \`dbt run\` or \`dbt build\`.](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied) [![](https://docs.getdbt.com/img/icons/dbt-bit.svg)\ \ #### Definition schema\ \ Query intended state in project code and configuration defined in your dbt project.](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-definition) [![](https://docs.getdbt.com/img/icons/dbt-bit.svg)\ \ #### Model Historical Runs schema\ \ Query information about a model's run history.](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied-modelHistoricalRuns) Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 --- # Environment object schema | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page You can use the environment object to query and compare definition (intended) and applied (actual) states for nodes (models, seeds, snapshots, models, and more) in your dbt project. For example, you specify an `environmentId` to learn more about a particular model (or other node type) in that environment. The [Example queries](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment#example-queries) illustrate a few fields you can query with this `environment` object. Refer to [Fields](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment#fields) to view the entire schema, which provides all possible fields you can query. ### Arguments[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment#arguments "Direct link to Arguments") When querying for `environment`, you can use the following arguments. Fetching data... ================ ### Example queries[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment#example-queries "Direct link to Example queries") You can use your production environment's `id`: query Example { environment(id: 834){ # Get the latest state of the production environment applied { # The state of an executed node as it exists as an object in the database models(first: 100){ # Pagination to ensure manageable response for large projects edges { node { uniqueId, name, description, rawCode, compiledCode, # Basic properties database, schema, alias, # Table/view identifier (can also filter by) executionInfo {executeCompletedAt, executionTime}, # Metadata from when the model was built tests {name, executionInfo{lastRunStatus, lastRunError}}, # Latest test results catalog {columns {name, description, type}, stats {label, value}}, # Catalog info ancestors(types:[Source]) {name, ...on SourceAppliedStateNode {freshness{maxLoadedAt, freshnessStatus}}}, # Source freshness } children {name, resourceType}}} # Immediate dependencies in lineage totalCount } # Number of models in the project } definition { # The logical state of a given project node given its most recent manifest generated models(first: 100, filter:{access:public}){ # Filter on model access (or other properties) edges { node { rawCode, # Compare to see if/how the model has changed since the last build jobDefinitionId, runGeneratedAt, # When the code was last compiled or run contractEnforced, group, version}}} # Model governance } } With the deprecation of the data type `Int` for `id`, below is an example of replacing it with `BigInt`: query ($environmentId: BigInt!, $first: Int!) { environment(id: $environmentId) { applied { models(first: $first) { edges { node { uniqueId executionInfo { lastRunId } } } } } }} With the deprecation of `modelByEnvironment`, below is an example of replacing it with `environment`: query ($environmentId: BigInt!, $uniqueId: String) { environment(id: $environmentId) { applied { modelHistoricalRuns(uniqueId: $uniqueId) { uniqueId executionTime executeCompletedAt } } }} ### Fields[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment#fields "Direct link to Fields") When querying an `environment`, you can use the following fields. Fetching data... ================ For details on querying the `applied` field of `environment`, you can visit: [Applied](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied) For details querying the `definition` field of `environment`, you can visit: [Definition](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-definition) Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Arguments](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment#arguments) * [Example queries](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment#example-queries) * [Fields](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment#fields) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/dbt-cloud-apis/schema-discovery-environment.mdx) --- # Tags object schema | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied-tags#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page [Tags](https://docs.getdbt.com/reference/resource-configs/tags) provide a mechanism to categorize and group resources within a dbt project, enabling selective execution and management of these resources. You can query tags through the Discovery API. The [Example query](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied-tags#example-query) illustrates a few fields you can query with the `tags` object. Refer to [Fields](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied-tags#fields) to view the entire schema, which provides all possible fields you can query. ### Example query[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied-tags#example-query "Direct link to Example query") You can use the `environmentId` to return the name of all the tags in your environment: query { environment(id: 834) { applied { tags { name } } }} ### Fields[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied-tags#fields "Direct link to Fields") When querying for `tags`, you can use the following fields: Fetching data... ================ Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Example query](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied-tags#example-query) * [Fields](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied-tags#fields) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/dbt-cloud-apis/schema-discovery-environment-applied-tags.mdx) --- # Resources object schema | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied-resources#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page The resources object allows you to paginate across all resources in your environment. The [Example query](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied-resources#example-query) illustrates a few fields you can query with the `resources` object. Refer to [Fields](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied-resources#fields) to view the entire schema, which provides all possible fields you can query. ### Arguments[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied-resources#arguments "Direct link to Arguments") When querying for `resources`, you can use the following arguments: Fetching data... ================ ### Example query[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied-resources#example-query "Direct link to Example query") You can specify the `environmentId`, filter by "Model" as the type, and limit to the first 100 results to see comprehensive information about the first 100 model resources in this environment, including their metadata, tags, and file locations: query { environment(id: 834) { applied { resources( filter: { types: [ Model ] }, first: 100 ) { edges { node { accountId description environmentId filePath meta name projectId resourceType uniqueId tags } } } } }} ### Fields[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied-resources#fields "Direct link to Fields") When querying for `resources`, you can use the following fields: Fetching data... ================ ### Key fields from nodes[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied-resources#key-fields-from-nodes "Direct link to Key fields from nodes") Fetching data... ================ Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Arguments](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied-resources#arguments) * [Example query](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied-resources#example-query) * [Fields](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied-resources#fields) * [Key fields from nodes](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied-resources#key-fields-from-nodes) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/dbt-cloud-apis/schema-discovery-environment-applied-resources.mdx) --- # Snapshots object schema | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied-snapshots#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page [Snapshots](https://docs.getdbt.com/docs/build/snapshots) represent point-in-time copies of your data, allowing you to track historical changes. You can query your snapshots from the Discovery API. The [Example query](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied-snapshots#example-query) illustrates a few fields you can query with the `snapshots` object. Refer to [Fields](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied-snapshots#fields) to view the entire schema, which provides all possible fields you can query. ### Arguments[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied-snapshots#arguments "Direct link to Arguments") When querying for `snapshots`, you can use the following arguments: Fetching data... ================ ### Example query[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied-snapshots#example-query "Direct link to Example query") You can specify the `environmentId`, filter by the database, and limit to the first 100 to see the first 100 snapshots in the `analytics` database, including their execution performance and status information: query { environment(id: 834) { applied { snapshots( filter: { database: "analytics" }, first: 100 ) { edges { node { executionInfo { compileCompletedAt compileStartedAt executeCompletedAt executeStartedAt executionTime lastRunStatus lastRunId } fqn name } } } } }} ### Fields[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied-snapshots#fields "Direct link to Fields") When querying for `snapshots`, you can use the following fields: Fetching data... ================ ### Key fields from nodes[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied-snapshots#key-fields-from-nodes "Direct link to Key fields from nodes") Fetching data... ================ Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Arguments](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied-snapshots#arguments) * [Example query](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied-snapshots#example-query) * [Fields](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied-snapshots#fields) * [Key fields from nodes](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied-snapshots#key-fields-from-nodes) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/dbt-cloud-apis/schema-discovery-environment-applied-snapshots.mdx) --- # Seeds object schema | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied-seeds#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page [Seeds](https://docs.getdbt.com/docs/build/seeds) are CSV files in your dbt project that dbt can load into your data warehouse. You can query seeds through the Discovery API. The [Example query](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied-seeds#example-query) illustrates a few fields you can query with the `seeds` object. Refer to [Fields](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied-seeds#fields) to view the entire schema, which provides all possible fields you can query. ### Arguments[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied-seeds#arguments "Direct link to Arguments") When querying for `seeds`, you can use the following arguments: Fetching data... ================ ### Example query[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied-seeds#example-query "Direct link to Example query") You can specify the `environmentId`, filter by the database, and limit to the first 100 to show information about the first 100 seed files in the `analytics` database, including their metadata and file locations: query ($environmentId: BigInt!, $first: Int!, $filter: GenericMaterializedFilter) { environment(id: $environmentId) { applied { seeds( first: 100, filter: { database: "analytics" } ) { edges { node { description name filePath projectId fqn tags uniqueId resourceType } } } } }} ### Fields[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied-seeds#fields "Direct link to Fields") When querying for `seeds`, you can use the following fields: Fetching data... ================ ### Key fields from nodes[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied-seeds#key-fields-from-nodes "Direct link to Key fields from nodes") Fetching data... ================ Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Arguments](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied-seeds#arguments) * [Example query](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied-seeds#example-query) * [Fields](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied-seeds#fields) * [Key fields from nodes](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied-seeds#key-fields-from-nodes) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/dbt-cloud-apis/schema-discovery-environment-applied-seeds.mdx) --- # Sources object schema | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied-sources#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page [Sources](https://docs.getdbt.com/docs/build/sources) make it possible to name and describe the data loaded into your warehouse by your extract and load tools. You can query sources through the Discovery API. The [Example query](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied-sources#example-query) illustrates a few fields you can query with the `sources` object. Refer to [Fields](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied-sources#fields) to view the entire schema, which provides all possible fields you can query. ### Arguments[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied-sources#arguments "Direct link to Arguments") When querying for `sources`, you can use the following arguments: Fetching data... ================ ### Example query[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied-sources#example-query "Direct link to Example query") You can specify the `environmentId` and filter on the database name, to return the freshness and execution status, for the first 100 sources from the given database: query { environment(id: 834) { applied { sources( filter: { database: "analytics" }, first: 100 ) { edges { node { name fqn description filePath freshness { freshnessChecked freshnessStatus } sourceName sourceDescription tests { name description testType executionInfo { lastRunStatus } } } } } } }} ### Fields[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied-sources#fields "Direct link to Fields") When querying for `sources`, you can use the following fields: Fetching data... ================ ### Key fields from nodes[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied-sources#key-fields-from-nodes "Direct link to Key fields from nodes") Fetching data... ================ Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Arguments](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied-sources#arguments) * [Example query](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied-sources#example-query) * [Fields](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied-sources#fields) * [Key fields from nodes](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied-sources#key-fields-from-nodes) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/dbt-cloud-apis/schema-discovery-environment-applied-sources.mdx) --- # Owners object schema | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied-owners#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page [Owners](https://docs.getdbt.com/docs/build/groups) help you identify the user or domain responsible for a dbt asset. For most assets, owners are defined in your project code using groups. Exposures are an exception: for downstream exposures that represent BI assets, owners are automatically pulled from the downstream tool based on who owns that asset. You can query ownership information through the Discovery API. The [Example query](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied-owners#example-query) illustrates a few fields you can query with the `owners` object. Refer to [Fields](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied-owners#fields) to view the entire schema, which provides all possible fields you can query. ### Arguments[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied-owners#arguments "Direct link to Arguments") When querying for `owners`, you can use the following arguments: Fetching data... ================ ### Example query[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied-owners#example-query "Direct link to Example query") You can specify the `environmentId` and "exposure" as the `OwnerResourceType` to return people who own exposures (downstream BI assets) in this environment, including their contact information. query { environment(id: 834) { applied { owners(resource: exposure) { email name } } }} ### Fields[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied-owners#fields "Direct link to Fields") When querying for `owners`, you can use the following fields: Fetching data... ================ Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Arguments](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied-owners#arguments) * [Example query](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied-owners#example-query) * [Fields](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied-owners#fields) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/dbt-cloud-apis/schema-discovery-environment-applied-owners.mdx) --- # What is dbt? | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/introduction#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page dbt is the industry standard for data transformation. Learn how it can help you transform data and deploy analytics code following software engineering best practices like version control, modularity, portability, CI/CD, and documentation. dbt is a transformation workflow that helps you get more work done while producing higher quality results. You can use dbt to modularize and centralize your analytics code, while also providing your data team with guardrails typically found in software engineering workflows. Collaborate on data models, version them, and test and document your queries before safely deploying them to production, with monitoring and visibility. dbt compiles and runs your analytics code against your data platform, enabling you and your team to collaborate on a single source of truth for metrics, insights, and business definitions. This single source of truth, combined with the ability to define tests for your data, reduces errors when logic changes, and alerts you when issues arise. [![dbt works alongside your ingestion, visualization, and other data tools, so you can transform data directly in your cloud data platform.](https://docs.getdbt.com/img/docs/cloud-overview.jpg?v=2 "dbt works alongside your ingestion, visualization, and other data tools, so you can transform data directly in your cloud data platform.")](https://docs.getdbt.com/docs/introduction#) dbt works alongside your ingestion, visualization, and other data tools, so you can transform data directly in your cloud data platform. Read more about why we want to enable analysts to work more like software engineers in [The dbt Viewpoint](https://docs.getdbt.com/community/resources/viewpoint) . Learn how other data practitioners around the world are using dbt by [joining the dbt Community](https://www.getdbt.com/community/join-the-community) . dbt[​](https://docs.getdbt.com/docs/introduction#dbt "Direct link to dbt") --------------------------------------------------------------------------- Use dbt to quickly and collaboratively transform data and deploy analytics code following software engineering best practices like version control, modularity, portability, CI/CD, and documentation. This means anyone on the data team comfortable with SQL can safely contribute to production-grade data pipelines. ### The dbt platform[​](https://docs.getdbt.com/docs/introduction#the-dbt-platform "Direct link to The dbt platform") The dbt platform offers the fastest, most reliable, and scalable way to deploy dbt. Allowing data teams to optimize their data transformation by developing, testing, scheduling, and investigating data models using a single, fully managed service through a web-based user interface (UI). You can learn about plans and pricing on [www.getdbt.com](https://www.getdbt.com/pricing/) . Learn more about the [dbt platform features](https://docs.getdbt.com/docs/cloud/about-cloud/dbt-cloud-features) and try one of the [dbt quickstarts](https://docs.getdbt.com/docs/get-started-dbt) . ### The dbt Fusion engine[​](https://docs.getdbt.com/docs/introduction#the-dbt-fusion-engine "Direct link to The dbt Fusion engine") The dbt Fusion Engine is the next-generation dbt engine, designed to deliver data teams a lightning-fast development experience, intelligent cost savings, and improved governance. For more information, refer to [About the dbt Fusion Engine](https://docs.getdbt.com/docs/fusion/about-fusion) , [supported features](https://docs.getdbt.com/docs/fusion/about-fusion) , and the [installation instructions](https://docs.getdbt.com/docs/fusion/install-fusion) . ### dbt Core[​](https://docs.getdbt.com/docs/introduction#dbt-core "Direct link to dbt Core") [dbt Core](https://docs.getdbt.com/docs/about-setup) is an open-source tool that enables data practitioners to transform data and is suitable for users who prefer to manually set up dbt and locally maintain it. You can [install dbt Core](https://docs.getdbt.com/docs/core/installation-overview) through the command line. Learn more with the [quickstart for dbt Core](https://docs.getdbt.com/guides/duckdb?step=1) . dbt optimizes your workflow[​](https://docs.getdbt.com/docs/introduction#dbt-optimizes-your-workflow "Direct link to dbt optimizes your workflow") --------------------------------------------------------------------------------------------------------------------------------------------------- * Avoid writing boilerplate DML and DDL by managing transactions, dropping tables, and managing schema changes. Write business logic with just a SQL `select` statement, or a Python DataFrame, that returns the dataset you need, and dbt takes care of materialization. * Build up reusable, or modular, data models that can be referenced in subsequent work instead of starting at the raw data with every analysis. * Dramatically reduce the time your queries take to run: Leverage metadata to find long-running models that you want to optimize and use [incremental models](https://docs.getdbt.com/docs/build/incremental-models) which dbt makes easy to configure and use. * Write DRYer code by leveraging [macros](https://docs.getdbt.com/docs/build/jinja-macros) , [hooks](https://docs.getdbt.com/docs/build/hooks-operations) , and [package management](https://docs.getdbt.com/docs/build/packages) . dbt provides more reliable analysis[​](https://docs.getdbt.com/docs/introduction#dbt-provides-more-reliable-analysis "Direct link to dbt provides more reliable analysis") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- * No longer copy and paste SQL, which can lead to errors when logic changes. Instead, build reusable data models that get pulled into subsequent models and analysis. Change a model once and that change will propagate to all its dependencies. * Publish the canonical version of a particular data model, encapsulating all complex business logic. All analysis on top of this model will incorporate the same business logic without needing to reimplement it. * Use mature source control processes like branching, pull requests, and code reviews. * Write data quality tests quickly and easily on the underlying data. Many analytic errors are caused by edge cases in the data: testing helps analysts find and handle those edge cases. The power of dbt[​](https://docs.getdbt.com/docs/introduction#the-power-of-dbt "Direct link to The power of dbt") ------------------------------------------------------------------------------------------------------------------ As a dbt user, your main focus will be on writing models (select queries) that reflect core business logic – there’s no need to write boilerplate code to create tables and views, or to define the order of execution of your models. Instead, dbt handles turning these models into objects in your warehouse for you. | Feature | Description | | --- | --- | | Handle boilerplate code to materialize queries as relations | For each model you create, you can easily configure a _materialization_. A materialization represents a build strategy for your select query – the code behind a materialization is robust, boilerplate SQL that wraps your select query in a statement to create a new, or update an existing, relation. Read more about [Materializations](https://docs.getdbt.com/docs/build/materializations)
. | | Use a code compiler | SQL files can contain Jinja, a lightweight templating language. Using Jinja in SQL provides a way to use control structures in your queries. For example, `if` statements and `for` loops. It also enables repeated SQL to be shared through `macros`. Read more about [Macros](https://docs.getdbt.com/docs/build/jinja-macros)
. | | Determine the order of model execution | Often, when transforming data, it makes sense to do so in a staged approach. dbt provides a mechanism to implement transformations in stages through the [ref function](https://docs.getdbt.com/reference/dbt-jinja-functions/ref)
. Rather than selecting from existing tables and views in your warehouse, you can select from another model. | | Document your dbt project | In the dbt platform, you can auto-generate the documentation when your dbt project runs. dbt provides a mechanism to write, version-control, and share documentation for your dbt models. You can write descriptions (in plain text or markdown) for each model and field. Read more about the [Documentation](https://docs.getdbt.com/docs/build/documentation)
. | | Test your models | Tests provide a way to improve the integrity of the SQL in each model by making assertions about the results generated by a model. Build, test, and run your project with a button click or by using the [Studio IDE](https://docs.getdbt.com/docs/cloud/dbt-cloud-ide/develop-in-the-cloud)
command bar. Read more about writing tests for your models [Testing](https://docs.getdbt.com/docs/build/data-tests) | | Manage packages | dbt ships with a package manager, which allows analysts to use and publish both public and private repositories of dbt code which can then be referenced by others. Read more about [Package Management](https://docs.getdbt.com/docs/build/packages)
. | | Load seed files | Often in analytics, raw values need to be mapped to a more readable value (for example, converting a country-code to a country name) or enriched with static or infrequently changing data. These data sources, known as seed files, can be saved as a CSV file in your `project` and loaded into your data warehouse using the `seed` command. Read more about [Seeds](https://docs.getdbt.com/docs/build/seeds)
. | | Snapshot data | Often, records in a data source are mutable, in that they change over time. This can be difficult to handle in analytics if you want to reconstruct historic values. dbt provides a mechanism to snapshot raw data for a point in time, through use of [snapshots](https://docs.getdbt.com/docs/build/snapshots)
. | Related docs[​](https://docs.getdbt.com/docs/introduction#related-docs "Direct link to Related docs") ------------------------------------------------------------------------------------------------------ * [Quickstarts for dbt](https://docs.getdbt.com/guides) * [Best practice guides](https://docs.getdbt.com/best-practices) * [What is a dbt Project?](https://docs.getdbt.com/docs/build/projects) * [dbt run](https://docs.getdbt.com/docs/running-a-dbt-project/run-your-dbt-projects) Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [dbt](https://docs.getdbt.com/docs/introduction#dbt) * [The dbt platform](https://docs.getdbt.com/docs/introduction#the-dbt-platform) * [The dbt Fusion engine](https://docs.getdbt.com/docs/introduction#the-dbt-fusion-engine) * [dbt Core](https://docs.getdbt.com/docs/introduction#dbt-core) * [dbt optimizes your workflow](https://docs.getdbt.com/docs/introduction#dbt-optimizes-your-workflow) * [dbt provides more reliable analysis](https://docs.getdbt.com/docs/introduction#dbt-provides-more-reliable-analysis) * [The power of dbt](https://docs.getdbt.com/docs/introduction#the-power-of-dbt) * [Related docs](https://docs.getdbt.com/docs/introduction#related-docs) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/introduction.md) --- # Explore your data | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/explore/explore-your-data#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) dbt provides a variety of tools for you to explore your data, models, and other resources. Many of the features you'd traditionally use your data warehouse services to explore are at your fingertips in your dbt account. [![](https://docs.getdbt.com/img/icons/dbt-bit.svg)\ \ #### dbt Catalog\ \ Interact with dbt Catalog to understand, improve, and leverage your dbt projects.](https://docs.getdbt.com/docs/explore/explore-projects) [![](https://docs.getdbt.com/img/icons/dbt-bit.svg)\ \ #### dbt Insights\ \ Query data and perform exploratory data analysis using dbt Insights](https://docs.getdbt.com/docs/explore/dbt-insights) [![](https://docs.getdbt.com/img/icons/dbt-bit.svg)\ \ #### Documentation\ \ Document your dbt projects so stakeholders, engineers, and analysts can understand your resources and lineage from start to finish.](https://docs.getdbt.com/docs/explore/build-and-view-your-docs) Some features are only available on [selected plans](https://www.getdbt.com/pricing/) . Related docs[​](https://docs.getdbt.com/docs/explore/explore-your-data#related-docs "Direct link to Related docs") ------------------------------------------------------------------------------------------------------------------- * [dbt plans and pricing](https://www.getdbt.com/pricing/) * [Quickstart guides](https://docs.getdbt.com/docs/get-started-dbt) * [Reference material](https://docs.getdbt.com/reference/references-overview) Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 --- # dbt Semantic Layer | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/use-dbt-semantic-layer/dbt-sl#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page The dbt Semantic Layer eliminates duplicate coding by allowing data teams to define metrics on top of existing models and automatically handling data joins. The dbt Semantic Layer, powered by [MetricFlow](https://docs.getdbt.com/docs/build/about-metricflow) , simplifies the process of defining and using critical business metrics, like `revenue` in the modeling layer (your dbt project). By centralizing metric definitions, data teams can ensure consistent self-service access to these metrics in downstream data tools and applications. Moving metric definitions out of the BI layer and into the modeling layer allows data teams to feel confident that different business units are working from the same metric definitions, regardless of their tool of choice. If a metric definition changes in dbt, it’s refreshed everywhere it’s invoked and creates consistency across all applications. To ensure secure access control, the Semantic Layer implements robust [access permissions](https://docs.getdbt.com/docs/use-dbt-semantic-layer/setup-sl#set-up-dbt-semantic-layer) mechanisms. Refer to the [Semantic Layer FAQs](https://docs.getdbt.com/docs/use-dbt-semantic-layer/sl-faqs) or [Why we need a universal semantic layer](https://www.getdbt.com/blog/universal-semantic-layer/) blog post to learn more. Get started with the dbt Semantic Layer[​](https://docs.getdbt.com/docs/use-dbt-semantic-layer/dbt-sl#get-started-with-the-dbt-semantic-layer "Direct link to Get started with the dbt Semantic Layer") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- To define and query metrics with the dbt Semantic Layer, you must be on a [dbt Starter or Enterprise-tier](https://www.getdbt.com/pricing/) account. [](https://docs.getdbt.com/docs/cloud/about-cloud/access-regions-ip-addresses) Suitable for both Multi-tenant and Single-tenant accounts. Note: Single-tenant accounts should contact their account representative for necessary setup and enablement. Not yet supported in the dbt Fusion engine Semantic Layer is currently supported in the dbt platform for environments running versions of dbt Core. Support for environments on the dbt Fusion engine is coming soon. This page points to various resources available to help you understand, configure, deploy, and integrate the Semantic Layer. The following sections contain links to specific pages that explain each aspect in detail. Use these links to navigate directly to the information you need, whether you're setting up the Semantic Layer for the first time, deploying metrics, or integrating with downstream tools. Refer to the following resources to get started with the Semantic Layer: * [Quickstart with the Semantic Layer](https://docs.getdbt.com/guides/sl-snowflake-qs) — Build and define metrics, set up the Semantic Layer, and query them using our first-class integrations. * [Build your metrics](https://docs.getdbt.com/docs/build/build-metrics-intro) — Use MetricFlow in dbt to centrally define your metrics. * [Semantic Layer FAQs](https://docs.getdbt.com/docs/use-dbt-semantic-layer/sl-faqs) — Discover answers to frequently asked questions about the Semantic Layer, such as availability, integrations, and more. Configure the dbt Semantic Layer[​](https://docs.getdbt.com/docs/use-dbt-semantic-layer/dbt-sl#configure-the-dbt-semantic-layer "Direct link to Configure the dbt Semantic Layer") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The following resources provide information on how to configure the Semantic Layer: * [Administer the Semantic Layer](https://docs.getdbt.com/docs/use-dbt-semantic-layer/setup-sl) — Seamlessly set up the credentials and tokens to start querying the Semantic Layer. * [Architecture](https://docs.getdbt.com/docs/use-dbt-semantic-layer/sl-architecture) — Explore the powerful components that make up the Semantic Layer. Deploy metrics[​](https://docs.getdbt.com/docs/use-dbt-semantic-layer/dbt-sl#deploy-metrics "Direct link to Deploy metrics") ----------------------------------------------------------------------------------------------------------------------------- This section provides information on how to deploy the Semantic Layer and materialize your metrics: * [Deploy your Semantic Layer](https://docs.getdbt.com/docs/use-dbt-semantic-layer/deploy-sl) — Run a dbt job to deploy the Semantic Layer and materialize your metrics. * [Write queries with exports](https://docs.getdbt.com/docs/use-dbt-semantic-layer/exports) — Use exports to write commonly used queries directly within your data platform, on a schedule. * [Cache common queries](https://docs.getdbt.com/docs/use-dbt-semantic-layer/sl-cache) — Leverage result caching and declarative caching for common queries to speed up performance and reduce query computation. Consume metrics and integrate[​](https://docs.getdbt.com/docs/use-dbt-semantic-layer/dbt-sl#consume-metrics-and-integrate "Direct link to Consume metrics and integrate") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Consume metrics and integrate the Semantic Layer with downstream tools and applications: * [Consume metrics](https://docs.getdbt.com/docs/use-dbt-semantic-layer/consume-metrics) — Query and consume metrics in downstream tools and applications using the Semantic Layer. * [Available integrations](https://docs.getdbt.com/docs/cloud-integrations/avail-sl-integrations) — Review a wide range of partners you can integrate and query with the Semantic Layer. * [Semantic Layer APIs](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-api-overview) — Use the Semantic Layer APIs to query metrics in downstream tools for consistent, reliable data metrics. Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Get started with the dbt Semantic Layer](https://docs.getdbt.com/docs/use-dbt-semantic-layer/dbt-sl#get-started-with-the-dbt-semantic-layer) * [Configure the dbt Semantic Layer](https://docs.getdbt.com/docs/use-dbt-semantic-layer/dbt-sl#configure-the-dbt-semantic-layer) * [Deploy metrics](https://docs.getdbt.com/docs/use-dbt-semantic-layer/dbt-sl#deploy-metrics) * [Consume metrics and integrate](https://docs.getdbt.com/docs/use-dbt-semantic-layer/dbt-sl#consume-metrics-and-integrate) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/use-dbt-semantic-layer/dbt-sl.md) --- # Frequently asked questions | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/faqs#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) [🗃️ Accounts\ ------------\ \ 11 items](https://docs.getdbt.com/category/accounts) [🗃️ dbt Core\ ------------\ \ 3 items](https://docs.getdbt.com/category/dbt-core) [🗃️ Documentation\ -----------------\ \ 6 items](https://docs.getdbt.com/category/documentation) [🗃️ Environments\ ----------------\ \ 6 items](https://docs.getdbt.com/category/environments) [🗃️ Git\ -------\ \ 9 items](https://docs.getdbt.com/category/git) [🗃️ Jinja\ ---------\ \ 3 items](https://docs.getdbt.com/category/jinja) [🗃️ Models\ ----------\ \ 12 items](https://docs.getdbt.com/category/models) [🗃️ Projects\ ------------\ \ 24 items](https://docs.getdbt.com/category/projects) [🗃️ Project\_ref\ ----------------\ \ 2 items](https://docs.getdbt.com/faqs/Project_ref/define-private-packages) [🗃️ Runs\ --------\ \ 8 items](https://docs.getdbt.com/category/runs) [🗃️ Seeds\ ---------\ \ 8 items](https://docs.getdbt.com/category/seeds) [🗃️ Snapshots\ -------------\ \ 4 items](https://docs.getdbt.com/category/snapshots) [🗃️ Tests\ ---------\ \ 9 items](https://docs.getdbt.com/category/tests) [🗃️ Troubleshooting\ -------------------\ \ 22 items](https://docs.getdbt.com/category/troubleshooting) [🗃️ Warehouse\ -------------\ \ 8 items](https://docs.getdbt.com/category/warehouse) --- # Deploy dbt | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/deploy/deployments#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) Use dbt's capabilities to seamlessly run a dbt job in production or staging environments. Rather than run dbt commands manually from the command line, you can leverage the [dbt's in-app scheduling](https://docs.getdbt.com/docs/deploy/job-scheduler) to automate how and when you execute dbt. The dbt platform offers the easiest and most reliable way to run your dbt project in production. Effortlessly promote high quality code from development to production and build fresh data assets that your business intelligence tools and end users query to make business decisions. Deploying with dbt lets you: * Keep production data fresh on a timely basis * Ensure CI and production pipelines are efficient * Identify the root cause of failures in deployment environments * Maintain high-quality code and data in production * Gain visibility into the [health](https://docs.getdbt.com/docs/explore/data-tile) of deployment jobs, models, and tests * Uses [exports](https://docs.getdbt.com/docs/use-dbt-semantic-layer/exports) to write [saved queries](https://docs.getdbt.com/docs/build/saved-queries) in your data platform for reliable and fast metric reporting * [Visualize](https://docs.getdbt.com/docs/cloud-integrations/downstream-exposures-tableau) and [orchestrate](https://docs.getdbt.com/docs/cloud-integrations/orchestrate-exposures) downstream exposures to understand how models are used in downstream tools and proactively refresh the underlying data sources during scheduled dbt jobs. [Enterprise](https://www.getdbt.com/pricing "Go to https://www.getdbt.com/pricing") [Enterprise +](https://www.getdbt.com/pricing "Go to https://www.getdbt.com/pricing") * Use [dbt's Git repository caching](https://docs.getdbt.com/docs/cloud/account-settings#git-repository-caching) to protect against third-party outages and improve job run reliability. [Enterprise](https://www.getdbt.com/pricing "Go to https://www.getdbt.com/pricing") [Enterprise +](https://www.getdbt.com/pricing "Go to https://www.getdbt.com/pricing") * Use [Hybrid projects](https://docs.getdbt.com/docs/deploy/hybrid-projects) to upload dbt artifacts into the dbt platform for central visibility, cross-project referencing, and easier collaboration. [Enterprise +](https://www.getdbt.com/pricing "Go to https://www.getdbt.com/pricing") Preview Before continuing, make sure you understand dbt's approach to [deployment environments](https://docs.getdbt.com/docs/deploy/deploy-environments) . Learn how to use dbt's features to help your team ship timely and quality production data more easily. Deploy with dbt[​](https://docs.getdbt.com/docs/deploy/deployments#deploy-with-dbt "Direct link to Deploy with dbt") --------------------------------------------------------------------------------------------------------------------- [![](https://docs.getdbt.com/img/icons/dbt-bit.svg)\ \ #### Job scheduler\ \ The job scheduler is the backbone of running jobs in the dbt platform, bringing power and simplicity to building data pipelines in both continuous integration and production environments.](https://docs.getdbt.com/docs/deploy/job-scheduler) [![](https://docs.getdbt.com/img/icons/dbt-bit.svg)\ \ #### Deploy jobs\ \ Create and schedule jobs for the job scheduler to run. \ \ Runs on a schedule, by API, or after another job completes.](https://docs.getdbt.com/docs/deploy/deploy-jobs) [![](https://docs.getdbt.com/img/icons/dbt-bit.svg)\ \ #### State-aware orchestration\ \ Intelligently determines which models to build by detecting changes in code or data at each job run.](https://docs.getdbt.com/docs/deploy/state-aware-about) [![](https://docs.getdbt.com/img/icons/dbt-bit.svg)\ \ #### Continuous integration\ \ Set up CI checks so you can build and test any modified code in a staging environment when you open PRs and push new commits to your dbt repository.](https://docs.getdbt.com/docs/deploy/continuous-integration) [![](https://docs.getdbt.com/img/icons/dbt-bit.svg)\ \ #### Continuous deployment\ \ Set up merge jobs to ensure the latest code changes are always in production when pull requests are merged to your Git repository.](https://docs.getdbt.com/docs/deploy/continuous-deployment) [![](https://docs.getdbt.com/img/icons/dbt-bit.svg)\ \ #### Job commands\ \ Configure which dbt commands to execute when running a dbt job.](https://docs.getdbt.com/docs/deploy/job-commands) Monitor jobs and alerts[​](https://docs.getdbt.com/docs/deploy/deployments#monitor-jobs-and-alerts "Direct link to Monitor jobs and alerts") --------------------------------------------------------------------------------------------------------------------------------------------- [![](https://docs.getdbt.com/img/icons/dbt-bit.svg)\ \ #### Visualize and orchestrate exposures\ \ Learn how to use dbt to automatically generate downstream exposures from dashboards and proactively refresh the underlying data sources during scheduled dbt jobs.](https://docs.getdbt.com/docs/deploy/orchestrate-exposures) [![](https://docs.getdbt.com/img/icons/dbt-bit.svg)\ \ #### Artifacts\ \ dbt generates and saves artifacts for your project, which it uses to power features like creating docs for your project and reporting the freshness of your sources.](https://docs.getdbt.com/docs/deploy/artifacts) [![](https://docs.getdbt.com/img/icons/dbt-bit.svg)\ \ #### Job notifications\ \ Receive email or Slack channel notifications when a job run succeeds, fails, or is canceled so you can respond quickly and begin remediation if necessary.](https://docs.getdbt.com/docs/deploy/job-notifications) [![](https://docs.getdbt.com/img/icons/dbt-bit.svg)\ \ #### Model notifications\ \ Receive email notifications in real time about issues encountered by your models and tests while a job is running.](https://docs.getdbt.com/docs/deploy/model-notifications) [![](https://docs.getdbt.com/img/icons/dbt-bit.svg)\ \ #### Run visibility\ \ View the history of your runs and the model timing dashboard to help identify where improvements can be made to the scheduled jobs.](https://docs.getdbt.com/docs/deploy/run-visibility) [![](https://docs.getdbt.com/img/icons/dbt-bit.svg)\ \ #### Retry jobs\ \ Rerun your errored jobs from start or the failure point.](https://docs.getdbt.com/docs/deploy/retry-jobs) [![](https://docs.getdbt.com/img/icons/dbt-bit.svg)\ \ #### Source freshness\ \ Enable snapshots to capture the freshness of your data sources and configure how frequent these snapshots should be taken. This can help you determine whether your source data freshness is meeting your SLAs.](https://docs.getdbt.com/docs/deploy/source-freshness) [![](https://docs.getdbt.com/img/icons/dbt-bit.svg)\ \ #### Webhooks\ \ Create outbound webhooks to send events about your dbt jobs' statuses to other systems in your organization.](https://docs.getdbt.com/docs/deploy/webhooks) Hybrid projects [Enterprise](https://www.getdbt.com/pricing "Go to https://www.getdbt.com/pricing") Preview[​](https://docs.getdbt.com/docs/deploy/deployments#hybrid-projects-- "Direct link to hybrid-projects--") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- [![](https://docs.getdbt.com/img/icons/dbt-bit.svg)\ \ #### Hybrid projects\ \ Use Hybrid projects to upload dbt Core artifacts into the dbt platform for central visibility, cross-project referencing, and easier collaboration.](https://docs.getdbt.com/docs/deploy/hybrid-projects) Related docs[​](https://docs.getdbt.com/docs/deploy/deployments#related-docs "Direct link to Related docs") ------------------------------------------------------------------------------------------------------------ * [Use exports to materialize saved queries](https://docs.getdbt.com/docs/use-dbt-semantic-layer/exports) * [Integrate with other orchestration tools](https://docs.getdbt.com/docs/deploy/deployment-tools) Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 --- # Job scheduler | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/deploy/job-scheduler#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page The job scheduler is the backbone of running jobs in dbt, bringing power and simplicity to building data pipelines in both continuous integration and production contexts. The scheduler frees teams from having to build and maintain their own infrastructure, and ensures the timeliness and reliability of data transformations. The scheduler enables both cron-based and event-driven execution of dbt commands in the user’s data platform. Specifically, it handles: * Cron-based execution of dbt jobs that run on a predetermined cadence * Event-driven execution of dbt jobs that run based on the completion of another job ([trigger on job completion](https://docs.getdbt.com/docs/deploy/deploy-jobs#trigger-on-job-completion) ) * Event-driven execution of dbt CI jobs triggered when a pull request is merged to the branch ([merge jobs](https://docs.getdbt.com/docs/deploy/merge-jobs) ) * Event-driven execution of dbt jobs triggered by API * Event-driven execution of dbt jobs manually triggered by a user to **Run now** The scheduler handles various tasks including: * Queuing jobs * Creating temporary environments to run the dbt commands required for those jobs * Providing logs for debugging and remediation * Storing dbt artifacts for direct consumption/ingestion by the Discovery API The scheduler also: * Uses [dbt's Git repository caching](https://docs.getdbt.com/docs/cloud/account-settings#git-repository-caching) to protect against third-party outages and improve job run reliability. [Enterprise](https://www.getdbt.com/pricing "Go to https://www.getdbt.com/pricing") [Enterprise +](https://www.getdbt.com/pricing "Go to https://www.getdbt.com/pricing") * Powers running dbt in staging and production environments, bringing ease and confidence to CI/CD workflows and enabling observability and governance in deploying dbt at scale. * Uses [Hybrid projects](https://docs.getdbt.com/docs/deploy/hybrid-projects) to upload dbt Core artifacts into dbt for central visibility, cross-project referencing, and easier collaboration. [beta](https://docs.getdbt.com/docs/dbt-versions/product-lifecycles "Go to https://docs.getdbt.com/docs/dbt-versions/product-lifecycles") [Enterprise +](https://www.getdbt.com/pricing "Go to https://www.getdbt.com/pricing") * Uses [state-aware orchestration](https://docs.getdbt.com/docs/deploy/state-aware-about) to decide what needs to be rebuilt based on source freshness, model staleness, and code changes. [beta](https://docs.getdbt.com/docs/dbt-versions/product-lifecycles "Go to https://docs.getdbt.com/docs/dbt-versions/product-lifecycles") [Enterprise](https://www.getdbt.com/pricing "Go to https://www.getdbt.com/pricing") [Enterprise +](https://www.getdbt.com/pricing "Go to https://www.getdbt.com/pricing") Scheduler terms[​](https://docs.getdbt.com/docs/deploy/job-scheduler#scheduler-terms "Direct link to Scheduler terms") ----------------------------------------------------------------------------------------------------------------------- Familiarize yourself with these useful terms to help you understand how the job scheduler works. | Term | Definition | | --- | --- | | Scheduler | The dbt engine that powers job execution. The scheduler queues scheduled or API-triggered job runs, prepares an environment to execute job commands in your cloud data platform, and stores and serves logs and artifacts that are byproducts of run execution. | | Job | A collection of run steps, settings, and a trigger to invoke dbt commands against a project in the user's cloud data platform. | | Job queue | The job queue acts as a waiting area for job runs when they are scheduled or triggered to run; runs remain in queue until execution begins. More specifically, the Scheduler checks the queue for runs that are due to execute, ensures the run is eligible to start, and then prepares an environment with appropriate settings, credentials, and commands to begin execution. Once execution begins, the run leaves the queue. | | Over-scheduled job | A situation when a cron-scheduled job's run duration becomes longer than the frequency of the job’s schedule, resulting in a job queue that will grow faster than the scheduler can process the job’s runs. | | Deactivated job | A situation where a job has reached 100 consecutive failing runs. | | Prep time | The time dbt takes to create a short-lived environment to execute the job commands in the user's cloud data platform. Prep time varies most significantly at the top of the hour when the dbt Scheduler experiences a lot of run traffic. | | Run | A single, unique execution of a dbt job. | | Run slot | Run slots control the number of jobs that can run concurrently. Each running job occupies a run slot for the duration of the run. To view the number of run slots available in your plan, check out the [dbt pricing page](https://www.getdbt.com/pricing)
.

Starter and Developer plans are limited to one project each. For additional projects or more run slots, consider upgrading to an [Enterprise-tier plan](https://www.getdbt.com/pricing/)
. | | Threads | When dbt builds a project's DAG, it tries to parallelize the execution by using threads. The [thread](https://docs.getdbt.com/docs/running-a-dbt-project/using-threads)
count is the maximum number of paths through the DAG that dbt can work on simultaneously. The default thread count in a job is 4. | | Wait time | Amount of time that dbt waits before running a job, either because there are no available slots or because a previous run of the same job is still in progress. | Scheduler queue[​](https://docs.getdbt.com/docs/deploy/job-scheduler#scheduler-queue "Direct link to Scheduler queue") ----------------------------------------------------------------------------------------------------------------------- The scheduler queues a deployment job to be processed when it's triggered to run by a [set schedule](https://docs.getdbt.com/docs/deploy/deploy-jobs#schedule-days) , [a job completed](https://docs.getdbt.com/docs/deploy/deploy-jobs#trigger-on-job-completion) , an API call, or manual action. Before the job starts executing, the scheduler checks these conditions to determine if the run can start executing: * **Is there a run slot that's available on the account for use?** — If all run slots are occupied, the queued run will wait. The wait time is displayed in dbt. If there are long wait times, [upgrading to an Enterprise-tier plan](https://www.getdbt.com/contact/) can provide more run slots and allow for higher job concurrency. * **Does this same job have a run already in progress?** — The scheduler executes distinct runs of the same dbt job serially to avoid model build collisions. If there's a job already running, the queued job will wait, and the wait time will be displayed in dbt. If there is an available run slot and there isn't an actively running instance of the job, the scheduler will prepare the job to run in your cloud data platform. This prep involves readying a Kubernetes pod with the right version of dbt installed, setting environment variables, loading data platform credentials, and Git provider authorization, amongst other environment-setting tasks. The time it takes to prepare the job is displayed as **Prep time** in the UI. [![An overview of a dbt job run](https://docs.getdbt.com/img/docs/dbt-cloud/deployment/deploy-scheduler.png?v=2 "An overview of a dbt job run")](https://docs.getdbt.com/docs/deploy/job-scheduler#) An overview of a dbt job run ### Treatment of CI jobs[​](https://docs.getdbt.com/docs/deploy/job-scheduler#treatment-of-ci-jobs "Direct link to Treatment of CI jobs") When compared to deployment jobs, the scheduler behaves differently when handling [continuous integration (CI) jobs](https://docs.getdbt.com/docs/deploy/continuous-integration) . It queues a CI job to be processed when it's triggered to run by a Git pull request, and the conditions the scheduler checks to determine if the run can start executing are also different: * **Will the CI run consume a run slot?** — CI runs don't consume run slots and will never block production runs. * **Does this same job have a run already in progress?** — CI runs can execute concurrently (in parallel). CI runs build into unique temporary schemas, and CI checks execute in parallel to help increase team productivity. Teammates never have to wait to get a CI check review. ### Treatment of merge jobs[​](https://docs.getdbt.com/docs/deploy/job-scheduler#treatment-of-merge-jobs "Direct link to Treatment of merge jobs") When triggered by a _merged_ Git pull request, the scheduler queues a [merge job](https://docs.getdbt.com/docs/deploy/merge-jobs) to be processed. * **Will the merge job run consume a run slot?** — Yes, merge jobs do consume run slots. * **Does this same job have a run already in progress?** — A merge job can only have one run in progress at a time. If there are multiple runs queued up, the scheduler will enqueue the most recent run and cancel all the other runs. If there is a run in progress, it will wait until the run completes before queuing the next run. Job memory[​](https://docs.getdbt.com/docs/deploy/job-scheduler#job-memory "Direct link to Job memory") -------------------------------------------------------------------------------------------------------- In dbt, the setting to provision memory available to a job is defined at the account-level and applies to each job running in the account; the memory limit cannot be customized per job. If a running job reaches its memory limit, the run is terminated with a "memory limit error" message. Jobs consume a lot of memory in the following situations: * A high thread count was specified * Custom dbt macros attempt to load data into memory instead of pushing compute down to the cloud data platform * Having a job that generates dbt project documentation for a large and complex dbt project. * To prevent problems with the job running out of memory, we recommend generating documentation in a separate job that is set aside for that task and removing `dbt docs generate` from all other jobs. This is especially important for large and complex projects. Refer to [dbt architecture](https://docs.getdbt.com/docs/cloud/about-cloud/architecture) for an architecture diagram and to learn how the data flows. Run cancellation for over-scheduled jobs[​](https://docs.getdbt.com/docs/deploy/job-scheduler#run-cancellation-for-over-scheduled-jobs "Direct link to Run cancellation for over-scheduled jobs") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Scheduler won't cancel API-triggered jobs The scheduler will not cancel over-scheduled jobs triggered by the [API](https://docs.getdbt.com/docs/dbt-cloud-apis/overview) . The dbt scheduler prevents too many job runs from clogging the queue by canceling unnecessary ones. If a job takes longer to run than its scheduled frequency, the queue will grow faster than the scheduler can process the runs, leading to an ever-expanding queue with runs that don’t need to be processed (called _over-scheduled jobs_). The scheduler prevents queue clog by canceling runs that aren't needed, ensuring there is only one run of the job in the queue at any given time. If a newer run is queued, the scheduler cancels any previously queued run for that job and displays an error message. [![The cancelled runs display an error message explaining why the run was cancelled and recommendations](https://docs.getdbt.com/img/docs/dbt-cloud/deployment/run-error-message.png?v=2 "The cancelled runs display an error message explaining why the run was cancelled and recommendations")](https://docs.getdbt.com/docs/deploy/job-scheduler#) The cancelled runs display an error message explaining why the run was cancelled and recommendations To prevent over-scheduling, users will need to take action by either refactoring the job so it runs faster or modifying its [schedule](https://docs.getdbt.com/docs/deploy/deploy-jobs#schedule-days) . Deactivation of jobs [beta](https://docs.getdbt.com/docs/dbt-versions/product-lifecycles "Go to https://docs.getdbt.com/docs/dbt-versions/product-lifecycles") [​](https://docs.getdbt.com/docs/deploy/job-scheduler#deactivation-of-jobs- "Direct link to deactivation-of-jobs-") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- To reduce unnecessary resource consumption and reduce contention for run slots in your account, dbt will deactivate a [deploy job](https://docs.getdbt.com/docs/deploy/deploy-jobs) or a [CI job](https://docs.getdbt.com/docs/deploy/ci-jobs) if it reaches 100 consecutive failing runs. A banner containing this message is displayed when a job is deactivated: "Job has been deactivated due to repeated run failures. To reactivate, verify the job is configured properly and run manually or reenable any trigger". When this happens, scheduled and triggered-to-run jobs will no longer be enqueued. To reactivate a deactivated job, you can either: * Update the job's settings to fix the issue and save the job (recommended) * Perform a manual run by clicking **Run now** on the job's page FAQs[​](https://docs.getdbt.com/docs/deploy/job-scheduler#faqs "Direct link to FAQs") -------------------------------------------------------------------------------------- I'm receiving a 'This run exceeded your account's run memory limits' error in my failed job If you're receiving a `This run exceeded your account's run memory limits` error in your failed job, it means that the job exceeded the [memory limits](https://docs.getdbt.com/docs/deploy/job-scheduler#job-memory) set for your account. All dbt accounts have a pod memory of 600Mib and memory limits are on a per run basis. They're typically influenced by the amount of result data that dbt has to ingest and process, which is small but can become bloated unexpectedly by project design choices. ### Common reasons[​](https://docs.getdbt.com/docs/deploy/job-scheduler#common-reasons "Direct link to Common reasons") Some common reasons for higher memory usage are: * dbt run/build: Macros that capture large result sets from run query may not all be necessary and may be memory inefficient. * dbt docs generate: Source or model schemas with large numbers of tables (even if those tables aren't all used by dbt) cause the ingest of very large results for catalog queries. ### Resolution[​](https://docs.getdbt.com/docs/deploy/job-scheduler#resolution "Direct link to Resolution") There are various reasons why you could be experiencing this error but they are mostly the outcome of retrieving too much data back into dbt. For example, using the `run_query()` operations or similar macros, or even using database/schemas that have a lot of other non-dbt related tables/views. Try to reduce the amount of data / number of rows retrieved back into dbt by refactoring the SQL in your `run_query()` operation using `group`, `where`, or `limit` clauses. Additionally, you can also use a database/schema with fewer non-dbt related tables/views. Video example As an additional resource, check out [this example video](https://www.youtube.com/watch?v=sTqzNaFXiZ8) , which demonstrates how to refactor the sample code by reducing the number of rows returned. If you've tried the earlier suggestions and are still experiencing failed job runs with this error about hitting the memory limits of your account, please [reach out to support](mailto:support@getdbt.com) . We're happy to help! ### Additional resources[​](https://docs.getdbt.com/docs/deploy/job-scheduler#additional-resources "Direct link to Additional resources") * [Blog post on how we shaved 90 mins off](https://docs.getdbt.com/blog/how-we-shaved-90-minutes-off-model) Related docs[​](https://docs.getdbt.com/docs/deploy/job-scheduler#related-docs "Direct link to Related docs") -------------------------------------------------------------------------------------------------------------- * [dbt architecture](https://docs.getdbt.com/docs/cloud/about-cloud/architecture#dbt-cloud-features-architecture) * [Job commands](https://docs.getdbt.com/docs/deploy/job-commands) * [Job notifications](https://docs.getdbt.com/docs/deploy/job-notifications) * [Webhooks](https://docs.getdbt.com/docs/deploy/webhooks) * [dbt continuous integration](https://docs.getdbt.com/docs/deploy/continuous-integration) Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Scheduler terms](https://docs.getdbt.com/docs/deploy/job-scheduler#scheduler-terms) * [Scheduler queue](https://docs.getdbt.com/docs/deploy/job-scheduler#scheduler-queue) * [Treatment of CI jobs](https://docs.getdbt.com/docs/deploy/job-scheduler#treatment-of-ci-jobs) * [Treatment of merge jobs](https://docs.getdbt.com/docs/deploy/job-scheduler#treatment-of-merge-jobs) * [Job memory](https://docs.getdbt.com/docs/deploy/job-scheduler#job-memory) * [Run cancellation for over-scheduled jobs](https://docs.getdbt.com/docs/deploy/job-scheduler#run-cancellation-for-over-scheduled-jobs) * [Deactivation of jobs](https://docs.getdbt.com/docs/deploy/job-scheduler#deactivation-of-jobs-) * [FAQs](https://docs.getdbt.com/docs/deploy/job-scheduler#faqs) * [Related docs](https://docs.getdbt.com/docs/deploy/job-scheduler#related-docs) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/deploy/job-scheduler.md) --- # Build and view your docs with dbt | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/explore/build-and-view-your-docs#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page dbt enables you to generate documentation for your project and data platform. The documentation is automatically updated with new information after a fully successful job run, ensuring accuracy and relevance. The default documentation experience in dbt is [Catalog](https://docs.getdbt.com/docs/explore/explore-projects) , available on [Starter, Enterprise, or Enterprise+ plans](https://www.getdbt.com/pricing/) . Use [Catalog](https://docs.getdbt.com/docs/explore/explore-projects) to view your project's resources (such as models, tests, and metrics) and their lineage to gain a better understanding of its latest production state. Refer to [documentation](https://docs.getdbt.com/docs/build/documentation) for more configuration details. This shift makes [dbt Docs](https://docs.getdbt.com/docs/explore/build-and-view-your-docs#dbt-docs) a legacy documentation feature in dbt. dbt Docs is still accessible and offers basic documentation, but it doesn't offer the same speed, metadata, or visibility as Catalog. dbt Docs is available to dbt developer plans or dbt Core users. Set up a documentation job[​](https://docs.getdbt.com/docs/explore/build-and-view-your-docs#set-up-a-documentation-job "Direct link to Set up a documentation job") -------------------------------------------------------------------------------------------------------------------------------------------------------------------- Catalog uses the [metadata](https://docs.getdbt.com/docs/explore/explore-projects#generate-metadata) generated after each job run in the production or staging environment, ensuring it always has the latest project results. To view richer metadata, you can set up documentation for a job in dbt when you edit your job settings or create a new job. Configure the job to [generate metadata](https://docs.getdbt.com/docs/explore/explore-projects#generate-metadata) when it runs. If you want to view column and statistics for models, sources, and snapshots in Catalog, then this step is necessary. To set up a job to generate docs: 1. In the top left, click **Deploy** and select **Jobs**. 2. Create a new job or select an existing job and click **Settings**. 3. Under **Execution Settings**, select **Generate docs on run** and click **Save**. [![Setting up a job to generate documentation](https://docs.getdbt.com/img/docs/dbt-cloud/using-dbt-cloud/documentation-job-execution-settings.png?v=2 "Setting up a job to generate documentation")](https://docs.getdbt.com/docs/explore/build-and-view-your-docs#) Setting up a job to generate documentation _Note, for dbt Docs users you need to configure the job to generate docs when it runs, then manually link that job to your project. Proceed to [configure project documentation](https://docs.getdbt.com/docs/explore/build-and-view-your-docs#configure-project-documentation) so your project generates the documentation when this job runs._ You can also add the [`dbt docs generate` command](https://docs.getdbt.com/reference/commands/cmd-docs) to the list of commands in the job run steps. However, you can expect different outcomes when adding the command to the run steps compared to configuring a job selecting the **Generate docs on run** checkbox. Review the following options and outcomes: | Options | Outcomes | | --- | --- | | **Select checkbox** | Select the **Generate docs on run** checkbox to automatically generate updated project docs each time your job runs. If that particular step in your job fails, the job can still be successful if all subsequent steps are successful. | | **Add as a run step** | Add `dbt docs generate` to the list of commands in the job run steps, in whatever order you prefer. If that particular step in your job fails, the job will fail and all subsequent steps will be skipped. | Tip — Documentation-only jobs To create and schedule documentation-only jobs at the end of your production jobs, add the `dbt compile` command in the **Commands** section. dbt Docs[​](https://docs.getdbt.com/docs/explore/build-and-view-your-docs#dbt-docs "Direct link to dbt Docs") -------------------------------------------------------------------------------------------------------------- dbt Docs, available on developer plans or dbt Core users, generates a website from your dbt project using the `dbt docs generate` command. It provides a central location to view your project's resources, such as models, tests, and lineage — and helps you understand the data in your warehouse. ### Configure project documentation[​](https://docs.getdbt.com/docs/explore/build-and-view-your-docs#configure-project-documentation "Direct link to Configure project documentation") You configure project documentation to generate documentation when the job you set up in the previous section runs. In the project settings, specify the job that generates documentation artifacts for that project. Once you configure this setting, subsequent runs of the job will automatically include a step to generate documentation. 1. From dbt, click on your account name in the left side menu and select **Account settings**. 2. Navigate to **Projects** and select the project that needs documentation. 3. Click **Edit**. 4. Under **Artifacts**, select the job that should generate docs when it runs and click **Save**. [![Configuring project documentation](https://docs.getdbt.com/img/docs/dbt-cloud/using-dbt-cloud/documentation-project-details.png?v=2 "Configuring project documentation")](https://docs.getdbt.com/docs/explore/build-and-view-your-docs#) Configuring project documentation Use Catalog for a richer documentation experience For a richer and more interactive experience, try out [Catalog](https://docs.getdbt.com/docs/explore/explore-projects) , available on [Starter, Enterprise, or Enterprise+ plans](https://www.getdbt.com/pricing/) . It includes map layers of your DAG, keyword search, interacts with the Studio IDE, model performance, project recommendations, and more. ### Generating documentation[​](https://docs.getdbt.com/docs/explore/build-and-view-your-docs#generating-documentation "Direct link to Generating documentation") To generate documentation in the Studio IDE, run the `dbt docs generate` command in the **Command Bar** in the Studio IDE. This command will generate the documentation for your dbt project as it exists in development in your IDE session. After running `dbt docs generate` in the Studio IDE, click the icon above the file tree, to see the latest version of your documentation rendered in a new browser window. ### View documentation[​](https://docs.getdbt.com/docs/explore/build-and-view-your-docs#view-documentation "Direct link to View documentation") Once you set up a job to generate documentation for your project, you can click **Explore** in the navigation and then click on **dbt Docs**. Your project's documentation should open. This link will always help you find the most recent version of your project's documentation in dbt. These generated docs always show the last fully successful run, which means that if you have any failed tasks, including tests, then you will not see changes to the docs by this run. If you don't see a fully successful run, then you won't see any changes to the documentation. The Studio IDE makes it possible to view [documentation](https://docs.getdbt.com/docs/build/documentation) for your dbt project while your code is still in development. With this workflow, you can inspect and verify what your project's generated documentation will look like before your changes are released to production. Related docs[​](https://docs.getdbt.com/docs/explore/build-and-view-your-docs#related-docs "Direct link to Related docs") -------------------------------------------------------------------------------------------------------------------------- * [Documentation](https://docs.getdbt.com/docs/build/documentation) * [Catalog](https://docs.getdbt.com/docs/explore/explore-projects) Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Set up a documentation job](https://docs.getdbt.com/docs/explore/build-and-view-your-docs#set-up-a-documentation-job) * [dbt Docs](https://docs.getdbt.com/docs/explore/build-and-view-your-docs#dbt-docs) * [Configure project documentation](https://docs.getdbt.com/docs/explore/build-and-view-your-docs#configure-project-documentation) * [Generating documentation](https://docs.getdbt.com/docs/explore/build-and-view-your-docs#generating-documentation) * [View documentation](https://docs.getdbt.com/docs/explore/build-and-view-your-docs#view-documentation) * [Related docs](https://docs.getdbt.com/docs/explore/build-and-view-your-docs#related-docs) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/explore/build-and-view-your-docs.md) --- # About dbt Insights | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/explore/dbt-insights#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page Learn how to query data with Insights and view documentation in Catalog. Insights in dbt empowers users to seamlessly explore and query data with an intuitive, context-rich interface. It bridges technical and business users by combining metadata, documentation, AI-assisted tools, and powerful querying capabilities into one unified experience. Insights in dbt integrates with [Catalog](https://docs.getdbt.com/docs/explore/explore-projects) , [Studio IDE](https://docs.getdbt.com/docs/cloud/dbt-cloud-ide/develop-in-the-cloud) , [Canvas](https://docs.getdbt.com/docs/cloud/canvas) , [Copilot](https://docs.getdbt.com/docs/cloud/dbt-copilot) , and [Semantic Layer](https://docs.getdbt.com/docs/use-dbt-semantic-layer/dbt-sl) to make it easier for you to perform exploratory data analysis, leverage AI-assisted tools, make faster decisions, and collaborate across teams. [![Overview of the dbt Insights and its features](https://docs.getdbt.com/img/docs/dbt-insights/insights-main.gif?v=2 "Overview of the dbt Insights and its features")](https://docs.getdbt.com/docs/explore/dbt-insights#) Overview of the dbt Insights and its features Key benefits[​](https://docs.getdbt.com/docs/explore/dbt-insights#key-benefits "Direct link to Key benefits") -------------------------------------------------------------------------------------------------------------- Key benefits include: * Quickly write, run, and iterate on SQL queries with tools like syntax highlighting, tabbed editors, and query history. * Leverage dbt metadata, trust signals, and lineage from Catalog for informed query construction. * Make data accessible to users of varied technical skill levels with SQL, Semantic Layer queries, and visual tools. * Use Copilot's AI-assistance to generate or edit SQL queries, descriptions, and more. Some example use cases include: * Analysts can quickly construct queries to analyze sales performance metrics across regions and view results. * All users have a rich development experience powered by Catalog's end-to-end exploration experience. Prerequisites[​](https://docs.getdbt.com/docs/explore/dbt-insights#prerequisites "Direct link to Prerequisites") ----------------------------------------------------------------------------------------------------------------- * Be on a dbt [Enterprise-tier](https://www.getdbt.com/pricing) plan — [book a demo](https://www.getdbt.com/contact) to learn more about Insights. * Available on all [tenant](https://docs.getdbt.com/docs/cloud/about-cloud/tenancy) configurations. * Have a dbt [developer license](https://docs.getdbt.com/docs/cloud/manage-access/seats-and-users) with access to Insights. * Configured [developer credentials](https://docs.getdbt.com/docs/cloud/dbt-cloud-ide/develop-in-the-cloud#get-started-with-the-cloud-ide) . * Your production and development [environments](https://docs.getdbt.com/docs/dbt-cloud-environments) are on dbt’s ‘Latest’ [release track](https://docs.getdbt.com/docs/dbt-versions/cloud-release-tracks) or a supported dbt version. * Use a supported data platform: Snowflake, BigQuery, Databricks, Redshift, or Postgres. * Single sign-on (SSO) for development user accounts is supported. Deployment environments will be queried leveraging the user's development credentials. * (Optional) — To query [Semantic Layer](https://docs.getdbt.com/docs/use-dbt-semantic-layer/dbt-sl) metrics from the Insights, you must also: * [Configure](https://docs.getdbt.com/docs/use-dbt-semantic-layer/setup-sl) the Semantic Layer for your dbt project. * Have a successful job run in the environment where you configured the Semantic Layer. Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Key benefits](https://docs.getdbt.com/docs/explore/dbt-insights#key-benefits) * [Prerequisites](https://docs.getdbt.com/docs/explore/dbt-insights#prerequisites) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/explore/dbt-insights.md) --- # Continuous integration in dbt | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/deploy/continuous-integration#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page To implement a continuous integration (CI) workflow in dbt, you can set up automation that tests code changes by running [CI jobs](https://docs.getdbt.com/docs/deploy/ci-jobs) before merging to production. dbt tracks the state of what’s running in your production environment so, when you run a CI job, only the modified data assets in your pull request (PR) and their downstream dependencies are built and tested in a staging schema. You can also view the status of the CI checks (tests) directly from within the PR; this information is posted to your Git provider as soon as a CI job completes. Additionally, you can enable settings in your Git provider that allow PRs only with successful CI checks to be approved for merging. [![Workflow of continuous integration in dbt](https://docs.getdbt.com/img/docs/dbt-cloud/using-dbt-cloud/ci-workflow.png?v=2 "Workflow of continuous integration in dbt")](https://docs.getdbt.com/docs/deploy/continuous-integration#) Workflow of continuous integration in dbt Using CI helps: * Provide increased confidence and assurances that project changes will work as expected in production. * Reduce the time it takes to push code changes to production, through build and test automation, leading to better business outcomes. * Allow organizations to make code changes in a standardized and governed way that ensures code quality without sacrificing speed. How CI works[​](https://docs.getdbt.com/docs/deploy/continuous-integration#how-ci-works "Direct link to How CI works") ----------------------------------------------------------------------------------------------------------------------- When you [set up CI jobs](https://docs.getdbt.com/docs/deploy/ci-jobs#set-up-ci-jobs) , dbt listens for a notification from your Git provider indicating that a new PR has been opened or updated with new commits. When dbt receives one of these notifications, it enqueues a new run of the CI job. dbt builds and tests models, semantic models, metrics, and saved queries affected by the code change in a temporary schema, unique to the PR. This process ensures that the code builds without error and that it matches the expectations as defined by the project's dbt tests. The unique schema name follows the naming convention `dbt_cloud_pr__` (for example, `dbt_cloud_pr_1862_1704`) and can be found in the run details for the given run, as shown in the following image: [![Viewing the temporary schema name for a run triggered by a PR](https://docs.getdbt.com/img/docs/dbt-cloud/using-dbt-cloud/using_ci_dbt_cloud.png?v=2 "Viewing the temporary schema name for a run triggered by a PR")](https://docs.getdbt.com/docs/deploy/continuous-integration#) Viewing the temporary schema name for a run triggered by a PR When the CI run completes, you can view the run status directly from within the pull request. dbt updates the pull request in GitHub, GitLab, or Azure DevOps with a status message indicating the results of the run. The status message states whether the models and tests ran successfully or not. dbt deletes the temporary schema from your data warehouse when you close or merge the pull request. If your project has schema customization using the [generate\_schema\_name](https://docs.getdbt.com/docs/build/custom-schemas#how-does-dbt-generate-a-models-schema-name)  macro, dbt might not drop the temporary schema from your data warehouse. For more information, refer to [Troubleshooting](https://docs.getdbt.com/docs/deploy/ci-jobs#troubleshooting) . Availability of features by Git provider[​](https://docs.getdbt.com/docs/deploy/continuous-integration#availability-of-features-by-git-provider "Direct link to Availability of features by Git provider") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- * If your git provider has a [native dbt integration](https://docs.getdbt.com/docs/cloud/git/git-configuration-in-dbt-cloud) , you can seamlessly set up [continuous integration (CI)](https://docs.getdbt.com/docs/deploy/ci-jobs) jobs directly within dbt. * For providers without native integration, you can still use the [Git clone method](https://docs.getdbt.com/docs/cloud/git/import-a-project-by-git-url) to import your git URL and leverage the [dbt Administrative API](https://docs.getdbt.com/docs/dbt-cloud-apis/admin-cloud-api) to trigger a CI job to run. The following table outlines the available integration options and their corresponding capabilities. | **Git provider** | **Native dbt integration** | **Automated CI job** | **Git clone** | **Information** | **Supported plans** | | --- | --- | --- | --- | --- | --- | | [Azure DevOps](https://docs.getdbt.com/docs/cloud/git/connect-azure-devops) | ✅ | ✅ | ✅ | Organizations on the Starter and Developer plans can connect to Azure DevOps using a deploy key. Note, you won’t be able to configure automated CI jobs but you can still develop. | Enterprise, Enterprise+ | | [GitHub](https://docs.getdbt.com/docs/cloud/git/connect-github) | ✅ | ✅ | | | All dbt plans | | [GitLab](https://docs.getdbt.com/docs/cloud/git/connect-gitlab) | ✅ | ✅ | ✅ | | All dbt plans | | All other git providers using [Git clone](https://docs.getdbt.com/docs/cloud/git/import-a-project-by-git-url)
([BitBucket](https://docs.getdbt.com/docs/cloud/git/import-a-project-by-git-url#bitbucket)
, [AWS CodeCommit](https://docs.getdbt.com/docs/cloud/git/import-a-project-by-git-url#aws-codecommit)
, and others) | ❌ | ❌ | ✅ | Refer to the [Customizing CI/CD with custom pipelines](https://docs.getdbt.com/guides/custom-cicd-pipelines?step=1)
guide to set up continuous integration and continuous deployment (CI/CD). | | Differences between CI jobs and other deployment jobs[​](https://docs.getdbt.com/docs/deploy/continuous-integration#differences-between-ci-jobs-and-other-deployment-jobs "Direct link to Differences between CI jobs and other deployment jobs") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The [dbt scheduler](https://docs.getdbt.com/docs/deploy/job-scheduler) executes CI jobs differently from other deployment jobs in these important ways: * [**Concurrent CI checks**](https://docs.getdbt.com/docs/deploy/continuous-integration#concurrent-ci-checks) — CI runs triggered by the same dbt CI job execute concurrently (in parallel), when appropriate. * [**Smart cancellation of stale builds**](https://docs.getdbt.com/docs/deploy/continuous-integration#smart-cancellation-of-stale-builds) — Automatically cancels stale, in-flight CI runs when there are new commits to the PR. * [**Run slot treatment**](https://docs.getdbt.com/docs/deploy/continuous-integration#run-slot-treatment) — CI runs don't consume a run slot. * [**SQL linting**](https://docs.getdbt.com/docs/deploy/continuous-integration#sql-linting) — When enabled, automatically lints all SQL files in your project as a run step before your CI job builds. ### Concurrent CI checks [Starter](https://www.getdbt.com/pricing "Go to https://www.getdbt.com/pricing") [Enterprise](https://www.getdbt.com/pricing "Go to https://www.getdbt.com/pricing") [Enterprise +](https://www.getdbt.com/pricing "Go to https://www.getdbt.com/pricing") [​](https://docs.getdbt.com/docs/deploy/continuous-integration#concurrent-ci-checks- "Direct link to concurrent-ci-checks-") When you have teammates collaborating on the same dbt project creating pull requests on the same dbt repository, the same CI job will get triggered. Since each run builds into a dedicated, temporary schema that’s tied to the pull request, dbt can safely execute CI runs _concurrently_ instead of _sequentially_ (differing from what is done with deployment dbt jobs). Because no one needs to wait for one CI run to finish before another one can start, with concurrent CI checks, your whole team can test and integrate dbt code faster. The following describes the conditions when CI checks are run concurrently and when they’re not: * CI runs with different PR numbers execute concurrently. * CI runs with the _same_ PR number and _different_ commit SHAs execute serially because they’re building into the same schema. dbt will run the latest commit and cancel any older, stale commits. For details, refer to [Smart cancellation of stale builds](https://docs.getdbt.com/docs/deploy/continuous-integration#smart-cancellation) . * CI runs with the same PR number and same commit SHA, originating from different dbt projects will execute jobs concurrently. This can happen when two CI jobs are set up in different dbt projects that share the same dbt repository. ### Smart cancellation of stale builds [Starter](https://www.getdbt.com/pricing "Go to https://www.getdbt.com/pricing") [Enterprise](https://www.getdbt.com/pricing "Go to https://www.getdbt.com/pricing") [Enterprise +](https://www.getdbt.com/pricing "Go to https://www.getdbt.com/pricing") [​](https://docs.getdbt.com/docs/deploy/continuous-integration#smart-cancellation-of-stale-builds- "Direct link to smart-cancellation-of-stale-builds-") When you push a new commit to a PR, dbt enqueues a new CI run for the latest commit and cancels any CI run that is (now) stale and still in flight. This can happen when you’re pushing new commits while a CI build is still in process and not yet done. By cancelling runs in a safe and deliberate way, dbt helps improve productivity and reduce data platform spend on wasteful CI runs. [![Example of an automatically canceled run](https://docs.getdbt.com/img/docs/dbt-cloud/using-dbt-cloud/example-smart-cancel-job.png?v=2 "Example of an automatically canceled run")](https://docs.getdbt.com/docs/deploy/continuous-integration#) Example of an automatically canceled run ### Run slot treatment [Starter](https://www.getdbt.com/pricing "Go to https://www.getdbt.com/pricing") [Enterprise](https://www.getdbt.com/pricing "Go to https://www.getdbt.com/pricing") [Enterprise +](https://www.getdbt.com/pricing "Go to https://www.getdbt.com/pricing") [​](https://docs.getdbt.com/docs/deploy/continuous-integration#run-slot-treatment- "Direct link to run-slot-treatment-") CI runs don't consume run slots. This guarantees a CI check will never block a production run. ### SQL linting [Starter](https://www.getdbt.com/pricing "Go to https://www.getdbt.com/pricing") [Enterprise](https://www.getdbt.com/pricing "Go to https://www.getdbt.com/pricing") [Enterprise +](https://www.getdbt.com/pricing "Go to https://www.getdbt.com/pricing") [​](https://docs.getdbt.com/docs/deploy/continuous-integration#sql-linting- "Direct link to sql-linting-") Available on [dbt release tracks](https://docs.getdbt.com/docs/dbt-versions/cloud-release-tracks) and dbt Starter or Enterprise-tier accounts. When [enabled for your CI job](https://docs.getdbt.com/docs/deploy/ci-jobs#set-up-ci-jobs) , dbt invokes [SQLFluff](https://sqlfluff.com/)  which is a modular and configurable SQL linter that warns you of complex functions, syntax, formatting, and compilation errors. By default, SQL linting lints all the changed SQL files in your project (compared to the last deferred production state). Note that [snapshots](https://docs.getdbt.com/docs/build/snapshots) can be defined in YAML _and_ `.sql` files, but its SQL isn't lintable and can cause errors during linting. To prevent SQLFluff from linting snapshot files, add the snapshots directory to your `.sqlfluffignore` file (for example `snapshots/`). Refer to [snapshot linting](https://docs.getdbt.com/docs/cloud/dbt-cloud-ide/lint-format#snapshot-linting) for more information. If the linter runs into errors, you can specify whether dbt should stop running the job on error or continue running it on error. When failing jobs, it helps reduce compute costs by avoiding builds for pull requests that don't meet your SQL code quality CI check. #### To configure SQLFluff linting:[​](https://docs.getdbt.com/docs/deploy/continuous-integration#to-configure-sqlfluff-linting "Direct link to To configure SQLFluff linting:") You can optionally configure SQLFluff linting rules to override default linting behavior. * Use [SQLFluff Configuration Files](https://docs.sqlfluff.com/en/stable/configuration/setting_configuration.html#configuration-files)  to override the default linting behavior in dbt. * Create a `.sqlfluff` configuration file in your project, add your linting rules to it, and dbt will use them when linting. * When configuring, you can use `dbt` as the templater (for example, `templater = dbt`) * If you’re using the Studio IDE, dbt CLI, or any other editor, refer to [Customize linting](https://docs.getdbt.com/docs/cloud/dbt-cloud-ide/lint-format#customize-linting) for guidance on how to add the dbt-specific (or dbtonic) linting rules we use for own project. * For complete details, refer to [Custom Usage](https://docs.sqlfluff.com/en/stable/gettingstarted.html#custom-usage)  in the SQLFluff documentation. Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [How CI works](https://docs.getdbt.com/docs/deploy/continuous-integration#how-ci-works) * [Availability of features by Git provider](https://docs.getdbt.com/docs/deploy/continuous-integration#availability-of-features-by-git-provider) * [Differences between CI jobs and other deployment jobs](https://docs.getdbt.com/docs/deploy/continuous-integration#differences-between-ci-jobs-and-other-deployment-jobs) * [Concurrent CI checks](https://docs.getdbt.com/docs/deploy/continuous-integration#concurrent-ci-checks-) * [Smart cancellation of stale builds](https://docs.getdbt.com/docs/deploy/continuous-integration#smart-cancellation-of-stale-builds-) * [Run slot treatment](https://docs.getdbt.com/docs/deploy/continuous-integration#run-slot-treatment-) * [SQL linting](https://docs.getdbt.com/docs/deploy/continuous-integration#sql-linting-) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/deploy/continuous-integration.md) --- # docs-paths | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/reference/project-configs/docs-paths#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page dbt\_project.yml docs-paths: [directorypath] Definition[​](https://docs.getdbt.com/reference/project-configs/docs-paths#definition "Direct link to Definition") ------------------------------------------------------------------------------------------------------------------- Optionally specify a custom list of directories where [docs blocks](https://docs.getdbt.com/docs/build/documentation#docs-blocks) are located. Default[​](https://docs.getdbt.com/reference/project-configs/docs-paths#default "Direct link to Default") ---------------------------------------------------------------------------------------------------------- Paths specified in `docs-paths` must be relative to the location of your `dbt_project.yml` file. Avoid using absolute paths like `/Users/username/project/docs`, as it will lead to unexpected behavior and outcomes. * ✅ **Do** * Use relative path: docs-paths: ["docs"] * ❌ **Don't** * Avoid absolute paths: docs-paths: ["/Users/username/project/docs"] Example[​](https://docs.getdbt.com/reference/project-configs/docs-paths#example "Direct link to Example") ---------------------------------------------------------------------------------------------------------- Use a subdirectory named `docs` for docs blocks: dbt\_project.yml docs-paths: ["docs"] **Note:** We typically omit this configuration as we prefer dbt's default behavior. Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Definition](https://docs.getdbt.com/reference/project-configs/docs-paths#definition) * [Default](https://docs.getdbt.com/reference/project-configs/docs-paths#default) * [Example](https://docs.getdbt.com/reference/project-configs/docs-paths#example) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/reference/project-configs/docs-paths.md) --- # Python SDK | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-python#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page The [`dbt-sl-sdk` Python software development kit](https://github.com/dbt-labs/semantic-layer-sdk-python) (SDK) is a Python library that provides you with easy access to the dbt Semantic Layer with Python. It allows developers to interact with the dbt Semantic Layer APIs and query metrics and dimensions in downstream tools. Installation[​](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-python#installation "Direct link to Installation") ------------------------------------------------------------------------------------------------------------------ To install the Python SDK, you'll need to specify optional dependencies depending on whether you want to use it synchronously, backed by [requests](https://github.com/psf/requests/) , or with asynchronous ([asyncio](https://docs.python.org/3/library/asyncio.html) backed by [aiohttp](https://github.com/aio-libs/aiohttp/) ). The Python SDK supports the Long-Term Support (LTS) versions of Python, such as 3.9, 3.10, 3.11, and 3.12. When Python discontinues support for a version, the Python SDK will also discontinue support for that version. If you’re using a non-supported version, you may experience compatibility issues and won’t receive updates or security patches from the SDK. * Sync installation * Async installation Sync installation means your program waits for each task to finish before moving on to the next one. It's simpler, easier to understand, and suitable for smaller tasks or when your program doesn't need to handle many tasks at the same time. pip install "dbt-sl-sdk[sync]" If you're using async frameworks like [FastAPI](https://fastapi.tiangolo.com/) or [Strawberry](https://github.com/strawberry-graphql/strawberry) , installing the sync version of the SDK will block your event loop and can significantly slow down your program. In this case, we strongly recommend using async installation. Async installation means your program can start a task and then move on to other tasks while waiting for the first one to finish. This can handle many tasks at once without waiting, making it faster and more efficient for larger tasks or when you need to manage multiple tasks at the same time. For more details, refer to [asyncio](https://docs.python.org/3/library/asyncio.html) . pip install "dbt-sl-sdk[sync]" Since the [Python ADBC driver](https://github.com/apache/arrow-adbc/tree/main/python/adbc_driver_manager) doesn't yet support asyncio natively, `dbt-sl-sdk` uses a [`ThreadPoolExecutor`](https://github.com/dbt-labs/semantic-layer-sdk-python/blob/5e52e1ca840d20a143b226ae33d194a4a9bc008f/dbtsl/api/adbc/client/asyncio.py#L62) to run `query` and `list dimension-values` (all operations that are done with ADBC). This is why you might see multiple Python threads spawning. If you're using async frameworks like [FastAPI](https://fastapi.tiangolo.com/) or [Strawberry](https://github.com/strawberry-graphql/strawberry) , installing the sync version of the Python SDK will block your event loop and can significantly slow down your program. In this case, we strongly recommend using async installation. Usage[​](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-python#usage "Direct link to Usage") --------------------------------------------------------------------------------------------- To run operations against the Semantic Layer APIs, instantiate (create an instance of) a `SemanticLayerClient` with your specific [API connection parameters](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-api-overview) : from dbtsl import SemanticLayerClientclient = SemanticLayerClient( environment_id=123, auth_token="", host="semantic-layer.cloud.getdbt.com",)# query the first metric by `metric_time`def main(): with client.session(): metrics = client.metrics() table = client.query( metrics=[metrics[0].name], group_by=["metric_time"], ) print(table)main() **Note**: All method calls that reach out to the APIs need to be within a `client.session()` context manager. This allows the client to establish a connection to the APIs only once and reuse the same connection between API calls. We recommend creating an application-wide session and reusing the same session throughout the application for optimal performance. Creating a session per request is discouraged and inefficient. ### asyncio usage[​](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-python#asyncio-usage "Direct link to asyncio usage") If you're using asyncio, import `AsyncSemanticLayerClient` from `dbtsl.asyncio`. The `SemanticLayerClient` and `AsyncSemanticLayerClient` APIs are identical, but the async version has async methods that you need to `await`. import asynciofrom dbtsl.asyncio import AsyncSemanticLayerClientclient = AsyncSemanticLayerClient( environment_id=123, auth_token="", host="semantic-layer.cloud.getdbt.com",)async def main(): async with client.session(): metrics = await client.metrics() table = await client.query( metrics=[metrics[0].name], group_by=["metric_time"], ) print(table)asyncio.run(main()) ### Lazy loading for large fields[​](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-python#lazy-loading-for-large-fields "Direct link to Lazy loading for large fields") By default, the Python SDK eagerly loads nested lists of objects such as `dimensions`, `entities`, and `measures` for each `Metric` — even if you don't need them. This is generally convenient, but in large projects, it can lead to slower responses due to the amount of data returned. To improve performance, you can opt into lazy loading by passing `lazy=True` when creating the client. With lazy loading enabled, the SDK skips fetching large nested fields until you explicitly request them on a per-model basis. Lazy loading is currently only supported for `dimensions`, `entities`, and `measures` on `Metric` objects. For example, the following code fetches all available metrics from the metadata API and displays only the dimensions of certain metrics: list\_metrics\_lazy\_sync.py """Fetch all available metrics from the metadata API and display only the dimensions of certain metrics."""from argparse import ArgumentParserfrom dbtsl import SemanticLayerClientdef get_arg_parser() -> ArgumentParser: p = ArgumentParser() p.add_argument("--env-id", required=True, help="The dbt environment ID", type=int) p.add_argument("--token", required=True, help="The API auth token") p.add_argument("--host", required=True, help="The API host") return pdef main() -> None: arg_parser = get_arg_parser() args = arg_parser.parse_args() client = SemanticLayerClient( environment_id=args.env_id, auth_token=args.token, host=args.host, lazy=True, ) with client.session(): metrics = client.metrics() for i, m in enumerate(metrics): print(f"📈 {m.name}") print(f" type={m.type}") print(f" description={m.description}") assert len(m.dimensions) == 0 # skip if index is odd if i & 1: print(" dimensions=skipped") continue # load dimensions only if index is even m.load_dimensions() print(" dimensions=[") for dim in m.dimensions: print(f" {dim.name},") print(" ]")if __name__ == "__main__": main() Refer to the [lazy loading example](https://github.com/dbt-labs/semantic-layer-sdk-python/blob/main/examples/list_metrics_lazy_sync.py) for more details. Integrate with dataframe libraries[​](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-python#integrate-with-dataframe-libraries "Direct link to Integrate with dataframe libraries") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ The Python SDK returns all query data as [pyarrow](https://arrow.apache.org/docs/python/index.html) tables. The Python SDK library doesn't come bundled with [Polars](https://pola.rs/) or [Pandas](https://pandas.pydata.org/) . If you use these libraries, add them as dependencies in your project. To use the data with libraries like Polars or Pandas, manually convert the data into the desired format. For example: #### If you're using pandas[​](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-python#if-youre-using-pandas "Direct link to If you're using pandas") # ... initialize clientarrow_table = client.query(...)pandas_df = arrow_table.to_pandas() #### If you're using polars[​](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-python#if-youre-using-polars "Direct link to If you're using polars") import polars as pl# ... initialize clientarrow_table = client.query(...)polars_df = pl.from_arrow(arrow_table) Usage examples[​](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-python#usage-examples "Direct link to Usage examples") ------------------------------------------------------------------------------------------------------------------------ For additional usage examples, check out the [usage examples](https://github.com/dbt-labs/semantic-layer-sdk-python/tree/main/examples) , some of which include: * [Fetching dimension values sync](https://github.com/dbt-labs/semantic-layer-sdk-python/blob/main/examples/fetch_dimension_values_sync.py) * Fetching metrics [async](https://github.com/dbt-labs/semantic-layer-sdk-python/blob/main/examples/fetch_metric_async.py) and [sync](https://github.com/dbt-labs/semantic-layer-sdk-python/blob/main/examples/fetch_metric_sync.py) * [List saved queries async](https://github.com/dbt-labs/semantic-layer-sdk-python/blob/main/examples/list_saved_queries_async.py) Disable telemetry[​](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-python#disable-telemetry "Direct link to Disable telemetry") --------------------------------------------------------------------------------------------------------------------------------- By default, the Python SDK sends some [platform-related information](https://github.com/dbt-labs/semantic-layer-sdk-python/blob/main/dbtsl/env.py) to dbt Labs. To opt-out, set the `PLATFORM.anonymous` attribute to `True`: from dbtsl.env import PLATFORMPLATFORM.anonymous = True# ... initialize client Contribute[​](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-python#contribute "Direct link to Contribute") ------------------------------------------------------------------------------------------------------------ To contribute to this project, check out our [contribution guidelines](https://github.com/dbt-labs/semantic-layer-sdk-python/blob/main/CONTRIBUTING.md) and open a GitHub [issue](https://github.com/dbt-labs/semantic-layer-sdk-python/issues) or [pull request](https://github.com/dbt-labs/semantic-layer-sdk-python/pulls) . Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Installation](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-python#installation) * [Usage](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-python#usage) * [asyncio usage](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-python#asyncio-usage) * [Lazy loading for large fields](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-python#lazy-loading-for-large-fields) * [Integrate with dataframe libraries](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-python#integrate-with-dataframe-libraries) * [Usage examples](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-python#usage-examples) * [Disable telemetry](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-python#disable-telemetry) * [Contribute](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-python#contribute) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/dbt-cloud-apis/sl-python-sdk.md) --- # GraphQL | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-graphql#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page [GraphQL](https://graphql.org/) (GQL) is an open-source query language for APIs. It offers a more efficient and flexible approach compared to traditional RESTful APIs. With GraphQL, users can request specific data using a single query, reducing the need for many server round trips. This improves performance and minimizes network overhead. GraphQL has several advantages, such as self-documenting, having a strong typing system, supporting versioning and evolution, enabling rapid development, and having a robust ecosystem. These features make GraphQL a powerful choice for APIs prioritizing flexibility, performance, and developer productivity. dbt Semantic Layer GraphQL API[​](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-graphql#dbt-semantic-layer-graphql-api "Direct link to dbt Semantic Layer GraphQL API") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The Semantic Layer GraphQL API allows you to explore and query metrics and dimensions. Due to its self-documenting nature, you can explore the calls conveniently through a schema explorer. The schema explorer URLs vary depending on your [deployment region](https://docs.getdbt.com/docs/cloud/about-cloud/access-regions-ip-addresses) . Use the following table to find the right link for your region: | Deployment type | Schema explorer URL | | --- | --- | | North America multi-tenant | [https://semantic-layer.cloud.getdbt.com/api/graphql](https://semantic-layer.cloud.getdbt.com/api/graphql) | | EMEA multi-tenant | [https://semantic-layer.emea.dbt.com/api/graphql](https://semantic-layer.emea.dbt.com/api/graphql) | | APAC multi-tenant | [https://semantic-layer.au.dbt.com/api/graphql](https://semantic-layer.au.dbt.com/api/graphql) | | Single tenant | `https://semantic-layer.YOUR_ACCESS_URL/api/graphql`

Replace `YOUR_ACCESS_URL` with your specific account prefix followed by the appropriate Access URL for your region and plan. | | Multi-cell | `https://YOUR_ACCOUNT_PREFIX.semantic-layer.REGION.dbt.com/api/graphql`

Replace `YOUR_ACCOUNT_PREFIX` with your specific account identifier and `REGION` with your location, which could be `us1.dbt.com`. | **Example** * If your Single tenant access URL is `ABC123.getdbt.com`, your schema explorer URL will be `https://semantic-layer.ABC123.getdbt.com/api/graphql`. dbt Partners can use the Semantic Layer GraphQL API to build an integration with the Semantic Layer. Note that the Semantic Layer GraphQL API doesn't support `ref` to call dbt objects. Instead, use the complete qualified table name. If you're using dbt macros at query time to calculate your metrics, you should move those calculations into your Semantic Layer metric definitions as code. Requirements to use the GraphQL API[​](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-graphql#requirements-to-use-the-graphql-api "Direct link to Requirements to use the GraphQL API") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- * A dbt project on dbt v1.6 or higher * Metrics are defined and configured * A dbt [service token](https://docs.getdbt.com/docs/dbt-cloud-apis/service-tokens) with "Semantic Layer Only” and "Metadata Only" permissions or a [personal access token](https://docs.getdbt.com/docs/dbt-cloud-apis/user-tokens) Using the GraphQL API[​](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-graphql#using-the-graphql-api "Direct link to Using the GraphQL API") ---------------------------------------------------------------------------------------------------------------------------------------------- If you're a dbt user or partner with access to dbt and the [Semantic Layer](https://docs.getdbt.com/docs/use-dbt-semantic-layer/dbt-sl) , you can [set up](https://docs.getdbt.com/docs/use-dbt-semantic-layer/setup-sl) and test this API with data from your own instance by configuring the Semantic Layer and obtaining the right GQL connection parameters described in this document. Refer to [Get started with the Semantic Layer](https://docs.getdbt.com/guides/sl-snowflake-qs) for more info. Authentication uses either a dbt [service account token](https://docs.getdbt.com/docs/dbt-cloud-apis/service-tokens) or a [personal access token](https://docs.getdbt.com/docs/dbt-cloud-apis/user-tokens) passed through a header as follows. To explore the schema, you can enter this information in the "header" section. {"Authorization": "Bearer "} Each GQL request also requires a dbt `environmentId`. The API uses both the service or personal token in the header and `environmentId` for authentication. ### Metadata calls[​](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-graphql#metadata-calls "Direct link to Metadata calls") #### Fetch data platform dialect[​](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-graphql#fetch-data-platform-dialect "Direct link to Fetch data platform dialect") In some cases in your application, it may be useful to know the dialect or data platform that's internally used for the Semantic Layer connection (such as if you are building `where` filters from a user interface rather than user-inputted SQL). The GraphQL API has an easy way to fetch this with the following query: { environmentInfo(environmentId: BigInt!) { dialect }} #### Fetch available metrics[​](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-graphql#fetch-available-metrics "Direct link to Fetch available metrics") metricsPaginated( environmentId: BigInt! search: String = null groupBy: [GroupByInput!] = null pageNum: Int! = 1 pageSize: Int = null): MetricResultPage! { items: [Metric!]! pageNum: Int! pageSize: Int totalItems: Int! totalPages: Int!} #### Fetch available dimensions for metrics[​](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-graphql#fetch-available-dimensions-for-metrics "Direct link to Fetch available dimensions for metrics") dimensionsPaginated( environmentId: BigInt! metrics: [MetricInput!]! search: String = null pageNum: Int! = 1 pageSize: Int = null): DimensionResultPage! { items: [Dimension!]! pageNum: Int! pageSize: Int totalItems: Int! totalPages: Int!} #### Fetch available granularities given metrics[​](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-graphql#fetch-available-granularities-given-metrics "Direct link to Fetch available granularities given metrics") Note: This call for `queryableGranularities` returns only queryable granularities for metric time - the primary time dimension across all metrics selected. queryableGranularities( environmentId: BigInt! metrics: [MetricInput!]!): [TimeGranularity!]! You can also get queryable granularities for all other dimensions using the `dimensions` call: { dimensionsPaginated(environmentId: BigInt!, metrics:[{name:"order_total"}]) { items { name queryableGranularities # --> ["DAY", "WEEK", "MONTH", "QUARTER", "YEAR"] } }} You can also optionally access it from the metrics endpoint: { metricsPaginated(environmentId: BigInt!) { items { name dimensions { name queryableGranularities } } }} #### Fetch measures[​](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-graphql#fetch-measures "Direct link to Fetch measures") { measures(environmentId: BigInt!, metrics: [{name:"order_total"}]) { name aggTimeDimension }} `aggTimeDimension` tells you the name of the dimension that maps to `metric_time` for a given measure. You can also query `measures` from the `metrics` endpoint, which allows you to see what dimensions map to `metric_time` for a given metric: { metricsPaginated(environmentId: BigInt!) { items { measures { name aggTimeDimension } } }} #### Fetch entities[​](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-graphql#fetch-entities "Direct link to Fetch entities") entitiesPaginated( environmentId: BigInt! metrics: [MetricInput!] = null search: String = null pageNum: Int! = 1 pageSize: Int = null): EntityResultPage! { items: [Entity!]! pageNum: Int! pageSize: Int totalItems: Int! totalPages: Int!} #### Fetch entities and dimensions to group metrics[​](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-graphql#fetch-entities-and-dimensions-to-group-metrics "Direct link to Fetch entities and dimensions to group metrics") groupBysPaginated( environmentId: BigInt! metrics: [MetricInput!] = null search: String = null pageNum: Int! = 1 pageSize: Int = null): EntityDimensionResultPage! { items: [EntityDimension!]! pageNum: Int! pageSize: Int totalItems: Int! totalPages: Int!} #### Metric types[​](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-graphql#metric-types "Direct link to Metric types") Metric { name: String! description: String type: MetricType! typeParams: MetricTypeParams! filter: WhereFilter dimensions: [Dimension!]! queryableGranularities: [TimeGranularity!]!} MetricType = [SIMPLE, RATIO, CUMULATIVE, DERIVED] #### Metric type parameters[​](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-graphql#metric-type-parameters "Direct link to Metric type parameters") MetricTypeParams { measure: MetricInputMeasure inputMeasures: [MetricInputMeasure!]! numerator: MetricInput denominator: MetricInput expr: String window: MetricTimeWindow grainToDate: TimeGranularity metrics: [MetricInput!]} #### Dimension types[​](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-graphql#dimension-types "Direct link to Dimension types") Dimension { name: String! description: String type: DimensionType! typeParams: DimensionTypeParams isPartition: Boolean! expr: String queryableGranularities: [TimeGranularity!]!} DimensionType = [CATEGORICAL, TIME] #### List saved queries[​](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-graphql#list-saved-queries "Direct link to List saved queries") List all saved queries for the specified environment: savedQueriesPaginated( environmentId: BigInt! search: String = null pageNum: Int! = 1 pageSize: Int = null): SavedQueryResultPage! { items: [SavedQuery!]! pageNum: Int! pageSize: Int totalItems: Int! totalPages: Int!} #### List a saved query[​](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-graphql#list-a-saved-query "Direct link to List a saved query") List a single saved query using environment ID and query name: {savedQuery(environmentId: "123", savedQueryName: "query_name") { name description label queryParams { metrics { name } groupBy { name grain datePart } where { whereSqlTemplate } }}} ### Querying[​](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-graphql#querying "Direct link to Querying") When querying for data, _either_ a `groupBy` _or_ a `metrics` selection is required. The following section provides examples of how to query metrics: * [Create query](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-graphql#create-metric-query) * [Fetch query result](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-graphql#fetch-query-result) #### Create query[​](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-graphql#create-query "Direct link to Create query") createQuery( environmentId: BigInt! metrics: [MetricInput!]! groupBy: [GroupByInput!] = null limit: Int = null where: [WhereInput!] = null order: [OrderByInput!] = null): CreateQueryResult MetricInput { name: String! alias: String!}GroupByInput { name: String! grain: TimeGranularity = null}WhereInput { sql: String!}OrderByinput { # -- pass one and only one of metric or groupBy metric: MetricInput = null groupBy: GroupByInput = null descending: Boolean! = false} #### Fetch query result[​](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-graphql#fetch-query-result "Direct link to Fetch query result") query( environmentId: BigInt! queryId: String!): QueryResult! The GraphQL API uses a polling process for querying since queries can be long-running in some cases. It works by first creating a query with a mutation, \`createQuery, which returns a query ID. This ID is then used to continuously check (poll) for the results and status of your query. The typical flow would look as follows: 1. Kick off a query mutation { createQuery( environmentId: 123456 metrics: [{name: "order_total"}] groupBy: [{name: "metric_time"}] ) { queryId # => Returns 'QueryID_12345678' }} 2. Poll for results { query(environmentId: 123456, queryId: "QueryID_12345678") { sql status error totalPages jsonResult arrowResult }} 3. Keep querying 2. at an appropriate interval until status is `FAILED` or `SUCCESSFUL` ### Output format and pagination[​](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-graphql#output-format-and-pagination "Direct link to Output format and pagination") #### Output format[​](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-graphql#output-format "Direct link to Output format") By default, the output is in Arrow format. You can switch to JSON format using the following parameter. However, due to performance limitations, we recommend using the JSON parameter for testing and validation. The JSON received is a base64 encoded string. To access it, you can decode it using a base64 decoder. The JSON is created from pandas, which means you can change it back to a dataframe using `pandas.read_json(json, orient="table")`. Or you can work with the data directly using `json["data"]`, and find the table schema using `json["schema"]["fields"]`. Alternatively, you can pass `encoded:false` to the jsonResult field to get a raw JSON string directly. { query(environmentId: BigInt!, queryId: Int!, pageNum: Int! = 1) { sql status error totalPages arrowResult jsonResult(orient: PandasJsonOrient! = TABLE, encoded: Boolean! = true) }} The results default to the table but you can change it to any [pandas](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.to_json.html) supported value. #### Pagination[​](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-graphql#pagination "Direct link to Pagination") By default, we return 1024 rows per page. If your result set exceeds this, you need to increase the page number using the `pageNum` option. ### Run a Python query[​](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-graphql#run-a-python-query "Direct link to Run a Python query") The `arrowResult` in the GraphQL query response is a byte dump, which isn't visually useful. You can convert this byte data into an Arrow table using any Arrow-supported language. Refer to the following Python example explaining how to query and decode the arrow result: import base64import pyarrow as paimport timeheaders = {"Authorization":"Bearer "}query_result_request = """{ query(environmentId: 70, queryId: "12345678") { sql status error arrowResult }}"""while True: gql_response = requests.post( "https://semantic-layer.cloud.getdbt.com/api/graphql", json={"query": query_result_request}, headers=headers, ) if gql_response.json()["data"]["status"] in ["FAILED", "SUCCESSFUL"]: break # Set an appropriate interval between polling requests time.sleep(1)"""gql_response.json() => { "data": { "query": { "sql": "SELECT\n ordered_at AS metric_time__day\n , SUM(order_total) AS order_total\nFROM semantic_layer.orders orders_src_1\nGROUP BY\n ordered_at", "status": "SUCCESSFUL", "error": null, "arrowResult": "arrow-byte-data" } }}"""def to_arrow_table(byte_string: str) -> pa.Table: """Get a raw base64 string and convert to an Arrow Table.""" with pa.ipc.open_stream(base64.b64decode(byte_string)) as reader: return pa.Table.from_batches(reader, reader.schema)arrow_table = to_arrow_table(gql_response.json()["data"]["query"]["arrowResult"])# Perform whatever functionality is available, like convert to a pandas table.print(arrow_table.to_pandas())"""order_total ordered_at 3 2023-08-07 112 2023-08-08 12 2023-08-09 5123 2023-08-10""" ### Additional create query examples[​](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-graphql#additional-create-query-examples "Direct link to Additional create query examples") The following section provides query examples for the GraphQL API, such as how to query metrics, dimensions, where filters, and more: * [Query metric alias](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-graphql#query-metric-alias) — Query with metric alias, which allows you to use simpler or more intuitive names for metrics instead of their full definitions. * [Query with a time grain](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-graphql#query-with-a-time-grain) — Fetch multiple metrics with a change in time dimension granularities. * [Query multiple metrics and multiple dimensions](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-graphql#query-multiple-metrics-and-multiple-dimensions) — Select common dimensions for multiple metrics. * [Query a categorical dimension on its own](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-graphql#query-a-categorical-dimension-on-its-own) — Group by a categorical dimension. * [Query with a where filter](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-graphql#query-with-a-where-filter) — Use the `where` parameter to filter on dimensions and entities using parameters. * [Query with order](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-graphql#query-with-order) — Query with `orderBy`, accepts basic string that's a Dimension, Metric, or Entity. Defaults to ascending order. * [Query with limit](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-graphql#query-with-limit) — Query using a `limit` clause. * [Query saved queries](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-graphql#query-saved-queries) — Query using a saved query using the `savedQuery` parameter for frequently used queries. * [Query with just compiling SQL](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-graphql#query-with-just-compiling-sql) — Query using a compile keyword using the `compileSql` mutation. * [Query records](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-graphql#query-records) — View all the queries made in your project. #### Query metric alias[​](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-graphql#query-metric-alias "Direct link to Query metric alias") mutation { createQuery( environmentId: "123" metrics: [{name: "metric_name", alias: "metric_alias"}] ) { ... }} #### Query with a time grain[​](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-graphql#query-with-a-time-grain "Direct link to Query with a time grain") mutation { createQuery( environmentId: "123" metrics: [{name: "order_total"}] groupBy: [{name: "metric_time", grain: MONTH}] ) { queryId }} Note that when using granularity in the query, the output of a time dimension with a time grain applied to it always takes the form of a dimension name appended with a double underscore and the granularity level - `{time_dimension_name}__{DAY|WEEK|MONTH|QUARTER|YEAR}`. Even if no granularity is specified, it will also always have a granularity appended to it and will default to the lowest available (usually daily for most data sources). It is encouraged to specify a granularity when using time dimensions so that there won't be any unexpected results with the output data. #### Query multiple metrics and multiple dimensions[​](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-graphql#query-multiple-metrics-and-multiple-dimensions "Direct link to Query multiple metrics and multiple dimensions") mutation { createQuery( environmentId: "123" metrics: [{name: "food_order_amount"}, {name: "order_gross_profit"}] groupBy: [{name: "metric_time", grain: MONTH}, {name: "customer__customer_type"}] ) { queryId }} #### Query a categorical dimension on its own[​](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-graphql#query-a-categorical-dimension-on-its-own "Direct link to Query a categorical dimension on its own") mutation { createQuery( environmentId: "123" groupBy: [{name: "customer__customer_type"}] ) { queryId }} #### Query with a where filter[​](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-graphql#query-with-a-where-filter "Direct link to Query with a where filter") The `where` filter takes a list argument (or a string for a single input). Depending on the object you are filtering, there are a couple of parameters: * `Dimension()` — Used for any categorical or time dimensions. For example, `Dimension('metric_time').grain('week')` or `Dimension('customer__country')`. * `Entity()` — Used for entities like primary and foreign keys, such as `Entity('order_id')`. Note: If you prefer a `where` clause with a more explicit path, you can optionally use `TimeDimension()` to separate categorical dimensions from time ones. The `TimeDimension` input takes the time dimension and optionally the granularity level. `TimeDimension('metric_time', 'month')`. mutation { createQuery( environmentId: "123" metrics:[{name: "order_total"}] groupBy:[{name: "customer__customer_type"}, {name: "metric_time", grain: month}] where:[{sql: "{{ Dimension('customer__customer_type') }} = 'new'"}, {sql:"{{ Dimension('metric_time').grain('month') }} > '2022-10-01'"}] ) { queryId }} For both `TimeDimension()`, the grain is only required in the `where` filter if the aggregation time dimensions for the measures and metrics associated with the where filter have different grains. #### Example[​](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-graphql#example "Direct link to Example") For example, consider this semantic model and metric configuration, which contains two metrics that are aggregated across different time grains. This example shows a single semantic model, but the same goes for metrics across more than one semantic model. semantic_model: name: my_model_sourcedefaults: agg_time_dimension: created_month measures: - name: measure_0 agg: sum - name: measure_1 agg: sum agg_time_dimension: order_year dimensions: - name: created_month type: time type_params: time_granularity: month - name: order_year type: time type_params: time_granularity: yearmetrics: - name: metric_0 description: A metric with a month grain. type: simple type_params: measure: measure_0 - name: metric_1 description: A metric with a year grain. type: simple type_params: measure: measure_1 Assuming the user is querying `metric_0` and `metric_1` together, the following are valid or invalid filters: | Example | Filter | | --- | --- | | ✅
Valid filter | `"{{ TimeDimension('metric_time', 'year') }} > '2020-01-01'"` | | ❌
Invalid filter | `"{{ TimeDimension('metric_time') }} > '2020-01-01'"`

Metrics in the query are defined based on measures with different grains. | | ❌
Invalid filter | `"{{ TimeDimension('metric_time', 'month') }} > '2020-01-01'"`

`metric_1` is not available at a month grain. | #### Multi-hop joins[​](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-graphql#multi-hop-joins "Direct link to Multi-hop joins") In cases where you need to query across multiple related tables (multi-hop joins), use the `entity_path` argument to specify the path between related entities. The following are examples of how you can define these joins: * In this example, you're querying the `location_name` dimension but specifying that it should be joined using the `order_id` field. {{Dimension('location__location_name', entity_path=['order_id'])}} * In this example, the `salesforce_account_owner` dimension is joined to the `region` field, with the path going through `salesforce_account`. {{ Dimension('salesforce_account_owner__region',['salesforce_account']) }} #### Query with order[​](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-graphql#query-with-order "Direct link to Query with order") mutation { createQuery( environmentId: "123" metrics: [{name: "order_total"}] groupBy: [{name: "metric_time", grain: MONTH}] orderBy: [{metric: {name: "order_total"}}, {groupBy: {name: "metric_time", grain: MONTH}, descending:true}] ) { queryId }} #### Query with limit[​](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-graphql#query-with-limit "Direct link to Query with limit") mutation { createQuery( environmentId: "123" metrics: [{name:"food_order_amount"}, {name: "order_gross_profit"}] groupBy: [{name:"metric_time", grain: MONTH}, {name: "customer__customer_type"}] limit: 10 ) { queryId }} #### Query saved queries[​](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-graphql#query-saved-queries "Direct link to Query saved queries") This takes the same inputs as the `createQuery` mutation, but includes the field `savedQuery`. You can use this for frequently used queries. mutation { createQuery( environmentId: "123" savedQuery: "new_customer_orders" ) { queryId }} A note on querying saved queries When querying [saved queries](https://docs.getdbt.com/docs/build/saved-queries) ,you can use parameters such as `where`, `limit`, `order`, `compile`, and so on. However, keep in mind that you can't access `metric` or `group_by` parameters in this context. This is because they are predetermined and fixed parameters for saved queries, and you can't change them at query time. If you would like to query more metrics or dimensions, you can build the query using the standard format. #### Query with just compiling SQL[​](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-graphql#query-with-just-compiling-sql "Direct link to Query with just compiling SQL") This takes the same inputs as the `createQuery` mutation. mutation { compileSql( environmentId: "123" metrics: [{name:"food_order_amount"} {name:"order_gross_profit"}] groupBy: [{name:"metric_time", grain: MONTH}, {name:"customer__customer_type"}] ) { sql }} #### Query records[​](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-graphql#query-records "Direct link to Query records") Use this endpoint to view all the queries made in your project. This covers both Insights and Semantic Layer queries. { queryRecords( environmentId:123 ) { items { queryId status startTime endTime connectionDetails sqlDialect connectionSchema error queryDetails { ... on SemanticLayerQueryDetails { params { type metrics { name } groupBy { name grain } limit where { sql } orderBy { groupBy { name grain } metric { name } descending } savedQuery } } ... on RawSqlQueryDetails { queryStr compiledSql numCols queryDescription queryTitle } } } totalItems pageNum pageSize }} Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [dbt Semantic Layer GraphQL API](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-graphql#dbt-semantic-layer-graphql-api) * [Requirements to use the GraphQL API](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-graphql#requirements-to-use-the-graphql-api) * [Using the GraphQL API](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-graphql#using-the-graphql-api) * [Metadata calls](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-graphql#metadata-calls) * [Querying](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-graphql#querying) * [Output format and pagination](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-graphql#output-format-and-pagination) * [Run a Python query](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-graphql#run-a-python-query) * [Additional create query examples](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-graphql#additional-create-query-examples) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/dbt-cloud-apis/sl-graphql.md) --- # Advanced CI | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/deploy/advanced-ci#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page [Continuous integration workflows](https://docs.getdbt.com/docs/deploy/continuous-integration) help increase the governance and improve the quality of the data. Additionally for these CI jobs, you can use Advanced CI features, such as [compare changes](https://docs.getdbt.com/docs/deploy/advanced-ci#compare-changes) , that provide details about the changes between what's currently in your production environment and the pull request's latest commit, giving you observability into how data changes are affected by your code changes. By analyzing the data changes that code changes produce, you can ensure you're always shipping trustworthy data products as you're developing. How to enable this feature You can opt into Advanced CI in dbt. Please refer to [Account access to Advanced CI features](https://docs.getdbt.com/docs/cloud/account-settings#account-access-to-advanced-ci-features) to learn how enable it in your dbt account. Prerequisites[​](https://docs.getdbt.com/docs/deploy/advanced-ci#prerequisites "Direct link to Prerequisites") --------------------------------------------------------------------------------------------------------------- * You have a dbt Enterprise or Enterprise+ account. * You have [Advanced CI features](https://docs.getdbt.com/docs/cloud/account-settings#account-access-to-advanced-features) enabled. * You use a supported data platform: BigQuery, Databricks, Postgres, Redshift, or Snowflake. Support for additional data platforms coming soon. Compare changes feature[​](https://docs.getdbt.com/docs/deploy/advanced-ci#compare-changes "Direct link to Compare changes feature") ------------------------------------------------------------------------------------------------------------------------------------- For [CI jobs](https://docs.getdbt.com/docs/deploy/ci-jobs) that have the [**dbt compare** option enabled](https://docs.getdbt.com/docs/deploy/ci-jobs#set-up-ci-jobs) , dbt compares the changes between the last applied state of the production environment (defaulting to deferral for lower compute costs) and the latest changes from the pull request, whenever a pull request is opened or new commits are pushed. dbt reports the comparison differences in: * **dbt** — Shows the changes (if any) to the data's primary keys, rows, and columns in the [Compare tab](https://docs.getdbt.com/docs/deploy/run-visibility#compare-tab) from the [Job run details](https://docs.getdbt.com/docs/deploy/run-visibility#job-run-details) page. * **The pull request from your Git provider** — Shows a summary of the changes as a Git comment. [![Example of the Compare tab](https://docs.getdbt.com/img/docs/dbt-cloud/example-ci-compare-changes-tab.png?v=2 "Example of the Compare tab")](https://docs.getdbt.com/docs/deploy/advanced-ci#) Example of the Compare tab ### Optimizing comparisons[​](https://docs.getdbt.com/docs/deploy/advanced-ci#optimizing-comparisons "Direct link to Optimizing comparisons") When an [`event_time`](https://docs.getdbt.com/reference/resource-configs/event-time) column is specified on your model, compare changes can optimize comparisons by using only the overlapping timeframe (meaning the timeframe exists in both the CI and production environment), helping you avoid incorrect row-count changes and return results faster. This is useful in scenarios like: * **Subset of data in CI** — When CI builds only a [subset of data](https://docs.getdbt.com/best-practices/best-practice-workflows#limit-the-data-processed-when-in-development) (like the most recent 7 days), compare changes would interpret the excluded data as "deleted rows." Configuring `event_time` allows you to avoid this issue by limiting comparisons to the overlapping timeframe, preventing false alerts about data deletions that are just filtered out in CI. * **Fresher data in CI than in production** — When your CI job includes fresher data than production (because it has run more recently), compare changes would flag the additional rows as "new" data, even though they’re just fresher data in CI. With `event_time` configured, the comparison only includes the shared timeframe and correctly reflects actual changes in the data. [![event_time ensures the same time-slice of data is accurately compared between your CI and production environments.](https://docs.getdbt.com/img/docs/deploy/apples_to_apples.png?v=2 "event_time ensures the same time-slice of data is accurately compared between your CI and production environments.")](https://docs.getdbt.com/docs/deploy/advanced-ci#) event\_time ensures the same time-slice of data is accurately compared between your CI and production environments. About the cached data[​](https://docs.getdbt.com/docs/deploy/advanced-ci#about-the-cached-data "Direct link to About the cached data") --------------------------------------------------------------------------------------------------------------------------------------- After [comparing changes](https://docs.getdbt.com/docs/deploy/advanced-ci#compare-changes) , dbt stores a cache of no more than 100 records for each modified model for preview purposes. By caching this data, you can view the examples of changed data without rerunning the comparison against the data warehouse every time (optimizing for lower compute costs). To display the changes, dbt uses a cached version of a sample of the data records. These data records are queried from the database using the connection configuration (such as user, role, service account, and so on) that's set in the CI job's environment. You control what data to use. This may include synthetic data if pre-production or development data is heavily regulated or sensitive. * The selected data is cached on dbt Labs' systems for up to 30 days. No data is retained on dbt Labs' systems beyond this period. * The cache is encrypted and stored in an Amazon S3 or Azure blob storage in your account’s region. * dbt Labs will not access cached data from Advanced CI for its benefit and the data is only used to provide services as directed by you. * Third-party subcontractors, other than storage subcontractors, will not have access to the cached data. If you access a CI job run that's more than 30 days old, you will not be able to see the comparison results. Instead, a message will appear indicating that the data has expired. [![Example of message about expired data in the Compare tab](https://docs.getdbt.com/img/docs/deploy/compare-expired.png?v=2 "Example of message about expired data in the Compare tab")](https://docs.getdbt.com/docs/deploy/advanced-ci#) Example of message about expired data in the Compare tab Connection permissions[​](https://docs.getdbt.com/docs/deploy/advanced-ci#connection-permissions "Direct link to Connection permissions") ------------------------------------------------------------------------------------------------------------------------------------------ The compare changes feature uses the same credentials as the CI job, as defined in the CI job’s environment. The dbt administrator must ensure that client CI credentials are appropriately restricted since all customer's account users will be able to view the comparison results and the cached data. If using dynamic data masking in the data warehouse, the cached data will no longer be dynamically masked in the Advanced CI output, depending on the permissions of the users who view it. dbt Labs recommends limiting user access to unmasked data or considering using synthetic data for the Advanced CI testing functionality. [![Example of credentials in the user settings](https://docs.getdbt.com/img/docs/deploy/compare-credentials.png?v=2 "Example of credentials in the user settings")](https://docs.getdbt.com/docs/deploy/advanced-ci#) Example of credentials in the user settings Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Prerequisites](https://docs.getdbt.com/docs/deploy/advanced-ci#prerequisites) * [Compare changes feature](https://docs.getdbt.com/docs/deploy/advanced-ci#compare-changes) * [Optimizing comparisons](https://docs.getdbt.com/docs/deploy/advanced-ci#optimizing-comparisons) * [About the cached data](https://docs.getdbt.com/docs/deploy/advanced-ci#about-the-cached-data) * [Connection permissions](https://docs.getdbt.com/docs/deploy/advanced-ci#connection-permissions) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/deploy/advanced-ci.md) --- # dbt support | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/dbt-support#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page Support for dbt is available to all users through the following channels: * Dedicated dbt Support team (dbt users). * [The Community Forum](https://discourse.getdbt.com/) . * [dbt Community slack](https://www.getdbt.com/community/join-the-community/) . dbt Core support[​](https://docs.getdbt.com/docs/dbt-support#dbt-core-support "Direct link to dbt Core support") ----------------------------------------------------------------------------------------------------------------- If you're developing on the command line (CLI) and have questions or need some help — reach out to the helpful dbt community through [the Community Forum](https://discourse.getdbt.com/) or [dbt Community slack](https://www.getdbt.com/community/join-the-community/) . dbt platform support[​](https://docs.getdbt.com/docs/dbt-support#dbt-platform-support "Direct link to dbt platform support") ----------------------------------------------------------------------------------------------------------------------------- The global dbt Support team is available to dbt customers by [email](mailto:support@getdbt.com) or by clicking **Create a support ticket** through the dbt navigation. ### Create a support ticket[​](https://docs.getdbt.com/docs/dbt-support#create-a-support-ticket "Direct link to Create a support ticket") To create a support ticket in dbt: 1. In the dbt navigation, click on **Help & Guides**. 2. Click **Create a support ticket**. 3. Fill out the form and click **Create Ticket**. 4. A dbt Support team member will respond to your ticket through email. [![Create a support ticket in dbt](https://docs.getdbt.com/img/create-support-ticket.gif?v=2 "Create a support ticket in dbt")](https://docs.getdbt.com/docs/dbt-support#) Create a support ticket in dbt ### Ask dbt Support Assistant[​](https://docs.getdbt.com/docs/dbt-support#ask-dbt-support-assistant "Direct link to Ask dbt Support Assistant") dbt Support Assistant is an AI widget that provides instant, AI-generated responses to common questions. This feature is available to dbt users and can help answer troubleshooting questions, give a synopsis of features and functionality, or link to relevant documentation. The dbt Support Assistant AI widget is separate from [Copilot](https://docs.getdbt.com/docs/cloud/dbt-copilot) , a powerful AI engine that helps with code generation to accelerate your analytics workflows. The dbt Support Assistant focuses on answering documentation and troubleshooting-related questions. Enabling or disabling AI features in dbt won't affect the dbt Support Assistant's availability. info We recommend validating information received in AI responses for any scenario using our documentation. Please [contact support](mailto:support@getdbt.com) to report incorrect information provided by the Support Assistant. ### Support plans and resources[​](https://docs.getdbt.com/docs/dbt-support#support-plans-and-resources "Direct link to Support plans and resources") We want to help you work through implementing and utilizing dbt platform at your organization. Have a question you can't find an answer to in [our docs](https://docs.getdbt.com/) or [the Community Forum](https://discourse.getdbt.com/) ? Our Support team is here to `dbt help` you! * **Enterprise and Enterprise+ plans** — Priority [support](https://docs.getdbt.com/docs/dbt-support#severity-level-for-enterprise-support) , optional premium plans, enhanced SLAs, implementation assistance, dedicated management, and dbt Labs security reviews depending on price point. * **Developer and Starter plans** — 24x5 support (no service level agreement (SLA); [contact Sales](https://www.getdbt.com/pricing/) for Enterprise plan inquiries). * **Support team help** — Assistance with [common dbt questions](https://docs.getdbt.com/category/troubleshooting) , like project setup, login issues, error understanding, setup private packages, link to a new GitHub account, [how to generate a har file](https://docs.getdbt.com/faqs/Troubleshooting/generate-har-file) , and so on. * **Resource guide** — Check the [guide](https://docs.getdbt.com/community/resources/getting-help) for effective help-seeking strategies. Example of common support questions Types of dbt cloud-based platform related questions our Support team can assist you with, regardless of your dbt plan: **How do I...** * set up a dbt project? * set up a private package in dbt? * configure custom branches on git repos? * link dbt to a new GitHub account? **Help! I can't...** * log in. * access logs. * update user groups. **I need help understanding...** * why this run failed. * why I am getting this error message in dbt? * why my CI jobs are not kicking off as expected. dbt Enterprise accounts[​](https://docs.getdbt.com/docs/dbt-support#dbt-enterprise-accounts "Direct link to dbt Enterprise accounts") -------------------------------------------------------------------------------------------------------------------------------------- Basic assistance with dbt project troubleshooting. Help with errors and issues in macros, models, and dbt Labs' packages. For strategic advice, best practices, or expansion conversations, consult your Account team. For customers on a dbt Enterprise-tier plan, we **also** offer basic assistance in troubleshooting issues with your dbt project: * **Something isn't working the way I would expect it to...** * in a macro I created... * in an incremental model I'm building... * in one of dbt Labs' packages like dbt\_utils or audit\_helper... * **I need help understanding and troubleshooting this error...** * `Server error: Compilation Error in rpc request (from remote system) 'dbt_utils' is undefined` * `SQL compilation error: syntax error line 1 at position 38 unexpected ''.` * `Compilation Error Error reading name_of_folder/name_of_file.yml - Runtime Error Syntax error near line 9` Types of questions you should ask your Account team: * How should we think about setting up our dbt projects, environments, and jobs based on our company structure and needs? * I want to expand my account! How do I add more people and train them? * Here is our data road map for the next year - can we talk through how dbt fits into it and what features we may not be utilizing that can help us achieve our goals? * It is time for our contract renewal, what options do I have? ### Severity level for Enterprise support[​](https://docs.getdbt.com/docs/dbt-support#severity-level-for-enterprise-support "Direct link to Severity level for Enterprise support") Support tickets are assigned a severity level based on the impact of the issue on your business. The severity level is assigned by dbt Labs, and the level assigned determines the priority level of support you will receive. For specific ticket response time or other questions that relate to your Enterprise or Enterprise+ account’s SLA, please refer to your Enterprise contract. | Severity Level | Description | | --- | --- | | Severity Level 1 | Any Error which makes the use or continued use of the Subscription or material features impossible; Subscription is not operational, with no alternative available. | | Severity Level 2 | Feature failure, without a workaround, but Subscription is operational. | | Severity Level 3 | Feature failure, but a workaround exists. | | Severity Level 4 | Error with low-to-no impact on Client’s access to or use of the Subscription, or Client has a general question or feature enhancement request. | Leave feedback[​](https://docs.getdbt.com/docs/dbt-support#leave-feedback "Direct link to Leave feedback") ----------------------------------------------------------------------------------------------------------- Leave feedback or submit a feature request for dbt or dbt Core. #### Share feedback or feature request for the dbt platform[​](https://docs.getdbt.com/docs/dbt-support#share-feedback-or-feature-request-for-the-dbt-platform "Direct link to Share feedback or feature request for the dbt platform") 1. In the dbt navigation, click **Leave feedback**. 2. In the **Leave feedback** pop up, fill out the form. 3. Upload any relevant files to the feedback form (optional). 4. Confirm if you'd like dbt Labs to contact you about the feedback (optional). 5. Click **Send Feedback**. [![Leave feedback in dbt](https://docs.getdbt.com/img/docs/leave-feedback.gif?v=2 "Leave feedback in dbt")](https://docs.getdbt.com/docs/dbt-support#) Leave feedback in dbt #### Share feedback or feature request for dbt Core[​](https://docs.getdbt.com/docs/dbt-support#share-feedback-or-feature-request-for-dbt-core "Direct link to Share feedback or feature request for dbt Core") * [Create a GitHub issue here](https://github.com/dbt-labs/dbt-core/issues) . External help[​](https://docs.getdbt.com/docs/dbt-support#external-help "Direct link to External help") -------------------------------------------------------------------------------------------------------- For SQL writing, project performance review, or project building, refer to dbt Preferred Consulting Providers and dbt Labs' Services. For help writing SQL, reviewing the overall performance of your project, or want someone to actually help build your dbt project, refer to the following pages: * List of [dbt Consulting Partners](https://www.getdbt.com/partner-directory) . * dbt Labs' [Services](https://www.getdbt.com/dbt-labs/services/) . Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [dbt Core support](https://docs.getdbt.com/docs/dbt-support#dbt-core-support) * [dbt platform support](https://docs.getdbt.com/docs/dbt-support#dbt-platform-support) * [Create a support ticket](https://docs.getdbt.com/docs/dbt-support#create-a-support-ticket) * [Ask dbt Support Assistant](https://docs.getdbt.com/docs/dbt-support#ask-dbt-support-assistant) * [Support plans and resources](https://docs.getdbt.com/docs/dbt-support#support-plans-and-resources) * [dbt Enterprise accounts](https://docs.getdbt.com/docs/dbt-support#dbt-enterprise-accounts) * [Severity level for Enterprise support](https://docs.getdbt.com/docs/dbt-support#severity-level-for-enterprise-support) * [Leave feedback](https://docs.getdbt.com/docs/dbt-support#leave-feedback) * [External help](https://docs.getdbt.com/docs/dbt-support#external-help) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/dbt-support.md) --- # Install Fusion | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/fusion/install-fusion#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page Learn more about installing Fusion locally, along with important prerequisites, step-by-step installation instructions, troubleshooting common issues, and configuration guidance. Prerequisites[​](https://docs.getdbt.com/docs/fusion/install-fusion#prerequisites "Direct link to Prerequisites") ------------------------------------------------------------------------------------------------------------------ Before installing Fusion, ensure that you: * Have administrative privileges to install software on your local machine. * Are comfortable using a command-line interface (Terminal on macOS/Linux, PowerShell on Windows). * Use a supported data warehouse and authentication method and configure permissions as needed:  BigQuery * Service Account / User Token * Native OAuth * External OAuth * [Required permissions](https://docs.getdbt.com/docs/core/connect-data-platform/bigquery-setup#required-permissions) Databricks * Service Account / User Token * Native OAuth Redshift * Username / Password Snowflake * Username / Password * Native OAuth * External OAuth * Key pair * MFA * Use a supported operating system: 🟢 - Supported 🟡 - Not yet supported | Operating System | X86-64 | ARM | | --- | --- | --- | | macOS | 🟢 | 🟢 | | Linux | 🟢 | 🟢 | | Windows | 🟢 | 🟡 | [![](https://docs.getdbt.com/img/icons/dbt-bit.svg)\ \ #### dbt VS Code Extension\ \ Learn how to connect to a data platform, integrate with secure authentication methods, and configure a sync with a git repo.](https://docs.getdbt.com/docs/fusion/install-dbt-extension) [![](https://docs.getdbt.com/img/icons/dbt-bit.svg)\ \ #### dbt Fusion engine from the CLI\ \ Learn how to install the dbt Fusion engine on the CLI.](https://docs.getdbt.com/docs/fusion/install-fusion-cli) [![](https://docs.getdbt.com/img/icons/dbt-bit.svg)\ \ #### dbt Fusion engine upgrade\ \ Learn how you can upgrade and leverage the speed and scale of the dbt Fusion engine.](https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-version-in-cloud#dbt-fusion-engine) Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Prerequisites](https://docs.getdbt.com/docs/fusion/install-fusion#prerequisites) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/fusion/install-fusion.md) --- # Access the dbt Insights interface | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/explore/access-dbt-insights#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page Learn how to access Insights, run queries, and view results. Insights provides a rich console experience with editor navigation. You can expect Insights to: * Enable you to write SQL queries, with the option to open multiple tabs * Have SQL + dbt autocomplete suggestions and syntax highlighting * Save SQL queries * View the results of the query and its details using the **Results** or **Details** tabs * Create a visualization of your query results using the **Chart** tab * View the history of queries and their statuses (like Success, Error, Pending) using the **Query history** tab * Use Copilot to generate or edit SQL queries using natural language prompts * Integrate with [Copilot](https://docs.getdbt.com/docs/cloud/dbt-copilot) , [Catalog](https://docs.getdbt.com/docs/explore/explore-projects) , [Studio IDE](https://docs.getdbt.com/docs/cloud/dbt-cloud-ide/develop-in-the-cloud) , and [Canvas](https://docs.getdbt.com/docs/cloud/canvas) to provide a seamless experience for data exploration, AI-assisted writing, and collaboration Access the dbt Insights interface[​](https://docs.getdbt.com/docs/explore/access-dbt-insights#access-the-dbt-insights-interface "Direct link to Access the dbt Insights interface") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ Before accessing Insights, ensure that the [prerequisites](https://docs.getdbt.com/docs/explore/dbt-insights#prerequisites) are met. 1. To access Insights, select the **Insights** option in the navigation sidebar. 2. If your [developer credentials](https://docs.getdbt.com/docs/cloud/dbt-cloud-ide/develop-in-the-cloud#get-started-with-the-cloud-ide) aren’t set up, Insights will prompt you to set them up. The ability to query data is subject to warehouse provider permissions according to your developer credentials. 3. Once your credentials are set up, you can write, run, and edit SQL queries in the Insights editor for existing models in your project. Run queries[​](https://docs.getdbt.com/docs/explore/access-dbt-insights#run-queries "Direct link to Run queries") ------------------------------------------------------------------------------------------------------------------ To run queries in Insights, you can use: * Standard SQL * Jinja ([`ref`](https://docs.getdbt.com/reference/dbt-jinja-functions/ref) , [`source`](https://docs.getdbt.com/reference/dbt-jinja-functions/source) functions, and other Jinja functions) * Links from SQL code `ref` to the corresponding Explorer page * CTEs and subqueries * Basic aggregations and joins * Semantic Layer queries using Semantic Layer Jinja functions Example[​](https://docs.getdbt.com/docs/explore/access-dbt-insights#example "Direct link to Example") ------------------------------------------------------------------------------------------------------ Let's use an example to illustrate how to run queries in Insights: * A [Jaffle Shop](https://github.com/dbt-labs/jaffle-shop) location wants to count unique orders and unique customers to understand whether they can expand their awesome Jaffle shop business to other parts of the world. * To express this logic in SQL, you (an analyst assigned to this project) want to understand yearly trends to help guide expansion decisions. Write the following SQL query to calculate the number of unique customers, cities, and total order revenue: with orders as ( select * from {{ ref('orders') }}),customers as ( select * from {{ ref('customers') }})select date_trunc('year', ordered_at) as order_year, count(distinct orders.customer_id) as unique_customers, count(distinct orders.location_id) as unique_cities, to_char(sum(orders.order_total), '999,999,999.00') as total_order_revenuefrom ordersjoin customers on orders.customer_id = customers.customer_idgroup by 1order by 1 ### Use dbt Copilot[​](https://docs.getdbt.com/docs/explore/access-dbt-insights#use-dbt-copilot "Direct link to Use dbt Copilot") To make things easier, [use Copilot](https://docs.getdbt.com/docs/cloud/use-dbt-copilot#build-queries) to save time and explore other ways to analyze the data. Copilot can help you quickly update the query or generate a new one based on your prompt. 1. Click the **Copilot** icon in the Query console sidebar to open the prompt box. 2. Enter your prompt in natural language and ask for a yearly breakdown of unique customers and total revenue. Then click **Submit**. 3. Copilot responds with: * A summary of the query * An explanation of the logic * The SQL it generated * Options to **Add** or **Replace** the existing query with the generated SQL 4. Review the output and click **Replace** to use the Copilot\-generated SQL in your editor. 5. Then, click **Run** to preview the results. [![dbt Insights with dbt Copilot](https://docs.getdbt.com/img/docs/dbt-insights/insights-copilot.png?v=2 "dbt Insights with dbt Copilot")](https://docs.getdbt.com/docs/explore/access-dbt-insights#) dbt Insights with dbt Copilot From here, you can: * Continue building or modifying the query using Copilot * Explore the [results](https://docs.getdbt.com/docs/explore/access-dbt-insights#view-results) in the **Results** tab * [View metadata and query details](https://docs.getdbt.com/docs/explore/access-dbt-insights#view-details) in the **Details** tab * [Visualize results](https://docs.getdbt.com/docs/explore/access-dbt-insights#chart-results) in the **Chart** tab * Check the [**Query history**](https://docs.getdbt.com/docs/explore/access-dbt-insights#query-history) for status and past runs * Use [**Catalog**](https://docs.getdbt.com/docs/explore/access-dbt-insights#use-dbt-explorer) to explore model lineage and context * If you want to save the query, you can click **Save Insight** in the [query console menu](https://docs.getdbt.com/docs/explore/navigate-dbt-insights#query-console-menu) to save it for future reference. Want to turn a query into a model? You can access the [Studio IDE](https://docs.getdbt.com/docs/cloud/dbt-cloud-ide/develop-in-the-cloud) or [Canvas](https://docs.getdbt.com/docs/cloud/canvas) from the [Query console menu](https://docs.getdbt.com/docs/explore/navigate-dbt-insights#query-console-menu) to promote your SQL into a reusable dbt model — all within dbt! ### View results[​](https://docs.getdbt.com/docs/explore/access-dbt-insights#view-results "Direct link to View results") Using the same example, you can perform some exploratory data analysis by running the query and: * Viewing results in **Results** tab — View the paginated results of the query. * Sorting results — Click on the column header to sort the results by that column. * Exporting to CSV — On the top right of the table, click the download button to export the dataset. [![dbt Insights Export to CSV](https://docs.getdbt.com/img/docs/dbt-insights/insights-export-csv.png?v=2 "dbt Insights Export to CSV")](https://docs.getdbt.com/docs/explore/access-dbt-insights#) dbt Insights Export to CSV ### View details[​](https://docs.getdbt.com/docs/explore/access-dbt-insights#view-details "Direct link to View details") View the details of the query by clicking on the **Details** tab: * **Query metadata** — Copilot\-generated title and description, the supplied SQL, and corresponding compiled SQL. * **Connection details** — Relevant data platform connection information. * **Query details** — Query duration, status, column count, row count. [![dbt Insights Details tab](https://docs.getdbt.com/img/docs/dbt-insights/insights-details.png?v=2 "dbt Insights Details tab")](https://docs.getdbt.com/docs/explore/access-dbt-insights#) dbt Insights Details tab ### Chart results[​](https://docs.getdbt.com/docs/explore/access-dbt-insights#chart-results "Direct link to Chart results") Visualize the chart results of the query by clicking on the **Chart** tab to: * Select the chart type using the chart icon. * Choose from **line chart, bar chart, or scatterplot**. * Select the axis and columns to visualize using the **Chart settings** icon. [![dbt Insights Chart tab](https://docs.getdbt.com/img/docs/dbt-insights/insights-chart.png?v=2 "dbt Insights Chart tab")](https://docs.getdbt.com/docs/explore/access-dbt-insights#) dbt Insights Chart tab ### Query history[​](https://docs.getdbt.com/docs/explore/access-dbt-insights#query-history "Direct link to Query history") View the history of queries and their statuses (All, Success, Error, or Pending) using the **Query history** icon: * Select a query to re-run to view the results. * Search for past queries and filter by status. * Hover over the query to view the SQL code or copy it. The query history is stored indefinitely. [![dbt Insights Query history icon](https://docs.getdbt.com/img/docs/dbt-insights/insights-query-history.png?v=2 "dbt Insights Query history icon")](https://docs.getdbt.com/docs/explore/access-dbt-insights#) dbt Insights Query history icon ### Use dbt Catalog[​](https://docs.getdbt.com/docs/explore/access-dbt-insights#use-dbt-catalog "Direct link to Use dbt Catalog") Access [Catalog](https://docs.getdbt.com/docs/explore/explore-projects) directly in Insights to view project resources such as models, columns, metrics, and dimensions, and more — all integrated in the Insights interface. This integrated view allows you and your users to maintain your query workflow, while getting more context on models, semantic models, metrics, macros, and more. The integrated Catalog view comes with: * Same search capabilities as Catalog * Allows users to narrow down displayed objects by type * Hyperlink from SQL code `ref` to the corresponding Catalog page * View assets in more detail by opening with the full Catalog experience or open them in Copilot. To access Catalog, click on the **Catalog** icon in the [Query console sidebar menu](https://docs.getdbt.com/docs/explore/navigate-dbt-insights#query-console-sidebar-menu) . [![dbt Insights integrated with dbt Catalog](https://docs.getdbt.com/img/docs/dbt-insights/insights-explorer.png?v=2 "dbt Insights integrated with dbt Catalog")](https://docs.getdbt.com/docs/explore/access-dbt-insights#) dbt Insights integrated with dbt Catalog ### Set Jinja environment[​](https://docs.getdbt.com/docs/explore/access-dbt-insights#set-jinja-environment "Direct link to Set Jinja environment") Set the compilation environment to control how Jinja functions are rendered. This feature: * Supports "typed" environments marked as `Production`, `Staging`, and/or `Development`. * Enables you to run Semantic Layer. queries against staging environments (development environments not supported). * Still uses the individual user credentials, so users must have appropriate access to query `PROD` and `STG`. * Changing the environment changes context for the Catalog view in Insights, as well as the environment context during the handoff to Catalog and Canvas. For example, switching to `Staging` in Insights and selecting **View in Catalog** will open the `Staging` view in Catalog. [![Set the environment for your Jinja context](https://docs.getdbt.com/img/docs/dbt-insights/insights-jinja-environment.png?v=2 "Set the environment for your Jinja context")](https://docs.getdbt.com/docs/explore/access-dbt-insights#) Set the environment for your Jinja context Save your Insights[​](https://docs.getdbt.com/docs/explore/access-dbt-insights#save-your-insights "Direct link to Save your Insights") --------------------------------------------------------------------------------------------------------------------------------------- Insights offers a robust save feature for quickly finding the queries you use most. There's also an option to share saved Insights with other dbt users (and have them share with you). Click the **bookmark icon** in a query to add it to your list! * Click the **bookmark icon** on the right menu to manage your saved Insights. You can view your personal and shared queries [![Manage your saved Insights](https://docs.getdbt.com/img/docs/dbt-insights/saved-insights.png?v=2 "Manage your saved Insights")](https://docs.getdbt.com/docs/explore/access-dbt-insights#) Manage your saved Insights * View saved Insight details including description and creation date in the **Overview** tab. * View the Insight history in the **Version history** tab. Click a version to compare it the current and view changes. Considerations[​](https://docs.getdbt.com/docs/explore/access-dbt-insights#considerations "Direct link to Considerations") --------------------------------------------------------------------------------------------------------------------------- * Insights uses your development credentials to query. You have the ability to query against any object in your data warehouse that is accessible using your development credentials. * Every Jinja function uses [`defer --favor-state`](https://docs.getdbt.com/reference/node-selection/defer) to resolve Jinja. FAQs[​](https://docs.getdbt.com/docs/explore/access-dbt-insights#faqs "Direct link to FAQs") --------------------------------------------------------------------------------------------- * What’s the difference between Insights and Catalog? * That’s a great question! Catalog helps you understand your dbt project's structure, resources, lineage, and metrics, offering context for your data. * Insights builds on that context, allowing you to write, run, and iterate on SQL queries directly in dbt. It’s designed for ad-hoc or exploratory analysis and empowers business users and analysts to explore data, ask questions, and collaborate seamlessly. * Catalog provides the context, while Insights enables action. Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Access the dbt Insights interface](https://docs.getdbt.com/docs/explore/access-dbt-insights#access-the-dbt-insights-interface) * [Run queries](https://docs.getdbt.com/docs/explore/access-dbt-insights#run-queries) * [Example](https://docs.getdbt.com/docs/explore/access-dbt-insights#example) * [Use dbt Copilot](https://docs.getdbt.com/docs/explore/access-dbt-insights#use-dbt-copilot) * [View results](https://docs.getdbt.com/docs/explore/access-dbt-insights#view-results) * [View details](https://docs.getdbt.com/docs/explore/access-dbt-insights#view-details) * [Chart results](https://docs.getdbt.com/docs/explore/access-dbt-insights#chart-results) * [Query history](https://docs.getdbt.com/docs/explore/access-dbt-insights#query-history) * [Use dbt Catalog](https://docs.getdbt.com/docs/explore/access-dbt-insights#use-dbt-catalog) * [Set Jinja environment](https://docs.getdbt.com/docs/explore/access-dbt-insights#set-jinja-environment) * [Save your Insights](https://docs.getdbt.com/docs/explore/access-dbt-insights#save-your-insights) * [Considerations](https://docs.getdbt.com/docs/explore/access-dbt-insights#considerations) * [FAQs](https://docs.getdbt.com/docs/explore/access-dbt-insights#faqs) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/explore/access-dbt-insights.md) --- # Source freshness | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/deploy/source-freshness#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page dbt provides a helpful interface around dbt's [source data freshness](https://docs.getdbt.com/docs/build/sources#source-data-freshness) calculations. When a dbt job is configured to snapshot source data freshness, dbt will render a user interface showing you the state of the most recent snapshot. This interface is intended to help you determine if your source data freshness is meeting the service level agreement (SLA) that you've defined for your organization. [![Data Sources in dbt](https://docs.getdbt.com/img/docs/dbt-cloud/using-dbt-cloud/data-sources-next.png?v=2 "Data Sources in dbt")](https://docs.getdbt.com/docs/deploy/source-freshness#) Data Sources in dbt ### Enabling source freshness snapshots[​](https://docs.getdbt.com/docs/deploy/source-freshness#enabling-source-freshness-snapshots "Direct link to Enabling source freshness snapshots") [`dbt build`](https://docs.getdbt.com/reference/commands/build) does _not_ include source freshness checks when building and testing resources in your DAG. Instead, you can use one of these common patterns for defining jobs: * Add `dbt build` to the run step to run models, tests, and so on. * Select the **Generate docs on run** checkbox to automatically [generate project docs](https://docs.getdbt.com/docs/explore/build-and-view-your-docs) . * Select the **Run source freshness** checkbox to enable [source freshness](https://docs.getdbt.com/docs/deploy/source-freshness#checkbox) as the first step of the job. [![Selecting source freshness](https://docs.getdbt.com/img/docs/dbt-cloud/select-source-freshness.png?v=2 "Selecting source freshness")](https://docs.getdbt.com/docs/deploy/source-freshness#) Selecting source freshness To enable source freshness snapshots, firstly make sure to configure your sources to [snapshot freshness information](https://docs.getdbt.com/docs/build/sources#source-data-freshness) . You can add source freshness to the list of commands in the job run steps or enable the checkbox. However, you can expect different outcomes when you configure a job by selecting the **Run source freshness** checkbox compared to adding the command to the run steps. Review the following options and outcomes: | Options | Outcomes | | --- | --- | | **Select checkbox** | The **Run source freshness** checkbox in your **Execution Settings** will run `dbt source freshness` as the first step in your job and won't break subsequent steps if it fails. If you wanted your job dedicated _exclusively_ to running freshness checks, you still need to include at least one placeholder step, such as `dbt compile`. | | **Add as a run step** | Add the `dbt source freshness` command to a job anywhere in your list of run steps. However, if your source data is out of date — this step will "fail", and subsequent steps will not run. dbt will trigger email notifications (if configured) based on the end state of this step.

You can create a new job to snapshot source freshness.

If you _do not_ want your models to run if your source data is out of date, then it could be a good idea to run `dbt source freshness` as the first step in your job. Otherwise, we recommend adding `dbt source freshness` as the last step in the job, or creating a separate job just for this task. | [![Adding a step to snapshot source freshness](https://docs.getdbt.com/img/docs/dbt-cloud/using-dbt-cloud/job-step-source-freshness.png?v=2 "Adding a step to snapshot source freshness")](https://docs.getdbt.com/docs/deploy/source-freshness#) Adding a step to snapshot source freshness ### Source freshness snapshot frequency[​](https://docs.getdbt.com/docs/deploy/source-freshness#source-freshness-snapshot-frequency "Direct link to Source freshness snapshot frequency") It's important that your freshness jobs run frequently enough to snapshot data latency in accordance with your SLAs. You can imagine that if you have a 1 hour SLA on a particular dataset, snapshotting the freshness of that table once daily would not be appropriate. As a good rule of thumb, you should run your source freshness jobs with at least double the frequency of your lowest SLA. Here's an example table of some reasonable snapshot frequencies given typical SLAs: | SLA | Snapshot Frequency | | --- | --- | | 1 hour | 30 mins | | 1 day | 12 hours | | 1 week | About daily | Further reading[​](https://docs.getdbt.com/docs/deploy/source-freshness#further-reading "Direct link to Further reading") -------------------------------------------------------------------------------------------------------------------------- * Refer to [Artifacts](https://docs.getdbt.com/docs/deploy/artifacts) for more info on how to create dbt artifacts, share links to the latest documentation, and share source freshness reports with your team. * Source freshness for Snowflake is calculated using the `LAST_ALTERED` column. Read about the limitations in [Snowflake configs](https://docs.getdbt.com/reference/resource-configs/snowflake-configs#source-freshness-known-limitation) . Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Enabling source freshness snapshots](https://docs.getdbt.com/docs/deploy/source-freshness#enabling-source-freshness-snapshots) * [Source freshness snapshot frequency](https://docs.getdbt.com/docs/deploy/source-freshness#source-freshness-snapshot-frequency) * [Further reading](https://docs.getdbt.com/docs/deploy/source-freshness#further-reading) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/deploy/source-freshness.md) --- # Service account tokens | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/dbt-cloud-apis/service-tokens#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page Service account tokens enable you to securely authenticate with the dbt API by assigning each token a narrow set of permissions that more precisely manages access to the API. While similar to [personal access tokens](https://docs.getdbt.com/docs/dbt-cloud-apis/user-tokens) , service account tokens belong to an account rather than a user. You can use service account tokens for system-level integrations that do not run on behalf of any one user. Assign any permission sets available in dbt to your service account token, which can vary slightly depending on your plan: * Enterprise and Enterprise+ plans can apply any permission sets available to service tokens. * Developer and Starter plans can apply Semantic Layer permissions set to service tokens. * Legacy Team plans can apply Account Admin, Member, Job Admin, Read-Only, Metadata, and Semantic Layer permissions set to service tokens. You can assign as many permission sets as needed to one token. For more on permissions sets, see "[Enterprise Permissions](https://docs.getdbt.com/docs/cloud/manage-access/enterprise-permissions) ." Generate service account tokens[​](https://docs.getdbt.com/docs/dbt-cloud-apis/service-tokens#generate-service-account-tokens "Direct link to Generate service account tokens") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- You can generate service tokens if you have a Developer [license](https://docs.getdbt.com/docs/cloud/manage-access/seats-and-users) and account admin [permissions](https://docs.getdbt.com/docs/cloud/manage-access/about-user-access#permission-sets) . To create a service token in dbt, follow these steps: 1. From dbt, click on your account name in the left side menu and select **Account settings**. 2. On the left sidebar, click on **Service Tokens**. 3. Click the **\+ New Token** button to generate a new token. 4. Once the token is generated, you won't be able to view this token again so make sure to save it somewhere safe. Permissions for service account tokens[​](https://docs.getdbt.com/docs/dbt-cloud-apis/service-tokens#permissions-for-service-account-tokens "Direct link to Permissions for service account tokens") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- You can assign service account tokens to any permission set available in dbt. When you assign a permission set to a token, you will also be able to choose whether to grant those permissions to all projects in the account or to specific projects. ### Team plans using service account tokens[​](https://docs.getdbt.com/docs/dbt-cloud-apis/service-tokens#team-plans-using-service-account-tokens "Direct link to Team plans using service account tokens") The following permissions can be assigned to a service account token on a Team plan. Refer to [Enterprise permissions](https://docs.getdbt.com/docs/cloud/manage-access/enterprise-permissions) for more information about these roles. * Account Admin — Account Admin service tokens have full `read + write` access to an account, so please use them with caution. A Team plan refers to this permission set as an "Owner role." * Billing Admin * Job Admin * Metadata Only * Member * Read-only * Semantic Layer Only ### Enterprise plans using service account tokens[​](https://docs.getdbt.com/docs/dbt-cloud-apis/service-tokens#enterprise-plans-using-service-account-tokens "Direct link to Enterprise plans using service account tokens") Refer to [Enterprise permissions](https://docs.getdbt.com/docs/cloud/manage-access/enterprise-permissions) for more information about these roles. * Account Admin — Account Admin service tokens have full `read + write` access to an account, so please use them with caution. * Account Viewer * Admin * Analyst * Billing Admin * Database Admin * Developer * Git Admin * Job Admin * Job Runner * Job Viewer * Manage marketplace apps * Metadata Only * Semantic Layer Only * Security Admin * Stakeholder * Team Admin Service token update[​](https://docs.getdbt.com/docs/dbt-cloud-apis/service-tokens#service-token-update "Direct link to Service token update") ----------------------------------------------------------------------------------------------------------------------------------------------- On July 18, 2023, dbt Labs changed how tokens are generated and validated to increase performance. These improvements only apply to tokens created after July 18, 2023. Old tokens remain valid, but if they are used in high-frequency API invocations, we recommend you rotate them for reduced latency. To rotate your token: 1. Navigate to **Account settings** and click **Service tokens** on the left side pane. 2. Verify the **Created** date for the token is _on or before_ July 18, 2023. 3. Click **\+ New Token** on the top right side of the screen. Ensure the new token has the same permissions as the old one. 4. Copy the new token and replace the old one in your systems. Store it in a safe place, as it will not be available again once the creation screen is closed. 5. Delete the old token in dbt by clicking the **trash can icon**. _Only take this action after the new token is in place to avoid service disruptions_. FAQs[​](https://docs.getdbt.com/docs/dbt-cloud-apis/service-tokens#faqs "Direct link to FAQs") ----------------------------------------------------------------------------------------------- I'm receiving a 403 error 'Forbidden: Access denied' when using service tokens All [service token](https://docs.getdbt.com/docs/dbt-cloud-apis/service-tokens) traffic is subject to IP restrictions. When using a service token, the following 403 response error indicates the IP is not on the allowlist. To resolve this, you should add your third-party integration CIDRs (network addresses) to your allowlist. The following is an example of the 403 response error: { "status": { "code": 403, "is_success": False, "user_message": ("Forbidden: Access denied"), "developer_message": None, }, "data": { "account_id": , "user_id": , "is_service_token": , "account_access_denied": True, }, } Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Generate service account tokens](https://docs.getdbt.com/docs/dbt-cloud-apis/service-tokens#generate-service-account-tokens) * [Permissions for service account tokens](https://docs.getdbt.com/docs/dbt-cloud-apis/service-tokens#permissions-for-service-account-tokens) * [Team plans using service account tokens](https://docs.getdbt.com/docs/dbt-cloud-apis/service-tokens#team-plans-using-service-account-tokens) * [Enterprise plans using service account tokens](https://docs.getdbt.com/docs/dbt-cloud-apis/service-tokens#enterprise-plans-using-service-account-tokens) * [Service token update](https://docs.getdbt.com/docs/dbt-cloud-apis/service-tokens#service-token-update) * [FAQs](https://docs.getdbt.com/docs/dbt-cloud-apis/service-tokens#faqs) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/dbt-cloud-apis/service-tokens.md) --- # Using threads | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/running-a-dbt-project/using-threads#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page When dbt runs, it creates a directed acyclic graph (DAG) of links between models. The number of threads represents the maximum number of paths through the graph dbt may work on at once – increasing the number of threads can minimize the run time of your project. For example, if you specify `threads: 1`, dbt will start building only one model, and finish it, before moving onto the next. Specifying `threads: 8` means that dbt will work on _up to_ 8 models at once without violating dependencies – the actual number of models it can work on will likely be constrained by the available paths through the dependency graph. There's no set limit of the maximum number of threads you can set – while increasing the number of threads generally decreases execution time, there are a number of things to consider: * Increasing the number of threads increases the load on your warehouse, which may impact other tools in your data stack. For example, if your BI tool uses the same compute resources as dbt, their queries may get queued during a dbt run. * The number of concurrent queries your database will allow you to run may be a limiting factor in how many models can be actively built – some models may queue while waiting for an available query slot. Generally the optimal number of threads depends on your data warehouse and its configuration. It’s best to test different values to find the best number of threads for your project. We recommend setting this to 4 to start with. You can use a different number of threads than the value defined in your target by using the `--threads` option when executing a dbt command. You will define the number of threads in your `profiles.yml` file (for dbt Core users only), dbt job definition, and dbt development credentials under your profile. Related docs[​](https://docs.getdbt.com/docs/running-a-dbt-project/using-threads#related-docs "Direct link to Related docs") ----------------------------------------------------------------------------------------------------------------------------- * [About profiles.yml](https://docs.getdbt.com/docs/core/connect-data-platform/profiles.yml) * [dbt job scheduler](https://docs.getdbt.com/docs/deploy/job-scheduler) Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Related docs](https://docs.getdbt.com/docs/running-a-dbt-project/using-threads#related-docs) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/running-a-dbt-project/using-threads.md) --- # Model access | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/mesh/govern/model-access#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page "Model access" is not "User access" **Model groups and access** and **user groups and access** mean two different things. "User groups and access" is a specific term used in dbt to manage permissions. Refer to [User access](https://docs.getdbt.com/docs/cloud/manage-access/about-user-access) for more info. The two concepts will be closely related, as we develop multi-project collaboration workflows this year: * Users with access to develop in a dbt project can view and modify **all** models in that project, including private models. * Users in the same dbt account _without_ access to develop in a project cannot view that project's private models, and they can take a dependency on its public models only. Related documentation[​](https://docs.getdbt.com/docs/mesh/govern/model-access#related-documentation "Direct link to Related documentation") --------------------------------------------------------------------------------------------------------------------------------------------- * [`groups`](https://docs.getdbt.com/docs/build/groups) * [`access`](https://docs.getdbt.com/reference/resource-configs/access) Groups[​](https://docs.getdbt.com/docs/mesh/govern/model-access#groups "Direct link to Groups") ------------------------------------------------------------------------------------------------ Models can be grouped under a common designation with a shared owner. For example, you could group together all models owned by a particular team, or related to modeling a specific data source (`github`). Why define model `groups`? There are two reasons: * It turns implicit relationships into an explicit grouping, with a defined owner. By thinking about the interface boundaries _between_ groups, you can have a cleaner (less entangled) DAG. In the future, those interface boundaries could be appropriate as the interfaces between separate projects. * It enables you to designate certain models as having "private" access—for use exclusively within that group. Other models will be restricted from referencing (taking a dependency on) those models. In the future, they won't be visible to other teams taking a dependency on your project—only "public" models will be. If you follow our [best practices for structuring a dbt project](https://docs.getdbt.com/best-practices/how-we-structure/1-guide-overview) , you're probably already using subdirectories to organize your dbt project. It's easy to apply a `group` label to an entire subdirectory at once: dbt\_project.yml models: my_project_name: marts: customers: +group: customer_success finance: +group: finance Each model can only belong to one `group`, and groups cannot be nested. If you set a different `group` in that model's YAML or in-file config, it will override the `group` applied at the project level. Considerations Model governance features like model access, contracts, and versions strengthen trust and stability in your dbt project. Because they add structure, it can make it harder to roll changes back later (for example, removing model access) and increases maintenance if adopted too early. Before adding governance features, consider whether your dbt project is ready to benefit from them. Introducing them too soon can make future changes harder if your models are still changing/evolving. Access modifiers[​](https://docs.getdbt.com/docs/mesh/govern/model-access#access-modifiers "Direct link to Access modifiers") ------------------------------------------------------------------------------------------------------------------------------ Some models are implementation details, meant for reference only within their group of related models. Other models should be accessible through the [ref](https://docs.getdbt.com/reference/dbt-jinja-functions/ref) function across groups and projects. Models can set an [access modifier](https://en.wikipedia.org/wiki/Access_modifiers) to indicate their intended level of accessibility. | Access | Referenceable by | | --- | --- | | private | Same group | | protected | Same project (or installed as a package) | | public | Any group, package, or project. When defined, rerun a production job to apply the change | If you try to reference a model outside of its supported access, you will see an error: dbt run -s marketing_model...dbt.exceptions.DbtReferenceError: Parsing Error Node model.jaffle_shop.marketing_model attempted to reference node model.jaffle_shop.finance_model, which is not allowed because the referenced node is private to the finance group. By default, all models are `protected`. This means that other models in the same project can reference them, regardless of their group. This is largely for backward compatibility when assigning groups to an existing set of models, as there may already be existing references across group assignments. However, it is recommended to set the access modifier of a new model to `private` to prevent other project resources from taking dependencies on models not intentionally designed for sharing across groups. models/marts/customers.yml # First, define the group and ownergroups: - name: customer_success owner: name: Customer Success Team email: cx@jaffle.shop# Then, add 'group' + 'access' modifier to specific modelsmodels: # This is a public model -- it's a stable & mature interface for other teams/projects - name: dim_customers config: group: customer_success # changed to config in v1.10 access: public # changed to config in v1.10 # This is a private model -- it's an intermediate transformation intended for use in this context *only* - name: int_customer_history_rollup config: group: customer_success # changed to config in v1.10 access: private # changed to config in v1.10 # This is a protected model -- it might be useful elsewhere in *this* project, # but it shouldn't be exposed elsewhere - name: stg_customer__survey_results config: group: customer_success # changed to config in v1.10 access: protected # changed to config in v1.10 Models with `materialized` set to `ephemeral` cannot have the access property set to public. For example, if you have a model config set as: models/my\_model.sql {{ config(materialized='ephemeral') }} And the model access is defined: models/my\_project.yml models: - name: my_model config: access: public # changed to config in v1.10 It will lead to the following error: ❯ dbt parse02:19:30 Encountered an error:Parsing Error Node model.jaffle_shop.my_model with 'ephemeral' materialization has an invalid value (public) for the access field FAQs[​](https://docs.getdbt.com/docs/mesh/govern/model-access#faqs "Direct link to FAQs") ------------------------------------------------------------------------------------------ ### How does model access relate to database permissions?[​](https://docs.getdbt.com/docs/mesh/govern/model-access#how-does-model-access-relate-to-database-permissions "Direct link to How does model access relate to database permissions?") These are different! Specifying `access: public` on a model does not trigger dbt to automagically grant `select` on that model to every user or role in your data platform when you materialize it. You have complete control over managing database permissions on every model/schema, as makes sense to you & your organization. Of course, dbt can facilitate this by means of [the `grants` config](https://docs.getdbt.com/reference/resource-configs/grants) , and other flexible mechanisms. For example: * Grant access to downstream queriers on public models * Restrict access to private models, by revoking default/future grants, or by landing them in a different schema As we continue to develop multi-project collaboration, `access: public` will mean that other teams are allowed to start taking a dependency on that model. This assumes that they've requested, and you've granted them access, to select from the underlying dataset. ### How do I ref a model from another project?[​](https://docs.getdbt.com/docs/mesh/govern/model-access#how-do-i-ref-a-model-from-another-project "Direct link to How do I ref a model from another project?") You can `ref` a model from another project in two ways: 1. [Project dependency](https://docs.getdbt.com/docs/mesh/govern/project-dependencies) : In dbt Enterprise, you can use project dependencies to `ref` a model. dbt uses a behind-the-scenes metadata service to resolve the reference, enabling efficient collaboration across teams and at scale. 2. ["Package" dependency](https://docs.getdbt.com/docs/build/packages) : Another way to `ref` a model from another project is to treat the other project as a package dependency. This requires installing the other project as a package, including its full source code, as well as its upstream dependencies. ### How do I restrict access to models defined in a package?[​](https://docs.getdbt.com/docs/mesh/govern/model-access#how-do-i-restrict-access-to-models-defined-in-a-package "Direct link to How do I restrict access to models defined in a package?") Source code installed from a package becomes part of your runtime environment. You can call macros and run models as if they were macros and models that you had defined in your own project. For this reason, model access restrictions are "off" by default for models defined in packages. You can reference models from that package regardless of their `access` modifier. The project is installed as a package can optionally restrict external `ref` access to just its public models. The package maintainer does this by setting a `restrict-access` config to `True` in `dbt_project.yml`. By default, the value of this config is `False`. This means that: * Models in the package with `access: protected` may be referenced by models in the root project, as if they were defined in the same project * Models in the package with `access: private` may be referenced by models in the root project, so long as they also have the same `group` config When `restrict-access: True`: * Any `ref` from outside the package to a protected or private model in that package will fail. * Only models with `access: public` can be referenced outside the package. dbt\_project.yml restrict-access: True # default is False Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Related documentation](https://docs.getdbt.com/docs/mesh/govern/model-access#related-documentation) * [Groups](https://docs.getdbt.com/docs/mesh/govern/model-access#groups) * [Access modifiers](https://docs.getdbt.com/docs/mesh/govern/model-access#access-modifiers) * [FAQs](https://docs.getdbt.com/docs/mesh/govern/model-access#faqs) * [How does model access relate to database permissions?](https://docs.getdbt.com/docs/mesh/govern/model-access#how-does-model-access-relate-to-database-permissions) * [How do I ref a model from another project?](https://docs.getdbt.com/docs/mesh/govern/model-access#how-do-i-ref-a-model-from-another-project) * [How do I restrict access to models defined in a package?](https://docs.getdbt.com/docs/mesh/govern/model-access#how-do-i-restrict-access-to-models-defined-in-a-package) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/mesh/govern/model-access.md) --- # About dbt Mesh | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/mesh/about-mesh#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page Organizations of all sizes rely upon dbt to manage their data transformations, from small startups to large enterprises. At scale, it can be challenging to coordinate all the organizational and technical requirements demanded by your stakeholders within the scope of a single dbt project. To date, there also hasn't been a first-class way to effectively manage the dependencies, governance, and workflows between multiple dbt projects. That's where **Mesh** comes in - empowering data teams to work _independently and collaboratively_; sharing data, code, and best practices without sacrificing security or autonomy. Mesh is not a single product - it is a pattern enabled by a convergence of several features in dbt: * **[Cross-project references](https://docs.getdbt.com/docs/mesh/govern/project-dependencies#how-to-write-cross-project-ref) ** - this is the foundational feature that enables the multi-project deployments. `{{ ref() }}`s now work across dbt projects on Enterprise and Enterprise+ plans. * **[Catalog](https://docs.getdbt.com/docs/explore/explore-projects) ** - dbt's metadata-powered documentation platform, complete with full, cross-project lineage. * **Governance** - dbt's governance features allow you to manage access to your dbt models both within and across projects. * **[Groups](https://docs.getdbt.com/docs/mesh/govern/model-access#groups) ** - With groups, you can organize nodes in your dbt DAG that share a logical connection (for example, by functional area) and assign an owner to the entire group. * **[Access](https://docs.getdbt.com/docs/mesh/govern/model-access#access-modifiers) ** - access configs allow you to control who can reference models. * **[Model Versions](https://docs.getdbt.com/docs/mesh/govern/model-versions) ** - when coordinating across projects and teams, we recommend treating your data models as stable APIs. Model versioning is the mechanism to allow graceful adoption and deprecation of models as they evolve. * **[Model Contracts](https://docs.getdbt.com/docs/mesh/govern/model-contracts) ** - data contracts set explicit expectations on the shape of the data to ensure data changes upstream of dbt or within a project's logic don't break downstream consumers' data products. When is the right time to use dbt Mesh?[​](https://docs.getdbt.com/docs/mesh/about-mesh#when-is-the-right-time-to-use-dbt-mesh "Direct link to When is the right time to use dbt Mesh?") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The multi-project architecture helps organizations with mature, complex transformation workflows in dbt increase the flexibility and performance of their dbt projects. If you're already using dbt and your project has started to experience any of the following, you're likely ready to start exploring this paradigm: * The **number of models** in your project is degrading performance and slowing down development. * Teams have developed **separate workflows** and need to decouple development from each other. * Teams are experiencing **communication challenges**, and the reliability of some of your data products has started to deteriorate. * **Security and governance** requirements are increasing and would benefit from increased isolation. dbt is designed to coordinate the features above and simplify the complexity to solve for these problems. If you're just starting your dbt journey, don't worry about building a multi-project architecture right away. You can _incrementally_ adopt the features as you scale. The collection of features work effectively as independent tools. Familiarizing yourself with the tooling and features that make up a multi-project architecture, and how they can apply to your organization will help you make better decisions as you grow. For additional information, refer to the [Mesh FAQs](https://docs.getdbt.com/best-practices/how-we-mesh/mesh-5-faqs) . Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [When is the right time to use dbt Mesh?](https://docs.getdbt.com/docs/mesh/about-mesh#when-is-the-right-time-to-use-dbt-mesh) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/mesh/about-mesh.md) --- # About the dbt Fusion engine | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/fusion/about-fusion#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page dbt is the industry standard for data transformation. The dbt Fusion Engine enables dbt to operate at speed and scale like never before. The dbt Fusion Engine shares the same familiar framework for authoring data transformations as dbt Core, while enabling data developers to work faster and deploy transformation workloads more efficiently. ### What is Fusion[​](https://docs.getdbt.com/docs/fusion/about-fusion#what-is-fusion "Direct link to What is Fusion") Fusion is an entirely new piece of software, written in a different programming language (Rust) than dbt Core (Python). Fusion is significantly faster than dbt Core, and it has a native understanding of SQL across multiple engine dialects. Fusion will eventually support the full dbt Core framework, a superset of dbt Core’s capabilities, and the vast majority of existing dbt projects. Fusion contains mixture of source-available, proprietary, and open source code. That means: * dbt Labs publishes much of the source code in the [`dbt-fusion` repository](https://github.com/dbt-labs/dbt-fusion) , where you can read the code and participate in community discussions. * Some Fusion capabilities are exclusively available for paying customers of the cloud-based [dbt platform](https://www.getdbt.com/signup) . Refer to [supported features](https://docs.getdbt.com/docs/fusion/supported-features#paid-features) for more information. Read more about the licensing for the dbt Fusion engine [here](http://www.getdbt.com/licenses-faq) . Why use Fusion[​](https://docs.getdbt.com/docs/fusion/about-fusion#why-use-fusion "Direct link to Why use Fusion") ------------------------------------------------------------------------------------------------------------------- As a developer, Fusion can: * Immediately catch incorrect SQL in your dbt models * Preview inline CTEs for faster debugging * Trace model and column definitions across your dbt project All of that and more is available in the [dbt extension for VSCode](https://docs.getdbt.com/docs/about-dbt-extension) , with Fusion at the foundation. Fusion also enables more-efficient deployments of large DAGs. By tracking which columns are used where, and which source tables have fresh data, Fusion can ensure that models are rebuilt only when they need to process new data. This ["state-aware orchestration"](https://docs.getdbt.com/docs/deploy/state-aware-about) is a feature of the dbt platform. ### How to use Fusion[​](https://docs.getdbt.com/docs/fusion/about-fusion#how-to-use-fusion "Direct link to How to use Fusion") You can: * Select Fusion from the [dropdown/toggle in the dbt platform](https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-version-in-cloud#dbt-fusion-engine) [beta](https://docs.getdbt.com/docs/dbt-versions/product-lifecycles "Go to https://docs.getdbt.com/docs/dbt-versions/product-lifecycles") * [Install the dbt extension for VSCode](https://docs.getdbt.com/docs/install-dbt-extension) [preview](https://docs.getdbt.com/docs/dbt-versions/product-lifecycles "Go to https://docs.getdbt.com/docs/dbt-versions/product-lifecycles") * [Install the Fusion CLI](https://docs.getdbt.com/docs/fusion/install-fusion) [preview](https://docs.getdbt.com/docs/dbt-versions/product-lifecycles "Go to https://docs.getdbt.com/docs/dbt-versions/product-lifecycles") Go straight to the [Quickstart](https://docs.getdbt.com/guides/fusion) to _feel the Fusion_ as fast as possible. What's next?[​](https://docs.getdbt.com/docs/fusion/about-fusion#whats-next "Direct link to What's next?") ----------------------------------------------------------------------------------------------------------- dbt Labs launched the dbt Fusion engine as a public beta on May 28, 2025, with plans to reach full feature parity with dbt Core ahead of [Fusion's general availability](https://docs.getdbt.com/blog/dbt-fusion-engine-path-to-ga) . More information about Fusion[​](https://docs.getdbt.com/docs/fusion/about-fusion#more-information-about-fusion "Direct link to More information about Fusion") ---------------------------------------------------------------------------------------------------------------------------------------------------------------- Fusion marks a significant update to dbt. While many of the workflows you've grown accustomed to remain unchanged, there are a lot of new ideas, and a lot of old ones going away. The following is a list of the full scope of our current release of the Fusion engine, including implementation, installation, deprecations, and limitations: * [About the dbt Fusion engine](https://docs.getdbt.com/docs/fusion/about-fusion) * [About the dbt extension](https://docs.getdbt.com/docs/about-dbt-extension) * [New concepts in Fusion](https://docs.getdbt.com/docs/fusion/new-concepts) * [Supported features matrix](https://docs.getdbt.com/docs/fusion/supported-features) * [Installing Fusion CLI](https://docs.getdbt.com/docs/fusion/install-fusion) * [Installing VS Code extension](https://docs.getdbt.com/docs/install-dbt-extension) * [Fusion release track](https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-version-in-cloud#dbt-fusion-engine) * [Quickstart for Fusion](https://docs.getdbt.com/guides/fusion?step=1) * [Upgrade guide](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-fusion) * [Fusion licensing](http://www.getdbt.com/licenses-faq) Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [What is Fusion](https://docs.getdbt.com/docs/fusion/about-fusion#what-is-fusion) * [Why use Fusion](https://docs.getdbt.com/docs/fusion/about-fusion#why-use-fusion) * [How to use Fusion](https://docs.getdbt.com/docs/fusion/about-fusion#how-to-use-fusion) * [What's next?](https://docs.getdbt.com/docs/fusion/about-fusion#whats-next) * [More information about Fusion](https://docs.getdbt.com/docs/fusion/about-fusion#more-information-about-fusion) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/fusion/about-fusion.md) --- # dbt Product lifecycles | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/dbt-versions/product-lifecycles#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page dbt Labs is directly involved with the maintenance of two products: * dbt Core: The [open-source](https://github.com/dbt-labs/dbt-core) software that’s freely available. * dbt: The cloud-based [SaaS solution](https://www.getdbt.com/signup) , originally built on top of dbt Core. We're now introducing dbt's new engine, the dbt Fusion Engine. For more information, refer to [About the dbt Fusion engine](https://docs.getdbt.com/docs/fusion/about-fusion) . * dbt Fusion Engine: The next-generation dbt engine, substantially faster than dbt Core and has built in SQL comprehension technology to power the next generation of analytics engineering workflows. The dbt Fusion Engine is designed to deliver data teams a lightning-fast development experience, intelligent cost savings, and improved governance. All dbt features fall into a lifecycle category determined by their availability in the following products: ### The dbt platform[​](https://docs.getdbt.com/docs/dbt-versions/product-lifecycles#the-dbt-platform "Direct link to The dbt platform") dbt features all fall into one of the following categories: * **Beta:** Beta features are still in development and are only available to select customers. To join a beta, there might be a signup form or dbt Labs may contact specific customers about testing. Some features can be activated by enabling [experimental features](https://docs.getdbt.com/docs/dbt-versions/experimental-features) in your account. Beta features are incomplete and might not be entirely stable; they should be used at the customer’s risk, as breaking changes could occur. Beta features might not be fully documented, technical support is limited, and service level objectives (SLOs) might not be provided. Download the [Beta Features Terms and Conditions](https://docs.getdbt.com/assets/files/beta-tc-740ff696113c89c38a96bb70b968775e.pdf) for more details. * **Preview:** Preview features are stable and considered functionally ready for production deployments. Some planned additions and modifications to feature behaviors could occur before they become generally available. New functionality that is not backward compatible could also be introduced. Preview features include documentation, technical support, and service level objectives (SLOs). Features in preview are provided at no extra cost, although they might become paid features when they become generally available. * **Generally available (GA):** Generally available features provide stable features introduced to all qualified dbt accounts. Service level agreements (SLAs) apply to GA features, including documentation and technical support. Certain GA feature availability is determined by the dbt version of the environment. To always receive the latest GA features, ensure your dbt [environments](https://docs.getdbt.com/docs/dbt-cloud-environments) are on a supported [Release Track](https://docs.getdbt.com/docs/dbt-versions/cloud-release-tracks) . * **Deprecated:** Features in this state are no longer being developed or enhanced by dbt Labs. They will continue functioning as-is, and their documentation will persist until their removal date. However, they are no longer subject to technical support. * **Removed:** Removed features are no longer available on the platform in any capacity. ### dbt Core[​](https://docs.getdbt.com/docs/dbt-versions/product-lifecycles#dbt-core "Direct link to dbt Core") We release dbt Core in the following lifecycle states. Core releases follow semantic versioning, which you can read more about in [About Core versions](https://docs.getdbt.com/docs/dbt-versions/core) . * **Unreleased:** We will include this functionality in the next minor version prerelease. However, we make no commitments about its behavior or implementation. As maintainers, we reserve the right to change any part of it, or remove it entirely (with an accompanying explanation.) * **Prerelease:** * **Beta:** The purpose of betas is to provide a first glimpse of the net-new features that will be arriving in this minor version, when it has its final release. The code included in beta should work, without regression from existing functionality, or negative interactions with other released features. Net-new features included in a beta _may be_ incomplete or have known edge cases/limitations. Changes included in beta are not “locked,” and the maintainers reserve the right to change or remove (with an explanation). * **Release Candidate:** The purpose of a release candidate is to offer a 2-week window for more extensive production-level testing, with the goal of catching regressions before they go live in a final release. Users can believe that features in a Release Candidate will work the same on release day. However, if we do find a significant bug, we do still reserve the right to change or remove the underlying behavior, with a clear explanation. * **Released:** Ready for use in production. * **Experimental:** Features we release for general availability, which we believe are usable in their current form, but for which we may document additional caveats. * **Undocumented:** These are subsets of dbt Core functionality that are internal, not contracted, or intentionally left undocumented. Do not consider this functionality part of that release’s product surface area. * **Deprecated:** Features in this state are not actively worked on or enhanced by dbt Labs and will continue to function as-is until their removal date. * **Removed:** Removed features no longer have any level of product functionality or platform support. ### dbt Fusion engine[​](https://docs.getdbt.com/docs/dbt-versions/product-lifecycles#dbt-fusion-engine "Direct link to dbt Fusion engine") The dbt Fusion Engine is currently in beta. * **Beta:** Beta features are still in development and are only available to select customers. Beta features are incomplete and might not be entirely stable; they should be used at the customer’s risk, as breaking changes could occur. Beta features might not be fully documented, technical support is limited, and service level objectives (SLOs) might not be provided. Download the [Beta Features Terms and Conditions](https://docs.getdbt.com/assets/files/beta-tc-740ff696113c89c38a96bb70b968775e.pdf) for more details. * **Path to Generally available (GA):** Learn what's required for the dbt Fusion engine to reach GA in our [Path to GA](https://docs.getdbt.com/blog/dbt-fusion-engine-path-to-ga) blog post. Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [The dbt platform](https://docs.getdbt.com/docs/dbt-versions/product-lifecycles#the-dbt-platform) * [dbt Core](https://docs.getdbt.com/docs/dbt-versions/product-lifecycles#dbt-core) * [dbt Fusion engine](https://docs.getdbt.com/docs/dbt-versions/product-lifecycles#dbt-fusion-engine) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/dbt-versions/product-lifecycles.md) --- # Project dependencies | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/mesh/govern/project-dependencies#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page For a long time, dbt has supported code reuse and extension by installing other projects as [packages](https://docs.getdbt.com/docs/build/packages) . When you install another project as a package, you are pulling in its full source code, and adding it to your own. This enables you to call macros and run models defined in that other project. While this is a great way to reuse code, share utility macros, and establish a starting point for common transformations, it's not a great way to enable collaboration across teams and at scale, especially in larger organizations. dbt Labs supports an expanded notion of `dependencies` across multiple dbt projects: * **Packages** — Familiar and pre-existing type of dependency. You take this dependency by installing the package's full source code (like a software library). * **Projects** — The dbt method to take a dependency on another project. Using a metadata service that runs behind the scenes, dbt resolves references on-the-fly to public models defined in other projects. You don't need to parse or run those upstream models yourself. Instead, you treat your dependency on those models as an API that returns a dataset. The maintainer of the public model is responsible for guaranteeing its quality and stability. Prerequisites[​](https://docs.getdbt.com/docs/mesh/govern/project-dependencies#prerequisites "Direct link to Prerequisites") ----------------------------------------------------------------------------------------------------------------------------- * Available in [dbt Enterprise or Enterprise+](https://www.getdbt.com/pricing) . To use it, designate a [public model](https://docs.getdbt.com/docs/mesh/govern/model-access) and add a [cross-project ref](https://docs.getdbt.com/docs/mesh/govern/project-dependencies#how-to-write-cross-project-ref) . * For the upstream ("producer") project setup: * Configure models in upstream project with [`access: public`](https://docs.getdbt.com/reference/resource-configs/access) and have at least one successful job run after defining `access`. * Define a deployment environment in the upstream project as [Production environment](https://docs.getdbt.com/docs/deploy/deploy-environments#set-as-production-environment) , ensuring at least one successful _deployment_ job run in that environment. Make sure the deployment job run generates a [manifest.json](https://docs.getdbt.com/reference/artifacts/manifest-json) file, as this contains necessary metadata information for downstream projects. * If the upstream project has a Staging environment, run a job in that Staging environment to ensure the downstream cross-project ref resolves. * Each project `name` must be unique in your dbt account. For example, if you have a dbt project (codebase) for the `jaffle_marketing` team, avoid creating projects for `Jaffle Marketing - Dev` and `Jaffle Marketing - Prod`; use [environment-level isolation](https://docs.getdbt.com/docs/dbt-cloud-environments#types-of-environments) instead. * dbt supports [Connections](https://docs.getdbt.com/docs/cloud/connect-data-platform/about-connections#connection-management) , available to all dbt users. Connections allows different data platform connections per environment, eliminating the need to duplicate projects. Projects can use multiple connections of the same warehouse type. Connections are reusable across projects and environments. * The `dbt_project.yml` file is case-sensitive, which means the project name must exactly match the name in your `dependencies.yml`. For example, `jaffle_marketing`, not `JAFFLE_MARKETING`. Use cases[​](https://docs.getdbt.com/docs/mesh/govern/project-dependencies#use-cases "Direct link to Use cases") ----------------------------------------------------------------------------------------------------------------- The following setup will work for every dbt project: * Add [any package dependencies](https://docs.getdbt.com/docs/mesh/govern/project-dependencies#when-to-use-project-dependencies) to `packages.yml` * Add [any project dependencies](https://docs.getdbt.com/docs/mesh/govern/project-dependencies#when-to-use-package-dependencies) to `dependencies.yml` However, you may be able to consolidate both into a single `dependencies.yml` file. Read the following section to learn more. #### About packages.yml and dependencies.yml[​](https://docs.getdbt.com/docs/mesh/govern/project-dependencies#about-packagesyml-and-dependenciesyml "Direct link to About packages.yml and dependencies.yml") The `dependencies.yml`. file can contain both types of dependencies: "package" and "project" dependencies. * [Package dependencies](https://docs.getdbt.com/docs/build/packages#how-do-i-add-a-package-to-my-project) lets you add source code from someone else's dbt project into your own, like a library. * Project dependencies provide a different way to build on top of someone else's work in dbt. If your dbt project doesn't require the use of Jinja within the package specifications, you can simply rename your existing `packages.yml` to `dependencies.yml`. However, something to note is if your project's package specifications use Jinja, particularly for scenarios like adding an environment variable or a [Git token method](https://docs.getdbt.com/docs/build/packages#git-token-method) in a private Git package specification, you should continue using the `packages.yml` file name. Use the following toggles to understand the differences and determine when to use `dependencies.yml` or `packages.yml` (or both). Refer to the [FAQs](https://docs.getdbt.com/docs/mesh/govern/project-dependencies#faqs) for more info.  When to use Project dependencies Project dependencies are designed for the [dbt Mesh](https://docs.getdbt.com/best-practices/how-we-mesh/mesh-1-intro) and [cross-project reference](https://docs.getdbt.com/docs/mesh/govern/project-dependencies#how-to-write-cross-project-ref) workflow: * Use `dependencies.yml` when you need to set up cross-project references between different dbt projects, especially in a dbt Mesh setup. * Use `dependencies.yml` when you want to include both projects and non-private dbt packages in your project's dependencies. * Private packages are not supported in `dependencies.yml` because they intentionally don't support Jinja rendering or conditional configuration. This is to maintain static and predictable configuration and ensures compatibility with other services, like dbt. * Use `dependencies.yml` for organization and maintainability if you're using both [cross-project refs](https://docs.getdbt.com/docs/mesh/govern/project-dependencies#how-to-write-cross-project-ref) and [dbt Hub packages](https://hub.getdbt.com/) . This reduces the need for multiple YAML files to manage dependencies. When to use Package dependencies Package dependencies allow you to add source code from someone else's dbt project into your own, like a library: * If you only use packages like those from the [dbt Hub](https://hub.getdbt.com/) , remain with `packages.yml`. * Use `packages.yml` when you want to download dbt packages, such as dbt projects, into your root or parent dbt project. Something to note is that it doesn't contribute to the dbt Mesh workflow. * Use `packages.yml` to include packages in your project's dependencies. This includes both public packages, such as those from the [dbt Hub](https://hub.getdbt.com/) , and private packages. dbt now supports [native private packages](https://docs.getdbt.com/docs/build/packages#native-private-packages) . * `packages.yml` supports Jinja rendering for historical reasons, allowing dynamic configurations. This can be useful if you need to insert values, like a [Git token method](https://docs.getdbt.com/docs/build/packages#git-token-method) from an environment variable, into your package specifications. Previously, to use private Git repositories in dbt, you needed to use a workaround that involved embedding a Git token with Jinja. This is not ideal as it requires extra steps like creating a user and sharing a Git token. We’ve introduced support for [native private packages](https://docs.getdbt.com/docs/build/packages#native-private-packages-) to address this. Example[​](https://docs.getdbt.com/docs/mesh/govern/project-dependencies#example "Direct link to Example") ----------------------------------------------------------------------------------------------------------- As an example, let's say you work on the Marketing team at the Jaffle Shop. The name of your team's project is `jaffle_marketing`: dbt\_project.yml name: jaffle_marketing As part of your modeling of marketing data, you need to take a dependency on two other projects: * `dbt_utils` as a [package](https://docs.getdbt.com/docs/mesh/govern/project-dependencies#packages-use-case) : A collection of utility macros you can use while writing the SQL for your own models. This package is open-source public and maintained by dbt Labs. * `jaffle_finance` as a [project use-case](https://docs.getdbt.com/docs/mesh/govern/project-dependencies#projects-use-case) : Data models about the Jaffle Shop's revenue. This project is private and maintained by your colleagues on the Finance team. You want to select from some of this project's final models, as a starting point for your own work. dependencies.yml packages: - package: dbt-labs/dbt_utils version: 1.1.1projects: - name: jaffle_finance # case sensitive and matches the 'name' in the 'dbt_project.yml' What's happening here? The `dbt_utils` package — When you run `dbt deps`, dbt will pull down this package's full contents (100+ macros) as source code and add them to your environment. You can then call any macro from the package, just as you can call macros defined in your own project. The `jaffle_finance` projects — This is a new scenario. Unlike installing a package, the models in the `jaffle_finance` project will _not_ be pulled down as source code and parsed into your project. Instead, dbt provides a metadata service that resolves references to [**public models**](https://docs.getdbt.com/docs/mesh/govern/model-access) defined in the `jaffle_finance` project. ### Advantages[​](https://docs.getdbt.com/docs/mesh/govern/project-dependencies#advantages "Direct link to Advantages") When you're building on top of another team's work, resolving the references in this way has several advantages: * You're using an intentional interface designated by the model's maintainer with `access: public`. * You're keeping the scope of your project narrow, and avoiding unnecessary resources and complexity. This is faster for you and faster for dbt. * You don't need to mirror any conditional configuration of the upstream project such as `vars`, environment variables, or `target.name`. You can reference them directly wherever the Finance team is building their models in production. Even if the Finance team makes changes like renaming the model, changing the name of its schema, or [bumping its version](https://docs.getdbt.com/docs/mesh/govern/model-versions) , your `ref` would still resolve successfully. * You eliminate the risk of accidentally building those models with `dbt run` or `dbt build`. While you can select those models, you can't actually build them. This prevents unexpected warehouse costs and permissions issues. This also ensures proper ownership and cost allocation for each team's models. ### How to write cross-project ref[​](https://docs.getdbt.com/docs/mesh/govern/project-dependencies#how-to-write-cross-project-ref "Direct link to How to write cross-project ref") **Writing `ref`:** Models referenced from a `project`\-type dependency must use [two-argument `ref`](https://docs.getdbt.com/reference/dbt-jinja-functions/ref#ref-project-specific-models) , including the project name: models/marts/roi\_by\_channel.sql with monthly_revenue as ( select * from {{ ref('jaffle_finance', 'monthly_revenue') }}),... #### Cycle detection[​](https://docs.getdbt.com/docs/mesh/govern/project-dependencies#cycle-detection "Direct link to Cycle detection") You can enable bidirectional dependencies across projects so these relationships can go in either direction, meaning that the `jaffle_finance` project can add a new model that depends on any public models produced by the `jaffle_marketing` project, so long as the new dependency doesn't introduce any node-level cycles. dbt checks for cycles across projects and raises errors if any are detected. When setting up projects that depend on each other, it's important to do so in a stepwise fashion. Each project must run and produce public models before the original producer project can take a dependency on the original consumer project. For example, the order of operations would be as follows for a simple two-project setup: 1. The `project_a` project runs in a deployment environment and produces public models. 2. The `project_b` project adds `project_a` as a dependency. 3. The `project_b` project runs in a deployment environment and produces public models. 4. The `project_a` project adds `project_b` as a dependency. For more guidance on how to use Mesh, refer to the dedicated [Mesh guide](https://docs.getdbt.com/best-practices/how-we-mesh/mesh-1-intro) and also our freely available [Mesh learning course](https://learn.getdbt.com/courses/dbt-mesh) . ### Safeguarding production data with staging environments[​](https://docs.getdbt.com/docs/mesh/govern/project-dependencies#safeguarding-production-data-with-staging-environments "Direct link to Safeguarding production data with staging environments") When working in a Development environment, cross-project `ref`s normally resolve to the Production environment of the project. However, to protect production data, set up a [Staging deployment environment](https://docs.getdbt.com/docs/deploy/deploy-environments#staging-environment) within your projects. With a staging environment integrated into the project, Mesh automatically fetches public model information from the producer’s staging environment if the consumer is also in staging. Similarly, Mesh fetches from the producer’s production environment if the consumer is in production. This ensures consistency between environments and adds a layer of security by preventing access to production data during development workflows. Read [Why use a staging environment](https://docs.getdbt.com/docs/deploy/deploy-environments#why-use-a-staging-environment) for more information about the benefits. #### Staging with downstream dependencies[​](https://docs.getdbt.com/docs/mesh/govern/project-dependencies#staging-with-downstream-dependencies "Direct link to Staging with downstream dependencies") dbt begins using the Staging environment to resolve cross-project references from downstream projects as soon as it exists in a project without "fail-over" to Production. This means that dbt will consistently use metadata from the Staging environment to resolve references in downstream projects, even if there haven't been any successful runs in the configured Staging environment. To avoid causing downtime for downstream developers, you should define and trigger a job before marking the environment as Staging: 1. Create a new environment, but do NOT mark it as **Staging**. 2. Define a job in that environment. 3. Trigger the job to run, and ensure it completes successfully. 4. Update the environment to mark it as **Staging**. ### Comparison[​](https://docs.getdbt.com/docs/mesh/govern/project-dependencies#comparison "Direct link to Comparison") If you were to instead install the `jaffle_finance` project as a `package` dependency, you would instead be pulling down its full source code and adding it to your runtime environment. This means: * dbt needs to parse and resolve more inputs (which is slower) * dbt expects you to configure these models as if they were your own (with `vars`, env vars, etc) * dbt will run these models as your own unless you explicitly `--exclude` them * You could be using the project's models in a way that their maintainer (the Finance team) hasn't intended There are a few cases where installing another internal project as a package can be a useful pattern: * Unified deployments — In a production environment, if the central data platform team of Jaffle Shop wanted to schedule the deployment of models across both `jaffle_finance` and `jaffle_marketing`, they could use dbt's [selection syntax](https://docs.getdbt.com/reference/node-selection/syntax) to create a new "passthrough" project that installed both projects as packages. * Coordinated changes — In development, if you wanted to test the effects of a change to a public model in an upstream project (`jaffle_finance.monthly_revenue`) on a downstream model (`jaffle_marketing.roi_by_channel`) _before_ introducing changes to a staging or production environment, you can install the `jaffle_finance` package as a package within `jaffle_marketing`. The installation can point to a specific git branch, however, if you find yourself frequently needing to perform end-to-end testing across both projects, we recommend you re-examine if this represents a stable interface boundary. These are the exceptions, rather than the rule. Installing another team's project as a package adds complexity, latency, and risk of unnecessary costs. By defining clear interface boundaries across teams, by serving one team's public models as "APIs" to another, and by enabling practitioners to develop with a more narrowly defined scope, we can enable more people to contribute, with more confidence, while requiring less context upfront. FAQs[​](https://docs.getdbt.com/docs/mesh/govern/project-dependencies#faqs "Direct link to FAQs") -------------------------------------------------------------------------------------------------- Can I define private packages in the dependencies.yml file? It depends on how you're accessing your private packages: * If you're using [native private packages](https://docs.getdbt.com/docs/build/packages#native-private-packages) , you can define them in the `dependencies.yml` file. * If you're using the [git token method](https://docs.getdbt.com/docs/build/packages#git-token-method) , you must define them in the `packages.yml` file instead of the `dependencies.yml` file. This is because conditional rendering (like Jinja-in-yaml) is not supported in `dependencies.yml`. Why doesn’t an indirectly referenced upstream public model appear in Explorer? For [project dependencies](https://docs.getdbt.com/docs/mesh/govern/project-dependencies) in Mesh, [Catalog](https://docs.getdbt.com/docs/explore/explore-multiple-projects) only displays directly referenced [public models](https://docs.getdbt.com/docs/mesh/govern/model-access) from upstream projects, even if an upstream model indirectly depends on another public model. So for example, if: * `project_b` adds `project_a` as a dependency * `project_b`'s model `downstream_c` references `project_a.upstream_b` * `project_a.upstream_b` references another public model, `project_a.upstream_a` Then: * In Explorer, only directly referenced public models (`upstream_b` in this case) appear. * In the [Studio IDE](https://docs.getdbt.com/docs/cloud/dbt-cloud-ide/develop-in-the-cloud) lineage view, however, `upstream_a` (the indirect dependency) _will_ appear because dbt dynamically resolves the full dependency graph. This behavior makes sure that Catalog only shows the immediate dependencies available to that specific project. Related docs[​](https://docs.getdbt.com/docs/mesh/govern/project-dependencies#related-docs "Direct link to Related docs") -------------------------------------------------------------------------------------------------------------------------- * Refer to the [Mesh](https://docs.getdbt.com/best-practices/how-we-mesh/mesh-1-intro) guide for more guidance on how to use Mesh. * [Quickstart with Mesh](https://docs.getdbt.com/guides/mesh-qs) Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Prerequisites](https://docs.getdbt.com/docs/mesh/govern/project-dependencies#prerequisites) * [Use cases](https://docs.getdbt.com/docs/mesh/govern/project-dependencies#use-cases) * [Example](https://docs.getdbt.com/docs/mesh/govern/project-dependencies#example) * [Advantages](https://docs.getdbt.com/docs/mesh/govern/project-dependencies#advantages) * [How to write cross-project ref](https://docs.getdbt.com/docs/mesh/govern/project-dependencies#how-to-write-cross-project-ref) * [Safeguarding production data with staging environments](https://docs.getdbt.com/docs/mesh/govern/project-dependencies#safeguarding-production-data-with-staging-environments) * [Comparison](https://docs.getdbt.com/docs/mesh/govern/project-dependencies#comparison) * [FAQs](https://docs.getdbt.com/docs/mesh/govern/project-dependencies#faqs) * [Related docs](https://docs.getdbt.com/docs/mesh/govern/project-dependencies#related-docs) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/mesh/govern/project-dependencies.md) --- # User tokens | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/dbt-cloud-apis/user-tokens#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page warning User API tokens have been deprecated and will no longer work. [Migrate](https://docs.getdbt.com/docs/dbt-cloud-apis/user-tokens#migrate-deprecated-user-api-keys-to-personal-access-tokens) to personal access tokens to resume services. Each dbt user with a [Developer license](https://docs.getdbt.com/docs/cloud/manage-access/seats-and-users)  can create a new personal access token (PAT) to access the dbt API and dbt CLI. This token can execute queries against the dbt API on the user's behalf. To access dbt APIs and resources on behalf of the _account_, we recommend using service tokens instead. Learn more about [which token type you should use](https://docs.getdbt.com/docs/dbt-cloud-apis/authentication#which-token-type-should-you-use) to understand the token differences. PATs inherit the permissions of the user that created them. For example, if a developer-licensed user with Project Admin role access to specific projects creates a PAT, the token will get the Project Admin role with access to the same projects as the user. These tokens are also account-specific, so if a user has access to more than one dbt account with the same email address, they need to create a unique PAT for each one of these accounts. Create a personal access token[​](https://docs.getdbt.com/docs/dbt-cloud-apis/user-tokens#create-a-personal-access-token "Direct link to Create a personal access token") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Creating an account-scoped PAT requires only a few steps. 1. Navigate to your **Account Settings**, expand **API tokens** and click **Personal tokens**. 2. Click **Create personal access token**. 3. Give the token a descriptive name and click **Save**. 4. Copy the token before closing the window. _It will not be available after, and you will have to create a new token if you lose it._ To maintain best security practices, it's recommended that you regularly rotate your PATs. To do so, create a new token and delete the old one once it's in place. Delete a personal access token[​](https://docs.getdbt.com/docs/dbt-cloud-apis/user-tokens#delete-a-personal-access-token "Direct link to Delete a personal access token") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- To permanently delete a PAT: 1. Navigate to your **Account Settings**, expand **API tokens** and click **Personal tokens**. 2. Find the token you want to delete and click "X" to the right of the token description fields. 3. **Confirm delete** and the token will no longer be valid. Migrate deprecated user API keys to personal access tokens[​](https://docs.getdbt.com/docs/dbt-cloud-apis/user-tokens#migrate-deprecated-user-api-keys-to-personal-access-tokens "Direct link to Migrate deprecated user API keys to personal access tokens") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The migration to PATs is critical if you are using user API keys today. The current API key is located under **Personal Settings → API Key**. There are a few things to understand if you are using a user API key today: * PATs are more secure. * To promote the least privilege and high-security assurance for your dbt accounts, we highly recommend moving to the new account-scoped PATs. * You must create and use unique tokens in each one of your dbt accounts that share the same email address. * For example, if [paul.atreides@example.com](mailto:paul.atreides@example.com) belongs to two dbt accounts: Spice Harvesting Account and Guild Navigator Account. Before this release, the same API key was used to access both of these accounts. * After this release, Paul has to individually go into these accounts and create a unique PAT for each account he wants to access the API for. These PATs are account-specific and not user specific. * Cross-Account API endpoints will change in behavior when using PATs. * These are namely /v2/accounts and /v3/accounts. Since all PATs are now account specific, getting all accounts associated with a username cannot work. /v3/accounts will only return account metadata that’s relevant to the PAT that’s being used. * User account metadata will only contain information about the specific account under which the request is being made. * Any other accounts that belong to that user account will need to be requested through the PAT that belongs to that account. Undocumented APIs If you’re using any undocumented and unsupported API endpoints, please note that these can be deprecated without any notice. If you are using any undocumented endpoints and have use-cases that are not satisfied by the current API, please reach out to [support@getdbt.com](mailto:support@getdbt.com) . ### Using the personal access tokens[​](https://docs.getdbt.com/docs/dbt-cloud-apis/user-tokens#using-the-personal-access-tokens "Direct link to Using the personal access tokens") Are you using a user API key today to access dbt APIs in any of your workflows? If not, you don’t have any action to take. If you are using a user API key, please follow the instructions below. 1. Make a list of all the places where you’re making a call to the dbt API using the dbt user API key. 2. Create a new PAT under **Account Settings → API Tokens → Personal Tokens.** For instructions, see [Create a personal access token](https://docs.getdbt.com/docs/dbt-cloud-apis/user-tokens#create-a-personal-access-token) . 3. Replace the API key in your APIs with the PAT you created. You can use a PAT wherever you previously used an API key. To replace the API key with a PAT, include the PAT in the Authorization header of your API requests. For example: `Authorization: Bearer `. Make sure to replace `` with the new PAT you created. note The option to rotate API keys is used for existing API keys, not for replacing them with PATs. You do not need to replace your API key with a PAT in the dbt UI. 4. Ensure that you’re using a PAT only where it's needed. For flows that require a service account, please use a service token. Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Create a personal access token](https://docs.getdbt.com/docs/dbt-cloud-apis/user-tokens#create-a-personal-access-token) * [Delete a personal access token](https://docs.getdbt.com/docs/dbt-cloud-apis/user-tokens#delete-a-personal-access-token) * [Migrate deprecated user API keys to personal access tokens](https://docs.getdbt.com/docs/dbt-cloud-apis/user-tokens#migrate-deprecated-user-api-keys-to-personal-access-tokens) * [Using the personal access tokens](https://docs.getdbt.com/docs/dbt-cloud-apis/user-tokens#using-the-personal-access-tokens) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/dbt-cloud-apis/user-tokens.md) --- # Consume metrics from your Semantic Layer | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/use-dbt-semantic-layer/consume-metrics#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page After [deploying](https://docs.getdbt.com/docs/use-dbt-semantic-layer/deploy-sl) your Semantic Layer, the next important (and fun!) step is querying and consuming the metrics you’ve defined. This page links to key resources that guide you through the process of consuming metrics across different integrations, APIs, and tools, using various different [query syntaxes](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc#querying-the-api-for-metric-metadata) . Once your Semantic Layer is deployed, you can start querying your metrics using a variety of tools and APIs. Here are the main resources to get you started: ### Available integrations[​](https://docs.getdbt.com/docs/use-dbt-semantic-layer/consume-metrics#available-integrations "Direct link to Available integrations") Integrate the Semantic Layer with a variety of business intelligence (BI) tools and data platforms, enabling seamless metric queries within your existing workflows. Explore the following integrations: * [Available integrations](https://docs.getdbt.com/docs/cloud-integrations/avail-sl-integrations) — Review a wide range of partners such as Tableau, Google Sheets, Microsoft Excel, and more, where you can query your metrics directly from the Semantic Layer. ### Query with APIs[​](https://docs.getdbt.com/docs/use-dbt-semantic-layer/consume-metrics#query-with-apis "Direct link to Query with APIs") To leverage the full power of the Semantic Layer, you can use the Semantic Layer APIs for querying metrics programmatically: * [Semantic Layer APIs](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-api-overview) — Learn how to use the Semantic Layer APIs to query metrics in downstream tools, ensuring consistent and reliable data metrics. * [JDBC API query syntax](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc#querying-the-api-for-metric-metadata) — Dive into the syntax for querying metrics with the JDBC API, with examples and detailed instructions. * [GraphQL API query syntax](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-graphql#querying) — Learn the syntax for querying metrics via the GraphQL API, including examples and detailed instructions. * [Python SDK](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-python#usage-examples) — Use the Python SDK library to query metrics programmatically with Python. ### Query during development[​](https://docs.getdbt.com/docs/use-dbt-semantic-layer/consume-metrics#query-during-development "Direct link to Query during development") For developers working within the dbt ecosystem, it’s essential to understand how to query metrics during the development phase using MetricFlow commands: * [MetricFlow commands](https://docs.getdbt.com/docs/build/metricflow-commands) — Learn how to use MetricFlow commands to query metrics directly during the development process, ensuring your metrics are correctly defined and working as expected. Next steps[​](https://docs.getdbt.com/docs/use-dbt-semantic-layer/consume-metrics#next-steps "Direct link to Next steps") -------------------------------------------------------------------------------------------------------------------------- After understanding the basics of querying metrics, consider optimizing your setup and ensuring the integrity of your metric definitions: * [Optimize querying performance](https://docs.getdbt.com/docs/use-dbt-semantic-layer/sl-cache) — Improve query speed and efficiency by using declarative caching techniques. * [Validate semantic nodes in CI](https://docs.getdbt.com/docs/deploy/ci-jobs#semantic-validations-in-ci) — Ensure that any changes to dbt models don’t break your metrics by validating semantic nodes in Continuous Integration (CI) jobs. * [Build your metrics and semantic models](https://docs.getdbt.com/docs/build/build-metrics-intro) — If you haven’t already, learn how to define and build your metrics and semantic models using your preferred development tool. Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Available integrations](https://docs.getdbt.com/docs/use-dbt-semantic-layer/consume-metrics#available-integrations) * [Query with APIs](https://docs.getdbt.com/docs/use-dbt-semantic-layer/consume-metrics#query-with-apis) * [Query during development](https://docs.getdbt.com/docs/use-dbt-semantic-layer/consume-metrics#query-during-development) * [Next steps](https://docs.getdbt.com/docs/use-dbt-semantic-layer/consume-metrics#next-steps) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/use-dbt-semantic-layer/consume-metrics.md) --- # dbt Quickstarts | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/get-started-dbt#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) Begin your dbt journey by trying one of our quickstarts, which provides a step-by-step guide to help you set up [dbt](https://docs.getdbt.com/docs/get-started-dbt#dbt-cloud) or [dbt Core](https://docs.getdbt.com/docs/get-started-dbt#dbt-core) with a [variety of data platforms](https://docs.getdbt.com/docs/cloud/connect-data-platform/about-connections) . the dbt platform[​](https://docs.getdbt.com/docs/get-started-dbt#the-dbt-platform "Direct link to the dbt platform") --------------------------------------------------------------------------------------------------------------------- dbt is a scalable solution that enables you to develop, test, deploy, and explore data products using a single, fully managed software service. It enables teams with diverse skills to build reliable data products at any scale, with capabilities including: * Development experiences tailored to multiple personas (in-browser [Studio IDE](https://docs.getdbt.com/docs/cloud/dbt-cloud-ide/develop-in-the-cloud) or locally with the [dbt CLI](https://docs.getdbt.com/docs/cloud/cloud-cli-installation) ) * Out-of-the-box [CI/CD workflows](https://docs.getdbt.com/docs/deploy/ci-jobs) * The [Semantic Layer](https://docs.getdbt.com/docs/use-dbt-semantic-layer/dbt-sl) for consistent metrics that can be delivered to any endpoint * Domain ownership of data with multi-project [Mesh](https://docs.getdbt.com/best-practices/how-we-mesh/mesh-1-intro) setups * [Catalog](https://docs.getdbt.com/docs/explore/explore-projects) for collaborative data discovery and understanding Learn more about [dbt features](https://docs.getdbt.com/docs/cloud/about-cloud/dbt-cloud-features) and [start your free trial](https://www.getdbt.com/signup/) today. [![](https://docs.getdbt.com/img/icons/athena.svg)\ \ #### Quickstart for dbt and Amazon Athena\ \ Integrate dbt with Amazon Athena for your data transformations.](https://docs.getdbt.com/guides/athena) [![](https://docs.getdbt.com/img/icons/azure-synapse-analytics-2.svg)\ \ #### Quickstart for dbt and Azure Synapse Analytics\ \ Discover how to integrate dbt with Azure Synapse Analytics for your data transformations.](https://docs.getdbt.com/guides/azure-synapse-analytics) [![](https://docs.getdbt.com/img/icons/bigquery.svg)\ \ #### Quickstart for dbt and BigQuery\ \ Discover how to leverage dbt with BigQuery to streamline your analytics workflows.](https://docs.getdbt.com/guides/bigquery) [![](https://docs.getdbt.com/img/icons/databricks.svg)\ \ #### Quickstart for dbt and Databricks\ \ Learn how to integrate dbt with Databricks for efficient data processing and analysis.](https://docs.getdbt.com/guides/databricks) [![](https://docs.getdbt.com/img/icons/fabric.svg)\ \ #### Quickstart for dbt and Microsoft Fabric\ \ Explore the synergy between dbt and Microsoft Fabric to optimize your data transformations.](https://docs.getdbt.com/guides/microsoft-fabric) [![](https://docs.getdbt.com/img/icons/redshift.svg)\ \ #### Quickstart for dbt and Redshift\ \ Learn how to connect dbt to Redshift for more agile data transformations.](https://docs.getdbt.com/guides/redshift) [![](https://docs.getdbt.com/img/icons/snowflake.svg)\ \ #### Quickstart for dbt and Snowflake\ \ Unlock the full potential of using dbt with Snowflake for your data transformations.](https://docs.getdbt.com/guides/snowflake) [![](https://docs.getdbt.com/img/icons/starburst.svg)\ \ #### Quickstart for dbt and Starburst Galaxy\ \ Leverage dbt with Starburst Galaxy to enhance your data transformation workflows.](https://docs.getdbt.com/guides/starburst-galaxy) [![](https://docs.getdbt.com/img/icons/teradata.svg)\ \ #### Quickstart for dbt and Teradata\ \ Discover and use dbt with Teradata to enhance your data transformation workflows.](https://docs.getdbt.com/guides/teradata) dbt local installations[​](https://docs.getdbt.com/docs/get-started-dbt#dbt-local-installations "Direct link to dbt local installations") ------------------------------------------------------------------------------------------------------------------------------------------ [dbt Core and dbt Fusion Engine](https://docs.getdbt.com/docs/about-dbt-install) provide command-line tools that enable data practitioners to transform data using analytics engineering best practices. These tools suit individuals and small technical teams who prefer manual setup and customization, support community adapters, and follow open-source standards. [![](https://docs.getdbt.com/img/icons/dbt-bit.svg)\ \ #### dbt Fusion engine from a manual install\ \ Learn how to install dbt Fusion and set up a project.](https://docs.getdbt.com/guides/fusion?step=2) [![](https://docs.getdbt.com/img/icons/dbt-bit.svg)\ \ #### dbt Core from a manual install\ \ Learn how to install dbt Core and set up a project.](https://docs.getdbt.com/guides/manual-install) [![](https://docs.getdbt.com/img/icons/duckdb.svg)\ \ #### Quickstart for dbt Core using DuckDB\ \ Learn how to connect to DuckDB.](https://docs.getdbt.com/guides/duckdb?step=1) Related docs[​](https://docs.getdbt.com/docs/get-started-dbt#related-docs "Direct link to Related docs") --------------------------------------------------------------------------------------------------------- Expand your dbt knowledge and expertise with these additional resources: * [Join the monthly demos](https://www.getdbt.com/resources/webinars/dbt-cloud-demos-with-experts) to see dbt in action and ask questions. * [dbt AWS marketplace](https://aws.amazon.com/marketplace/pp/prodview-tjpcf42nbnhko) contains information on how to deploy dbt on AWS, user reviews, and more. * [Best practices](https://docs.getdbt.com/best-practices) contains information on how dbt Labs approaches building projects through our current viewpoints on structure, style, and setup. * [dbt Learn](https://learn.getdbt.com/) offers free online courses that cover dbt fundamentals, advanced topics, and more. * [Join the dbt Community](https://www.getdbt.com/community/join-the-community) to learn how other data practitioners globally are using dbt, share your own experiences, and get help with your dbt projects. Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 --- # About environments | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/environments-in-dbt#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) In software engineering, environments are used to enable engineers to develop and test code without impacting the users of their software. Typically, there are two types of environments in dbt: * **Deployment or Production** (or _prod_) — Refers to the environment that end users interact with. * **Development** (or _dev_) — Refers to the environment that engineers work in. This means that engineers can work iteratively when writing and testing new code in _development_. Once they are confident in these changes, they can deploy their code to _production_. In traditional software engineering, different environments often use completely separate architecture. For example, the dev and prod versions of a website may use different servers and databases. Data warehouses can also be designed to have separate environments — the _production_ environment refers to the relations (for example, schemas, tables, and views) that your end users query (often through a BI tool). Configure environments to tell dbt or dbt Core how to build and execute your project in development and production: [![](https://docs.getdbt.com/img/icons/dbt-bit.svg)\ \ #### Environments in dbt\ \ Seamlessly configure development and deployment environments in dbt to control how your project runs in both the Studio IDE, dbt CLI, and dbt jobs.](https://docs.getdbt.com/docs/dbt-cloud-environments) [![](https://docs.getdbt.com/img/icons/command-line.svg)\ \ #### Environments in dbt Core\ \ Setup and maintain separate deployment and development environments through the use of targets within a profile file](https://docs.getdbt.com/docs/core/dbt-core-environments) Related docs[​](https://docs.getdbt.com/docs/environments-in-dbt#related-docs "Direct link to Related docs") ------------------------------------------------------------------------------------------------------------- * [dbt environment best practices](https://docs.getdbt.com/guides/set-up-ci) * [Deployment environments](https://docs.getdbt.com/docs/deploy/deploy-environments) * [About dbt Core versions](https://docs.getdbt.com/docs/dbt-versions/core) * [Set Environment variables in dbt](https://docs.getdbt.com/docs/build/environment-variables#special-environment-variables) * [Use Environment variables in jinja](https://docs.getdbt.com/reference/dbt-jinja-functions/env_var) Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 --- # Model contracts | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/mesh/govern/model-contracts#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page Related documentation[​](https://docs.getdbt.com/docs/mesh/govern/model-contracts#related-documentation "Direct link to Related documentation") ------------------------------------------------------------------------------------------------------------------------------------------------ * [`contract`](https://docs.getdbt.com/reference/resource-configs/contract) * [`columns`](https://docs.getdbt.com/reference/resource-properties/columns) * [`constraints`](https://docs.getdbt.com/reference/resource-properties/constraints) Why define a contract?[​](https://docs.getdbt.com/docs/mesh/govern/model-contracts#why-define-a-contract "Direct link to Why define a contract?") -------------------------------------------------------------------------------------------------------------------------------------------------- Defining a dbt model is as easy as writing a SQL `select` statement. Your query naturally produces a dataset with columns of names and types based on the columns you select and the transformations you apply. While this is ideal for quick and iterative development, for some models, constantly changing the shape of its returned dataset poses a risk when other people and processes are querying that model. It's better to define a set of upfront "guarantees" that define the shape of your model. We call this set of guarantees a "contract." While building your model, dbt will verify that your model's transformation will produce a dataset matching up with its contract, or it will fail to build. Considerations Model governance features like model access, contracts, and versions strengthen trust and stability in your dbt project. Because they add structure, it can make it harder to roll changes back later (for example, removing model access) and increases maintenance if adopted too early. Before adding governance features, consider whether your dbt project is ready to benefit from them. Introducing them too soon can make future changes harder if your models are still changing/evolving. Where are contracts supported?[​](https://docs.getdbt.com/docs/mesh/govern/model-contracts#where-are-contracts-supported "Direct link to Where are contracts supported?") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- At present, model contracts are supported for: * SQL models. * Models materialized as one of the following: * `table` * `view` — Views offer limited support for column names and data types, but not `constraints`. * `incremental` — with `on_schema_change: append_new_columns` or `on_schema_change: fail`. * Certain data platforms, but the supported and enforced `constraints` vary by platform. Model contracts are _not_ supported for: * Python models. * `materialized view` or `ephemeral`\-materialized SQL models. * Custom materializations (unless added by the author). * Models with recursive CTE's in BigQuery. * Other resource types, such as `sources`, `seeds`, `snapshots`, and so on. How to define a contract[​](https://docs.getdbt.com/docs/mesh/govern/model-contracts#how-to-define-a-contract "Direct link to How to define a contract") --------------------------------------------------------------------------------------------------------------------------------------------------------- Let's say you have a model with a query like: models/marts/dim\_customers.sql -- lots of SQLfinal as ( select customer_id, customer_name, -- ... many more ... from ...)select * from final To enforce a model's contract, set `enforced: true` under the `contract` configuration. When enforced, your contract _must_ include every column's `name` and `data_type` (where `data_type` matches one that your data platform understands). If your model is materialized as `table` or `incremental`, and depending on your data platform, you may optionally specify additional [constraints](https://docs.getdbt.com/reference/resource-properties/constraints) , such as `not_null` (containing zero null values). models/marts/customers.yml models: - name: dim_customers config: contract: enforced: true columns: - name: customer_id data_type: int constraints: - type: not_null - name: customer_name data_type: string ... When building a model with a defined contract, dbt will do two things differently: 1. dbt will run a "preflight" check to ensure that the model's query will return a set of columns with names and data types matching the ones you have defined. This check is agnostic to the order of columns specified in your model (SQL) or YAML spec. 2. dbt will include the column names, data types, and constraints in the DDL statements it submits to the data platform, which will be enforced while building or updating the model's table, and order the columns per the contract instead of your dbt model. Platform constraint support[​](https://docs.getdbt.com/docs/mesh/govern/model-contracts#platform-constraint-support "Direct link to Platform constraint support") ------------------------------------------------------------------------------------------------------------------------------------------------------------------ Select the adapter-specific tab for more information on [constraint](https://docs.getdbt.com/reference/resource-properties/constraints) support across platforms. Constraints fall into three categories based on definability and platform enforcement: * **Definable and enforced** — The model won't build if it violates the constraint. * **Definable and not enforced** — The platform supports specifying the type of constraint, but a model can still build even if building the model violates the constraint. This constraint exists for metadata purposes only. This approach is more typical in cloud data warehouses than in transactional databases, where strict rule enforcement is more common. * **Not definable and not enforced** — You can't specify the type of constraint for the platform. * Redshift * Snowflake * BigQuery * Postgres * Spark * Databricks * Athena | Constraint type | Definable | Enforced | | --- | --- | --- | | not\_null | ✅ | ✅ | | primary\_key | ✅ | ❌ | | foreign\_key | ✅ | ❌ | | unique | ✅ | ❌ | | check | ❌ | ❌ | | Constraint type | Definable | Enforced | | --- | --- | --- | | not\_null | ✅ | ✅ | | primary\_key | ✅ | ❌ | | foreign\_key | ✅ | ❌ | | unique | ✅ | ❌ | | check | ❌ | ❌ | | Constraint type | Definable | Enforced | | --- | --- | --- | | not\_null | ✅ | ✅ | | primary\_key | ✅ | ❌ | | foreign\_key | ✅ | ❌ | | unique | ❌ | ❌ | | check | ❌ | ❌ | | Constraint type | Definable | Enforced | | --- | --- | --- | | not\_null | ✅ | ✅ | | primary\_key | ✅ | ✅ | | foreign\_key | ✅ | ✅ | | unique | ✅ | ✅ | | check | ✅ | ✅ | Currently, `not_null` and `check` constraints are enforced only after a model is built. Because of this platform limitation, dbt considers these constraints definable but not enforced, which means they're not part of the _model contract_ since they can't be enforced at build time. This table will change as the features evolve. | Constraint type | Definable | Enforced | | --- | --- | --- | | not\_null | ✅ | ❌ | | primary\_key | ✅ | ❌ | | foreign\_key | ✅ | ❌ | | unique | ✅ | ❌ | | check | ✅ | ❌ | Currently, `not_null` and `check` constraints are enforced only after a model is built. Because of this platform limitation, dbt considers these constraints definable but not enforced, which means they're not part of the _model contract_ since they can't be enforced at build time. This table will change as the features evolve. | Constraint type | Definable | Enforced | | --- | --- | --- | | not\_null | ✅ | ❌ | | primary\_key | ✅ | ❌ | | foreign\_key | ✅ | ❌ | | unique | ✅ | ❌ | | check | ✅ | ❌ | | Constraint type | Definable | Enforced | | --- | --- | --- | | not\_null | ❌ | ❌ | | primary\_key | ❌ | ❌ | | foreign\_key | ❌ | ❌ | | unique | ❌ | ❌ | | check | ❌ | ❌ | FAQs[​](https://docs.getdbt.com/docs/mesh/govern/model-contracts#faqs "Direct link to FAQs") --------------------------------------------------------------------------------------------- ### Which models should have contracts?[​](https://docs.getdbt.com/docs/mesh/govern/model-contracts#which-models-should-have-contracts "Direct link to Which models should have contracts?") Any model meeting the criteria described above _can_ define a contract. We recommend defining contracts for ["public" models](https://docs.getdbt.com/docs/mesh/govern/model-access) that are being relied on downstream. * Inside of dbt: Shared with other groups, other teams, and [other dbt projects](https://docs.getdbt.com/best-practices/how-we-mesh/mesh-1-intro) . * Outside of dbt: Reports, dashboards, or other systems & processes that expect this model to have a predictable structure. You might reflect these downstream uses with [exposures](https://docs.getdbt.com/docs/build/exposures) . ### How are contracts different from tests?[​](https://docs.getdbt.com/docs/mesh/govern/model-contracts#how-are-contracts-different-from-tests "Direct link to How are contracts different from tests?") A model's contract defines the **shape** of the returned dataset. If the model's logic or input data doesn't conform to that shape, the model does not build. [Data Tests](https://docs.getdbt.com/docs/build/data-tests) are a more flexible mechanism for validating the content of your model _after_ it's built. So long as you can write the query, you can run the data test. Data tests are more configurable, such as with [custom severity thresholds](https://docs.getdbt.com/reference/resource-configs/severity) . They are easier to debug after finding failures because you can query the already-built model, or [store the failing records in the data warehouse](https://docs.getdbt.com/reference/resource-configs/store_failures) . In some cases, you can replace a data test with its equivalent constraint. This has the advantage of guaranteeing the validation at build time, and it probably requires less compute (cost) in your data platform. The prerequisites for replacing a data test with a constraint are: * Making sure that your data platform can support and enforce the constraint that you need. Most platforms only enforce `not_null`. * Materializing your model as `table` or `incremental` (**not** `view` or `ephemeral`). * Defining a full contract for this model by specifying the `name` and `data_type` of each column. **Why aren't tests part of the contract?** In a parallel for software APIs, the structure of the API response is the contract. Quality and reliability ("uptime") are also very important attributes of an API's quality, but they are not part of the contract per se. When the contract changes in a backwards-incompatible way, it is a breaking change that requires a bump in major version. ### Do I need to define every column for a contract?[​](https://docs.getdbt.com/docs/mesh/govern/model-contracts#do-i-need-to-define-every-column-for-a-contract "Direct link to Do I need to define every column for a contract?") Currently, dbt contracts apply to **all** columns defined in a model, and they require declaring explicit expectations about **all** of those columns. The explicit declaration of a contract is not an accident—it's very much the intent of this feature. At the same time, for models with many columns, we understand that this can mean a _lot_ of yaml. We are investigating the feasibility of supporting "inferred" contracts. This would enable you to define constraints and strict data typing for a subset of columns, while still detecting breaking changes on other columns by comparing against the same model in production. This isn't the same as a "partial" contract, because all columns in the model are still checked at runtime, and matched up with what's defined _explicitly_ in your yaml contract or _implicitly_ with the comparison state. If you're interested in "inferred" contract, please upvote or comment on [dbt Core#7432](https://github.com/dbt-labs/dbt-core/issues/7432) . ### How are breaking changes handled?[​](https://docs.getdbt.com/docs/mesh/govern/model-contracts#how-are-breaking-changes-handled "Direct link to How are breaking changes handled?") When comparing to a previous project state, dbt will look for breaking changes that could impact downstream consumers. If breaking changes are detected, dbt will present a contract error. Breaking changes include: * Removing an existing column * Changing the data\_type of an existing column * Removing or modifying one of the `constraints` on an existing column (dbt v1.6 or higher) * Removing a contracted model by deleting, renaming, or disabling it (dbt v1.9 or higher). * versioned models will raise an error. unversioned models will raise a warning. More details are available in the [contract reference](https://docs.getdbt.com/reference/resource-configs/contract#detecting-breaking-changes) . Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Related documentation](https://docs.getdbt.com/docs/mesh/govern/model-contracts#related-documentation) * [Why define a contract?](https://docs.getdbt.com/docs/mesh/govern/model-contracts#why-define-a-contract) * [Where are contracts supported?](https://docs.getdbt.com/docs/mesh/govern/model-contracts#where-are-contracts-supported) * [How to define a contract](https://docs.getdbt.com/docs/mesh/govern/model-contracts#how-to-define-a-contract) * [Platform constraint support](https://docs.getdbt.com/docs/mesh/govern/model-contracts#platform-constraint-support) * [FAQs](https://docs.getdbt.com/docs/mesh/govern/model-contracts#faqs) * [Which models should have contracts?](https://docs.getdbt.com/docs/mesh/govern/model-contracts#which-models-should-have-contracts) * [How are contracts different from tests?](https://docs.getdbt.com/docs/mesh/govern/model-contracts#how-are-contracts-different-from-tests) * [Do I need to define every column for a contract?](https://docs.getdbt.com/docs/mesh/govern/model-contracts#do-i-need-to-define-every-column-for-a-contract) * [How are breaking changes handled?](https://docs.getdbt.com/docs/mesh/govern/model-contracts#how-are-breaking-changes-handled) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/mesh/govern/model-contracts.md) --- # APIs Overview | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/dbt-cloud-apis/overview#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page Accounts on the Enterprise and Enterprise+ plans can query the dbt APIs. dbt provides the following APIs: * The [dbt Administrative API](https://docs.getdbt.com/docs/dbt-cloud-apis/admin-cloud-api) can be used to administrate a dbt account. It can be called manually or with [the dbt Terraform provider](https://registry.terraform.io/providers/dbt-labs/dbtcloud/latest) . * The [dbt Discovery API](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-api) can be used to fetch metadata related to the state and health of your dbt project. * The [Semantic Layer APIs](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-api-overview) provides multiple API options which allow you to query your metrics defined in the Semantic Layer. If you want to learn more about webhooks, refer to [Webhooks for your jobs](https://docs.getdbt.com/docs/deploy/webhooks) . How to Access the APIs[​](https://docs.getdbt.com/docs/dbt-cloud-apis/overview#how-to-access-the-apis "Direct link to How to Access the APIs") ----------------------------------------------------------------------------------------------------------------------------------------------- dbt supports two types of API Tokens: [personal access tokens](https://docs.getdbt.com/docs/dbt-cloud-apis/user-tokens) and [service account tokens](https://docs.getdbt.com/docs/dbt-cloud-apis/service-tokens) . Requests to the dbt APIs can be authorized using these tokens. Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [How to Access the APIs](https://docs.getdbt.com/docs/dbt-cloud-apis/overview#how-to-access-the-apis) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/dbt-cloud-apis/apis-overview.md) --- # Definition object schema | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-definition#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page The definition object allows you to query the logical state of a given project node given its most recent manifest generated models. The [Example queries](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-definition#example-queries) illustrate a few fields you can query with this `definition` object. Refer to [Fields](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-definition#fields) to view the entire schema, which provides all possible fields you can query. ### Example queries[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-definition#example-queries "Direct link to Example queries") You can use your production environment's `id`: query Example { environment(id: 834){ # Get the latest state of the production environment definition { # The logical state of a given project node given its most recent manifest generated models(first: 100, filter:{access:public}){ # Filter on model access (or other properties) edges { node { rawCode, # Compare to see if/how the model has changed since the last build jobDefinitionId, runGeneratedAt, # When the code was last compiled or run contractEnforced, group, version}}} # Model governance } }} ### Fields[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-definition#fields "Direct link to Fields") When querying the `definition` field of `environment`, you can use the following fields. Fetching data... ================ Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Example queries](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-definition#example-queries) * [Fields](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-definition#fields) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/dbt-cloud-apis/schema-discovery-environment-definition.mdx) --- # Supported data platforms | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/supported-data-platforms#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) dbt connects to and runs SQL against your database, warehouse, lake, or query engine. These SQL-speaking platforms are collectively referred to as _data platforms_. dbt connects with data platforms by using a dedicated adapter plugin for each. Plugins are built as Python modules that dbt Core discovers if they are installed on your system. Refer to the [Build, test, document, and promote adapters](https://docs.getdbt.com/guides/adapter-creation) guide for details. You can [connect](https://docs.getdbt.com/docs/connect-adapters) to adapters and data platforms natively in dbt or install them manually using dbt Core. You can also further customize how dbt works with your specific data platform via configuration: see [Configuring Postgres](https://docs.getdbt.com/reference/resource-configs/postgres-configs) for an example. Types of Adapters[​](https://docs.getdbt.com/docs/supported-data-platforms#types-of-adapters "Direct link to Types of Adapters") --------------------------------------------------------------------------------------------------------------------------------- There are two types of adapters available today: * **Trusted** — [Trusted adapters](https://docs.getdbt.com/docs/trusted-adapters) are those where the adapter maintainers have decided to participate in the Trusted Adapter Program and have made a commitment to meeting those requirements. For adapters supported in dbt, maintainers have undergone an additional rigorous process that covers contractual requirements for development, documentation, user experience, and maintenance. * **Community** — [Community adapters](https://docs.getdbt.com/docs/community-adapters) are open-source and maintained by community members. These adapters are not part of the Trusted Adapter Program and could have usage inconsistencies. Considerations for depending on an open-source project 1. Does it work? 2. Does anyone "own" the code, or is anyone liable for ensuring it works? 3. Do bugs get fixed quickly? 4. Does it stay up-to-date with new dbt Core features? 5. Is the usage substantial enough to self-sustain? 6. Do other known projects depend on this library? Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 --- # Deployment environments | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/deploy/deploy-environments#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page Deployment environments in dbt are crucial for deploying dbt jobs in production and using features or integrations that depend on dbt metadata or results. To execute dbt, environments determine the settings used during job runs, including: * The version of dbt Core that will be used to run your project * The warehouse connection information (including the target database/schema settings) * The version of your code to execute A dbt project can have multiple deployment environments, providing you the flexibility and customization to tailor the execution of dbt jobs. You can use deployment environments to [create and schedule jobs](https://docs.getdbt.com/docs/deploy/deploy-jobs#create-and-schedule-jobs) , [enable continuous integration](https://docs.getdbt.com/docs/deploy/continuous-integration) , or more based on your specific needs or requirements. Learn how to manage dbt environments To learn different approaches to managing dbt environments and recommendations for your organization's unique needs, read [dbt environment best practices](https://docs.getdbt.com/guides/set-up-ci) . Learn more about development vs. deployment environments in [dbt Environments](https://docs.getdbt.com/docs/dbt-cloud-environments) . There are three types of deployment environments: * **Production**: Environment for transforming data and building pipelines for production use. * **Staging**: Environment for working with production tools while limiting access to production data. * **General**: General use environment for deployment development. We highly recommend using the `Production` environment type for the final, source of truth deployment data. There can be only one environment marked for final production workflows and we don't recommend using a `General` environment for this purpose. Create a deployment environment[​](https://docs.getdbt.com/docs/deploy/deploy-environments#create-a-deployment-environment "Direct link to Create a deployment environment") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- To create a new dbt deployment environment, navigate to **Deploy** -> **Environments** and then click **Create Environment**. Select **Deployment** as the environment type. The option will be greyed out if you already have a development environment. [![Navigate to Deploy -> Environments to create a deployment environment](https://docs.getdbt.com/img/docs/dbt-cloud/cloud-configuring-dbt-cloud/create-deploy-env.png?v=2 "Navigate to Deploy -> Environments to create a deployment environment")](https://docs.getdbt.com/docs/deploy/deploy-environments#) Navigate to Deploy -> Environments to create a deployment environment ### Set as production environment[​](https://docs.getdbt.com/docs/deploy/deploy-environments#set-as-production-environment "Direct link to Set as production environment") In dbt, each project can have one designated deployment environment, which serves as its production environment. This production environment is _essential_ for using features like Catalog and cross-project references. It acts as the source of truth for the project's production state in dbt. [![Set your production environment as the default environment in your Environment Settings](https://docs.getdbt.com/img/docs/dbt-cloud/using-dbt-cloud/prod-settings-1.png?v=2 "Set your production environment as the default environment in your Environment Settings")](https://docs.getdbt.com/docs/deploy/deploy-environments#) Set your production environment as the default environment in your Environment Settings ### Semantic Layer[​](https://docs.getdbt.com/docs/deploy/deploy-environments#semantic-layer "Direct link to Semantic Layer") For customers using the Semantic Layer, the next section of environment settings is the Semantic Layer configurations. [The Semantic Layer setup guide](https://docs.getdbt.com/docs/use-dbt-semantic-layer/setup-sl) has the most up-to-date setup instructions. You can also leverage the dbt Job scheduler to [validate your semantic nodes in a CI job](https://docs.getdbt.com/docs/deploy/ci-jobs#semantic-validations-in-ci) to ensure code changes made to dbt models don't break these metrics. Staging environment[​](https://docs.getdbt.com/docs/deploy/deploy-environments#staging-environment "Direct link to Staging environment") ----------------------------------------------------------------------------------------------------------------------------------------- Use a Staging environment to grant developers access to deployment workflows and tools while controlling access to production data. Staging environments enable you to achieve more granular control over permissions, data warehouse connections, and data isolation — within the purview of a single project in dbt. ### Git workflow[​](https://docs.getdbt.com/docs/deploy/deploy-environments#git-workflow "Direct link to Git workflow") You can approach this in a couple of ways, but the most straightforward is configuring Staging with a long-living branch (for example, `staging`) similar to but separate from the primary branch (for example, `main`). In this scenario, the workflows would ideally move upstream from the Development environment -> Staging environment -> Production environment with developer branches feeding into the `staging` branch, then ultimately merging into `main`. In many cases, the `main` and `staging` branches will be identical after a merge and remain until the next batch of changes from the `development` branches are ready to be elevated. We recommend setting branch protection rules on `staging` similar to `main`. Some customers prefer to connect Development and Staging to their `main` branch and then cut release branches on a regular cadence (daily or weekly), which feeds into Production. ### Why use a staging environment[​](https://docs.getdbt.com/docs/deploy/deploy-environments#why-use-a-staging-environment "Direct link to Why use a staging environment") These are the primary motivations for using a Staging environment: 1. An additional validation layer before changes are deployed into Production. You can deploy, test, and explore your dbt models in Staging. 2. Clear isolation between development workflows and production data. It enables developers to work in metadata-powered ways, using features like deferral and cross-project references, without accessing data in production deployments. 3. Provide developers with the ability to create, edit, and trigger ad hoc jobs in the Staging environment, while keeping the Production environment locked down using [environment-level permissions](https://docs.getdbt.com/docs/cloud/manage-access/environment-permissions) . **Conditional configuration of sources** enables you to point to "prod" or "non-prod" source data, depending on the environment you're running in. For example, this source will point to `.sensitive_source.table_with_pii`, where `` is dynamically resolved based on an environment variable. models/sources.yml sources: - name: sensitive_source database: "{{ env_var('SENSITIVE_SOURCE_DATABASE') }}" tables: - name: table_with_pii There is exactly one source (`sensitive_source`), and all downstream dbt models select from it as `{{ source('sensitive_source', 'table_with_pii') }}`. The code in your project and the shape of the DAG remain consistent across environments. By setting it up in this way, rather than duplicating sources, you get some important benefits. **Cross-project references in dbt Mesh:** Let's say you have `Project B` downstream of `Project A` with cross-project refs configured in the models. When developers work in the IDE for `Project B`, cross-project refs will resolve to the Staging environment of `Project A`, rather than production. You'll get the same results with those refs when jobs are run in the Staging environment. Only the Production environment will reference the Production data, keeping the data and access isolated without needing separate projects. **Faster development enabled by deferral:** If `Project B` also has a Staging deployment, then references to unbuilt upstream models within `Project B` will resolve to that environment, using [deferral](https://docs.getdbt.com/docs/cloud/about-cloud-develop-defer) , rather than resolving to the models in Production. This saves developers time and warehouse spend, while preserving clear separation of environments. Finally, the Staging environment has its own view in [Catalog](https://docs.getdbt.com/docs/explore/explore-projects) , giving you a full view of your prod and pre-prod data. [![Explore in a staging environment](https://docs.getdbt.com/img/docs/collaborate/dbt-explorer/explore-staging-env.png?v=2 "Explore in a staging environment")](https://docs.getdbt.com/docs/deploy/deploy-environments#) Explore in a staging environment ### Create a Staging environment[​](https://docs.getdbt.com/docs/deploy/deploy-environments#create-a-staging-environment "Direct link to Create a Staging environment") In the dbt, navigate to **Deploy** -> **Environments** and then click **Create Environment**. Select **Deployment** as the environment type. The option will be greyed out if you already have a development environment. [![Create a staging environment](https://docs.getdbt.com/img/docs/dbt-cloud/cloud-configuring-dbt-cloud/create-staging-environment.png?v=2 "Create a staging environment")](https://docs.getdbt.com/docs/deploy/deploy-environments#) Create a staging environment Follow the steps outlined in [deployment credentials](https://docs.getdbt.com/docs/deploy/deploy-environments#deployment-connection) to complete the remainder of the environment setup. We recommend that the data warehouse credentials be for a dedicated user or service principal. Deployment connection[​](https://docs.getdbt.com/docs/deploy/deploy-environments#deployment-connection "Direct link to Deployment connection") ----------------------------------------------------------------------------------------------------------------------------------------------- Warehouse Connections Warehouse connections are created and managed at the account-level for dbt accounts and assigned to an environment. To change warehouse type, we recommend creating a new environment. Each project can have multiple connections (Snowflake account, Redshift host, Bigquery project, Databricks host, and so on.) of the same warehouse type. Some details of that connection (databases/schemas/and so on.) can be overridden within this section of the dbt environment settings. This section determines the exact location in your warehouse dbt should target when building warehouse objects! This section will look a bit different depending on your warehouse provider. For all warehouses, use [extended attributes](https://docs.getdbt.com/docs/dbt-cloud-environments#extended-attributes) to override missing or inactive (grayed-out) settings. * Postgres * Redshift * Snowflake * Bigquery * Spark * Databricks This section will not appear if you are using Postgres, as all values are inferred from the project's connection. Use [extended attributes](https://docs.getdbt.com/docs/dbt-cloud-environments#extended-attributes) to override these values. This section will not appear if you are using Redshift, as all values are inferred from the project's connection. Use [extended attributes](https://docs.getdbt.com/docs/dbt-cloud-environments#extended-attributes) to override these values. [![Snowflake Deployment Connection Settings](https://docs.getdbt.com/img/docs/collaborate/snowflake-deploy-env-deploy-connection.png?v=2 "Snowflake Deployment Connection Settings")](https://docs.getdbt.com/docs/deploy/deploy-environments#) Snowflake Deployment Connection Settings #### Editable fields[​](https://docs.getdbt.com/docs/deploy/deploy-environments#editable-fields "Direct link to Editable fields") * **Role**: Snowflake role * **Database**: Target database * **Warehouse**: Snowflake warehouse This section will not appear if you are using Bigquery, as all values are inferred from the project's connection. Use [extended attributes](https://docs.getdbt.com/docs/dbt-cloud-environments#extended-attributes) to override these values. This section will not appear if you are using Spark, as all values are inferred from the project's connection. Use [extended attributes](https://docs.getdbt.com/docs/dbt-cloud-environments#extended-attributes) to override these values. [![Databricks Deployment Connection Settings](https://docs.getdbt.com/img/docs/collaborate/databricks-deploy-env-deploy-connection.png?v=2 "Databricks Deployment Connection Settings")](https://docs.getdbt.com/docs/deploy/deploy-environments#) Databricks Deployment Connection Settings #### Editable fields[​](https://docs.getdbt.com/docs/deploy/deploy-environments#editable-fields-1 "Direct link to Editable fields") * **Catalog** (optional): [Unity Catalog namespace](https://docs.getdbt.com/docs/core/connect-data-platform/databricks-setup) ### Deployment credentials[​](https://docs.getdbt.com/docs/deploy/deploy-environments#deployment-credentials "Direct link to Deployment credentials") This section allows you to determine the credentials that should be used when connecting to your warehouse. The authentication methods may differ depending on the warehouse and dbt tier you are on. For all warehouses, use [extended attributes](https://docs.getdbt.com/docs/dbt-cloud-environments#extended-attributes) to override missing or inactive (grayed-out) settings. For credentials, we recommend wrapping extended attributes in [environment variables](https://docs.getdbt.com/docs/build/environment-variables) (`password: '{{ env_var(''DBT_ENV_SECRET_PASSWORD'') }}'`) to avoid displaying the secret value in the text box and the logs. * Postgres * Redshift * Snowflake * Bigquery * Spark * Databricks [![Postgres Deployment Credentials Settings](https://docs.getdbt.com/img/docs/collaborate/postgres-deploy-env-deploy-credentials.png?v=2 "Postgres Deployment Credentials Settings")](https://docs.getdbt.com/docs/deploy/deploy-environments#) Postgres Deployment Credentials Settings #### Editable fields[​](https://docs.getdbt.com/docs/deploy/deploy-environments#editable-fields-2 "Direct link to Editable fields") * **Username**: Postgres username to use (most likely a service account) * **Password**: Postgres password for the listed user * **Schema**: Target schema [![Redshift Deployment Credentials Settings](https://docs.getdbt.com/img/docs/collaborate/postgres-deploy-env-deploy-credentials.png?v=2 "Redshift Deployment Credentials Settings")](https://docs.getdbt.com/docs/deploy/deploy-environments#) Redshift Deployment Credentials Settings #### Editable fields[​](https://docs.getdbt.com/docs/deploy/deploy-environments#editable-fields-3 "Direct link to Editable fields") * **Username**: Redshift username to use (most likely a service account) * **Password**: Redshift password for the listed user * **Schema**: Target schema [![Snowflake Deployment Credentials Settings](https://docs.getdbt.com/img/docs/collaborate/snowflake-deploy-env-deploy-credentials.png?v=2 "Snowflake Deployment Credentials Settings")](https://docs.getdbt.com/docs/deploy/deploy-environments#) Snowflake Deployment Credentials Settings #### Editable fields[​](https://docs.getdbt.com/docs/deploy/deploy-environments#editable-fields-4 "Direct link to Editable fields") * **Auth Method**: This determines the way dbt connects to your warehouse * One of: \[**Username & Password**, **Key Pair**\] * If **Username & Password**: * **Username**: username to use (most likely a service account) * **Password**: password for the listed user * If **Key Pair**: * **Username**: username to use (most likely a service account) * **Private Key**: value of the Private SSH Key (optional) * **Private Key Passphrase**: value of the Private SSH Key Passphrase (optional, only if required) * **Schema**: Target Schema for this environment [![Bigquery Deployment Credentials Settings](https://docs.getdbt.com/img/docs/collaborate/bigquery-deploy-env-deploy-credentials.png?v=2 "Bigquery Deployment Credentials Settings")](https://docs.getdbt.com/docs/deploy/deploy-environments#) Bigquery Deployment Credentials Settings #### Editable fields[​](https://docs.getdbt.com/docs/deploy/deploy-environments#editable-fields-5 "Direct link to Editable fields") * **Dataset**: Target dataset Use [extended attributes](https://docs.getdbt.com/docs/dbt-cloud-environments#extended-attributes) to override missing or inactive (grayed-out) settings. For credentials, we recommend wrapping extended attributes in [environment variables](https://docs.getdbt.com/docs/build/environment-variables) (`password: '{{ env_var(''DBT_ENV_SECRET_PASSWORD'') }}'`) to avoid displaying the secret value in the text box and the logs. [![Spark Deployment Credentials Settings](https://docs.getdbt.com/img/docs/collaborate/spark-deploy-env-deploy-credentials.png?v=2 "Spark Deployment Credentials Settings")](https://docs.getdbt.com/docs/deploy/deploy-environments#) Spark Deployment Credentials Settings #### Editable fields[​](https://docs.getdbt.com/docs/deploy/deploy-environments#editable-fields-6 "Direct link to Editable fields") * **Token**: Access token * **Schema**: Target schema [![Databricks Deployment Credentials Settings](https://docs.getdbt.com/img/docs/collaborate/spark-deploy-env-deploy-credentials.png?v=2 "Databricks Deployment Credentials Settings")](https://docs.getdbt.com/docs/deploy/deploy-environments#) Databricks Deployment Credentials Settings #### Editable fields[​](https://docs.getdbt.com/docs/deploy/deploy-environments#editable-fields-7 "Direct link to Editable fields") * **Token**: Access token * **Schema**: Target schema Delete an environment[​](https://docs.getdbt.com/docs/deploy/deploy-environments#delete-an-environment "Direct link to Delete an environment") ----------------------------------------------------------------------------------------------------------------------------------------------- Deleting an environment automatically deletes its associated job(s). If you want to keep those jobs, move them to a different environment first. Follow these steps to delete an environment in dbt: 1. Click **Deploy** on the navigation header and then click **Environments** 2. Select the environment you want to delete. 3. Click **Settings** on the top right of the page and then click **Edit**. 4. Scroll to the bottom of the page and click **Delete** to delete the environment. [![Delete an environment](https://docs.getdbt.com/img/docs/dbt-cloud/cloud-configuring-dbt-cloud/delete-environment.png?v=2 "Delete an environment")](https://docs.getdbt.com/docs/deploy/deploy-environments#) Delete an environment 5. Confirm your action in the pop-up by clicking **Confirm delete** in the bottom right to delete the environment immediately. This action cannot be undone. However, you can create a new environment with the same information if the deletion was made in error. 6. Refresh your page and the deleted environment should now be gone. To delete multiple environments, you'll need to perform these steps to delete each one. If you're having any issues, feel free to [contact us](mailto:support@getdbt.com) for additional help. Related docs[​](https://docs.getdbt.com/docs/deploy/deploy-environments#related-docs "Direct link to Related docs") -------------------------------------------------------------------------------------------------------------------- * [dbt environment best practices](https://docs.getdbt.com/guides/set-up-ci) * [Deploy jobs](https://docs.getdbt.com/docs/deploy/deploy-jobs) * [CI jobs](https://docs.getdbt.com/docs/deploy/continuous-integration) * [Delete a job or environment in dbt](https://docs.getdbt.com/faqs/Environments/delete-environment-job) Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Create a deployment environment](https://docs.getdbt.com/docs/deploy/deploy-environments#create-a-deployment-environment) * [Set as production environment](https://docs.getdbt.com/docs/deploy/deploy-environments#set-as-production-environment) * [Semantic Layer](https://docs.getdbt.com/docs/deploy/deploy-environments#semantic-layer) * [Staging environment](https://docs.getdbt.com/docs/deploy/deploy-environments#staging-environment) * [Git workflow](https://docs.getdbt.com/docs/deploy/deploy-environments#git-workflow) * [Why use a staging environment](https://docs.getdbt.com/docs/deploy/deploy-environments#why-use-a-staging-environment) * [Create a Staging environment](https://docs.getdbt.com/docs/deploy/deploy-environments#create-a-staging-environment) * [Deployment connection](https://docs.getdbt.com/docs/deploy/deploy-environments#deployment-connection) * [Deployment credentials](https://docs.getdbt.com/docs/deploy/deploy-environments#deployment-credentials) * [Delete an environment](https://docs.getdbt.com/docs/deploy/deploy-environments#delete-an-environment) * [Related docs](https://docs.getdbt.com/docs/deploy/deploy-environments#related-docs) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/deploy/deploy-environments.md) --- # Release tracks in dbt platform | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/dbt-versions/cloud-release-tracks#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page Since May 2024, new capabilities in the dbt framework are delivered continuously to dbt. Your projects and environments are upgraded automatically on a cadence that you choose, depending on your dbt plan. Previously, customers would pin to a minor version of dbt Core, and receive only patch updates during that specific version's active support period. Release tracks ensure that your project stays up-to-date with the modern capabilities of dbt and recent versions of dbt Core. This will require you to make one final update to your current jobs and environments. When that's done, you'll never have to think about managing, coordinating, or upgrading dbt versions again. By moving your environments and jobs to release tracks you can get all the functionality in dbt as soon as it's ready. On the "Latest" release track, this includes access to features _before_ they're available in final releases of dbt Core OSS. Which release tracks are available?[​](https://docs.getdbt.com/docs/dbt-versions/cloud-release-tracks#which-release-tracks-are-available "Direct link to Which release tracks are available?") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | Release track | Description | Plan availability | API value | | --- | --- | --- | --- | | **Latest** | Formerly called "Versionless", provides a continuous release of the latest functionality in the dbt platform.

Includes early access to new features of the dbt framework before they're available in open source releases of dbt Core. | All plans | `latest` (or `versionless`) | | **Compatible** | Provides a monthly release aligned with the most recent open source versions of dbt Core and adapters, plus functionality exclusively available in the dbt platform.

See [Compatible track changelog](https://docs.getdbt.com/docs/dbt-versions/compatible-track-changelog)
for more information. | Starter, Enterprise, Enterprise+ | `compatible` | | **Extended** | The previous month's "Compatible" release. | Enterprise, Enterprise+ | `extended` | To configure an environment in the [dbt Admin API](https://docs.getdbt.com/docs/dbt-cloud-apis/admin-cloud-api) or [Terraform](https://registry.terraform.io/providers/dbt-labs/dbtcloud/latest) to use a release track, set `dbt_version` to the release track name: * `latest` (or `versionless`, the old name is still supported) * `compatible` * `extended` Which release track should I choose?[​](https://docs.getdbt.com/docs/dbt-versions/cloud-release-tracks#which-release-track-should-i-choose "Direct link to Which release track should I choose?") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Choose the "Latest" release track to continuously receive new features, fixes, performance improvements — latest & greatest dbt. This is the default for all customers on dbt. Choose the "Compatible" and "Extended" release tracks if you need a less-frequent release cadence, the ability to test new dbt releases before they go live in production, and/or ongoing compatibility with the latest open source releases of dbt Core. ### Common architectures[​](https://docs.getdbt.com/docs/dbt-versions/cloud-release-tracks#common-architectures "Direct link to Common architectures") **Default** - Majority of customers on all plans * Prioritize immediate access to fixes and features * Leave all environments on the "Latest" release track (default configuration) **Hybrid** - Starter, Enterprise, Enterprise+ * Prioritize ongoing compatibility between dbt and dbt Core for development & deployment using both products in the same dbt projects * Configure all environments to use the "Compatible" release track * Understand that new features will not be available until they are first released in dbt Core OSS (several months after the "Latest" release track) **Cautious** - Enterprise, Enterprise+, Business Critical * Prioritize "bake in" time for new features & fixes * Configure development & test environments to use the "Compatible" release track * Configure pre-production & production environments to use the "Extended" release track * Understand that new features will not be available until _a month after_ they are first released in dbt Core OSS and the Compatible track. Developers (on "Compatible") will get access to new features before they can leverage those capabilities in production (on "Extended"), and must be mindful of the additional delay. **Virtual Private dbt or Single Tenant** * Changes to all release tracks roll out as part of dbt instance upgrades once per week Upgrading from older versions[​](https://docs.getdbt.com/docs/dbt-versions/cloud-release-tracks#upgrading-from-older-versions "Direct link to Upgrading from older versions") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ ### How to upgrade[​](https://docs.getdbt.com/docs/dbt-versions/cloud-release-tracks#upgrade-tips "Direct link to How to upgrade") If you regularly develop your dbt project in dbt, and you're still running on a legacy version of dbt Core, dbt Labs recommends that you try upgrading your project in a development environment. [Override your dbt version in development](https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-version-in-cloud#override-dbt-version) . Then, launch the Studio IDE or Cloud CLI and do your development work as usual. Everything should work as you expect. If you do see something unexpected or surprising, revert back to the previous version and record the differences you observed. [Contact dbt support](https://docs.getdbt.com/docs/dbt-support#dbt-cloud-support) with your findings for a more detailed investigation. Next, we recommend that you try upgrading your project’s [deployment environment](https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-version-in-cloud#environments) . If your project has a [staging deployment environment](https://docs.getdbt.com/docs/deploy/deploy-environments#staging-environment) , upgrade and try working with it for a few days before you proceed with upgrading the production environment. If your organization has multiple dbt projects, we recommend starting your upgrade with projects that are smaller, newer, or more familiar for your team. That way, if you do encounter any issues, it'll be easier and faster to troubleshoot those before proceeding to upgrade larger or more complex projects. ### Considerations[​](https://docs.getdbt.com/docs/dbt-versions/cloud-release-tracks#considerations "Direct link to Considerations") To learn more about how dbt Labs deploys stable dbt upgrades in a safe manner to dbt, we recommend that you read our blog post: [How we're making sure you can confidently switch to the "Latest" release track in dbt](https://docs.getdbt.com/blog/latest-dbt-stability) . If you're running dbt version 1.6 or older, please know that your version of dbt Core has reached [end-of-life (EOL)](https://docs.getdbt.com/docs/dbt-versions/core#eol-version-support) and is no longer supported. We strongly recommend that you update to a newer version as soon as reasonably possible. dbt Labs has extended the critical support period of dbt Core v1.7 for dbt Enterprise-tier customers to March 2025. At that point, we will be encouraging all customers to select a Release Track for ongoing updates in dbt.  I'm using an older version of dbt in the dbt platform. What should I do? What happens if I do nothing? If you're running dbt version v1.6 or older, please know that your version of dbt Core has reached [end-of-life (EOL)](https://docs.getdbt.com/docs/dbt-versions/core#eol-version-support) and is no longer supported. We strongly recommend that you update to a newer version as soon as reasonably possible. dbt Labs has extended the "Critical Support" period of dbt Core v1.7 for dbt Enterprise-tier customers while we work through the migration with those customers to Release Tracks. In the meantime, this means that v1.7 will continue to be accessible in dbt for Enteprise customers, jobs and environments on v1.7 for those customers will not be automatically migrated to "Latest," and dbt Labs will continue to fix critical bugs and security issues. Starting in October 2024, dbt accounts on the Developer and Starter (formerly Teams) plans have been migrated to release tracks from older dbt Core versions. If your account was migrated to the "Latest" release track and you notice new failures in scheduled jobs, please [contact dbt support](https://docs.getdbt.com/docs/dbt-support#dbt-cloud-support) to report the problem or request an extension. I'm using the legacy metrics definitions from dbt Core version ≤1.5. What should I do? The legacy dbt Semantic Layer was deprecated in the second half of 2023. We recommend that you refer to the [Legacy dbt Semantic Layer migration guide](https://docs.getdbt.com/guides/sl-migration?step=1) for more information. What are other known issues when upgrading from older dbt Core versions? If you are upgrading from a very old unsupported version of dbt Core, you may run into one of these edge cases after the upgrade to a newer version: * \[v1.1\] Customers on BigQuery should be aware that dbt sets a default [per-model timeout](https://docs.getdbt.com/docs/core/connect-data-platform/bigquery-setup#job_execution_timeout_seconds) of 5 minutes. You may override this config in your connection details. Older versions of dbt (including v1.0) did not appropriately respect this timeout configuration. * \[v1.3\] Customers with non-dbt `.py` files defined within their project directories, such as `models/`. Since v1.3, dbt expects these files be valid [Python models](https://docs.getdbt.com/docs/build/python-models) . The customer needs to move these files out of their `models/` directory, or ignore them via `.dbtignore` * \[v1.5\] Customers who have `--m` in their job definitions, instead of `-m` or `--models`. This autocompletion (`--m[odels]` for `--models`) has never been officially documented or supported. It was an implicit behavior of argparse (CLI library used in dbt-core v1.0-1.4) that is not supported by `click` (the CLI library used in dbt-core since v1.5+). * \[v1.5\] Empty invalid `tests` config start raising a validation error\](/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.5). Replace empty `tests` config with `tests: []` or remove it altogether. * \[v1.6\] Performance optimization to `load_result` means you cannot call it on the same query result multiple times. Instead, save it to a local variable once, and reuse that variable (context: [dbt-core#7371](https://github.com/dbt-labs/dbt-core/pull/7371) You should [contact dbt support](https://docs.getdbt.com/docs/dbt-support#dbt-cloud-support) to request an extension, during which you will need to make those updates. I see that my account was migrated to Latest. What should I do? For the vast majority of customers, there is no further action needed. If you see new failures in your scheduled jobs now that they are running on a newer version of dbt, you may need to update your project code to account for one of the edge cases described on this page. You should [contact dbt support](https://docs.getdbt.com/docs/dbt-support#dbt-cloud-support) to request an extension, during which you will need to make those updates. What about breaking changes to packages (maintained by dbt Labs or by others)? When we talk about _latest version_, we’re referring to the underlying runtime for dbt, not the versions of packages you’re installing. Our continuous release for dbt includes testing against several popular dbt packages. This ensures that updates we make to dbt-core, adapters, or anywhere else are compatible with the code in those packages. If a new version of a dbt package includes a breaking change (for example, a change to one of the macros in `dbt_utils`), you don’t have to immediately use the new version. In your `packages` configuration (in `dependencies.yml` or `packages.yml`), you can still specify which versions or version ranges of packages you want dbt to install. If you're not already doing so, we strongly recommend [checking `package-lock.yml` into version control](https://docs.getdbt.com/reference/commands/deps#predictable-package-installs) for predictable package installs in deployment environments and a clear change history whenever you install upgrades. If you upgrade to the "Latest" release track, and immediately see something that breaks, please [contact support](https://docs.getdbt.com/docs/dbt-support#dbt-cloud-support) and, in the meantime, downgrade back to v1.7. If you’re already on the "Latest" release track, and you observe a breaking change (like something worked yesterday, but today it isn't working, or works in a surprising/different way), please [contact support](https://docs.getdbt.com/docs/dbt-support#dbt-cloud-support) immediately. Depending on your contracted support agreement, the dbt Labs team will respond within our SLA time and we would seek to roll back the change and/or roll out a fix (just as we would for any other part of dbt). This is the same whether or not the root cause of the breaking change is in the project code or in the code of a package. If the package you’ve installed relies on _undocumented_ functionality of dbt, it doesn't have the same guarantees as functionality that we’ve documented and tested. However, we will still do our best to avoid breaking them. I see that dbt Core version 1.8 was released in April 2024. Will a version 1.8 become available in the dbt platform? No. Going forward, customers will access new functionality and ongoing support in dbt by receiving automatic updates. We believe this is the best way for us to offer a reliable, stable, and secure runtime for dbt, and for you as dbt users to be able to consistently take advantage of new features. In 2023 (and earlier), customers were expected to manage their own upgrades by selecting dbt Core versions, up to and including dbt Core v1.7, which was released in October 2023. (Way back in 2021, dbt customers would pick specific _patch releases_ of dbt Core, such as upgrading from `v0.21.0` to `v0.21.1`. We’ve come a long way since then!) In 2024, we've changed the way that new dbt functionality is made available for dbt customers. Behavior or breaking changes are gated behind opt-in flags. Users don't need to spend valuable time managing their own upgrades. Currently, it is possible to receive continuous (daily) updates. We are adding other release cadence options for managed customers of dbt by the end of the year. Opting into a release cadence with automated upgrades is required for accessing any new functionality that we've released in 2024, and going forward. We continue to release new minor versions of dbt Core (OSS). We most recently released dbt Core v1.9 on December 9, 2024. These releases always include a subset of the functionality that's already available to the dbt platform customers, and always after the functionality has been available in the dbt platform. If you have comments or concerns, we’re happy to help. If you’re an existing dbt customer, you may reach out to your account team or [contact support](https://docs.getdbt.com/docs/dbt-support#dbt-cloud-support) . Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Which release tracks are available?](https://docs.getdbt.com/docs/dbt-versions/cloud-release-tracks#which-release-tracks-are-available) * [Which release track should I choose?](https://docs.getdbt.com/docs/dbt-versions/cloud-release-tracks#which-release-track-should-i-choose) * [Common architectures](https://docs.getdbt.com/docs/dbt-versions/cloud-release-tracks#common-architectures) * [Upgrading from older versions](https://docs.getdbt.com/docs/dbt-versions/cloud-release-tracks#upgrading-from-older-versions) * [How to upgrade](https://docs.getdbt.com/docs/dbt-versions/cloud-release-tracks#upgrade-tips) * [Considerations](https://docs.getdbt.com/docs/dbt-versions/cloud-release-tracks#considerations) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/dbt-versions/cloud-release-tracks.md) --- # Install the dbt VS Code extension | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/install-dbt-extension#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page The dbt extension for VS Code and Cursor streamlines dbt development workflows. The dbt extension is powered by the dbt Fusion Engine. Prerequisites[​](https://docs.getdbt.com/docs/install-dbt-extension#prerequisites "Direct link to Prerequisites") ------------------------------------------------------------------------------------------------------------------ To use the extension, you must meet the following prerequisites: * The dbt extension requires installation of the dbt Fusion Engine. Fusion installation is part of the extension installation process, but you can also [manually install](https://docs.getdbt.com/docs/fusion/install-fusion) separate from this workflow, either before or after the extension is installed. * You are using the [VS Code](https://code.visualstudio.com/) or [Cursor](https://www.cursor.com/en) code editor. * You are not using (or have disabled) third-party dbt extensions. * You are using a macOS or Linux-based computer. Installation instructions[​](https://docs.getdbt.com/docs/install-dbt-extension#installation-instructions "Direct link to Installation instructions") ------------------------------------------------------------------------------------------------------------------------------------------------------ note This is the only official dbt Labs VS Code extension. Please disable or uninstall any third-party dbt extensions before installing to avoid issues. Read the [Fusion Diaries](https://github.com/dbt-labs/dbt-fusion/discussions/categories/announcements) for the latest updates. In VS Code: 1. Navigate to the **Extensions** tab of your editor and search for `dbt`. Locate the extension from the publisher `dbtLabsInc` or `dbt Labs Inc`. Click **Install**. [![Search for the extension](https://docs.getdbt.com/img/docs/extension/extension-marketplace.png?v=2 "Search for the extension")](https://docs.getdbt.com/docs/install-dbt-extension#) Search for the extension 2. Open a dbt project in your VS Code environment if you haven't already. Make sure it is added to your current workspace. If you see a **dbt Extension** label in your editor's status bar, then the extension has installed successfully. You can hover over this **dbt Extension** label to see diagnostic information about the extension. [![If you see the 'dbt Extension` label, the extension is activated](https://docs.getdbt.com/img/docs/extension/dbt-extension-statusbar.png?v=2 "If you see the 'dbt Extension` label, the extension is activated")](https://docs.getdbt.com/docs/install-dbt-extension#) If you see the 'dbt Extension\` label, the extension is activated 3. Once the dbt extension is activated, it will automatically begin downloading the correct dbt Language Server for your operating system. [![The dbt Language Server will be installed automatically](https://docs.getdbt.com/img/docs/extension/extension-lsp-download.png?v=2 "The dbt Language Server will be installed automatically")](https://docs.getdbt.com/docs/install-dbt-extension#) The dbt Language Server will be installed automatically 4. If the dbt Fusion engine is not already installed on your machine, the extension will prompt you to download and install it. Follow the steps shown in the notification to complete the installation. [![Follow the prompt to install the dbt Fusion engine](https://docs.getdbt.com/img/docs/extension/install-dbt-fusion-engine.png?v=2 "Follow the prompt to install the dbt Fusion engine")](https://docs.getdbt.com/docs/install-dbt-extension#) Follow the prompt to install the dbt Fusion engine 5. Run the VS Code extension [upgrade tool](https://docs.getdbt.com/docs/install-dbt-extension#upgrade-to-fusion) to ensure your dbt project is Fusion ready and help you fix any errors and deprecations. 6. You're all set up! See [about the dbt extension](https://docs.getdbt.com/docs/about-dbt-extension) for more information on how to use the dbt extension. [![Showing lineage and compiled code in the extension](https://docs.getdbt.com/img/docs/extension/kitchen-sink.png?v=2 "Showing lineage and compiled code in the extension")](https://docs.getdbt.com/docs/install-dbt-extension#) Showing lineage and compiled code in the extension Upgrade to Fusion[​](https://docs.getdbt.com/docs/install-dbt-extension#upgrade-to-fusion "Direct link to Upgrade to Fusion") ------------------------------------------------------------------------------------------------------------------------------ note If you are already running the dbt Fusion Engine, you must be on version `2.0.0-beta.66` or higher to use the upgrade tool. The dbt extension provides a built-in upgrade tool to walk you through the process of configuring Fusion and updating your dbt project to support all of its features and fix any deprecated code. To start the process: 1. From the VS Code left-side menu, click the **dbt logo**. 2. In the resulting pane, open the **Get started** section and click the **Get started** button. [![The dbt extension help pane and upgrade assistant.](https://docs.getdbt.com/img/docs/extension/fusion-onboarding-experience.png?v=2 "The dbt extension help pane and upgrade assistant.")](https://docs.getdbt.com/docs/install-dbt-extension#) The dbt extension help pane and upgrade assistant. You can also manually start this process by opening a CLI window and running: dbt init --fusion-upgrade This will start the upgrade tool and guide you through the Fusion upgrade with a series of prompts: * **Do you have an existing dbt platform account?**: If you answer `Y`, you will be given instructions for downloading your dbt platform profile to register the extension. An `N` answer will skip to the next step. * **Ready to run a dbtf init?** (If there is no `profiles.yml` file present): You will go through the dbt configuration processes, including connecting to your data warehouse. * **Ready to run a dbtf debug?** (If there is an existing `profiles.yml` file): Validates that your project is configured correctly and can connect to your data warehouse. * **Ready to run a dbtf parse?**: Your dbt project will be parsed to check for compatibility with Fusion. * If any issues are encountered during the parsing, you'll be given the option to run the [dbt-autofix](https://github.com/dbt-labs/dbt-autofix?tab=readme-ov-file#installation) tool to resolve the errors. If you opt to not run the tool during the upgrade processes, you can always run it later or manually fix any errors. However, the upgrade tool cannot continue until the errors are resolved. * **Ready to run a ‘dbtf compile -static-analysis off’?** (Only runs once the parse passes): Compiles your project without any static analysis, mimicking dbt Core. This compile only renders Jinja into SQL, so Fusion's advanced SQL comprehension is temporarily disabled. * **Ready to run a ‘dbtf compile’?**: Compiles your project with full Fusion static analysis. It checks that your SQL code is valid in the context of your warehouse's tables and columns. [![The message received when you have completed upgrading your project to the dbt Fusion engine.](https://docs.getdbt.com/img/docs/extension/fusion-onboarding-complete.png?v=2 "The message received when you have completed upgrading your project to the dbt Fusion engine.")](https://docs.getdbt.com/docs/install-dbt-extension#) The message received when you have completed upgrading your project to the dbt Fusion engine. Once the upgrade is completed, you're ready to dive into all the features that the dbt Fusion Engine has to offer! Register the extension[​](https://docs.getdbt.com/docs/install-dbt-extension#register-the-extension "Direct link to Register the extension") --------------------------------------------------------------------------------------------------------------------------------------------- Users must complete registration within 14 days of installing the dbt extension. There are two ways to register: * Users without an existing dbt account can register quickly and easily through an online registration form. For the initial installation, you only need to provide your name and email address to complete the registration. Subsequent installations will require you to complete the entire [dbt account registration process](https://docs.getdbt.com/docs/install-dbt-extension#accessing-your-dbt-account) to use the extension. * Users with an existing dbt account can connect their account using a `dbt_cloud.yml` credentials file. The VS Code extension is free for organizations for up to 15 users. ### New user registration[​](https://docs.getdbt.com/docs/install-dbt-extension#new-user-registration "Direct link to New user registration") If you do not already have a dbt account, you'll need to get registered. This only takes a minute! 1. Click the registration prompt in your editor. [![The extension registration prompt in VS Code.](https://docs.getdbt.com/img/docs/extension/registration-prompt.png?v=2 "The extension registration prompt in VS Code.")](https://docs.getdbt.com/docs/install-dbt-extension#) The extension registration prompt in VS Code. 2. Accept any prompts to open the link in your browser. 3. Fill out the registration form, then click **Continue**. [![The extension registration page in the browser.](https://docs.getdbt.com/img/docs/extension/registration-screen.png?v=2 "The extension registration page in the browser.")](https://docs.getdbt.com/docs/install-dbt-extension#) The extension registration page in the browser. 4. You will receive an email with a verification link. Once you click it, your registration is complete! ### Accessing your dbt account[​](https://docs.getdbt.com/docs/install-dbt-extension#accessing-your-dbt-account "Direct link to Accessing your dbt account") Registering to use the dbt extension makes it easy to create a full dbt account. You can follow these steps to finish setting up your account (_Note: This is not required to use the dbt extension_). 1. Navigate to [us1.dbt.com](https://us1.dbt.com/) and click **Forgot password?**. 2. Enter the email address you used for your dbt extension registration and click **Continue**. 3. Check your email for a verification link and follow the password reset instructions to set a password for your account. Now that you have activated your dbt developer account, you can access features of the dbt platform. You can also re-download your registration key using the steps outlined in [Register with an existing dbt account](https://docs.getdbt.com/docs/install-dbt-extension#register-with-an-existing-dbt-account) if you need to set up the dbt extension on a new machine. ### Register with an existing dbt account[​](https://docs.getdbt.com/docs/install-dbt-extension#register-with-an-existing-dbt-account "Direct link to Register with an existing dbt account") If you already have a dbt account, you do not need to re-register to use the dbt extension. The dbt extension can authenticate with the dbt platform using a `dbt_cloud.yml` file. If this file is present in your `~/.dbt/` folder, then the registration flow will automatically attempt to use this file during registration. If you do not have a `~/.dbt/dbt_cloud.yml` file downloaded, refer to the following instructions:  For dbt accounts with Fusion enabled 1. Log in to your dbt account. 2. Click your account name at the bottom of the left-side menu and click **Account settings**. 3. Under the **Your profile** section, click **VS Code Extension**. 4. In the **Set up your credentials** section, click **Download credentials**. This downloads the `dbt_cloud.yml` file. [![Download the dbt_cloud.yml file to complete registration.](https://docs.getdbt.com/img/docs/extension/download-registration-2.png?v=2 "Download the dbt_cloud.yml file to complete registration.")](https://docs.getdbt.com/docs/install-dbt-extension#) Download the dbt\_cloud.yml file to complete registration. 5. Move the downloaded `dbt_cloud.yml` file to your `~/.dbt/` directory. 6. To update your registration in VS Code, open the command palette (`ctrl+shift+P` (Linux) or `cmd+shift+p` (macOS)), then select `dbt: Register dbt extension` to complete the registration. For dbt accounts without Fusion enabled 1. Log in to your dbt account. 2. Click your account name at the bottom of the left-side menu and click **Account settings**. 3. Under the **Your profile** section, click **CLI**. 4. In the **Configure Cloud authentication** section, click **Download CLI configuration file**. This downloads the `dbt_cloud.yml` file. [![Download the dbt_cloud.yml file to complete registration.](https://docs.getdbt.com/img/docs/extension/download-registration.png?v=2 "Download the dbt_cloud.yml file to complete registration.")](https://docs.getdbt.com/docs/install-dbt-extension#) Download the dbt\_cloud.yml file to complete registration. 5. Move the downloaded `dbt_cloud.yml` file to your `~/.dbt/` directory. 6. To update your registration in VS Code, open the command palette (`ctrl+shift+P` (Linux) or `cmd+shift+p` (macOS)), then select `dbt: Register dbt extension` to complete the registration. Troubleshooting[​](https://docs.getdbt.com/docs/install-dbt-extension#troubleshooting "Direct link to Troubleshooting") ------------------------------------------------------------------------------------------------------------------------ #### dbt platform configurations[​](https://docs.getdbt.com/docs/install-dbt-extension#dbt-platform-configurations "Direct link to dbt platform configurations") If you're a cloud-based dbt platform user who has the `dbt-cloud:` config in the `dbt_project.yml` file and are also using [dbt Mesh](https://docs.getdbt.com/docs/mesh/about-mesh) , you must have the project ID configured: dbt-cloud: project-id: 12345 # Required If you don’t configure this correctly, cross-platform references will not resolve properly, and you will encounter errors executing dbt commands. #### General troubleshooting tips[​](https://docs.getdbt.com/docs/install-dbt-extension#general-troubleshooting-tips "Direct link to General troubleshooting tips") If the dbt extension has activated successfully, you will see the `dbt Extension` label in the status bar at the bottom left of your editor. You can view diagnostic information about the dbt extension by clicking the **dbt Extension** button. If the dbt extension label is not present, then it is likely that the dbt extension was not installed successfully. If this happens, try uninstalling the extension, restarting your editor, and then reinstalling the extension. Note: It is possible to "hide" status bar items in VS Code. Double-check if the **dbt Extension** status bar label is hidden by right-clicking on the status bar in your editor. If you see **dbt Extension** in the right-click menu, then the extension has installed successfully. #### Missing dbt LSP features[​](https://docs.getdbt.com/docs/install-dbt-extension#missing-dbt-lsp-features "Direct link to Missing dbt LSP features") If you are not seeing dbt LSP features in your editor, first consult the general troubleshooting steps above. If you have confirmed that the dbt extension is installed correctly, but you still do not see dbt Language Server features (for example, autocomplete, go-to-definition, hover text): * Check the version of your dbt extension on the extensions page in your editor. Ensure that you are using the latest available version of the dbt extension. * Try reinstalling the dbt Language Server by pressing `cmd+shift+P` (macOS) or `ctrl+shift+P` (Linux) and selecting the `dbt: Reinstall dbt LSP` command. #### Unsupported dbt version[​](https://docs.getdbt.com/docs/install-dbt-extension#unsupported-dbt-version "Direct link to Unsupported dbt version") If you see an error message indicating that your version of dbt is unsupported, then there is likely a problem with your environment. * Check the **dbt Path** setting in your VS Code settings. If this path is set, ensure that it is pointing to a valid dbt Fusion Engine executable. * If necessary, you can also install the dbt Fusion Engine directly using these instructions: [Install the Fusion CLI](https://docs.getdbt.com/docs/fusion/install-fusion) . More information about Fusion[​](https://docs.getdbt.com/docs/install-dbt-extension#more-information-about-fusion "Direct link to More information about Fusion") ------------------------------------------------------------------------------------------------------------------------------------------------------------------ Fusion marks a significant update to dbt. While many of the workflows you've grown accustomed to remain unchanged, there are a lot of new ideas, and a lot of old ones going away. The following is a list of the full scope of our current release of the Fusion engine, including implementation, installation, deprecations, and limitations: * [About the dbt Fusion engine](https://docs.getdbt.com/docs/fusion/about-fusion) * [About the dbt extension](https://docs.getdbt.com/docs/about-dbt-extension) * [New concepts in Fusion](https://docs.getdbt.com/docs/fusion/new-concepts) * [Supported features matrix](https://docs.getdbt.com/docs/fusion/supported-features) * [Installing Fusion CLI](https://docs.getdbt.com/docs/fusion/install-fusion) * [Installing VS Code extension](https://docs.getdbt.com/docs/install-dbt-extension) * [Fusion release track](https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-version-in-cloud#dbt-fusion-engine) * [Quickstart for Fusion](https://docs.getdbt.com/guides/fusion?step=1) * [Upgrade guide](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-fusion) * [Fusion licensing](http://www.getdbt.com/licenses-faq) Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Prerequisites](https://docs.getdbt.com/docs/install-dbt-extension#prerequisites) * [Installation instructions](https://docs.getdbt.com/docs/install-dbt-extension#installation-instructions) * [Upgrade to Fusion](https://docs.getdbt.com/docs/install-dbt-extension#upgrade-to-fusion) * [Register the extension](https://docs.getdbt.com/docs/install-dbt-extension#register-the-extension) * [New user registration](https://docs.getdbt.com/docs/install-dbt-extension#new-user-registration) * [Accessing your dbt account](https://docs.getdbt.com/docs/install-dbt-extension#accessing-your-dbt-account) * [Register with an existing dbt account](https://docs.getdbt.com/docs/install-dbt-extension#register-with-an-existing-dbt-account) * [Troubleshooting](https://docs.getdbt.com/docs/install-dbt-extension#troubleshooting) * [More information about Fusion](https://docs.getdbt.com/docs/install-dbt-extension#more-information-about-fusion) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/install-dbt-extension.md) --- # Run your dbt projects | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/running-a-dbt-project/run-your-dbt-projects#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page You can run your dbt projects with [dbt](https://docs.getdbt.com/docs/cloud/about-cloud/dbt-cloud-features) or [dbt Core](https://github.com/dbt-labs/dbt-core) : * **dbt**: A hosted application where you can develop directly from a web browser using the [Studio IDE](https://docs.getdbt.com/docs/cloud/dbt-cloud-ide/develop-in-the-cloud) . It also natively supports developing using a command line interface, [dbt CLI](https://docs.getdbt.com/docs/cloud/cloud-cli-installation) . Among other features, dbt provides: * Development environment to help you build, test, run, and [version control](https://docs.getdbt.com/docs/cloud/git/git-version-control) your project faster. * Share your [dbt project's documentation](https://docs.getdbt.com/docs/build/documentation) with your team. * Integrates with the Studio IDE, allowing you to run development tasks and environment in the dbt UI for a seamless experience. * The dbt CLI to develop and run dbt commands against your dbt development environment from your local command line. * For more details, refer to [Develop dbt](https://docs.getdbt.com/docs/cloud/about-develop-dbt) . * **dbt Core**: An open source project where you can develop from the [command line](https://docs.getdbt.com/docs/core/installation-overview) . The dbt CLI and dbt Core are both command line tools that enable you to run dbt commands. The key distinction is the dbt CLI is tailored for dbt's infrastructure and integrates with all its [features](https://docs.getdbt.com/docs/cloud/about-cloud/dbt-cloud-features) . The command line is available from your computer's terminal application such as Terminal and iTerm. With the command line, you can run commands and do other work from the current working directory on your computer. Before running the dbt project from the command line, make sure you are working in your dbt project directory. Learning terminal commands such as `cd` (change directory), `ls` (list directory contents), and `pwd` (present working directory) can help you navigate the directory structure on your system. In dbt or dbt Core, the commands you commonly use are: * [dbt run](https://docs.getdbt.com/reference/commands/run) — Runs the models you defined in your project * [dbt build](https://docs.getdbt.com/reference/commands/build) — Builds and tests your selected resources such as models, seeds, snapshots, and tests * [dbt test](https://docs.getdbt.com/reference/commands/test) — Executes the tests you defined for your project For information on all dbt commands and their arguments (flags), see the [dbt command reference](https://docs.getdbt.com/reference/dbt-commands) . If you want to list all dbt commands from the command line, run `dbt --help`. To list a dbt command’s specific arguments, run `dbt COMMAND_NAME --help` . Related docs[​](https://docs.getdbt.com/docs/running-a-dbt-project/run-your-dbt-projects#related-docs "Direct link to Related docs") ------------------------------------------------------------------------------------------------------------------------------------- * [How we set up our computers for working on dbt projects](https://discourse.getdbt.com/t/how-we-set-up-our-computers-for-working-on-dbt-projects/243) * [Model selection syntax](https://docs.getdbt.com/reference/node-selection/syntax) * [dbt CLI](https://docs.getdbt.com/docs/cloud/cloud-cli-installation) * [Cloud Studio IDE features](https://docs.getdbt.com/docs/cloud/dbt-cloud-ide/develop-in-the-cloud#ide-features) * [Does dbt offer extract and load functionality?](https://docs.getdbt.com/faqs/Project/transformation-tool) * [Why does dbt compile need a data platform connection](https://docs.getdbt.com/faqs/Warehouse/db-connection-dbt-compile) Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Related docs](https://docs.getdbt.com/docs/running-a-dbt-project/run-your-dbt-projects#related-docs) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/running-a-dbt-project/run-your-dbt-projects.md) --- # dbt Semantic Layer FAQs | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/use-dbt-semantic-layer/sl-faqs#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page The [Semantic Layer](https://docs.getdbt.com/docs/use-dbt-semantic-layer/dbt-sl) is a dbt offering that allows users to centrally define their metrics within their dbt project using [MetricFlow](https://docs.getdbt.com/docs/build/about-metricflow) . The Semantic Layer offers: * Dynamic SQL generation to compute metrics * APIs to query metrics and dimensions * First-class [integrations](https://docs.getdbt.com/docs/cloud-integrations/avail-sl-integrations) to query those centralized metrics in downstream tools The Semantic Layer is powered by MetricFlow, which is a source-available component. Overview of the dbt Semantic Layer[​](https://docs.getdbt.com/docs/use-dbt-semantic-layer/sl-faqs#overview-of-the-dbt-semantic-layer "Direct link to Overview of the dbt Semantic Layer") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------  What are the main benefits of using the dbt Semantic Layer? The primary value of the dbt Semantic Layer is to centralize and bring consistency to your metrics across your organization. Additionally, it allows you to: * **Meet your users where they are** by being agnostic to where your end users consume data through the supporting of different APIs for integrations. * **Optimize costs** by spending less time preparing data for consumption. * **Simplify your code** by not duplicating metric logic and allowing MetricFlow to perform complex calculations for you. * **Empower stakeholders** with rich context and flexible, yet governed experiences. [![This diagram shows how the dbt Semantic Layer works with your data stack.](https://docs.getdbt.com/img/docs/dbt-cloud/semantic-layer/sl-concept.png?v=2 "This diagram shows how the dbt Semantic Layer works with your data stack.")](https://docs.getdbt.com/docs/use-dbt-semantic-layer/sl-faqs#) This diagram shows how the dbt Semantic Layer works with your data stack. What's the main difference between the dbt Semantic Layer and dbt Metrics? dbt Metrics is the now-deprecated dbt package that was used to define metrics within dbt. dbt Metrics has been replaced with [MetricFlow](https://docs.getdbt.com/docs/build/about-metricflow) , a more flexible and powerful engine, which powers the foundation of the dbt Semantic Layer today. MetricFlow introduces SQL generation to the dbt Semantic Layer and offers more advanced capabilities than dbt Metrics, for example: * **Query construction** — MetricFlow iteratively constructs queries using a dataflow plan, our internal DAG for generating SQL. By comparison, dbt Metrics relied on templated Jinja to construct SQL. * **Joins** — MetricFlow also has a sophisticated way of handling joins, which dbt Metrics did not support. With MetricFlow you can effortlessly access all valid dimensions for your metrics on the fly, even when they are defined in different semantic models. Is there a dbt Semantic Layer discussion hub? Yes, absolutely! Join the [dbt Slack community](https://app.slack.com/client/T0VLPD22H)  and [#dbt-cloud-semantic-layer](https://getdbt.slack.com/archives/C046L0VTVR6) slack channel for all things related to the dbt Semantic Layer. How does the dbt Semantic Layer fit with different modeling approaches (Medallion, Data Vault, Dimensional modeling)? The dbt Semantic Layer is flexible enough to work with many common modeling approaches. It references dbt models, which means how you configure your Semantic Layer will mirror the modeling approach you've taken with the underlying data. The primary consideration is the flexibility and performance of the underlying queries. For example: * A star schema data model offers more flexibility for dimensions that are available for a given metric, but will require more joins. * A fully denormalized data model is simpler, will be materialized to a specific grain, but won’t be able to join to other tables. While the dbt Semantic Layer will work for both cases, it's best to allow MetricFlow do handle some level of denormalization for you in order to provide more flexibility to metric consumers. How is the dbt Semantic Layer priced? The dbt Semantic Layer measures usage in distinct 'Queried Metrics'. Refer to the [Billing](https://docs.getdbt.com/docs/cloud/billing#what-counts-as-a-queried-metric) to learn more about pricing. Availability[​](https://docs.getdbt.com/docs/use-dbt-semantic-layer/sl-faqs#availability "Direct link to Availability") ------------------------------------------------------------------------------------------------------------------------  What data platforms are supported by the dbt Semantic Layer? The dbt Semantic Layer supports the following data platforms: * Snowflake * BigQuery * Databricks * Redshift * Postgres * Trino Support for other data platforms, such as Fabric, isn't available at this time. If you're interested in using the dbt Semantic Layer with a data platform not on the list, please [contact us](https://www.getdbt.com/get-started) . Do I need to be on a specific version of dbt to use dbt Semantic Layer? Yes, the dbt Semantic Layer is compatible with [dbt v1.6 or higher](https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-version-in-cloud) . Does dbt Semantic Layer require a specific dbt plan? Yes, dbt [Starter, Enterprise, or Enterprise+](https://www.getdbt.com/pricing) plan customers can access the dbt Semantic Layer. Certain features like caching and using multiple credentials are available for Enterprise and Enterprise+ plans. Is there a way to leverage dbt Semantic Layer capabilities in dbt Core? The dbt Semantic Layer is proprietary to dbt, however some components of it are open-source. dbt Core users can use MetricFlow features, like defining metrics in their projects, without a dbt plan. dbt Core users can also query their semantic layer locally using the command line. However, they won't be able to use the [APIs](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-api-overview) or [available integrations](https://docs.getdbt.com/docs/cloud-integrations/avail-sl-integrations) to access metrics dynamically. Is there a solution or licensing path for an organization that doesn't use dbt for pipelining, but might like to implement the dbt Semantic Layer? If you're interested in the this type of implementation, please reach out to us [here](https://www.getdbt.com/get-started) . How does the dbt Semantic Layer work?[​](https://docs.getdbt.com/docs/use-dbt-semantic-layer/sl-faqs#how-does-the-dbt-semantic-layer-work "Direct link to How does the dbt Semantic Layer work?") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------  Why is the dbt Semantic Layer better than using tables or dbt models to calculate metrics? You can use tables and dbt models to calculate metrics as an option, but it's a static approach that is rigid and cumbersome to maintain. That’s because metrics are seldom useful on their own: they usually need dimensions, grains, and attributes for business users to analyze (or slice and dice) data effectively. If you create a table with a metric, you’ll need to create numerous other tables derived from that table to show the desired metric cut by the desired dimension or time grain. Mature data models have thousands of dimensions, so you can see how this will quickly result in unnecessary duplication, maintenance, and costs. It's also incredibly hard to predict all the slices of data that a user is going to need ahead of time. With the dbt Semantic Layer, you don’t need to pre-join or build any tables; rather, you can simply add a few lines of code to your semantic model, and that data will only be computed upon request. [![This diagram shows how the dbt Semantic Layer works with your data stack.](https://docs.getdbt.com/img/docs/dbt-cloud/semantic-layer/sl-concept.png?v=2 "This diagram shows how the dbt Semantic Layer works with your data stack.")](https://docs.getdbt.com/docs/use-dbt-semantic-layer/sl-faqs#) This diagram shows how the dbt Semantic Layer works with your data stack. Do I materialize anything when I define a semantic model? No, you don't. When querying the dbt Semantic Layer through the [Semantic Layer APIs](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-api-overview) , you're not materializing any data by default. The dbt Semantic Layer dynamically computes the metric using the underlying data tables. Then it returns the output to the end user. Is the dbt Semantic Layer a physical copy of your data stored on your data warehouse? The dbt Semantic Layer does not store a physical copy of your data. It uses underlying tables to construct or compute the requested output. How does the Semantic Layer handle data? The dbt Semantic Layer is part of the dbt platform. It allows data teams to define metrics once, centrally, and access them from any integrated analytics tool, ensuring consistent answers across diverse datasets. In providing this service, dbt Labs permits clients to access Semantic Layer metrics. Client data passes through the Semantic Layer on the way back from the data warehouse. dbt Labs handles this in a secure way using encryption and authentication from the client’s data warehouse. In certain cases, such data may be cached on dbt Labs system ephemerally (data is not persistently stored). dbt Labs employees cannot access cached data during normal business operations and must have a business need and/or direct manager approval for access to the underlying infrastructure. Access would only be when necessary for providing a client services and never with the purpose of enriching dbt Labs. No client warehouse data is retained on dbt Labs's systems. We offer a caching solution to optimize query performance. The caching feature uses client data warehouse storage rather than being stored on dbt Labs’s systems. In addition, this feature is activated only through a client opt-in. Therefore, caching is always in client hands and at client discretion Does our agreement, the Terms of Service (ToS) for dbt, apply to the Semantic Layer? Yes it does. Where is MetricFlow hosted? How do queries pass through MetricFlow and dbt and back to the end user? MetricFlow is hosted in dbt. Requests from the [Semantic Layer APIs](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-api-overview) are routed from our API gateway to MetricFlow, which generates the SQL to compute what's requested by the user. MetricFlow hands the SQL back to our gateway, which then executes it against the data platform. How do I configure the dbt Semantic Layer? 1. You define [semantic models](https://docs.getdbt.com/docs/build/semantic-models) in YAML files that describe your data, including entities (for joins), measures (with aggregation types as a building block to your metrics), and dimensions (to slice and dice your metrics). 2. Then you build your metrics on top of these semantic models. This is all done in `.yml` configurations alongside your dbt models in your projects. 3. Once you've defined your metrics and semantic models, you can [configure the dbt Semantic Layer](https://docs.getdbt.com/docs/use-dbt-semantic-layer/setup-sl) in dbt. Read our [dbt Semantic Layer quickstart](https://docs.getdbt.com/guides/sl-snowflake-qs) guide for more information. How does caching work in the dbt Semantic Layer? Beginning in March 2024, the dbt Semantic Layer will offer two layers of caching: * The result cache, which caches query results in the data platform so that subsequent runs of the same query are faster. * A declarative cache which also lives in your data platform. Does the dbt Semantic Layer expect all models to be in normalized format? No, the dbt Semantic Layer is flexible enough to work with many data modeling approaches including Snowflake, Star schemas, Data vaults, or other normalized tables. How are queries optimized to not scan more data than they should? MetricFlow always tries to generate SQL in the most performant way, while ensuring the metric value is correct. It generates SQL in a way that allows us to add optimizations, like predicate pushdown, to ensure we don’t perform full table scans. What are the latency considerations of using the dbt Semantic Layer? The latency of query runtimes is low, in the order of milliseconds. What if different teams have different definitions? If the underlying metric aggregation is different, then these would be different metrics. However, if teams have different definitions because they're using specific filters or dimensions, it's still the same metric. They're just using it in different ways. This can be managed by adjusting how the metric is viewed in downstream tools or setting up [saved queries](https://docs.getdbt.com/docs/build/saved-queries) to handle the various permutations of it. Build metrics and semantic models[​](https://docs.getdbt.com/docs/use-dbt-semantic-layer/sl-faqs#build-metrics-and-semantic-models "Direct link to Build metrics and semantic models") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------  Can I define my own aggregations? MetricFlow does not currently support custom aggregations on measures. You can find supported aggregation types [here](https://docs.getdbt.com/docs/build/measures#aggregation) . How are joins identified in the semantic model? [Joins](https://docs.getdbt.com/docs/build/join-logic) are identified through [entities](https://docs.getdbt.com/docs/build/entities) defined in a [semantic model](https://docs.getdbt.com/docs/build/semantic-models) . These are the keys in your dataset. You can specify `foreign`, `unique`, `primary`, or `natural` joins. With multiple semantic models and the entities within them, MetricFlow creates a graph using the semantic models as nodes and the join paths as edges to perform joins automatically. MetricFlow chooses the appropriate join type and avoids fan-out or chasm joins with other tables based on the entity types. You can find supported join types [here](https://docs.getdbt.com/docs/build/join-logic#types-of-joins) . What is the benefit of “expr” used in semantic models and metric configurations? Expr (short for “expression”) allows you to put any arbitrary SQL supported by your data platform in any definition of a measure, entity, or dimension. This is useful if you want the object name in the semantic model to be different than what it’s called in the database. Or if you want to include logic in the definition of the component you're creating. The MetricFlow spec is deliberately opinionated, and we offer “expr” as an escape hatch to allow developers to be more expressive. Do you support semi-additive metrics? Yes, we approach this by specifying a [dimension](https://docs.getdbt.com/docs/build/dimensions) that a metric cannot be aggregated across (such as `time`). You can learn how to configure semi-additive dimensions [here](https://docs.getdbt.com/docs/build/measures#non-additive-dimensions) . Can I use an entity as a dimension? Yes, while [entities](https://docs.getdbt.com/docs/build/entities) must be defined under “entities,” they can be queried like dimensions in downstream tools. Additionally, if the entity isn't used to perform joins across your semantic models, you may optionally define it as a dimension. Can I test my semantic models and metrics? Yes! You can validate your semantic nodes (semantic models, metrics, saved queries) in a few ways: * [Query and validate you metrics](https://docs.getdbt.com/docs/build/metricflow-commands) in your development tool before submitting your code changes. * [Validate semantic nodes in CI](https://docs.getdbt.com/docs/deploy/ci-jobs#semantic-validations-in-ci) to ensure code changes made to dbt models don't break these metrics. Available integrations[​](https://docs.getdbt.com/docs/use-dbt-semantic-layer/sl-faqs#available-integrations "Direct link to Available integrations") ------------------------------------------------------------------------------------------------------------------------------------------------------  What integrations are supported today? There are a number of data applications that have integrations with the dbt Semantic Layer, including Tableau, Google Sheets, Hex, and Mode, among others. Refer to [Available integrations](https://docs.getdbt.com/docs/cloud-integrations/avail-sl-integrations) for more information. How can I benefit from using the dbt Semantic Layer if my visualization tool is not currently supported? You can use [exports](https://docs.getdbt.com/docs/use-dbt-semantic-layer/exports) to materialize your metrics into a table or view in your data platform. From there, you can connect your visualization tool to your data platform. Although this approach doesn't provide the dynamic benefits of the dbt Semantic Layer, you still benefit from centralized metrics and from using MetricFlow configurations to define, generate, and compute SQL for your metrics. Why should I use exports as opposed to defining a view within my data platform? Creating an [export](https://docs.getdbt.com/docs/use-dbt-semantic-layer/exports) allows you to bring your governed metric definitions into your data platform as a table or view. This means your metric logic is managed centrally in dbt, instead of as a view in your data platform and ensures that metric values remain consistent across all interfaces. Can metric descriptions be viewed from third-party tools? Yes, all of our interfaces or APIs expose metric descriptions, which you can surface in downstream tools. Permissions and access[​](https://docs.getdbt.com/docs/use-dbt-semantic-layer/sl-faqs#permissions-and-access "Direct link to Permissions and access") ------------------------------------------------------------------------------------------------------------------------------------------------------  How do fine-grained access controls work with the dbt Semantic Layer? The dbt Semantic Layer uses service or personal tokens for authentication. [Service tokens](https://docs.getdbt.com/docs/dbt-cloud-apis/service-tokens) are mapped to underlying data platform credentials. These credentials control physical access to the raw data. The credential configuration allows admins to create a credential and map it to service tokens, which can then be shared to relevant teams for BI connection setup. You can configure credentials and service tokens to reflect your teams and their roles. Personal access tokens [(PATs)](https://docs.getdbt.com/docs/dbt-cloud-apis/user-tokens) enable user-level authentication. When you use PATs to authenticate, your personal development credentials are used when running queries against the Semantic Layer. Currently, the credentials you configure when setting up the dbt Semantic Layer are used for every request. Any physical access policies you have tied to your credentials will be respected. Implementation[​](https://docs.getdbt.com/docs/use-dbt-semantic-layer/sl-faqs#implementation "Direct link to Implementation") ------------------------------------------------------------------------------------------------------------------------------  How can I implement dbt Mesh with the dbt Semantic Layer When using the dbt Semantic Layer in a [dbt Mesh](https://docs.getdbt.com/best-practices/how-we-mesh/mesh-1-intro) setting, we recommend the following: * You have one standalone project that contains your semantic models and metrics. * Then as you build your Semantic Layer, you can [cross-reference dbt models](https://docs.getdbt.com/docs/mesh/govern/project-dependencies) across your various projects or packages to create your semantic models using the [two-argument `ref` function](https://docs.getdbt.com/reference/dbt-jinja-functions/ref#ref-project-specific-models) ( `ref('project_name', 'model_name')`). * Your dbt Semantic Layer project serves as a global source of truth across the rest of your projects. #### Usage example[​](https://docs.getdbt.com/docs/use-dbt-semantic-layer/sl-faqs#usage-example "Direct link to Usage example") For example, let's say you have a public model (`fct_orders`) that lives in the `jaffle_finance` project. As you build your semantic model, use the following syntax to ref the model: models/metrics/semantic\_model\_name.yml semantic_models: - name: customer_orders defaults: agg_time_dimension: first_ordered_at description: | Customer grain mart that aggregates customer orders. model: ref('jaffle_finance', 'fct_orders') # ref('project_name', 'model_name') entities: ...rest of configuration... dimensions: ...rest of configuration... measures: ...rest of configuration... Notice that in the `model` parameter, we're using the `ref` function with two arguments to reference the public model `fct_orders` defined in the `jaffle_finance` project. Which ‘staging layer’ should the dbt Semantic Layer talk to? Raw, staging, or marts? We recommend to build your semantic layer on top of the [marts layer](https://docs.getdbt.com/best-practices/how-we-structure/4-marts) , which represents the clean and transformed data from your dbt models. Should semantic layer credentials mirror those for production environments? Or should they be different? Semantic layer credentials are different than the credentials you use to run dbt models. Specifically, we recommend a less privileged set of credentials since consumers are only reading data. How does the dbt Semantic Layer support a dbt Mesh architecture design? Currently, semantic models can be created from dbt models that live across projects ([dbt Mesh](https://docs.getdbt.com/best-practices/how-we-mesh/mesh-1-intro) ). In the future, users will also be able to use mesh concepts on semantic objects and define metrics across dbt projects. How do I migrate from the legacy Semantic Layer? If you're using the legacy Semantic Layer, we highly recommend you [upgrade your dbt version](https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-version-in-cloud) to dbt v1.6 or higher to use the latest dbt Semantic Layer. Refer to the dedicated [migration guide](https://docs.getdbt.com/guides/sl-migration)  for more info. Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Overview of the dbt Semantic Layer](https://docs.getdbt.com/docs/use-dbt-semantic-layer/sl-faqs#overview-of-the-dbt-semantic-layer) * [Availability](https://docs.getdbt.com/docs/use-dbt-semantic-layer/sl-faqs#availability) * [How does the dbt Semantic Layer work?](https://docs.getdbt.com/docs/use-dbt-semantic-layer/sl-faqs#how-does-the-dbt-semantic-layer-work) * [Build metrics and semantic models](https://docs.getdbt.com/docs/use-dbt-semantic-layer/sl-faqs#build-metrics-and-semantic-models) * [Available integrations](https://docs.getdbt.com/docs/use-dbt-semantic-layer/sl-faqs#available-integrations) * [Permissions and access](https://docs.getdbt.com/docs/use-dbt-semantic-layer/sl-faqs#permissions-and-access) * [Implementation](https://docs.getdbt.com/docs/use-dbt-semantic-layer/sl-faqs#implementation) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/use-dbt-semantic-layer/sl-faqs.md) --- # Semantic Layer APIs | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-api-overview#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) The rapid growth of different tools in the modern data stack has helped data professionals address the diverse needs of different teams. The downside of this growth is the fragmentation of business logic across teams, tools, and workloads. The [Semantic Layer](https://docs.getdbt.com/docs/use-dbt-semantic-layer/dbt-sl) allows you to define metrics in code (with [MetricFlow](https://docs.getdbt.com/docs/build/about-metricflow) ) and dynamically generate and query datasets in downstream tools based on their dbt governed assets, such as metrics and models. Integrating with the Semantic Layer will help organizations that use your product make more efficient and trustworthy decisions with their data. It also helps you to avoid duplicative coding, optimize development workflow, ensure data governance, and guarantee consistency for data consumers. You can use the Semantic Layer for a variety of tools and applications of data. Some common use cases are: * Business intelligence (BI), reporting, and analytics * Data quality and monitoring * Governance and privacy * Data discovery and cataloging * Machine learning and data science [![](https://docs.getdbt.com/img/icons/dbt-bit.svg)\ \ #### GraphQL API\ \ Use GraphQL to query metrics and dimensions in downstream tools.](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-graphql) [![](https://docs.getdbt.com/img/icons/dbt-bit.svg)\ \ #### JDBC API\ \ Use a JDBC driver to query metrics and dimensions in downstream tools, while also providing standard metadata functionality.](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc) [![](https://docs.getdbt.com/img/icons/dbt-bit.svg)\ \ #### Python SDK\ \ Use the Python SDK to interact with the dbt Semantic Layer using Python.](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-python) Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 --- # JDBC | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page The Semantic Layer Java Database Connectivity (JDBC) API enables users to query metrics and dimensions using the JDBC protocol, while also providing standard metadata functionality. A JDBC driver is a software component enabling a Java application to interact with a data platform. Here's some more information about our JDBC API: * The Semantic Layer JDBC API utilizes the open-source JDBC driver with ArrowFlight SQL protocol. * You can download the JDBC driver from [Maven](https://search.maven.org/remotecontent?filepath=org/apache/arrow/flight-sql-jdbc-driver/12.0.0/flight-sql-jdbc-driver-12.0.0.jar) . * The Semantic Layer supports ArrowFlight SQL driver version 12.0.0 and higher. * You can embed the driver into your application stack as needed, and you can use dbt Labs' [example project](https://github.com/dbt-labs/example-semantic-layer-clients) for reference. * If you’re a partner or user building a homegrown application, you’ll need to install an AWS root CA to the Java Trust [documentation](https://www.amazontrust.com/repository/) (specific to Java and JDBC call). dbt Labs partners can use the JDBC API to build integrations in their tools with the Semantic Layer Using the JDBC API[​](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc#using-the-jdbc-api "Direct link to Using the JDBC API") ---------------------------------------------------------------------------------------------------------------------------------- If you are a dbt user or partner with access to dbt and the [Semantic Layer](https://docs.getdbt.com/docs/use-dbt-semantic-layer/dbt-sl) , you can [setup](https://docs.getdbt.com/docs/use-dbt-semantic-layer/setup-sl) and test this API with data from your own instance by configuring the Semantic Layer and obtaining the right JDBC connection parameters described in this document. You _may_ be able to use our JDBC API with tools that do not have an official integration with the Semantic Layer. If the tool you use allows you to write SQL and either supports a generic JDBC driver option (such as DataGrip) or supports Dremio and uses ArrowFlightSQL driver version 12.0.0 or higher, you can access the Semantic Layer API. Refer to [Get started with the Semantic Layer](https://docs.getdbt.com/guides/sl-snowflake-qs) for more info. Note that the Semantic Layer GraphQL API doesn't support `ref` to call dbt objects. Instead, use the complete qualified table name. If you're using dbt macros at query time to calculate your metrics, you should move those calculations into your Semantic Layer metric definitions as code. Authentication[​](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc#authentication "Direct link to Authentication") ---------------------------------------------------------------------------------------------------------------------- dbt authorizes requests to the Semantic Layer API. You need to provide an Environment ID, Host, and [service account tokens](https://docs.getdbt.com/docs/dbt-cloud-apis/service-tokens) or [personal access tokens](https://docs.getdbt.com/docs/dbt-cloud-apis/user-tokens) . Connection parameters[​](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc#connection-parameters "Direct link to Connection parameters") ------------------------------------------------------------------------------------------------------------------------------------------- The JDBC connection requires a few different connection parameters. This is an example of a URL connection string and the individual components: jdbc:arrow-flight-sql://semantic-layer.cloud.getdbt.com:443?&environmentId=202339&token=AUTHENTICATION_TOKEN | JDBC parameter | Description | Example | | --- | --- | --- | | `jdbc:arrow-flight-sql://` | The protocol for the JDBC driver. | `jdbc:arrow-flight-sql://` | | `semantic-layer.cloud.getdbt.com` | The [access URL](https://docs.getdbt.com/docs/cloud/about-cloud/access-regions-ip-addresses)
for your account's dbt region. You must always add the `semantic-layer` prefix before the access URL. | For dbt deployment hosted in North America, use `semantic-layer.cloud.getdbt.com` | | `environmentId` | The unique identifier for the dbt production environment, you can retrieve this from the dbt URL
when you navigate to **Environments** under **Deploy**. | If your URL ends with `.../environments/222222`, your `environmentId` is `222222` | | `AUTHENTICATION_TOKEN` | You can use either a dbt [service token](https://docs.getdbt.com/docs/dbt-cloud-apis/service-tokens)
with “Semantic Layer Only” and "Metadata Only" permissions or a dbt [personal access token](https://docs.getdbt.com/docs/dbt-cloud-apis/user-tokens)
. Create a new service or personal token on the **Account Settings** page. | `token=AUTHENTICATION_TOKEN` | \*Note — If you're testing locally on a tool like DataGrip, you may also have to provide the following variable at the end or beginning of the JDBC URL `&disableCertificateVerification=true`. Querying the API for metadata[​](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc#querying-the-api-for-metadata "Direct link to Querying the API for metadata") ------------------------------------------------------------------------------------------------------------------------------------------------------------------- The Semantic Layer JDBC API has built-in metadata calls which can provide a user with information about their metrics and dimensions. Expand the following toggles for examples and metadata commands:  Fetch defined metrics You can use this query to fetch all defined metrics in your dbt project: select * from {{ semantic_layer.metrics() }} Fetch dimension for a metric You can use this query to fetch all dimensions for a metric. Note, metrics is a required argument that lists one or multiple metrics in it. select * from {{ semantic_layer.dimensions(metrics=['food_order_amount'])}} Fetch granularities for metrics You can use this query to fetch queryable granularities for a list of metrics. This API request allows you to only show the time granularities that make sense for the primary time dimension of the metrics (such as metric\_time), but if you want queryable granularities for other time dimensions, you can use the dimensions() call, and find the column queryable\_granularities. Note, metrics is a required argument that lists one or multiple metrics. select * from {{ semantic_layer.queryable_granularities(metrics=['food_order_amount', 'order_gross_profit'])}} Fetch available metrics given dimensions You can use this query to fetch available metrics given dimensions. This command is essentially the opposite of getting dimensions given a list of metrics. Note, group\_by is a required argument that lists one or multiple dimensions. select * from {{ semantic_layer.metrics_for_dimensions(group_by=['customer__customer_type'])}} Fetch granularities for all time dimensions You can use this example query to fetch available granularities for all time dimensions (the similar queryable granularities API call only returns granularities for the primary time dimensions for metrics). The following call is a derivative of the dimensions() call and specifically selects the granularity field. select NAME, QUERYABLE_GRANULARITIES from {{ semantic_layer.dimensions( metrics=["order_total"] )}} Fetch primary time dimension names It may be useful in your application to expose the names of the time dimensions that represent metric\_time or the common thread across all metrics. You can first query the metrics() argument to fetch a list of measures, then use the measures() call which will return the name(s) of the time dimensions that make up metric time. select * from {{ semantic_layer.measures(metrics=['orders'])}} Fetch metrics by substring search You can filter your metrics to include only those that contain a specific substring (sequence of characters contained within a larger string (text)). Use the `search` argument to specify the substring you want to match. select * from {{ semantic_layer.metrics(search='order') }} If no substring is provided, the query returns all metrics. Paginate metadata calls In the case when you don't want to return the full result set from a metadata call, you can paginate the results for both `semantic_layer.metrics()` and `semantic_layer.dimensions()` calls using the `page_size` and `page_number` parameters. * `page_size`: This is an optional variable which sets the number of records per page. If left as None, there is no page limit. * `page_number`: This is an optional variable which specifies the page number to retrieve. Defaults to `1` (first page) if not specified. Examples: -- Retrieves the 5th page with a page size of 10 metricsselect * from {{ semantic_layer.metrics(page_size=10, page_number=5) }}-- Retrieves the 1st page with a page size of 10 metricsselect * from {{ semantic_layer.metrics(page_size=10) }}-- Retrieves all metrics without paginationselect * from {{ semantic_layer.metrics() }} You can use the same pagination parameters for `semantic_layer.dimensions(...)`. List saved queries You can use this example query to list all available saved queries in your dbt project. **Command** select * from semantic_layer.saved_queries() **Output** | NAME | DESCRIPTION | LABEL | METRICS | GROUP_BY | WHERE_FILTER | Fetch metric aliases You can query metrics using aliases for simpler or more intuitive names, even if the alias isn't defined in the metric configuration. The query returns the alias as the metric name, for example: select * from {{ semantic_layer.query(metrics=[Metric("metric_name", alias="metric_alias")])}} In this example, if you define an alias for `revenue` as `banana`, the query will return a column named `banana` even if `banana` isn't defined in the metric configuration. However, when using `where` Jinja clauses, you need to reference the _actual_ metric name (`revenue` in this case) instead of the alias. For more a more detailed example, see [Query metric alias](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc#query-metric-alias) . Querying the API for values[​](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc#querying-the-api-for-values "Direct link to Querying the API for values") ------------------------------------------------------------------------------------------------------------------------------------------------------------- To query values, the following parameters are available. Your query must have _either_ a `metric` **or** a `group_by` parameter to be valid. | Parameter | Description | Example | | --- | --- | --- | | `metrics` | The metric name as defined in your dbt metric configuration | `metrics=['revenue']` | | `group_by` | Dimension names or entities to group by. We require a reference to the entity of the dimension (other than for the primary time dimension), which is pre-appended to the front of the dimension name with a double underscore. | `group_by=['user__country', 'metric_time']` | | `grain` | A parameter specific to any time dimension and changes the grain of the data from the default for the metric. | `group_by=[Dimension('metric_time')`
`grain('week\|day\|month\|quarter\|year')]` | | `where` | A where clause that allows you to filter on dimensions and entities using parameters. This takes a filter list OR string. Inputs come with `Dimension`, and `Entity` objects. Granularity is required if the `Dimension` is a time dimension | `"{{ where=Dimension('customer__country') }} = 'US')"` | | `limit` | Limit the data returned | `limit=10` | | `order` | Order the data returned by a particular field | `order_by=['order_gross_profit']`, use `-` for descending, or full object notation if the object is operated on: `order_by=[Metric('order_gross_profit').descending(True)`\] | | `compile` | If true, returns generated SQL for the data platform but does not execute | `compile=True` | | `saved_query` | A saved query you can use for frequently used queries. | `select * from {{ semantic_layer.query(saved_query="new_customer_orders"` | ### Note on time dimensions and `metric_time`[​](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc#note-on-time-dimensions-and-metric_time "Direct link to note-on-time-dimensions-and-metric_time") You will notice that in the list of dimensions for all metrics, there is a dimension called `metric_time`. `Metric_time` is a reserved keyword for the measure-specific aggregation time dimensions. For any time-series metric, the `metric_time` keyword should always be available for use in queries. This is a common dimension across _all_ metrics in a semantic graph. You can look at a single metric or hundreds of metrics, and if you group by `metric_time`, it will always give you the correct time series. Additionally, when performing granularity calculations that are global (not specific to a particular time dimension), we recommend you always operate on `metric_time` and you will get the correct answer. Note that `metric_time` should be available in addition to any other time dimensions that are available for the metric(s). In the case where you are looking at one metric (or multiple metrics from the same data source), the values in the series for the primary time dimension and `metric_time` are equivalent. Examples[​](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc#examples "Direct link to Examples") ---------------------------------------------------------------------------------------------------- The following sections provide examples of how to query metrics using the JDBC API: * [Fetch metadata for metrics](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc#fetch-metadata-for-metrics) — Filter/add any SQL outside of the templating syntax. * [Query common dimensions](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc#query-common-dimensions) — Select common dimensions for multiple metrics. * [Query grouped by time](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc#query-grouped-by-time) — Fetch revenue and new customers grouped by time. * [Query with a time grain](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc#query-with-a-time-grain) — Fetch multiple metrics with a change in time dimension granularities. * [Group by categorical dimension](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc#group-by-categorical-dimension) — Group by a categorical dimension. * [Query only a dimension](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc#query-only-a-dimension) — Get the full list of dimension values for the chosen dimension. * [Query by all dimensions](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc#query-by-all-dimensions) — Query by all valid dimensions. * [Query with where filters](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc#query-with-where-filters) — Use the `where` parameter to filter on dimensions and entities using parameters. * [Query with a limit](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc#query-with-a-limit) — Query using a `limit` or `order_by` clause. * [Query with order by examples](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc#query-with-order-by-examples) — Query with `order_by`, accepts basic string that's a Dimension, Metric, or Entity. Defaults to ascending order. Add a `-` sign in front of the object for descending order. * [Query with compile keyword](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc#query-with-compile-keyword) — Query using a compile keyword to preview the final SQL before execution. * [Query a saved query](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc#query-a-saved-query) — Query using a saved query with optional parameters like `limit` or `where`. * [Query metric alias](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc#query-metric-alias) — Query metrics using aliases, which allow you to use simpler or more intuitive names for metrics instead of their full definitions. * [Multi-hop joins](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc#multi-hop-joins) — Query across multiple related tables (multi-hop joins) using the `entity_path` argument to specify the path between related entities. ### Fetch metadata for metrics[​](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc#fetch-metadata-for-metrics "Direct link to Fetch metadata for metrics") You can filter/add any SQL outside of the templating syntax. For example, you can use the following query to fetch the name and dimensions for a metric: select name, dimensions from {{ semantic_layer.metrics() }} WHERE name='food_order_amount' ### Query common dimensions[​](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc#query-common-dimensions "Direct link to Query common dimensions") You can select common dimensions for multiple metrics. Use the following query to fetch the name and dimensions for multiple metrics: select * from {{ semantic_layer.dimensions(metrics=['food_order_amount', 'order_gross_profit']) }} ### Query grouped by time[​](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc#query-grouped-by-time "Direct link to Query grouped by time") The following example query uses the [shorthand method](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc#faqs) to fetch revenue and new customers grouped by time: select * from {{ semantic_layer.query(metrics=['food_order_amount','order_gross_profit'], group_by=['metric_time']) }} ### Query with a time grain[​](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc#query-with-a-time-grain "Direct link to Query with a time grain") Use the following example query to fetch multiple metrics with a change in time dimension granularities: select * from {{ semantic_layer.query(metrics=['food_order_amount', 'order_gross_profit'], group_by=[Dimension('metric_time').grain('month')]) }} ### Group by categorical dimension[​](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc#group-by-categorical-dimension "Direct link to Group by categorical dimension") Use the following query to group by a categorical dimension: select * from {{ semantic_layer.query(metrics=['food_order_amount', 'order_gross_profit'], group_by=[Dimension('metric_time').grain('month'), 'customer__customer_type']) }} ### Query only a dimension[​](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc#query-only-a-dimension "Direct link to Query only a dimension") In this case, you'll get the full list of dimension values for the chosen dimension. select * from {{ semantic_layer.query(group_by=['customer__customer_type']) }} ### Query by all dimensions[​](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc#query-by-all-dimensions "Direct link to Query by all dimensions") You can use the `semantic_layer.query_with_all_group_bys` endpoint to query by all valid dimensions. select * from {{ semantic_layer.query_with_all_group_bys(metrics =['revenue','orders','food_orders'], compile= True)}} This returns all dimensions that are valid for the set of metrics in the request. ### Query with where filters[​](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc#query-with-where-filters "Direct link to Query with where filters") Where filters in API allow for a filter list or string. We recommend using the filter list for production applications as this format will realize all benefits from the Predicate pushdown where possible. Where Filters have a few objects that you can use: * `Dimension()` — Used for any categorical or time dimensions. `Dimension('metric_time').grain('week')` or `Dimension('customer__country')`. * `TimeDimension()` — Used as a more explicit definition for time dimensions, optionally takes in a granularity `TimeDimension('metric_time', 'month')`. * `Entity()` — Used for entities like primary and foreign keys - `Entity('order_id')`. For `TimeDimension()`, the grain is only required in the `WHERE` filter if the aggregation time dimensions for the measures and metrics associated with the where filter have different grains. For example, consider this Semantic model and Metric config, which contains two metrics that are aggregated across different time grains. This example shows a single semantic model, but the same goes for metrics across more than one semantic model. semantic_model: name: my_model_sourcedefaults: agg_time_dimension: created_month measures: - name: measure_0 agg: sum - name: measure_1 agg: sum agg_time_dimension: order_year dimensions: - name: created_month type: time type_params: time_granularity: month - name: order_year type: time type_params: time_granularity: yearmetrics: - name: metric_0 description: A metric with a month grain. type: simple type_params: measure: measure_0 - name: metric_1 description: A metric with a year grain. type: simple type_params: measure: measure_1 Assuming the user is querying `metric_0` and `metric_1` together in a single request, a valid `WHERE` filter would be: * `"{{ TimeDimension('metric_time', 'year') }} > '2020-01-01'"` Invalid filters would be: * `"{{ TimeDimension('metric_time') }} > '2020-01-01'"` — metrics in the query are defined based on measures with different grains. * `"{{ TimeDimension('metric_time', 'month') }} > '2020-01-01'"` — `metric_1` is not available at a month grain. * Use the following example to query using a `where` filter with the string format: select * from {{semantic_layer.query(metrics=['food_order_amount', 'order_gross_profit'],group_by=[Dimension('metric_time').grain('month'),'customer__customer_type'],where="{{ Dimension('metric_time').grain('month') }} >= '2017-03-09' AND {{ Dimension('customer__customer_type' }} in ('new') AND {{ Entity('order_id') }} = 10")}} * (Recommended for better performance) Use the following example to query using a `where` filter with a filter list format: select * from {{semantic_layer.query(metrics=['food_order_amount', 'order_gross_profit'],group_by=[Dimension('metric_time').grain('month'),'customer__customer_type'],where=["{{ Dimension('metric_time').grain('month') }} >= '2017-03-09'", "{{ Dimension('customer__customer_type') }} in ('new')", "{{ Entity('order_id') }} = 10"])}} ### Query with a limit[​](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc#query-with-a-limit "Direct link to Query with a limit") Use the following example to query using a `limit` or `order_by` clause: select * from {{semantic_layer.query(metrics=['food_order_amount', 'order_gross_profit'], group_by=[Dimension('metric_time')], limit=10) }} ### Query with order by examples[​](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc#query-with-order-by-examples "Direct link to Query with order by examples") Order By can take a basic string that's a Dimension, Metric, or Entity, and this will default to ascending order select * from {{semantic_layer.query(metrics=['food_order_amount', 'order_gross_profit'], group_by=[Dimension('metric_time')], limit=10, order_by=['order_gross_profit']) }} For descending order, you can add a `-` sign in front of the object. However, you can only use this short-hand notation if you aren't operating on the object or using the full object notation. select * from {{semantic_layer.query(metrics=['food_order_amount', 'order_gross_profit'], group_by=[Dimension('metric_time')], limit=10, order_by=['-order_gross_profit']) }} If you are ordering by an object that's been operated on (for example, you changed the granularity of the time dimension), or you are using the full object notation, descending order must look like: select * from {{semantic_layer.query(metrics=['food_order_amount', 'order_gross_profit'], group_by=[Dimension('metric_time').grain('week')], limit=10, order_by=[Metric('order_gross_profit').descending(True), Dimension('metric_time').grain('week').descending(True) ]) }} Similarly, this will yield ascending order: select * from {{semantic_layer.query(metrics=['food_order_amount', 'order_gross_profit'], group_by=[Dimension('metric_time').grain('week')], limit=10, order_by=[Metric('order_gross_profit'), Dimension('metric_time').grain('week')]) }} ### Query with compile keyword[​](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc#query-with-compile-keyword "Direct link to Query with compile keyword") * Use the following example to query using a `compile` keyword: select * from {{semantic_layer.query(metrics=['food_order_amount', 'order_gross_profit'], group_by=[Dimension('metric_time').grain('month'),'customer__customer_type'], compile=True) }} * Use the following example to compile SQL with a [saved query](https://docs.getdbt.com/docs/build/saved-queries) . You can use this for frequently used queries. select * from {{ semantic_layer.query(saved_query="new_customer_orders", limit=5, compile=True}} A note on querying saved queries When querying [saved queries](https://docs.getdbt.com/docs/build/saved-queries) ,you can use parameters such as `where`, `limit`, `order`, `compile`, and so on. However, keep in mind that you can't access `metric` or `group_by` parameters in this context. This is because they are predetermined and fixed parameters for saved queries, and you can't change them at query time. If you would like to query more metrics or dimensions, you can build the query using the standard format. ### Query a saved query[​](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc#query-a-saved-query "Direct link to Query a saved query") Use the following example to query a [saved query](https://docs.getdbt.com/docs/build/saved-queries) : select * from {{ semantic_layer.query(saved_query="new_customer_orders", limit=5}} The JDBC API will use the saved query (`new_customer_orders`) as defined and apply a limit of 5 records. ### Query metric alias[​](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc#query-metric-alias "Direct link to Query metric alias") You can query metrics using aliases, which allow you to use simpler or more intuitive names for metrics instead of their full definitions. select * from {{ semantic_layer.query(metrics=[Metric("revenue", alias="metric_alias")])}} For example, let's say your metric configuration includes an alias like `total_revenue_global` for the `order_total` metric. You can query the metric using the alias instead of the original name: select * from {{ semantic_layer.query(metrics=[Metric("order_total", alias="total_revenue_global")], group_by=['metric_time'])}} The result will be: | METRIC_TIME | TOTAL_REVENUE_GLOBAL ||:-------------:|:------------------: || 2023-12-01 | 1500.75 || 2023-12-02 | 1725.50 || 2023-12-03 | 1850.00 | tip Note that you need to use the actual metric name when using the `where` Jinja clauses. For example, if you used `banana` as an alias for `revenue`, you need to use the actual metric name, `revenue`, in the `where` clause, not `banana`. semantic_layer.query(metrics=[Metric("revenue", alias="banana")], where="{{ Metric('revenue') }} > 0") ### Multi-hop joins[​](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc#multi-hop-joins "Direct link to Multi-hop joins") In cases where you need to query across multiple related tables (multi-hop joins), use the `entity_path` argument to specify the path between related entities. The following are examples of how you can define these joins: * In this example, you're querying the `location_name` dimension but specifying that it should be joined using the `order_id` field. {{Dimension('location__location_name', entity_path=['order_id'])}} * In this example, the `salesforce_account_owner` dimension is joined to the `region` field, with the path going through `salesforce_account`. {{ Dimension('salesforce_account_owner__region',['salesforce_account']) }} FAQs[​](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc#faqs "Direct link to FAQs") ---------------------------------------------------------------------------------------- I'm receiving an \`Failed ALPN\` error when trying to connect to the dbt Semantic Layer. If you're receiving a `Failed ALPN` error when trying to connect the dbt Semantic Layer with the various [data integration tools](https://docs.getdbt.com/docs/cloud-integrations/avail-sl-integrations) (such as Tableau, DBeaver, Datagrip, ADBC, or JDBC), it typically happens when connecting from a computer behind a corporate VPN or Proxy (like Zscaler or Check Point). The root cause is typically the proxy interfering with the TLS handshake as the Semantic Layer uses gRPC/HTTP2 for connectivity. To resolve this: * If your proxy supports gRPC/HTTP2 but isn't configured to allow ALPN, adjust its settings accordingly to allow ALPN. Or create an exception for the dbt domain. * If your proxy does not support gRPC/HTTP2, add an SSL interception exception for the dbt domain in your proxy settings This should help in successfully establishing the connection without the Failed ALPN error.  Why do some dimensions use different syntax, like \`metric\_time\` versus \`Dimension('metric\_time')\`? When you select a dimension on its own, such as `metric_time` you can use the shorthand method which doesn't need the “Dimension” syntax. However, when you perform operations on the dimension, such as adding granularity, the object syntax `[Dimension('metric_time')` is required.\ \  What does the double underscore \`'\_\_'\` syntax in dimensions mean?\ \ The double underscore `"__"` syntax indicates a mapping from an entity to a dimension, as well as where the dimension is located. For example, `user__country` means someone is looking at the `country` dimension from the `user` table.\ \  What is the default output when adding granularity?\ \ The default output follows the format `{{time_dimension_name}__{granularity_level}}`.\ \ So for example, if the `time_dimension_name` is `ds` and the granularity level is yearly, the output is `ds__year`.\ \ Related docs[​](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc#related-docs "Direct link to Related docs")\ \ ----------------------------------------------------------------------------------------------------------------\ \ * [Semantic Layer integration best practices](https://docs.getdbt.com/guides/sl-partner-integration-guide)\ \ \ Was this page helpful?\ ----------------------\ \ YesNo\ \ [Privacy policy](https://www.getdbt.com/cloud/privacy-policy)\ [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues)\ \ This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy)\ and [Terms of Service](https://policies.google.com/terms)\ apply.\ \ 0\ \ * [Using the JDBC API](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc#using-the-jdbc-api)\ \ * [Authentication](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc#authentication)\ \ * [Connection parameters](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc#connection-parameters)\ \ * [Querying the API for metadata](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc#querying-the-api-for-metadata)\ \ * [Querying the API for values](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc#querying-the-api-for-values)\ * [Note on time dimensions and `metric_time`](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc#note-on-time-dimensions-and-metric_time)\ \ * [Examples](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc#examples)\ * [Fetch metadata for metrics](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc#fetch-metadata-for-metrics)\ \ * [Query common dimensions](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc#query-common-dimensions)\ \ * [Query grouped by time](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc#query-grouped-by-time)\ \ * [Query with a time grain](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc#query-with-a-time-grain)\ \ * [Group by categorical dimension](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc#group-by-categorical-dimension)\ \ * [Query only a dimension](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc#query-only-a-dimension)\ \ * [Query by all dimensions](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc#query-by-all-dimensions)\ \ * [Query with where filters](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc#query-with-where-filters)\ \ * [Query with a limit](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc#query-with-a-limit)\ \ * [Query with order by examples](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc#query-with-order-by-examples)\ \ * [Query with compile keyword](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc#query-with-compile-keyword)\ \ * [Query a saved query](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc#query-a-saved-query)\ \ * [Query metric alias](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc#query-metric-alias)\ \ * [Multi-hop joins](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc#multi-hop-joins)\ \ * [FAQs](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc#faqs)\ \ * [Related docs](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc#related-docs)\ \ \ [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/dbt-cloud-apis/sl-jdbc.md) --- # Version upgrade guides | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/dbt-versions/core-upgrade#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) [📄️ Upgrading to the dbt Fusion engine (v2.0)\ ---------------------------------------------\ \ New features and changes in Fusion](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-fusion) [📄️ Upgrading to v1.10\ ----------------------\ \ New features and changes in dbt Core v1.10](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.10) [📄️ Upgrading to v1.9\ ---------------------\ \ New features and changes in dbt Core v1.9](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.9) [📄️ Upgrading to v1.8\ ---------------------\ \ New features and changes in dbt Core v1.8](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.8) [📄️ Upgrading to v1.7\ ---------------------\ \ New features and changes in dbt Core v1.7](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.7) [🗃️ Older versions\ ------------------\ \ 8 items](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.6) --- # Run visibility | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/deploy/run-visibility#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page You can view the history of your runs and the model timing dashboard to help identify where improvements can be made to jobs. Run history[​](https://docs.getdbt.com/docs/deploy/run-visibility#run-history "Direct link to Run history") ------------------------------------------------------------------------------------------------------------ The **Run history** dashboard in dbt helps you monitor the health of your dbt project. It provides a detailed overview of all your project's job runs and empowers you with a variety of filters that enable you to focus on specific aspects. You can also use it to review recent runs, find errored runs, and track the progress of runs in progress. You can access it from the top navigation menu by clicking **Deploy** and then **Run history**. The dashboard displays your full run history, including job name, status, associated environment, job trigger, commit SHA, schema, and timing info. dbt developers can access their run history for the last 365 days through the dbt user interface (UI) and API. dbt Labs limits self-service retrieval of run history metadata to 365 days to improve dbt's performance. [![Run history dashboard allows you to monitor the health of your dbt project and displays jobs, job status, environment, timing, and more.](https://docs.getdbt.com/img/docs/dbt-cloud/deployment/run-history.png?v=2 "Run history dashboard allows you to monitor the health of your dbt project and displays jobs, job status, environment, timing, and more.")](https://docs.getdbt.com/docs/deploy/run-visibility#) Run history dashboard allows you to monitor the health of your dbt project and displays jobs, job status, environment, timing, and more. Job run details[​](https://docs.getdbt.com/docs/deploy/run-visibility#job-run-details "Direct link to Job run details") ------------------------------------------------------------------------------------------------------------------------ From the **Run history** dashboard, select a run to view complete details about it. The job run details page displays job trigger, commit SHA, time spent in the scheduler queue, all the run steps and their [logs](https://docs.getdbt.com/docs/deploy/run-visibility#access-logs) , [model timing](https://docs.getdbt.com/docs/deploy/run-visibility#model-timing) , and more. Click **Rerun now** to rerun the job immediately. An example of a completed run with a configuration for a [job completion trigger](https://docs.getdbt.com/docs/deploy/deploy-jobs#trigger-on-job-completion) : [![Example of run details](https://docs.getdbt.com/img/docs/dbt-cloud/deployment/example-job-details.png?v=2 "Example of run details")](https://docs.getdbt.com/docs/deploy/run-visibility#) Example of run details ### Run summary tab[​](https://docs.getdbt.com/docs/deploy/run-visibility#run-summary-tab "Direct link to Run summary tab") You can view or download in-progress and historical logs for your dbt runs. This makes it easier for the team to debug errors more efficiently. [![Access logs for run steps](https://docs.getdbt.com/img/docs/dbt-cloud/deployment/access-logs.png?v=2 "Access logs for run steps")](https://docs.getdbt.com/docs/deploy/run-visibility#) Access logs for run steps ### Lineage tab[​](https://docs.getdbt.com/docs/deploy/run-visibility#lineage-tab "Direct link to Lineage tab") View the lineage graph associated with the job run so you can better understand the dependencies and relationships of the resources in your project. To view a node's metadata directly in [Catalog](https://docs.getdbt.com/docs/explore/explore-projects) , select it (double-click) from the graph. [![Example of accessing dbt Catalog from the Lineage tab](https://docs.getdbt.com/img/docs/collaborate/dbt-explorer/explorer-from-lineage.gif?v=2 "Example of accessing dbt Catalog from the Lineage tab")](https://docs.getdbt.com/docs/deploy/run-visibility#) Example of accessing dbt Catalog from the Lineage tab ### Model timing tab [Starter](https://www.getdbt.com/pricing "Go to https://www.getdbt.com/pricing") [Enterprise](https://www.getdbt.com/pricing "Go to https://www.getdbt.com/pricing") [Enterprise +](https://www.getdbt.com/pricing "Go to https://www.getdbt.com/pricing") [​](https://docs.getdbt.com/docs/deploy/run-visibility#model-timing-tab- "Direct link to model-timing-tab-") The **Model timing** tab displays the composition, order, and time each model takes in a job run. The visualization appears for successful jobs and highlights the top 1% of model durations. This helps you identify bottlenecks in your runs so you can investigate them and potentially make changes to improve their performance. You can find the dashboard on the [job's run details](https://docs.getdbt.com/docs/deploy/run-visibility#job-run-details) . [![The Model timing tab displays the top 1% of model durations and visualizes model bottlenecks](https://docs.getdbt.com/img/docs/dbt-cloud/model-timing.png?v=2 "The Model timing tab displays the top 1% of model durations and visualizes model bottlenecks")](https://docs.getdbt.com/docs/deploy/run-visibility#) The Model timing tab displays the top 1% of model durations and visualizes model bottlenecks ### Artifacts tab[​](https://docs.getdbt.com/docs/deploy/run-visibility#artifacts-tab "Direct link to Artifacts tab") This provides a list of the artifacts generated by the job run. The files are saved and available for download. [![Example of the Artifacts tab](https://docs.getdbt.com/img/docs/dbt-cloud/example-artifacts-tab.png?v=2 "Example of the Artifacts tab")](https://docs.getdbt.com/docs/deploy/run-visibility#) Example of the Artifacts tab ### Compare tab [Enterprise](https://www.getdbt.com/pricing "Go to https://www.getdbt.com/pricing") [Enterprise +](https://www.getdbt.com/pricing "Go to https://www.getdbt.com/pricing") [​](https://docs.getdbt.com/docs/deploy/run-visibility#compare-tab- "Direct link to compare-tab-") The **Compare** tab is shown for [CI job runs](https://docs.getdbt.com/docs/deploy/ci-jobs) with the **Run compare changes** setting enabled. It displays details about [the changes from the comparison dbt performed](https://docs.getdbt.com/docs/deploy/advanced-ci#compare-changes) between what's in your production environment and the pull request. To help you better visualize the differences, dbt highlights changes to your models in red (deletions) and green (inserts). From the **Modified** section, you can view the following: * **Overview** — High-level summary about the changes to the models such as the number of primary keys that were added or removed. * **Primary keys** — Details about the changes to the records. * **Modified rows** — Details about the modified rows. Click **Show full preview** to display all columns. * **Columns** — Details about the changes to the columns. To view the dependencies and relationships of the resources in your project more closely, click **View in Catalog** to launch [Catalog](https://docs.getdbt.com/docs/explore/explore-projects) . [![Example of the Compare tab](https://docs.getdbt.com/img/docs/dbt-cloud/example-ci-compare-changes-tab.png?v=2 "Example of the Compare tab")](https://docs.getdbt.com/docs/deploy/run-visibility#) Example of the Compare tab Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Run history](https://docs.getdbt.com/docs/deploy/run-visibility#run-history) * [Job run details](https://docs.getdbt.com/docs/deploy/run-visibility#job-run-details) * [Run summary tab](https://docs.getdbt.com/docs/deploy/run-visibility#run-summary-tab) * [Lineage tab](https://docs.getdbt.com/docs/deploy/run-visibility#lineage-tab) * [Model timing tab](https://docs.getdbt.com/docs/deploy/run-visibility#model-timing-tab-) * [Artifacts tab](https://docs.getdbt.com/docs/deploy/run-visibility#artifacts-tab) * [Compare tab](https://docs.getdbt.com/docs/deploy/run-visibility#compare-tab-) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/deploy/run-visibility.md) --- # Webhooks for your jobs | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/deploy/webhooks#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page With dbt, you can create outbound webhooks to send events (notifications) about your dbt jobs to your other systems. Your other systems can listen for (subscribe to) these events to further automate your workflows or to help trigger automation flows you have set up. A webhook is an HTTP-based callback function that allows event-driven communication between two different web applications. This allows you to get the latest information on your dbt jobs in real time. Without it, you would need to make API calls repeatedly to check if there are any updates that you need to account for (polling). Because of this, webhooks are also called _push APIs_ or _reverse APIs_ and are often used for infrastructure development. dbt sends a JSON payload to your application's endpoint URL when your webhook is triggered. You can send a [Slack](https://docs.getdbt.com/guides/zapier-slack) notification, a [Microsoft Teams](https://docs.getdbt.com/guides/zapier-ms-teams) notification, [open a PagerDuty incident](https://docs.getdbt.com/guides/serverless-pagerduty) when a dbt job fails. You can create webhooks for these events from the [dbt web-based UI](https://docs.getdbt.com/docs/deploy/webhooks#create-a-webhook-subscription) and by using the [dbt API](https://docs.getdbt.com/docs/deploy/webhooks#api-for-webhooks) : * `job.run.started` — Run started. * `job.run.completed` — Run completed. This can be a run that has failed or succeeded. * `job.run.errored` — Run errored. dbt retries sending each event five times. dbt keeps a log of each webhook delivery for 30 days. Every webhook has its own **Recent Deliveries** section, which lists whether a delivery was successful or failed at a glance. A webhook in dbt has a timeout of 10 seconds. This means that if the endpoint doesn't respond within 10 seconds, the webhook processor will time out. This can result in a situation where the client responds successfully after the 10 second timeout and records a success status while the dbt webhooks system will interpret this as a failure. Videos If you're interested in course learning with videos, check out the [Webhooks on-demand course](https://learn.getdbt.com/courses/webhooks) from dbt Labs. You can also check out the free [dbt Fundamentals course](https://learn.getdbt.com/courses/dbt-fundamentals) . Prerequisites[​](https://docs.getdbt.com/docs/deploy/webhooks#prerequisites "Direct link to Prerequisites") ------------------------------------------------------------------------------------------------------------ * You have a dbt account that is on the [Starter or Enterprise-tier](https://www.getdbt.com/pricing/) plan. * For `write` access to webhooks: * **Enterprise-tier plans** — Permission sets are the same for both API service tokens and the dbt UI. You, or the API service token, must have the Account Admin, Admin, or Developer [permission set](https://docs.getdbt.com/docs/cloud/manage-access/enterprise-permissions) . * **Starter plan accounts** — For the dbt UI, you need to have a [Developer license](https://docs.getdbt.com/docs/cloud/manage-access/self-service-permissions) . * You have a multi-tenant or an AWS single-tenant deployment model in dbt. For more information, refer to [Tenancy](https://docs.getdbt.com/docs/cloud/about-cloud/tenancy) . * Your destination system supports [Authorization headers](https://docs.getdbt.com/docs/deploy/webhooks#troubleshooting) . Create a webhook subscription[​](https://docs.getdbt.com/docs/deploy/webhooks#create-a-webhook-subscription "Direct link to Create a webhook subscription") ------------------------------------------------------------------------------------------------------------------------------------------------------------ 1. Navigate to **Account settings** in dbt (by clicking your account name from the left side panel) 2. Go to the **Webhooks** section and click **Create webhook**. 3. To configure your new webhook: * **Webhook name** — Enter a name for your outbound webhook. * **Description** — Enter a description of the webhook. * **Events** — Choose the event you want to trigger this webhook. You can subscribe to more than one event. * **Jobs** — Specify the job(s) you want the webhook to trigger on. Or, you can leave this field empty for the webhook to trigger on all jobs in your account. By default, dbt configures your webhook at the account level. * **Endpoint** — Enter your application's endpoint URL, where dbt can send the event(s) to. 4. When done, click **Save**. dbt provides a secret token that you can use to [check for the authenticity of a webhook](https://docs.getdbt.com/docs/deploy/webhooks#validate-a-webhook) . It’s strongly recommended that you perform this check on your server to protect yourself from fake (spoofed) requests. info Note that dbt automatically deactivates a webhook after 5 consecutive failed attempts to send events to your endpoint. To re-activate the webhook, locate it in the webhooks list and click the reactivate button to enable it and continue receiving events. To find the appropriate dbt access URL for your region and plan, refer to [Regions & IP addresses](https://docs.getdbt.com/docs/cloud/about-cloud/access-regions-ip-addresses) . ### Differences between completed and errored webhook events[​](https://docs.getdbt.com/docs/deploy/webhooks#completed-errored-event-difference "Direct link to Differences between completed and errored webhook events") The `job.run.errored` event is a subset of the `job.run.completed` events. If you subscribe to both, you will receive two notifications when your job encounters an error. However, dbt triggers the two events at different times: * `job.run.completed` — This event only fires once the job’s metadata and artifacts have been ingested and are available from the dbt Admin and Discovery APIs. * `job.run.errored` — This event fires immediately so the job’s metadata and artifacts might not have been ingested. This means that information might not be available for you to use. If your integration depends on data from the Admin API (such as accessing the logs from the run) or Discovery API (accessing model-by-model statuses), use the `job.run.completed` event and filter on `runStatus` or `runStatusCode`. If your integration doesn’t depend on additional data or if improved delivery performance is more important for you, use `job.run.errored` and build your integration to handle API calls that might not return data a short period at first. Validate a webhook[​](https://docs.getdbt.com/docs/deploy/webhooks#validate-a-webhook "Direct link to Validate a webhook") --------------------------------------------------------------------------------------------------------------------------- You can use the secret token provided by dbt to validate that webhooks received by your endpoint were actually sent by dbt. Official webhooks will include the `Authorization` header that contains a SHA256 hash of the request body and uses the secret token as a key. An example for verifying the authenticity of the webhook in Python: auth_header = request.headers.get('authorization', None)app_secret = os.environ['MY_DBT_CLOUD_AUTH_TOKEN'].encode('utf-8')signature = hmac.new(app_secret, request_body, hashlib.sha256).hexdigest()return signature == auth_header Note that the destination system must support [Authorization headers](https://docs.getdbt.com/docs/deploy/webhooks#troubleshooting) for the webhook to work correctly. You can test your endpoint's support by sending a request with curl and an Authorization header, like this: curl -H 'Authorization: 123' -X POST https:// Inspect HTTP requests[​](https://docs.getdbt.com/docs/deploy/webhooks#inspect-http-requests "Direct link to Inspect HTTP requests") ------------------------------------------------------------------------------------------------------------------------------------ When working with webhooks, it’s good practice to use tools like [RequestBin](https://requestbin.com/) and [Requestly](https://requestly.io/) . These tools allow you to inspect your HTML requests, response payloads, and response headers so you can debug and test webhooks before incorporating them into your systems. Examples of JSON payloads[​](https://docs.getdbt.com/docs/deploy/webhooks#examples-of-json-payloads "Direct link to Examples of JSON payloads") ------------------------------------------------------------------------------------------------------------------------------------------------ An example of a webhook payload for a run that's started: { "accountId": 1, "webhooksID": "wsu_12345abcde", "eventId": "wev_2L6Z3l8uPedXKPq9D2nWbPIip7Z", "timestamp": "2023-01-31T19:28:15.742843678Z", "eventType": "job.run.started", "webhookName": "test", "data": { "jobId": "123", "jobName": "Daily Job (dbt build)", "runId": "12345", "environmentId": "1234", "environmentName": "Production", "dbtVersion": "1.0.0", "projectName": "Snowflake Github Demo", "projectId": "167194", "runStatus": "Running", "runStatusCode": 3, "runStatusMessage": "None", "runReason": "Kicked off from UI by test@test.com", "runStartedAt": "2023-01-31T19:28:07Z" }} An example of a webhook payload for a completed run: { "accountId": 1, "webhooksID": "wsu_12345abcde", "eventId": "wev_2L6ZDoilyiWzKkSA59Gmc2d7FDD", "timestamp": "2023-01-31T19:29:35.789265936Z", "eventType": "job.run.completed", "webhookName": "test", "data": { "jobId": "123", "jobName": "Daily Job (dbt build)", "runId": "12345", "environmentId": "1234", "environmentName": "Production", "dbtVersion": "1.0.0", "projectName": "Snowflake Github Demo", "projectId": "167194", "runStatus": "Success", "runStatusCode": 10, "runStatusMessage": "None", "runReason": "Kicked off from UI by test@test.com", "runStartedAt": "2023-01-31T19:28:07Z", "runFinishedAt": "2023-01-31T19:29:32Z" }} An example of a webhook payload for an errored run: { "accountId": 1, "webhooksID": "wsu_12345abcde", "eventId": "wev_2L6m5BggBw9uPNuSmtg4MUiW4Re", "timestamp": "2023-01-31T21:15:20.419714619Z", "eventType": "job.run.errored", "webhookName": "test", "data": { "jobId": "123", "jobName": "dbt Vault", "runId": "12345", "environmentId": "1234", "environmentName": "dbt Vault Demo", "dbtVersion": "1.0.0", "projectName": "Snowflake Github Demo", "projectId": "167194", "runStatus": "Errored", "runStatusCode": 20, "runStatusMessage": "None", "runReason": "Kicked off from UI by test@test.com", "runStartedAt": "2023-01-31T21:14:41Z", "runErroredAt": "2023-01-31T21:15:20Z" }} API for webhooks[​](https://docs.getdbt.com/docs/deploy/webhooks#api-for-webhooks "Direct link to API for webhooks") --------------------------------------------------------------------------------------------------------------------- You can use the dbt API to create new webhooks that you want to subscribe to, get detailed information about your webhooks, and to manage the webhooks that are associated with your account. The following sections describe the API endpoints you can use for this. Access URLs dbt is hosted in multiple regions in the world and each region has a different access URL. People on Enterprise-tier plans can choose to have their account hosted in any one of these regions. For a complete list of available dbt access URLs, refer to [Regions & IP addresses](https://docs.getdbt.com/docs/cloud/about-cloud/access-regions-ip-addresses) . ### List all webhook subscriptions[​](https://docs.getdbt.com/docs/deploy/webhooks#list-all-webhook-subscriptions "Direct link to List all webhook subscriptions") List all webhooks that are available from a specific dbt account. #### Request[​](https://docs.getdbt.com/docs/deploy/webhooks#request "Direct link to Request") GET https://{your access URL}/api/v3/accounts/{account_id}/webhooks/subscriptions #### Path parameters[​](https://docs.getdbt.com/docs/deploy/webhooks#path-parameters "Direct link to Path parameters") | Name | Description | | --- | --- | | `your access URL` | The login URL for your dbt account. | | `account_id` | The dbt account the webhooks are associated with. | #### Response sample[​](https://docs.getdbt.com/docs/deploy/webhooks#response-sample "Direct link to Response sample") { "data": [ { "id": "wsu_12345abcde", "account_identifier": "act_12345abcde", "name": "Webhook for jobs", "description": "A webhook for when jobs are started", "job_ids": [ "123", "321" ], "event_types": [ "job.run.started" ], "client_url": "https://test.com", "active": true, "created_at": "1675735768491774", "updated_at": "1675787482826757", "account_id": "123", "http_status_code": "0" }, { "id": "wsu_12345abcde", "account_identifier": "act_12345abcde", "name": "Notification Webhook", "description": "Webhook used to trigger notifications in Slack", "job_ids": [], "event_types": [ "job.run.completed", "job.run.started", "job.run.errored" ], "client_url": "https://test.com", "active": true, "created_at": "1674645300282836", "updated_at": "1675786085557224", "http_status_code": "410", "dispatched_at": "1675786085548538", "account_id": "123" } ], "status": { "code": 200 }, "extra": { "pagination": { "total_count": 2, "count": 2 }, "filters": { "offset": 0, "limit": 10 } }} #### Response schema[​](https://docs.getdbt.com/docs/deploy/webhooks#response-schema "Direct link to Response schema") | Name | Description | Possible Values | | --- | --- | --- | | `data` | List of available webhooks for the specified dbt account ID. | | | `id` | The webhook ID. This is a universally unique identifier (UUID) that's unique across all regions, including multi-tenant and single-tenant | | | `account_identifier` | The unique identifier for _your_ dbt account. | | | `name` | Name of the outbound webhook. | | | `description` | Description of the webhook. | | | `job_ids` | The specific jobs the webhook is set to trigger for. When the list is empty, the webhook is set to trigger for all jobs in your account; by default, dbt configures webhooks at the account level. | * Empty list
* List of job IDs | | `event_types` | The event type(s) the webhook is set to trigger on. | One or more of these:

* `job.run.started`
* `job.run.completed`
* `job.run.errored` | | `client_url` | The endpoint URL for an application where dbt can send event(s) to. | | | `active` | A Boolean value indicating whether the webhook is active or not. | One of these:

* `true`
* `false` | | `created_at` | Timestamp of when the webhook was created. | | | `updated_at` | Timestamp of when the webhook was last updated. | | | `http_status_code` | The latest HTTP status of the webhook. | Can be any [HTTP response status code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status)
. If the value is `0`, that means the webhook has never been triggered. | | `dispatched_at` | Timestamp of when the webhook was last dispatched to the specified endpoint URL. | | | `account_id` | The dbt account ID. | | ### Get details about a webhook[​](https://docs.getdbt.com/docs/deploy/webhooks#get-details-about-a-webhook "Direct link to Get details about a webhook") Get detailed information about a specific webhook. #### Request[​](https://docs.getdbt.com/docs/deploy/webhooks#request-1 "Direct link to Request") GET https://{your access URL}/api/v3/accounts/{account_id}/webhooks/subscription/{webhook_id} #### Path parameters[​](https://docs.getdbt.com/docs/deploy/webhooks#path-parameters-1 "Direct link to Path parameters") | Name | Description | | --- | --- | | `your access URL` | The login URL for your dbt account. | | `account_id` | The dbt account the webhook is associated with. | | `webhook_id` | The webhook you want detailed information on. | #### Response sample[​](https://docs.getdbt.com/docs/deploy/webhooks#response-sample-1 "Direct link to Response sample") { "data": { "id": "wsu_12345abcde", "account_identifier": "act_12345abcde", "name": "Webhook for jobs", "description": "A webhook for when jobs are started", "event_types": [ "job.run.started" ], "client_url": "https://test.com", "active": true, "created_at": "1675789619690830", "updated_at": "1675793192536729", "dispatched_at": "1675793192533160", "account_id": "123", "job_ids": [], "http_status_code": "0" }, "status": { "code": 200 }} #### Response schema[​](https://docs.getdbt.com/docs/deploy/webhooks#response-schema-1 "Direct link to Response schema") | Name | Description | Possible Values | | --- | --- | --- | | `id` | The webhook ID. | | | `account_identifier` | The unique identifier for _your_ dbt account. | | | `name` | Name of the outbound webhook. | | | `description` | Complete description of the webhook. | | | `event_types` | The event type the webhook is set to trigger on. | One or more of these:

* `job.run.started`
* `job.run.completed`
* `job.run.errored` | | `client_url` | The endpoint URL for an application where dbt can send event(s) to. | | | `active` | A Boolean value indicating whether the webhook is active or not. | One of these:

* `true`
* `false` | | `created_at` | Timestamp of when the webhook was created. | | | `updated_at` | Timestamp of when the webhook was last updated. | | | `dispatched_at` | Timestamp of when the webhook was last dispatched to the specified endpoint URL. | | | `account_id` | The dbt account ID. | | | `job_ids` | The specific jobs the webhook is set to trigger for. When the list is empty, the webhook is set to trigger for all jobs in your account; by default, dbt configures webhooks at the account level. | One of these:

* Empty list
* List of job IDs | | `http_status_code` | The latest HTTP status of the webhook. | Can be any [HTTP response status code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status)
. If the value is `0`, that means the webhook has never been triggered. | ### Create a new webhook subscription[​](https://docs.getdbt.com/docs/deploy/webhooks#create-a-new-webhook-subscription "Direct link to Create a new webhook subscription") Create a new outbound webhook and specify the endpoint URL that will be subscribing (listening) to the webhook's events. #### Request sample[​](https://docs.getdbt.com/docs/deploy/webhooks#request-sample "Direct link to Request sample") POST https://{your access URL}/api/v3/accounts/{account_id}/webhooks/subscriptions { "event_types": [ "job.run.started" ], "name": "Webhook for jobs", "client_url": "https://test.com", "active": true, "description": "A webhook for when jobs are started", "job_ids": [ 123, 321 ]} #### Path parameters[​](https://docs.getdbt.com/docs/deploy/webhooks#path-parameters-2 "Direct link to Path parameters") | Name | Description | | --- | --- | | `your access URL` | The login URL for your dbt account. | | `account_id` | The dbt account the webhook is associated with. | #### Request parameters[​](https://docs.getdbt.com/docs/deploy/webhooks#request-parameters "Direct link to Request parameters") | Name | Description | Possible Values | | --- | --- | --- | | `event_types` | Enter the event you want to trigger this webhook. You can subscribe to more than one event. | One or more of these:

* `job.run.started`
* `job.run.completed`
* `job.run.errored` | | `name` | Enter the name of your webhook. | | | `client_url` | Enter your application's endpoint URL, where dbt can send the event(s) to. | | | `active` | Enter a Boolean value to indicate whether your webhook is active or not. | One of these:

* `true`
* `false` | | `description` | Enter a description of your webhook. | | | `job_ids` | Enter the specific jobs you want the webhook to trigger on or you can leave this parameter as an empty list. If this is an empty list, the webhook is set to trigger for all jobs in your account; by default, dbt configures webhooks at the account level. | One of these:

* Empty list
* List of job IDs | #### Response sample[​](https://docs.getdbt.com/docs/deploy/webhooks#response-sample-2 "Direct link to Response sample") { "data": { "id": "wsu_12345abcde", "account_identifier": "act_12345abcde", "name": "Webhook for jobs", "description": "A webhook for when jobs are started", "job_ids": [ "123", "321" ], "event_types": [ "job.run.started" ], "client_url": "https://test.com", "hmac_secret": "12345abcde", "active": true, "created_at": "1675795644808877", "updated_at": "1675795644808877", "account_id": "123", "http_status_code": "0" }, "status": { "code": 201 }} #### Response schema[​](https://docs.getdbt.com/docs/deploy/webhooks#response-schema-2 "Direct link to Response schema") | Name | Description | Possible Values | | --- | --- | --- | | `id` | The webhook ID. | | | `account_identifier` | The unique identifier for _your_ dbt account. | | | `name` | Name of the outbound webhook. | | | `description` | Complete description of the webhook. | | | `job_ids` | The specific jobs the webhook is set to trigger for. When the list is empty, the webhook is set to trigger for all jobs in your account; by default, dbt configures webhooks at the account level. | One of these:

* Empty list
* List of job IDs | | `event_types` | The event type the webhook is set to trigger on. | One or more of these:

* `job.run.started`
* `job.run.completed`
* `job.run.errored` | | `client_url` | The endpoint URL for an application where dbt can send event(s) to. | | | `hmac_secret` | The secret key for your new webhook. You can use this key to [validate the authenticity of this webhook](https://docs.getdbt.com/docs/deploy/webhooks#validate-a-webhook)
. | | | `active` | A Boolean value indicating whether the webhook is active or not. | One of these:

* `true`
* `false` | | `created_at` | Timestamp of when the webhook was created. | | | `updated_at` | Timestamp of when the webhook was last updated. | | | `account_id` | The dbt account ID. | | | `http_status_code` | The latest HTTP status of the webhook. | Can be any [HTTP response status code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status)
. If the value is `0`, that means the webhook has never been triggered. | ### Update a webhook[​](https://docs.getdbt.com/docs/deploy/webhooks#update-a-webhook "Direct link to Update a webhook") Update the configuration details for a specific webhook. #### Request sample[​](https://docs.getdbt.com/docs/deploy/webhooks#request-sample-1 "Direct link to Request sample") PUT https://{your access URL}/api/v3/accounts/{account_id}/webhooks/subscription/{webhook_id} { "event_types": [ "job.run.started" ], "name": "Webhook for jobs", "client_url": "https://test.com", "active": true, "description": "A webhook for when jobs are started", "job_ids": [ 123, 321 ]} #### Path parameters[​](https://docs.getdbt.com/docs/deploy/webhooks#path-parameters-3 "Direct link to Path parameters") | Name | Description | | --- | --- | | `your access URL` | The login URL for your dbt account. | | `account_id` | The dbt account the webhook is associated with. | | `webhook_id` | The webhook you want to update. | #### Request parameters[​](https://docs.getdbt.com/docs/deploy/webhooks#request-parameters-1 "Direct link to Request parameters") | Name | Description | Possible Values | | --- | --- | --- | | `event_types` | Update the event type the webhook is set to trigger on. You can subscribe to more than one. | One or more of these:

* `job.run.started`
* `job.run.completed`
* `job.run.errored` | | `name` | Change the name of your webhook. | | | `client_url` | Update the endpoint URL for an application where dbt can send event(s) to. | | | `active` | Change the Boolean value indicating whether the webhook is active or not. | One of these:

* `true`
* `false` | | `description` | Update the webhook's description. | | | `job_ids` | Change which jobs you want the webhook to trigger for. Or, you can use an empty list to trigger it for all jobs in your account. | One of these:

* Empty list
* List of job IDs | #### Response sample[​](https://docs.getdbt.com/docs/deploy/webhooks#response-sample-3 "Direct link to Response sample") { "data": { "id": "wsu_12345abcde", "account_identifier": "act_12345abcde", "name": "Webhook for jobs", "description": "A webhook for when jobs are started", "job_ids": [ "123" ], "event_types": [ "job.run.started" ], "client_url": "https://test.com", "active": true, "created_at": "1675798888416144", "updated_at": "1675804719037018", "http_status_code": "200", "account_id": "123" }, "status": { "code": 200 }} #### Response schema[​](https://docs.getdbt.com/docs/deploy/webhooks#response-schema-3 "Direct link to Response schema") | Name | Description | Possible Values | | --- | --- | --- | | `id` | The webhook ID. | | | `account_identifier` | The unique identifier for _your_ dbt account. | | | `name` | Name of the outbound webhook. | | | `description` | Complete description of the webhook. | | | `job_ids` | The specific jobs the webhook is set to trigger for. When the list is empty, the webhook is set to trigger for all jobs in your account; by default, dbt configures webhooks at the account level. | One of these:

* Empty list
* List of job IDs | | `event_types` | The event type the webhook is set to trigger on. | One or more of these:

* `job.run.started`
* `job.run.completed`
* `job.run.errored` | | `client_url` | The endpoint URL for an application where dbt can send event(s) to. | | | `active` | A Boolean value indicating whether the webhook is active or not. | One of these:

* `true`
* `false` | | `created_at` | Timestamp of when the webhook was created. | | | `updated_at` | Timestamp of when the webhook was last updated. | | | `http_status_code` | The latest HTTP status of the webhook. | Can be any [HTTP response status code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status)
. If the value is `0`, that means the webhook has never been triggered. | | `account_id` | The dbt account ID. | | ### Test a webhook[​](https://docs.getdbt.com/docs/deploy/webhooks#test-a-webhook "Direct link to Test a webhook") Test a specific webhook. #### Request[​](https://docs.getdbt.com/docs/deploy/webhooks#request-2 "Direct link to Request") GET https://{your access URL}/api/v3/accounts/{account_id}/webhooks/subscription/{webhook_id}/test #### Path parameters[​](https://docs.getdbt.com/docs/deploy/webhooks#path-parameters-4 "Direct link to Path parameters") | Name | Description | | --- | --- | | `your access URL` | The login URL for your dbt account. | | `account_id` | The dbt account the webhook is associated with. | | `webhook_id` | The webhook you want to test. | #### Response sample[​](https://docs.getdbt.com/docs/deploy/webhooks#response-sample-4 "Direct link to Response sample") { "data": { "verification_error": null, "verification_status_code": "200" }, "status": { "code": 200 }} ### Delete a webhook[​](https://docs.getdbt.com/docs/deploy/webhooks#delete-a-webhook "Direct link to Delete a webhook") Delete a specific webhook. #### Request[​](https://docs.getdbt.com/docs/deploy/webhooks#request-3 "Direct link to Request") DELETE https://{your access URL}/api/v3/accounts/{account_id}/webhooks/subscription/{webhook_id} #### Path parameters[​](https://docs.getdbt.com/docs/deploy/webhooks#path-parameters-5 "Direct link to Path parameters") | Name | Description | | --- | --- | | `your access URL` | The login URL for your dbt account. | | `account_id` | The dbt account the webhook is associated with. | | `webhook_id` | The webhook you want to delete. | #### Response sample[​](https://docs.getdbt.com/docs/deploy/webhooks#response-sample-5 "Direct link to Response sample") { "data": { "id": "wsu_12345abcde" }, "status": { "code": 200, "is_success": true }} Related docs[​](https://docs.getdbt.com/docs/deploy/webhooks#related-docs "Direct link to Related docs") --------------------------------------------------------------------------------------------------------- * [dbt CI](https://docs.getdbt.com/docs/deploy/continuous-integration) * [Use dbt's webhooks with other SaaS apps](https://docs.getdbt.com/guides?tags=Webhooks) Troubleshooting[​](https://docs.getdbt.com/docs/deploy/webhooks#troubleshooting "Direct link to Troubleshooting") ------------------------------------------------------------------------------------------------------------------ If your destination system isn't receiving dbt webhooks, ensure it allows Authorization headers. dbt webhooks send an Authorization header, and if your endpoint doesn't support this, it may be incompatible. Services like Azure Logic Apps and Power Automate may not accept Authorization headers, so they won't work with dbt webhooks. You can test your endpoint's support by sending a request with curl and an Authorization header, like this: curl -H 'Authorization: 123' -X POST https:// Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Prerequisites](https://docs.getdbt.com/docs/deploy/webhooks#prerequisites) * [Create a webhook subscription](https://docs.getdbt.com/docs/deploy/webhooks#create-a-webhook-subscription) * [Differences between completed and errored webhook events](https://docs.getdbt.com/docs/deploy/webhooks#completed-errored-event-difference) * [Validate a webhook](https://docs.getdbt.com/docs/deploy/webhooks#validate-a-webhook) * [Inspect HTTP requests](https://docs.getdbt.com/docs/deploy/webhooks#inspect-http-requests) * [Examples of JSON payloads](https://docs.getdbt.com/docs/deploy/webhooks#examples-of-json-payloads) * [API for webhooks](https://docs.getdbt.com/docs/deploy/webhooks#api-for-webhooks) * [List all webhook subscriptions](https://docs.getdbt.com/docs/deploy/webhooks#list-all-webhook-subscriptions) * [Get details about a webhook](https://docs.getdbt.com/docs/deploy/webhooks#get-details-about-a-webhook) * [Create a new webhook subscription](https://docs.getdbt.com/docs/deploy/webhooks#create-a-new-webhook-subscription) * [Update a webhook](https://docs.getdbt.com/docs/deploy/webhooks#update-a-webhook) * [Test a webhook](https://docs.getdbt.com/docs/deploy/webhooks#test-a-webhook) * [Delete a webhook](https://docs.getdbt.com/docs/deploy/webhooks#delete-a-webhook) * [Related docs](https://docs.getdbt.com/docs/deploy/webhooks#related-docs) * [Troubleshooting](https://docs.getdbt.com/docs/deploy/webhooks#troubleshooting) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/deploy/webhooks.md) --- # Job notifications | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/deploy/job-notifications#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page Set up notifications in dbt to receive email or Slack alerts about the status of a job run. You can choose to be notified by one or more of the following job run statuses: * **Succeeds** option — A job run completed successfully with no warnings or errors. * **Warns** option — A job run encountered warnings from [data tests](https://docs.getdbt.com/docs/build/data-tests) or [source freshness](https://docs.getdbt.com/docs/deploy/source-freshness) checks (if applicable). * **Fails** option — A job run failed to complete. * **Is canceled** option — A job run is canceled. Email notifications[​](https://docs.getdbt.com/docs/deploy/job-notifications#email-notifications "Direct link to Email notifications") --------------------------------------------------------------------------------------------------------------------------------------- You can receive email alerts about jobs by configuring the dbt email notification settings. ### Prerequisites[​](https://docs.getdbt.com/docs/deploy/job-notifications#prerequisites "Direct link to Prerequisites") * You must be either a _developer user_ or an _account admin_ to configure email notifications in dbt. For more details, refer to [Users and licenses](https://docs.getdbt.com/docs/cloud/manage-access/seats-and-users) . * As a developer user, you can set up email notifications for yourself. * As an account admin, you can set up notifications for yourself and other team members. ### Configure email notifications[​](https://docs.getdbt.com/docs/deploy/job-notifications#configure-email-notifications "Direct link to Configure email notifications") 1. Select your profile icon and then click **Notification settings**. 2. By default, dbt sends notifications to the email address that's in your **User profile** page. If you're an account admin, you can choose a different email address to receive notifications. Select the **Notification email** dropdown and choose another address from the list. The list includes **Internal Users** with access to the account and **External Emails** that have been added. * To add an external email address, select the **Notification email** dropdown and choose **Add external email**. After you add the external email, it becomes available for selection in the **Notification email** dropdown list. External emails can be addresses that are outside of your dbt account and also for third-party integrations like [channels in Microsoft Teams](https://support.microsoft.com/en-us/office/tip-send-email-to-a-channel-2c17dbae-acdf-4209-a761-b463bdaaa4ca) and [PagerDuty email integration](https://support.pagerduty.com/docs/email-integration-guide) . [![Example of the Notification email dropdown](https://docs.getdbt.com/img/docs/deploy/example-notification-external-email.png?v=2 "Example of the Notification email dropdown")](https://docs.getdbt.com/docs/deploy/job-notifications#) Example of the Notification email dropdown 3. Select the **Environment** for the jobs you want to receive notifications about from the dropdown. 4. Click **Edit** to configure the email notification settings. Choose one or more of the run statuses for each job you want to receive notifications about. 5. When you're done with the settings, click **Save**. As an account admin, you can add more email recipients by choosing another **Notification email** from the dropdown, **Edit** the job notification settings, and **Save** the changes. To set up alerts on jobs from a different environment, select another **Environment** from the dropdown, **Edit** those job notification settings, and **Save** the changes. [![Example of the Email notifications page](https://docs.getdbt.com/img/docs/deploy/example-email-notification-settings-page.png?v=2 "Example of the Email notifications page")](https://docs.getdbt.com/docs/deploy/job-notifications#) Example of the Email notifications page ### Unsubscribe from email notifications[​](https://docs.getdbt.com/docs/deploy/job-notifications#unsubscribe-from-email-notifications "Direct link to Unsubscribe from email notifications") 1. Select your profile icon and click on **Notification settings**. 2. On the **Email notifications** page, click **Unsubscribe from all email notifications**. Slack notifications[​](https://docs.getdbt.com/docs/deploy/job-notifications#slack-notifications "Direct link to Slack notifications") --------------------------------------------------------------------------------------------------------------------------------------- You can receive Slack alerts about jobs by setting up the Slack integration and then configuring the dbt Slack notification settings. dbt integrates with Slack via OAuth to ensure secure authentication. note Virtual Private Cloud (VPC) admins must [contact support](mailto:support@getdbt.com) to complete the Slack integration. If there has been a change in user roles or Slack permissions where you no longer have access to edit a configured Slack channel, please [contact support](mailto:support@getdbt.com) for assistance. ### Prerequisites[​](https://docs.getdbt.com/docs/deploy/job-notifications#prerequisites-1 "Direct link to Prerequisites") * You must be a Slack Workspace Owner. * You must be an account admin to configure Slack notifications in dbt. For more details, refer to [Users and licenses](https://docs.getdbt.com/docs/cloud/manage-access/seats-and-users) . * The integration only supports _public_ channels in the Slack workspace. ### Set up the Slack integration[​](https://docs.getdbt.com/docs/deploy/job-notifications#set-up-the-slack-integration "Direct link to Set up the Slack integration") 1. Select **Account settings** and then select **Integrations** from the left sidebar. 2. Locate the **OAuth** section with the Slack application and click **Link**. [![Link for the Slack app](https://docs.getdbt.com/img/docs/dbt-cloud/Link-your-Slack-Profile.png?v=2 "Link for the Slack app")](https://docs.getdbt.com/docs/deploy/job-notifications#) Link for the Slack app #### Logged in to Slack[​](https://docs.getdbt.com/docs/deploy/job-notifications#logged-in-to-slack "Direct link to Logged in to Slack") If you're already logged in to Slack, the handshake only requires allowing the app access. If you're a member of multiple workspaces, you can select the appropriate workspace from the dropdown menu in the upper right corner. [![Allow dbt access to Slack](https://docs.getdbt.com/img/docs/dbt-cloud/Allow-dbt-to-access-slack.png?v=2 "Allow dbt access to Slack")](https://docs.getdbt.com/docs/deploy/job-notifications#) Allow dbt access to Slack #### Logged out[​](https://docs.getdbt.com/docs/deploy/job-notifications#logged-out "Direct link to Logged out") If you're logged out or the Slack app/website is closed, you must authenticate before completing the integration. 1. Complete the field defining the Slack workspace you want to integrate with dbt. [![Define the workspace](https://docs.getdbt.com/img/docs/dbt-cloud/define-workspace.png?v=2 "Define the workspace")](https://docs.getdbt.com/docs/deploy/job-notifications#) Define the workspace 2. Sign in with an existing identity or use the email address and password. 3. Once you have authenticated successfully, accept the permissions. [![Allow dbt access to Slack](https://docs.getdbt.com/img/docs/dbt-cloud/accept-permissions.png?v=2 "Allow dbt access to Slack")](https://docs.getdbt.com/docs/deploy/job-notifications#) Allow dbt access to Slack ### Configure Slack notifications[​](https://docs.getdbt.com/docs/deploy/job-notifications#configure-slack-notifications "Direct link to Configure Slack notifications") 1. Select your profile icon and then click on **Notification settings**. 2. Select **Slack notifications** in the left sidebar. 3. Select the **Notification channel** you want to receive the job run notifications from the dropdown. [![Example of the Notification channel dropdown](https://docs.getdbt.com/img/docs/deploy/example-notification-slack-channels.png?v=2 "Example of the Notification channel dropdown")](https://docs.getdbt.com/docs/deploy/job-notifications#) Example of the Notification channel dropdown 4. Select the **Environment** for the jobs you want to receive notifications about from the dropdown. 5. Click **Edit** to configure the Slack notification settings. Choose one or more of the run statuses for each job you want to receive notifications about. 6. When you're done with the settings, click **Save**. To send alerts to another Slack channel, select another **Notification channel** from the dropdown, **Edit** those job notification settings, and **Save** the changes. To set up alerts on jobs from a different environment, select another **Environment** from the dropdown, **Edit** those job notification settings, and **Save** the changes. [![Example of the Slack notifications page](https://docs.getdbt.com/img/docs/deploy/example-slack-notification-settings-page.png?v=2 "Example of the Slack notifications page")](https://docs.getdbt.com/docs/deploy/job-notifications#) Example of the Slack notifications page ### Disable the Slack integration[​](https://docs.getdbt.com/docs/deploy/job-notifications#disable-the-slack-integration "Direct link to Disable the Slack integration") 1. Select **Account settings** and on the **Integrations** page, scroll to the **OAuth** section. 2. Click the trash can icon (on the far right of the Slack integration) and click **Unlink**. Channels that you configured will no longer receive Slack notifications. _This is not an account-wide action._ Channels configured by other account admins will continue to receive Slack notifications if they still have active Slack integrations. To migrate ownership of a Slack channel notification configuration, have another account admin edit their configuration. Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Email notifications](https://docs.getdbt.com/docs/deploy/job-notifications#email-notifications) * [Prerequisites](https://docs.getdbt.com/docs/deploy/job-notifications#prerequisites) * [Configure email notifications](https://docs.getdbt.com/docs/deploy/job-notifications#configure-email-notifications) * [Unsubscribe from email notifications](https://docs.getdbt.com/docs/deploy/job-notifications#unsubscribe-from-email-notifications) * [Slack notifications](https://docs.getdbt.com/docs/deploy/job-notifications#slack-notifications) * [Prerequisites](https://docs.getdbt.com/docs/deploy/job-notifications#prerequisites-1) * [Set up the Slack integration](https://docs.getdbt.com/docs/deploy/job-notifications#set-up-the-slack-integration) * [Configure Slack notifications](https://docs.getdbt.com/docs/deploy/job-notifications#configure-slack-notifications) * [Disable the Slack integration](https://docs.getdbt.com/docs/deploy/job-notifications#disable-the-slack-integration) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/deploy/job-notifications.md) --- # Administer the Semantic Layer | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/use-dbt-semantic-layer/setup-sl#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page With the dbt Semantic Layer, you can centrally define business metrics, reduce code duplication and inconsistency, create self-service in downstream tools, and more. This topic shows you how to set up credentials and tokens so that other tools can query the Semantic Layer. Not yet supported in the dbt Fusion engine Semantic Layer is currently supported in the dbt platform for environments running versions of dbt Core. Support for environments on the dbt Fusion engine is coming soon. Prerequisites[​](https://docs.getdbt.com/docs/use-dbt-semantic-layer/setup-sl#prerequisites "Direct link to Prerequisites") ---------------------------------------------------------------------------------------------------------------------------- * Have a dbt Starter, Enterprise, or Enterprise+ account. Available on all [tenant configurations](https://docs.getdbt.com/docs/cloud/about-cloud/tenancy) . * Ensure your production and development environments are on a [supported dbt version](https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-version-in-cloud) . * Use Snowflake, BigQuery, Databricks, Redshift, Postgres, or Trino. * Create a successful run in the environment where you configure the Semantic Layer. * **Note:** Semantic Layer supports querying in Deployment environments; development querying is coming soon. * Understand [MetricFlow's](https://docs.getdbt.com/docs/build/about-metricflow) key concepts powering the Semantic Layer. * Note that the Semantic Layer doesn't support using [Single sign-on (SSO)](https://docs.getdbt.com/docs/cloud/manage-access/sso-overview) for [production credentials](https://docs.getdbt.com/docs/dbt-cloud-apis/service-tokens#permissions-for-service-account-tokens) , though SSO is supported for development user accounts. 📹 Learn about the dbt Semantic Layer with on-demand video courses! Explore our [dbt Semantic Layer on-demand course](https://learn.getdbt.com/courses/semantic-layer) to learn how to define and query metrics in your dbt project. Additionally, dive into mini-courses for querying the dbt Semantic Layer in your favorite tools: [Tableau](https://courses.getdbt.com/courses/tableau-querying-the-semantic-layer) , [Excel](https://learn.getdbt.com/courses/querying-the-semantic-layer-with-excel) , [Hex](https://courses.getdbt.com/courses/hex-querying-the-semantic-layer) , and [Mode](https://courses.getdbt.com/courses/mode-querying-the-semantic-layer) . Administer the Semantic Layer[​](https://docs.getdbt.com/docs/use-dbt-semantic-layer/setup-sl#administer-the-semantic-layer "Direct link to Administer the Semantic Layer") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- You must be part of the Owner group and have the correct [license](https://docs.getdbt.com/docs/cloud/manage-access/seats-and-users) and [permissions](https://docs.getdbt.com/docs/cloud/manage-access/enterprise-permissions) to administer the Semantic Layer at the environment and project level. * Enterprise+ and Enterprise plan: * Developer license with Account Admin permissions, or * Owner with a Developer license, assigned Project Creator, Database Admin, or Admin permissions. * Starter plan: Owner with a Developer license. * Free trial: You are on a free trial of the Starter plan as an Owner, which means you have access to the dbt Semantic Layer. ### 1\. Select environment[​](https://docs.getdbt.com/docs/use-dbt-semantic-layer/setup-sl#1-select-environment "Direct link to 1. Select environment") Select the environment where you want to enable the Semantic Layer: 1. Navigate to **Account settings** in the navigation menu. 2. Under **Settings**, click **Projects** and select the specific project you want to enable the Semantic Layer for. 3. In the **Project details** page, navigate to the **Semantic Layer** section. Select **Configure Semantic Layer**. [![Semantic Layer section in the 'Project details' page](https://docs.getdbt.com/img/docs/dbt-cloud/semantic-layer/new-sl-configure.png?v=2 "Semantic Layer section in the 'Project details' page")](https://docs.getdbt.com/docs/use-dbt-semantic-layer/setup-sl#) Semantic Layer section in the 'Project details' page 4. In the **Set Up Semantic Layer Configuration** page, select the deployment environment you want for the Semantic Layer and click **Save**. This provides administrators with the flexibility to choose the environment where the Semantic Layer will be enabled. [![Select the deployment environment to run your Semantic Layer against.](https://docs.getdbt.com/img/docs/dbt-cloud/semantic-layer/sl-select-env.png?v=2 "Select the deployment environment to run your Semantic Layer against.")](https://docs.getdbt.com/docs/use-dbt-semantic-layer/setup-sl#) Select the deployment environment to run your Semantic Layer against. ### 2\. Configure credentials and create tokens[​](https://docs.getdbt.com/docs/use-dbt-semantic-layer/setup-sl#2-configure-credentials-and-create-tokens "Direct link to 2. Configure credentials and create tokens") There are two options for setting up Semantic Layer using API tokens: * [Add a credential and create service tokens](https://docs.getdbt.com/docs/use-dbt-semantic-layer/setup-sl#add-a-credential-and-create-service-tokens) * [Configure development credentials and create personal tokens](https://docs.getdbt.com/docs/use-dbt-semantic-layer/setup-sl#configure-development-credentials-and-create-a-personal-token) #### Add a credential and create service tokens[​](https://docs.getdbt.com/docs/use-dbt-semantic-layer/setup-sl#add-a-credential-and-create-service-tokens "Direct link to Add a credential and create service tokens") The first option is to use [service tokens](https://docs.getdbt.com/docs/dbt-cloud-apis/service-tokens) for authentication which are tied to an underlying data platform credential that you configure. The credential configured is used to execute queries that the Semantic Layer issues against your data platform. This credential controls the physical access to underlying data accessed by the Semantic Layer, and all access policies set in the data platform for this credential will be respected. | Feature | Starter plan | Enterprise+ and Enterprise plan | | --- | --- | --- | | Service tokens | Can create multiple service tokens linked to one credential. | Can use multiple credentials and link multiple service tokens to each credential. Note that you cannot link a single service token to more than one credential. | | Credentials per project | One credential per project. | Can [add multiple](https://docs.getdbt.com/docs/use-dbt-semantic-layer/setup-sl#4-add-more-credentials)
credentials per project. | | Link multiple service tokens to a single credential | ✅ | ✅ | _If you're on a Starter plan and need to add more credentials, consider upgrading to our [Enterprise+ or Enterprise plan](https://www.getdbt.com/contact) . All Enterprise users can refer to [Add more credentials](https://docs.getdbt.com/docs/use-dbt-semantic-layer/setup-sl#4-add-more-credentials) for detailed steps on adding multiple credentials._ ##### 1\. Select deployment environment[​](https://docs.getdbt.com/docs/use-dbt-semantic-layer/setup-sl#1--select-deployment-environment "Direct link to 1. Select deployment environment") * After selecting the deployment environment, you should see the **Credentials & service tokens** page. * Click the **Add Semantic Layer credential** button. ##### 2\. Configure credential[​](https://docs.getdbt.com/docs/use-dbt-semantic-layer/setup-sl#2-configure-credential "Direct link to 2. Configure credential") * In the **1\. Add credentials** section, enter the credentials specific to your data platform that you want the Semantic Layer to use. * Use credentials with minimal privileges. The Semantic Layer requires read access to the schema(s) containing the dbt models used in your semantic models for downstream applications * Use [Extended Attributes](https://docs.getdbt.com/docs/dbt-cloud-environments#extended-attributes) and [Environment Variables](https://docs.getdbt.com/docs/build/environment-variables) when connecting to the Semantic Layer. If you set a value directly in the Semantic Layer Credentials, it will have a higher priority than Extended Attributes. When using environment variables, the default value for the environment will be used. For example, set the warehouse by using `{{env_var('DBT_WAREHOUSE')}}` in your Semantic Layer credentials. Similarly, if you set the account value using `{{env_var('DBT_ACCOUNT')}}` in Extended Attributes, dbt will check both the Extended Attributes and the environment variable. [![Add credentials and map them to a service token. ](https://docs.getdbt.com/img/docs/dbt-cloud/semantic-layer/sl-add-credential.png?v=2 "Add credentials and map them to a service token. ")](https://docs.getdbt.com/docs/use-dbt-semantic-layer/setup-sl#) Add credentials and map them to a service token. ##### 3\. Create or link service tokens[​](https://docs.getdbt.com/docs/use-dbt-semantic-layer/setup-sl#3-create-or-link-service-tokens "Direct link to 3. Create or link service tokens") * If you have permission to create service tokens, you’ll see the [**Map new service token** option](https://docs.getdbt.com/docs/use-dbt-semantic-layer/setup-sl#map-service-tokens-to-credentials) after adding the credential. Name the token, set permissions to 'Semantic Layer Only' and 'Metadata Only', and click **Save**. * Once the token is generated, you won't be able to view this token again, so make sure to record it somewhere safe. * If you don’t have access to create service tokens, you’ll see a message prompting you to contact your admin to create one for you. Admins can create and link tokens as needed. [![If you don’t have access to create service tokens, you can create a credential and contact your admin to create one for you.](https://docs.getdbt.com/img/docs/dbt-cloud/semantic-layer/sl-credential-no-service-token.png?v=2 "If you don’t have access to create service tokens, you can create a credential and contact your admin to create one for you.")](https://docs.getdbt.com/docs/use-dbt-semantic-layer/setup-sl#) If you don’t have access to create service tokens, you can create a credential and contact your admin to create one for you. info * Starter plans can create multiple service tokens that link to a single underlying credential, but each project can only have one credential. * All Enterprise plans can [add multiple credentials](https://docs.getdbt.com/docs/use-dbt-semantic-layer/setup-sl#4-add-more-credentials) and map those to service tokens for tailored access. [Book a free live demo](https://www.getdbt.com/contact) to discover the full potential of dbt Enterprise and higher plans. #### Configure development credentials and create a personal token[​](https://docs.getdbt.com/docs/use-dbt-semantic-layer/setup-sl#configure-development-credentials-and-create-a-personal-token "Direct link to Configure development credentials and create a personal token") Using [personal access tokens (PATs)](https://docs.getdbt.com/docs/dbt-cloud-apis/user-tokens) is also a supported authentication method for the dbt Semantic Layer. This enables user-level authentication, reducing the need for sharing tokens between users. When you authenticate using PATs, queries are run using your personal development credentials. To use PATs in Semantic Layer: 1. Configure your development credentials. 1. Click your account name at the bottom left-hand menu and go to **Account settings** > **Credentials**. 2. Select your project. 3. Click **Edit**. 4. Go to **Development credentials** and enter your details. 5. Click **Save**. 2. [Create a personal access token](https://docs.getdbt.com/docs/dbt-cloud-apis/user-tokens) . Make sure to copy the token. You can use the generated PAT as the authentication method for Semantic Layer [APIs](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-api-overview) and [integrations](https://docs.getdbt.com/docs/cloud-integrations/avail-sl-integrations) . ### 3\. View connection detail[​](https://docs.getdbt.com/docs/use-dbt-semantic-layer/setup-sl#3-view-connection-detail "Direct link to 3. View connection detail") 1. Go back to the **Project details** page for connection details to connect to downstream tools. 2. Copy and share the Environment ID, service or personal token, Host, as well as the service or personal token name to the relevant teams for BI connection setup. If your tool uses the GraphQL API, save the GraphQL API host information instead of the JDBC URL. For info on how to connect to other integrations, refer to [Available integrations](https://docs.getdbt.com/docs/cloud-integrations/avail-sl-integrations) . [![After configuring, you'll be provided with the connection details to connect to you downstream tools.](https://docs.getdbt.com/img/docs/dbt-cloud/semantic-layer/sl-configure-example.png?v=2 "After configuring, you'll be provided with the connection details to connect to you downstream tools.")](https://docs.getdbt.com/docs/use-dbt-semantic-layer/setup-sl#) After configuring, you'll be provided with the connection details to connect to you downstream tools. ### 4\. Add more credentials [Enterprise +](https://www.getdbt.com/pricing "Go to https://www.getdbt.com/pricing") [Enterprise](https://www.getdbt.com/pricing "Go to https://www.getdbt.com/pricing") [​](https://docs.getdbt.com/docs/use-dbt-semantic-layer/setup-sl#4-add-more-credentials- "Direct link to 4-add-more-credentials-") All dbt Enterprise plans can optionally add multiple credentials and map them to service tokens, offering more granular control and tailored access for different teams, which can then be shared to relevant teams for BI connection setup. These credentials control the physical access to underlying data accessed by the Semantic Layer. We recommend configuring credentials and service tokens to reflect your teams and their roles. For example, create tokens or credentials that align with your team's needs, such as providing access to finance-related schemas to the Finance team.  Considerations for linking credentials * Admins can link multiple service tokens to a single credential within a project, but each service token can only be linked to one credential per project. * When you send a request through the APIs, the service token of the linked credential will follow access policies of the underlying view and tables used to build your semantic layer requests. * Use [Extended Attributes](https://docs.getdbt.com/docs/dbt-cloud-environments#extended-attributes) and [Environment Variables](https://docs.getdbt.com/docs/build/environment-variables) when connecting to the Semantic Layer. If you set a value directly in the Semantic Layer Credentials, it will have a higher priority than Extended Attributes. When using environment variables, the default value for the environment will be used. For example, set the warehouse by using `{{env_var('DBT_WAREHOUSE')}}` in your Semantic Layer credentials. Similarly, if you set the account value using `{{env_var('DBT_ACCOUNT')}}` in Extended Attributes, dbt will check both the Extended Attributes and the environment variable. #### 1\. Add more credentials[​](https://docs.getdbt.com/docs/use-dbt-semantic-layer/setup-sl#1-add-more-credentials "Direct link to 1. Add more credentials") * After configuring your environment, on the **Credentials & service tokens** page, click the **Add Semantic Layer credential** button to create multiple credentials and map them to a service token. * In the **1\. Add credentials** section, fill in the data platform's credential fields. We recommend using “read-only” credentials. [![Add credentials and map them to a service token. ](https://docs.getdbt.com/img/docs/dbt-cloud/semantic-layer/sl-add-credential.png?v=2 "Add credentials and map them to a service token. ")](https://docs.getdbt.com/docs/use-dbt-semantic-layer/setup-sl#) Add credentials and map them to a service token. #### 2\. Map service tokens to credentials[​](https://docs.getdbt.com/docs/use-dbt-semantic-layer/setup-sl#2-map-service-tokens-to-credentials "Direct link to 2. Map service tokens to credentials") * In the **2\. Map new service token** section, [map a service token to the credential](https://docs.getdbt.com/docs/use-dbt-semantic-layer/setup-sl#map-service-tokens-to-credentials) you configured in the previous step. dbt automatically selects the service token permission set you need (Semantic Layer Only and Metadata Only). * To add another service token during configuration, click **Add Service Token**. * You can link more service tokens to the same credential later on in the **Semantic Layer Configuration Details** page. To add another service token to an existing Semantic Layer configuration, click **Add service token** under the **Linked service tokens** section. * Click **Save** to link the service token to the credential. Remember to copy and save the service token securely, as it won't be viewable again after generation. [![Use the configuration page to manage multiple credentials or link or unlink service tokens for more granular control.](https://docs.getdbt.com/img/docs/dbt-cloud/semantic-layer/sl-credentials-service-token.png?v=2 "Use the configuration page to manage multiple credentials or link or unlink service tokens for more granular control.")](https://docs.getdbt.com/docs/use-dbt-semantic-layer/setup-sl#) Use the configuration page to manage multiple credentials or link or unlink service tokens for more granular control. #### 3\. Delete credentials[​](https://docs.getdbt.com/docs/use-dbt-semantic-layer/setup-sl#3-delete-credentials "Direct link to 3. Delete credentials") * To delete a credential, go back to the **Credentials & service tokens** page. * Under **Linked Service Tokens**, click **Edit** and, select **Delete Credential** to remove a credential. When you delete a credential, any service tokens mapped to that credential in the project will no longer work and will break for any end users. ### Delete configuration[​](https://docs.getdbt.com/docs/use-dbt-semantic-layer/setup-sl#delete-configuration "Direct link to Delete configuration") You can delete the entire Semantic Layer configuration for a project. Note that deleting the Semantic Layer configuration will remove all credentials and unlink all service tokens to the project. It will also cause all queries to the Semantic Layer to fail. Follow these steps to delete the Semantic Layer configuration for a project: 1. Navigate to the **Project details** page. 2. In the **Semantic Layer** section, select **Delete Semantic Layer**. 3. Confirm the deletion by clicking **Yes, delete semantic layer** in the confirmation pop up. To re-enable the dbt Semantic Layer setup in the future, you will need to recreate your setup configurations by following the [previous steps](https://docs.getdbt.com/docs/use-dbt-semantic-layer/setup-sl#set-up-dbt-semantic-layer) . If your semantic models and metrics are still in your project, no changes are needed. If you've removed them, you'll need to set up the YAML configs again. [![Delete the Semantic Layer configuration for a project.](https://docs.getdbt.com/img/docs/dbt-cloud/semantic-layer/sl-delete-config.png?v=2 "Delete the Semantic Layer configuration for a project.")](https://docs.getdbt.com/docs/use-dbt-semantic-layer/setup-sl#) Delete the Semantic Layer configuration for a project. Additional configuration[​](https://docs.getdbt.com/docs/use-dbt-semantic-layer/setup-sl#additional-configuration "Direct link to Additional configuration") ------------------------------------------------------------------------------------------------------------------------------------------------------------- The following are the additional flexible configurations for Semantic Layer credentials. ### Map service tokens to credentials[​](https://docs.getdbt.com/docs/use-dbt-semantic-layer/setup-sl#map-service-tokens-to-credentials "Direct link to Map service tokens to credentials") * After configuring your environment, you can map additional service tokens to the same credential if you have the required [permissions](https://docs.getdbt.com/docs/cloud/manage-access/about-user-access#permission-sets) . * Go to the **Credentials & service tokens** page and click the **+Add Service Token** button in the **Linked Service Tokens** section. * Type the service token name and select the permission set you need (Semantic Layer Only and Metadata Only). * Click **Save** to link the service token to the credential. * Remember to copy and save the service token securely, as it won't be viewable again after generation. [![Map additional service tokens to a credential.](https://docs.getdbt.com/img/docs/dbt-cloud/semantic-layer/sl-add-service-token.gif?v=2 "Map additional service tokens to a credential.")](https://docs.getdbt.com/docs/use-dbt-semantic-layer/setup-sl#) Map additional service tokens to a credential. ### Unlink service tokens[​](https://docs.getdbt.com/docs/use-dbt-semantic-layer/setup-sl#unlink-service-tokens "Direct link to Unlink service tokens") * Unlink a service token from the credential by clicking **Unlink** under the **Linked service tokens** section. If you try to query the Semantic Layer with an unlinked credential, you'll experience an error in your BI tool because no valid token is mapped. ### Manage from service token page[​](https://docs.getdbt.com/docs/use-dbt-semantic-layer/setup-sl#manage-from-service-token-page "Direct link to Manage from service token page") **View credential from service token** * View your Semantic Layer credential directly by navigating to the **API tokens** and then **Service tokens** page. * Select the service token to view the credential it's linked to. This is useful if you want to know which service tokens are mapped to credentials in your project. #### Create a new service token[​](https://docs.getdbt.com/docs/use-dbt-semantic-layer/setup-sl#create-a-new-service-token "Direct link to Create a new service token") * From the **Service tokens** page, create a new service token and map it to the credential(s) (assuming the semantic layer permission exists). This is useful if you want to create a new service token and directly map it to a credential in your project. * Make sure to select the correct permission set for the service token (Semantic Layer Only and Metadata Only). [![Create a new service token and map credentials directly on the separate 'Service tokens page'.](https://docs.getdbt.com/img/docs/dbt-cloud/semantic-layer/sl-create-service-token-page.png?v=2 "Create a new service token and map credentials directly on the separate 'Service tokens page'.")](https://docs.getdbt.com/docs/use-dbt-semantic-layer/setup-sl#) Create a new service token and map credentials directly on the separate 'Service tokens page'. Next steps[​](https://docs.getdbt.com/docs/use-dbt-semantic-layer/setup-sl#next-steps "Direct link to Next steps") ------------------------------------------------------------------------------------------------------------------- * Now that you've set up your credentials and tokens, start querying your metrics with the [available integrations](https://docs.getdbt.com/docs/cloud-integrations/avail-sl-integrations) . * [Optimize querying performance](https://docs.getdbt.com/docs/use-dbt-semantic-layer/sl-cache) using declarative caching. * [Validate semantic nodes in CI](https://docs.getdbt.com/docs/deploy/ci-jobs#semantic-validations-in-ci) to ensure code changes made to dbt models don't break these metrics. * If you haven't already, learn how to [build you metrics and semantic models](https://docs.getdbt.com/docs/build/build-metrics-intro) in your development tool of choice. * Learn about commonly asked [Semantic Layer FAQs](https://docs.getdbt.com/docs/use-dbt-semantic-layer/sl-faqs) . FAQs[​](https://docs.getdbt.com/docs/use-dbt-semantic-layer/setup-sl#faqs "Direct link to FAQs") -------------------------------------------------------------------------------------------------  How does caching interact with access controls? Cached data is stored separately from the underlying models. If metrics are pulled from the cache, we don’t have the security context applied to those tables at query time. In the future, we plan to clone credentials, identify the minimum access level needed, and apply those permissions to cached tables. Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Prerequisites](https://docs.getdbt.com/docs/use-dbt-semantic-layer/setup-sl#prerequisites) * [Administer the Semantic Layer](https://docs.getdbt.com/docs/use-dbt-semantic-layer/setup-sl#administer-the-semantic-layer) * [1\. Select environment](https://docs.getdbt.com/docs/use-dbt-semantic-layer/setup-sl#1-select-environment) * [2\. Configure credentials and create tokens](https://docs.getdbt.com/docs/use-dbt-semantic-layer/setup-sl#2-configure-credentials-and-create-tokens) * [3\. View connection detail](https://docs.getdbt.com/docs/use-dbt-semantic-layer/setup-sl#3-view-connection-detail) * [4\. Add more credentials](https://docs.getdbt.com/docs/use-dbt-semantic-layer/setup-sl#4-add-more-credentials-) * [Delete configuration](https://docs.getdbt.com/docs/use-dbt-semantic-layer/setup-sl#delete-configuration) * [Additional configuration](https://docs.getdbt.com/docs/use-dbt-semantic-layer/setup-sl#additional-configuration) * [Map service tokens to credentials](https://docs.getdbt.com/docs/use-dbt-semantic-layer/setup-sl#map-service-tokens-to-credentials) * [Unlink service tokens](https://docs.getdbt.com/docs/use-dbt-semantic-layer/setup-sl#unlink-service-tokens) * [Manage from service token page](https://docs.getdbt.com/docs/use-dbt-semantic-layer/setup-sl#manage-from-service-token-page) * [Next steps](https://docs.getdbt.com/docs/use-dbt-semantic-layer/setup-sl#next-steps) * [FAQs](https://docs.getdbt.com/docs/use-dbt-semantic-layer/setup-sl#faqs) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/use-dbt-semantic-layer/setup-sl.md) --- # Artifacts | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/deploy/artifacts#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page When running dbt jobs, dbt generates and saves _artifacts_. You can use these artifacts, like `manifest.json`, `catalog.json`, and `sources.json` to power different aspects of the dbt platform, namely: [Catalog](https://docs.getdbt.com/docs/explore/explore-projects) , [dbt Docs](https://docs.getdbt.com/docs/explore/build-and-view-your-docs#dbt-docs) , and [source freshness reporting](https://docs.getdbt.com/docs/build/sources#source-data-freshness) . Create dbt Artifacts[​](https://docs.getdbt.com/docs/deploy/artifacts#create-dbt-artifacts "Direct link to Create dbt Artifacts") ---------------------------------------------------------------------------------------------------------------------------------- [Catalog](https://docs.getdbt.com/docs/explore/explore-projects#generate-metadata) uses the metadata provided by the [Discovery API](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-api) to display the details about [the state of your project](https://docs.getdbt.com/docs/dbt-cloud-apis/project-state) . It uses metadata from your staging and production [deployment environments](https://docs.getdbt.com/docs/deploy/deploy-environments) . Catalog automatically retrieves the metadata updates after each job run in the production or staging deployment environment so it always has the latest results for your project — meaning it's always automatically updated after each job run. To view a resource, its metadata, and what commands are needed, refer to [generate metadata](https://docs.getdbt.com/docs/explore/explore-projects#generate-metadata) for more details.  For dbt Docs The following steps are for legacy dbt Docs only. For the current documentation experience, see [dbt Catalog](https://docs.getdbt.com/docs/explore/explore-projects) . While running any job can produce artifacts, you should only associate one production job with a given project to produce the project's artifacts. You can designate this connection on the **Project details** page. To access this page: 1. From the dbt platform, click on your account name in the left side menu and select **Account settings**. 2. Select your project, and click **Edit** in the lower right. 3. Under **Artifacts**, select the jobs you want to produce documentation and source freshness artifacts for. [![Configuring Artifacts](https://docs.getdbt.com/img/docs/dbt-cloud/using-dbt-cloud/project-level-artifact-updated.png?v=2 "Configuring Artifacts")](https://docs.getdbt.com/docs/deploy/artifacts#) Configuring Artifacts If you don't see your job listed, you might need to edit the job and select **Run source freshness** and **Generate docs on run**. [![Editing the job to generate artifacts](https://docs.getdbt.com/img/docs/dbt-cloud/using-dbt-cloud/edit-job-generate-artifacts.png?v=2 "Editing the job to generate artifacts")](https://docs.getdbt.com/docs/deploy/artifacts#) Editing the job to generate artifacts When you add a production job to a project, dbt updates the content and provides links to the production documentation and source freshness artifacts it generated for that project. You can see these links by clicking **Deploy** in the upper left, selecting **Jobs**, and then selecting the production job. From the job page, you can select a specific run to see how artifacts were updated for that run only. ### Documentation[​](https://docs.getdbt.com/docs/deploy/artifacts#documentation "Direct link to Documentation") Navigate to [Catalog](https://docs.getdbt.com/docs/explore/explore-projects) through the **Explore** link to view your project's resources and lineage to gain a better understanding of its latest production state. To view a resource, its metadata, and what commands are needed, refer to [generate metadata](https://docs.getdbt.com/docs/explore/explore-projects#generate-metadata) for more details. Both the job's commands and the docs generate step (triggered by the **Generate docs on run** checkbox) must succeed during the job invocation to update the documentation.  For dbt Docs When set up, dbt updates the Documentation link in the header tab so it links to documentation for this job. This link always directs you to the latest version of the documentation for your project. ### Source Freshness[​](https://docs.getdbt.com/docs/deploy/artifacts#source-freshness "Direct link to Source Freshness") To view the latest source freshness result, refer to [generate metadata](https://docs.getdbt.com/docs/explore/explore-projects#generate-metadata) for more detail. Then navigate to Catalog through the **Explore** link.  For dbt Docs Configuring a job for the Source Freshness artifact setting also updates the data source link under **Orchestration** > **Data sources**. The link points to the latest Source Freshness report for the selected job. Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Create dbt Artifacts](https://docs.getdbt.com/docs/deploy/artifacts#create-dbt-artifacts) * [Documentation](https://docs.getdbt.com/docs/deploy/artifacts#documentation) * [Source Freshness](https://docs.getdbt.com/docs/deploy/artifacts#source-freshness) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/deploy/artifacts.md) --- # Project state in dbt | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/dbt-cloud-apis/project-state#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page dbt provides a stateful way of deploying dbt. Artifacts are accessible programmatically via the [Discovery API](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-querying) in the metadata platform. With the implementation of the `environment` endpoint in the Discovery API, we've introduced the idea of multiple states. The Discovery API provides a single API endpoint that returns the latest state of models, sources, and other nodes in the DAG. A single [deployment environment](https://docs.getdbt.com/docs/environments-in-dbt) should represent the production state of a given dbt project. There are two states that can be queried in dbt: * **Applied state** refers to what exists in the data warehouse after a successful `dbt run`. The model build succeeds and now exists as a table in the warehouse. * **Definition state** depends on what exists in the project given the code defined in it (for example, manifest state), which hasn’t necessarily been executed in the data platform (maybe just the result of `dbt compile`). Definition (logical) vs. applied state of dbt nodes[​](https://docs.getdbt.com/docs/dbt-cloud-apis/project-state#definition-logical-vs-applied-state-of-dbt-nodes "Direct link to Definition (logical) vs. applied state of dbt nodes") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- In a dbt project, the state of a node _definition_ represents the configuration, transformations, and dependencies defined in the SQL and YAML files. It captures how the node should be processed in relation to other nodes and tables in the data warehouse and may be produced by a `dbt build`, `run`, `parse`, or `compile`. It changes whenever the project code changes. A node’s _applied state_ refers to the node’s actual state after it has been successfully executed in the DAG; for example, models are executed; thus, their state is applied to the data warehouse via `dbt run` or `dbt build`. It changes whenever a node is executed. This state represents the result of the transformations and the actual data stored in the database, which for models can be a table or a view based on the defined logic. The applied state includes execution info, which contains metadata about how the node arrived in the applied state: the most recent execution (successful or attempted), such as when it began, its status, and how long it took. Here’s how you’d query and compare the definition vs. applied state of a model using the Discovery API: query Compare($environmentId: Int!, $first: Int!) { environment(id: $environmentId) { definition { models(first: $first) { edges { node { name rawCode } } } } applied { models(first: $first) { edges { node { name rawCode executionInfo { executeCompletedAt } } } } } }} Most Discovery API use cases will favor the _applied state_ since it pertains to what has actually been run and can be analyzed. Affected states by node type[​](https://docs.getdbt.com/docs/dbt-cloud-apis/project-state#affected-states-by-node-type "Direct link to Affected states by node type") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- The following table shows the states of dbt nodes and how they are affected by the Discovery API. | Node | Executed in DAG | Created by execution | Exists in database | Lineage | States | | --- | --- | --- | --- | --- | --- | | [Analysis](https://docs.getdbt.com/docs/build/analyses) | No | No | No | Upstream | Definition | | [Data test](https://docs.getdbt.com/docs/build/data-tests) | Yes | Yes | No | Upstream | Applied & definition | | [Exposure](https://docs.getdbt.com/docs/build/exposures) | No | No | No | Upstream | Definition | | [Group](https://docs.getdbt.com/docs/build/groups) | No | No | No | Downstream | Definition | | [Macro](https://docs.getdbt.com/docs/build/jinja-macros) | Yes | No | No | N/A | Definition | | [Metric](https://docs.getdbt.com/docs/build/metrics-overview) | No | No | No | Upstream & downstream | Definition | | [Model](https://docs.getdbt.com/docs/build/models) | Yes | Yes | Yes | Upstream & downstream | Applied & definition | | [Saved queries](https://docs.getdbt.com/docs/build/saved-queries)

(not in API) | N/A | N/A | N/A | N/A | N/A | | [Seed](https://docs.getdbt.com/docs/build/seeds) | Yes | Yes | Yes | Downstream | Applied & definition | | [Semantic model](https://docs.getdbt.com/docs/build/semantic-models) | No | No | No | Upstream & downstream | Definition | | [Snapshot](https://docs.getdbt.com/docs/build/snapshots) | Yes | Yes | Yes | Upstream & downstream | Applied & definition | | [Source](https://docs.getdbt.com/docs/build/sources) | Yes | No | Yes | Downstream | Applied & definition | | [Unit tests](https://docs.getdbt.com/docs/build/unit-tests) | Yes | Yes | No | Downstream | Definition | Caveats about state/metadata updates[​](https://docs.getdbt.com/docs/dbt-cloud-apis/project-state#caveats-about-statemetadata-updates "Direct link to Caveats about state/metadata updates") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Over time, Cloud Artifacts will provide information to maintain state for features/services in dbt and enable you to access state in dbt and its downstream ecosystem. Cloud Artifacts is currently focused on the latest production state, but this focus will evolve. Here are some limitations of the state representation in the Discovery API: * Users must access the default production environment to know the latest state of a project. * The API gets the definition from the latest manifest generated in a given deployment environment, but that often won’t reflect the latest project code state. * Compiled code results may be outdated depending on dbt run step order and failures. * Catalog info can be outdated, or incomplete (in the applied state), based on if/when `docs generate` was last run. * Source freshness checks can be out of date (in the applied state) depending on when the command was last run, and it’s not included in `build`. Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Definition (logical) vs. applied state of dbt nodes](https://docs.getdbt.com/docs/dbt-cloud-apis/project-state#definition-logical-vs-applied-state-of-dbt-nodes) * [Affected states by node type](https://docs.getdbt.com/docs/dbt-cloud-apis/project-state#affected-states-by-node-type) * [Caveats about state/metadata updates](https://docs.getdbt.com/docs/dbt-cloud-apis/project-state#caveats-about-statemetadata-updates) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/dbt-cloud-apis/project-state.md) --- # Tests object schema | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied-tests#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page [Tests](https://docs.getdbt.com/docs/build/data-tests) are assertions you make about your models and other resources in your dbt project. When you run `dbt test`, dbt will tell you if each test in your project passes or fails. You can query tests through the Discovery API to understand information about them. The [Example query](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied-tests#example-query) illustrates a few fields you can query with the `tests` object. Refer to [Fields](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied-tests#fields) to view the entire schema, which provides all possible fields you can query. ### Arguments[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied-tests#arguments "Direct link to Arguments") When querying for `tests`, you can use the following arguments: Fetching data... ================ ### Example query[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied-tests#example-query "Direct link to Example query") You can use the `environmentId` and filter by test types to return metadata for all tests in the environment: query { environment(id: 834) { applied { tests( filter: { testTypes: [ GENERIC_DATA_TEST, SINGULAR_DATA_TEST, UNIT_TEST ] }, first: 100 ) { edges { node { name model description expect resourceType testType given } } } } }} ### Fields[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied-tests#fields "Direct link to Fields") When querying for `tests`, you can use the following fields: Fetching data... ================ ### Key fields from nodes[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied-tests#key-fields-from-nodes "Direct link to Key fields from nodes") Fetching data... ================ Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Arguments](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied-tests#arguments) * [Example query](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied-tests#example-query) * [Fields](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied-tests#fields) * [Key fields from nodes](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-environment-applied-tests#key-fields-from-nodes) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/dbt-cloud-apis/schema-discovery-environment-applied-tests.mdx) --- # dbt environments | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/dbt-cloud-environments#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page An environment determines how dbt will execute your project in the [Studio IDE](https://docs.getdbt.com/docs/cloud/dbt-cloud-ide/develop-in-the-cloud) or [dbt CLI](https://docs.getdbt.com/docs/cloud/cloud-cli-installation) (for development) and scheduled jobs (for deployment). Critically, in order to execute dbt, environments define three variables: 1. The version of dbt Core that will be used to run your project 2. The warehouse connection information (including the target database/schema settings) 3. The version of your code to execute Each dbt project can have only one [development environment](https://docs.getdbt.com/docs/dbt-cloud-environments#create-a-development-environment) , but there is no limit to the number of [deployment environments](https://docs.getdbt.com/docs/deploy/deploy-environments) , providing you the flexibility and customization to tailor the execution of scheduled jobs. Use environments to customize settings for different stages of your project and streamline the execution process by using software engineering principles. [![dbt environment hierarchy showing projects, environments, connections, and orchestration jobs.](https://docs.getdbt.com/img/dbt-env.png?v=2 "dbt environment hierarchy showing projects, environments, connections, and orchestration jobs.")](https://docs.getdbt.com/docs/dbt-cloud-environments#) dbt environment hierarchy showing projects, environments, connections, and orchestration jobs. The following sections detail the different types of environments and how to intuitively configure your development environment in dbt. Types of environments[​](https://docs.getdbt.com/docs/dbt-cloud-environments#types-of-environments "Direct link to Types of environments") ------------------------------------------------------------------------------------------------------------------------------------------- In dbt, there are two types of environments: * **Deployment environment** — Determines the settings used when jobs created within that environment are executed. Types of deployment environments: * General * Staging * Production * **Development environment** — Determines the settings used in the Studio IDE or Cloud CLI, for that particular project. Each dbt project can only have a single development environment, but can have any number of General deployment environments, one Production deployment environment and one Staging deployment environment. | | Development | General | Production | Staging | | --- | --- | --- | --- | --- | | **Determines settings for** | Studio IDE or Cloud CLI | dbt Job runs | dbt Job runs | dbt Job runs | | **How many can I have in my project?** | 1 | Any number | 1 | 1 | note For users familiar with development on dbt Core, each environment is roughly analogous to an entry in your `profiles.yml` file, with some additional information about your repository to ensure the proper version of code is executed. More info on dbt core environments [here](https://docs.getdbt.com/docs/core/dbt-core-environments) . Common environment settings[​](https://docs.getdbt.com/docs/dbt-cloud-environments#common-environment-settings "Direct link to Common environment settings") ------------------------------------------------------------------------------------------------------------------------------------------------------------- Both development and deployment environments have a section called **General Settings**, which has some basic settings that all environments will define: | Setting | Example Value | Definition | Accepted Values | | --- | --- | --- | --- | | Environment name | Production | The environment name | Any string! | | Environment type | Deployment | The type of environment | Deployment, Development | | Set deployment type | PROD | Designates the deployment environment type. | Production, Staging, General | | dbt version | Latest | dbt automatically upgrades the dbt version running in this environment, based on the [release track](https://docs.getdbt.com/docs/dbt-versions/cloud-release-tracks)
you select. | Lastest, Compatible, Extended | | Only run on a custom branch | ☑️ | Determines whether to use a branch other than the repository’s default | See below | | Custom branch | dev | Custom Branch name | See below | About dbt version dbt allows users to select a [release track](https://docs.getdbt.com/docs/dbt-versions/cloud-release-tracks) to receive ongoing dbt version upgrades at the cadence that makes sense for their team. ### Custom branch behavior[​](https://docs.getdbt.com/docs/dbt-cloud-environments#custom-branch-behavior "Direct link to Custom branch behavior") By default, all environments will use the default branch in your repository (usually the `main` branch) when accessing your dbt code. This is overridable within each dbt Environment using the **Default to a custom branch** option. This setting will have slightly different behavior depending on the environment type: * **Development**: determines which branch in the Studio IDE or Cloud CLI developers create branches from and open PRs against. * **Deployment:** determines the branch is cloned during job executions for each environment. For more info, check out this [FAQ page on this topic](https://docs.getdbt.com/faqs/Environments/custom-branch-settings) ! ### Extended attributes[​](https://docs.getdbt.com/docs/dbt-cloud-environments#extended-attributes "Direct link to Extended attributes") note Extended attributes are currently _not_ supported for SSH tunneling Extended attributes allows users to set a flexible [profiles.yml](https://docs.getdbt.com/docs/core/connect-data-platform/profiles.yml) snippet in their dbt Environment settings. It provides users with more control over environments (both deployment and development) and extends how dbt connects to the data platform within a given environment. Extended attributes are set at the environment level, and can partially override connection or environment credentials, including any custom environment variables. You can set any YAML attributes that a dbt adapter accepts in its `profiles.yml`. [![Extended Attributes helps users add profiles.yml attributes to dbt Environment settings using a free form text box.](https://docs.getdbt.com/img/docs/dbt-cloud/using-dbt-cloud/extended-attributes.png?v=2 "Extended Attributes helps users add profiles.yml attributes to dbt Environment settings using a free form text box.")](https://docs.getdbt.com/docs/dbt-cloud-environments#) Extended Attributes helps users add profiles.yml attributes to dbt Environment settings using a free form text box. The following code is an example of the types of attributes you can add in the **Extended Attributes** text box: dbname: jaffle_shop schema: dbt_alice threads: 4username: alicepassword: '{{ env_var(''DBT_ENV_SECRET_PASSWORD'') }}' #### Extended Attributes don't mask secret values[​](https://docs.getdbt.com/docs/dbt-cloud-environments#extended-attributes-dont-mask-secret-values "Direct link to Extended Attributes don't mask secret values") We recommend avoiding setting secret values to prevent visibility in the text box and logs. A common workaround is to wrap extended attributes in [environment variables](https://docs.getdbt.com/docs/build/environment-variables) . In the earlier example, `password: '{{ env_var(''DBT_ENV_SECRET_PASSWORD'') }}'` will get a value from the `DBT_ENV_SECRET_PASSWORD` environment variable at runtime. #### How extended attributes work[​](https://docs.getdbt.com/docs/dbt-cloud-environments#how-extended-attributes-work "Direct link to How extended attributes work") If you're developing in the [Studio IDE](https://docs.getdbt.com/docs/cloud/dbt-cloud-ide/develop-in-the-cloud) , [Cloud CLI](https://docs.getdbt.com/docs/cloud/cloud-cli-installation) , or [orchestrating job runs](https://docs.getdbt.com/docs/deploy/deployments) , extended attributes parses through the provided YAML and extracts the `profiles.yml` attributes. For each individual attribute: * If the attribute exists in another source (such as your project settings), it will replace its value (like environment-level values) in the profile. It also overrides any custom environment variables (if not itself wired using the syntax described for secrets above) * If the attribute doesn't exist, it will add the attribute or value pair to the profile. #### Only the **top-level keys** are accepted in extended attributes[​](https://docs.getdbt.com/docs/dbt-cloud-environments#only-the-top-level-keys-are-accepted-in-extended-attributes "Direct link to only-the-top-level-keys-are-accepted-in-extended-attributes") This means that if you want to change a specific sub-key value, you must provide the entire top-level key as a JSON block in your resulting YAML. For example, if you want to customize a particular field within a [service account JSON](https://docs.getdbt.com/docs/core/connect-data-platform/bigquery-setup#service-account-json) for your BigQuery connection (like 'project\_id' or 'client\_email'), you need to provide an override for the entire top-level `keyfile_json` main key/attribute using extended attributes. Include the sub-fields as a nested JSON block. Create a development environment[​](https://docs.getdbt.com/docs/dbt-cloud-environments#create-a-development-environment "Direct link to Create a development environment") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- To create a new dbt development environment: 1. Navigate to **Deploy** -> **Environments** 2. Click **Create Environment**. 3. Select **Development** as the environment type. 4. Fill in the fields under **General Settings** and **Development Credentials**. 5. Click **Save** to create the environment. ### Set developer credentials[​](https://docs.getdbt.com/docs/dbt-cloud-environments#set-developer-credentials "Direct link to Set developer credentials") To use the dbt Studio IDE or Cloud CLI, each developer will need to set up [personal development credentials](https://docs.getdbt.com/docs/cloud/dbt-cloud-ide/develop-in-the-cloud#get-started-with-the-cloud-ide) to your warehouse connection in their **Profile Settings**. This allows you to set separate target information and maintain individual credentials to connect to your warehouse. [![Creating a development environment](https://docs.getdbt.com/img/docs/dbt-cloud/refresh-ide/new-environment-fields.png?v=2 "Creating a development environment")](https://docs.getdbt.com/docs/dbt-cloud-environments#) Creating a development environment Deployment environment[​](https://docs.getdbt.com/docs/dbt-cloud-environments#deployment-environment "Direct link to Deployment environment") ---------------------------------------------------------------------------------------------------------------------------------------------- Deployment environments in dbt are necessary to execute scheduled jobs and use other features (like different workspaces for different tasks). You can have many environments in a single dbt project, enabling you to set up each space in a way that suits different needs (such as experimenting or testing). Even though you can have many environments, only one of them can be the "main" deployment environment. This would be considered your "production" environment and represents your project's "source of truth", meaning it's where your most reliable and final data transformations live. To learn more about dbt deployment environments and how to configure them, refer to the [Deployment environments](https://docs.getdbt.com/docs/deploy/deploy-environments) page. For our best practices guide, read [dbt environment best practices](https://docs.getdbt.com/guides/set-up-ci) for more info. Delete an environment[​](https://docs.getdbt.com/docs/dbt-cloud-environments#delete-an-environment "Direct link to Delete an environment") ------------------------------------------------------------------------------------------------------------------------------------------- Deleting an environment automatically deletes its associated job(s). If you want to keep those jobs, move them to a different environment first. Follow these steps to delete an environment in dbt: 1. Click **Deploy** on the navigation header and then click **Environments** 2. Select the environment you want to delete. 3. Click **Settings** on the top right of the page and then click **Edit**. 4. Scroll to the bottom of the page and click **Delete** to delete the environment. [![Delete an environment](https://docs.getdbt.com/img/docs/dbt-cloud/cloud-configuring-dbt-cloud/delete-environment.png?v=2 "Delete an environment")](https://docs.getdbt.com/docs/dbt-cloud-environments#) Delete an environment 5. Confirm your action in the pop-up by clicking **Confirm delete** in the bottom right to delete the environment immediately. This action cannot be undone. However, you can create a new environment with the same information if the deletion was made in error. 6. Refresh your page and the deleted environment should now be gone. To delete multiple environments, you'll need to perform these steps to delete each one. If you're having any issues, feel free to [contact us](mailto:support@getdbt.com) for additional help. Environment settings history[​](https://docs.getdbt.com/docs/dbt-cloud-environments#environment-settings-history "Direct link to Environment settings history") ---------------------------------------------------------------------------------------------------------------------------------------------------------------- You can view historical environment settings changes over the last 90 days. To view the change history: 1. Navigate to **Orchestration** from the main menu and click **Environments**. 2. Click an **environment name**. 3. Click **Settings**. 4. Click **History**. [![Example of the environment history option.](https://docs.getdbt.com/img/docs/deploy/environment-history.png?v=2 "Example of the environment history option.")](https://docs.getdbt.com/docs/dbt-cloud-environments#) Example of the environment history option. Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Types of environments](https://docs.getdbt.com/docs/dbt-cloud-environments#types-of-environments) * [Common environment settings](https://docs.getdbt.com/docs/dbt-cloud-environments#common-environment-settings) * [Custom branch behavior](https://docs.getdbt.com/docs/dbt-cloud-environments#custom-branch-behavior) * [Extended attributes](https://docs.getdbt.com/docs/dbt-cloud-environments#extended-attributes) * [Create a development environment](https://docs.getdbt.com/docs/dbt-cloud-environments#create-a-development-environment) * [Set developer credentials](https://docs.getdbt.com/docs/dbt-cloud-environments#set-developer-credentials) * [Deployment environment](https://docs.getdbt.com/docs/dbt-cloud-environments#deployment-environment) * [Delete an environment](https://docs.getdbt.com/docs/dbt-cloud-environments#delete-an-environment) * [Environment settings history](https://docs.getdbt.com/docs/dbt-cloud-environments#environment-settings-history) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/dbt-cloud-environments.md) --- # Jobs in the dbt platform | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/deploy/jobs#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) These are the available job types in dbt: * [Deploy jobs](https://docs.getdbt.com/docs/deploy/deploy-jobs) — Build production data assets. Runs on a schedule, by API, or after another job completes. * [Continuous integration (CI) jobs](https://docs.getdbt.com/docs/deploy/continuous-integration) — Test and validate code changes before merging. Triggered by commit to a PR or by API. * [Merge jobs](https://docs.getdbt.com/docs/deploy/merge-jobs) — Deploy merged changes into production. Runs after a successful PR merge or by API. * [State-aware jobs](https://docs.getdbt.com/docs/deploy/state-aware-about) — Intelligently decide what needs to be rebuilt based on source freshness, code, or upstream data changes. Rebuild models only if they are older than the specified interval. The following comparison table describes the behaviors of the different job types: | | **Deploy jobs** | **CI jobs** | **Merge jobs** | **State-aware jobs** | | --- | --- | --- | --- | --- | | Purpose | Builds production data assets. | Builds and tests new code before merging changes into production. | Build merged changes into production or update state for deferral. | Trigger model builds and job runs only when source data is updated. | | Trigger types | Triggered by a schedule, API, or the successful completion of another job. | Triggered by a commit to a PR or by API. | Triggered by a successful merge into the environment's branch or by API. | Triggered when code, sources, or upstream data changes and at custom refresh intervals and for custom source freshness configurations | | Destination | Builds into a production database and schema. | Builds into a staging database and ephemeral schema, lived for the lifetime of the PR. | Builds into a production database and schema. | Builds into a production database and schema. | | Execution mode | Runs execute sequentially, so as to not have collisions on the underlying DAG. | Runs execute in parallel to promote team velocity. | Runs execute sequentially, so as to not have collisions on the underlying DAG. | | | Efficiency run savings | Detects over-scheduled jobs and cancels unnecessary runs to avoid queue clog. | Cancels existing runs when a newer commit is pushed to avoid redundant work. | N/A | Runs jobs and build models _only_ when source data is updated or if models are older than what you specified in the project refresh interval | | State comparison | Only sometimes needs to detect state. | Almost always needs to compare state against the production environment to build on modified code and its dependents. | Almost always needs to compare state against the production environment to build on modified code and its dependents. | | | Job run duration | Limit is 24 hours. | Limit is 24 hours. | Limit is 24 hours. | Limit is 24 hours. | Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 --- # Use cases and examples for the Discovery API | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-use-cases-and-examples#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page With the Discovery API, you can query the metadata in dbt to learn more about your dbt deployments and the data it generates to analyze them and make improvements. You can use the API in a variety of ways to get answers to your business questions. Below describes some of the uses of the API and is meant to give you an idea of the questions this API can help you answer. | Use case | Outcome | Example questions | | --- | --- | --- | | [Performance](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-use-cases-and-examples#performance) | Identify inefficiencies in pipeline execution to reduce infrastructure costs and improve timeliness. | * What’s the latest status of each model?
* Do I need to run this model?
* How long did my DAG take to run? | | [Quality](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-use-cases-and-examples#quality) | Monitor data source freshness and test results to resolve issues and drive trust in data. | * How fresh are my data sources?
* Which tests and models failed?
* What’s my project’s test coverage? | | [Discovery](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-use-cases-and-examples#discovery) | Find and understand relevant datasets and semantic nodes with rich context and metadata. | * What do these tables and columns mean?
* What's the full data lineage at a model level?
* Which metrics can I query? | | [Governance](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-use-cases-and-examples#governance) | Audit data development and facilitate collaboration within and between teams. | * Who is responsible for this model?
* How do I contact the model’s owner?
* Who can use this model? | | [Development](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-use-cases-and-examples#development) | Understand dataset changes and usage and gauge impacts to inform project definition. | * How is this metric used in BI tools?
* Which nodes depend on this data source?
* How has a model changed? What impact? | Performance[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-use-cases-and-examples#performance "Direct link to Performance") -------------------------------------------------------------------------------------------------------------------------------------- You can use the Discovery API to identify inefficiencies in pipeline execution to reduce infrastructure costs and improve timeliness. Below are example questions and queries you can run. For performance use cases, people typically query the historical or latest applied state across any part of the DAG (for example, models) using the `environment`, `modelHistoricalRuns`, or job-level endpoints. ### How long did each model take to run?[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-use-cases-and-examples#how-long-did-each-model-take-to-run "Direct link to How long did each model take to run?") It’s helpful to understand how long it takes to build models (tables) and tests to execute during a dbt run. Longer model build times result in higher infrastructure costs and fresh data arriving later to stakeholders. Analyses like these can be in observability tools or ad-hoc queries, like in a notebook. [![Model timing visualization in dbt](https://docs.getdbt.com/img/docs/dbt-cloud/discovery-api/model-timing.png?v=2 "Model timing visualization in dbt")](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-use-cases-and-examples#) Model timing visualization in dbt Example query with code Data teams can monitor the performance of their models, identify bottlenecks, and optimize the overall data pipeline by fetching execution details like `executionTime` and `runElapsedTime`: 1. Use latest state environment-level API to get a list of all executed models and their execution time. Then, sort the models by `executionTime` in descending order. query AppliedModels($environmentId: BigInt!, $first: Int!) { environment(id: $environmentId) { applied { models(first: $first) { edges { node { name uniqueId materializedType executionInfo { lastSuccessRunId executionTime executeStartedAt } } } } } }} 2. Get the most recent 20 run results for the longest running model. Review the results of the model across runs or you can go to the job/run or commit itself to investigate further. query ModelHistoricalRuns( $environmentId: BigInt! $uniqueId: String $lastRunCount: Int) { environment(id: $environmentId) { applied { modelHistoricalRuns( uniqueId: $uniqueId lastRunCount: $lastRunCount ) { name runId runElapsedTime runGeneratedAt executionTime executeStartedAt executeCompletedAt status } } }} 3. Use the query results to plot a graph of the longest running model’s historical run time and execution time trends. # Import librariesimport osimport matplotlib.pyplot as pltimport pandas as pdimport requests# Set API keyauth_token = *[SERVICE_TOKEN_HERE]*# Query the APIdef query_discovery_api(auth_token, gql_query, variables): response = requests.post('https://metadata.cloud.getdbt.com/graphql', headers={"authorization": "Bearer "+auth_token, "content-type": "application/json"}, json={"query": gql_query, "variables": variables}) data = response.json()['data'] return data# Get the latest run metadata for all modelsmodels_latest_metadata = query_discovery_api(auth_token, query_one, variables_query_one)['environment']# Convert to dataframemodels_df = pd.DataFrame([x['node'] for x in models_latest_metadata['applied']['models']['edges']])# Unnest the executionInfo columnmodels_df = pd.concat([models_df.drop(['executionInfo'], axis=1), models_df['executionInfo'].apply(pd.Series)], axis=1)# Sort the models by execution timemodels_df_sorted = models_df.sort_values('executionTime', ascending=False)print(models_df_sorted)# Get the uniqueId of the longest running modellongest_running_model = models_df_sorted.iloc[0]['uniqueId']# Define second query variablesvariables_query_two = { "environmentId": *[ENVR_ID_HERE]* "lastRunCount": 10, "uniqueId": longest_running_model}# Get the historical run metadata for the longest running modelmodel_historical_metadata = query_discovery_api(auth_token, query_two, variables_query_two)['environment']['applied']['modelHistoricalRuns']# Convert to dataframemodel_df = pd.DataFrame(model_historical_metadata)# Filter dataframe to only successful runsmodel_df = model_df[model_df['status'] == 'success']# Convert the runGeneratedAt, executeStartedAt, and executeCompletedAt columns to datetimemodel_df['runGeneratedAt'] = pd.to_datetime(model_df['runGeneratedAt'])model_df['executeStartedAt'] = pd.to_datetime(model_df['executeStartedAt'])model_df['executeCompletedAt'] = pd.to_datetime(model_df['executeCompletedAt'])# Plot the runElapsedTime over timeplt.plot(model_df['runGeneratedAt'], model_df['runElapsedTime'])plt.title('Run Elapsed Time')plt.show()# # Plot the executionTime over timeplt.plot(model_df['executeStartedAt'], model_df['executionTime'])plt.title(model_df['name'].iloc[0]+" Execution Time")plt.show() Plotting examples: [![The plot of runElapsedTime over time](https://docs.getdbt.com/img/docs/dbt-cloud/discovery-api/plot-of-runelapsedtime.png?v=2 "The plot of runElapsedTime over time")](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-use-cases-and-examples#) The plot of runElapsedTime over time [![The plot of executionTime over time](https://docs.getdbt.com/img/docs/dbt-cloud/discovery-api/plot-of-executiontime.png?v=2 "The plot of executionTime over time")](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-use-cases-and-examples#) The plot of executionTime over time ### What’s the latest state of each model?[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-use-cases-and-examples#whats-the-latest-state-of-each-model "Direct link to What’s the latest state of each model?") The Discovery API provides information about the applied state of models and how they arrived in that state. You can retrieve the status information from the most recent run and most recent successful run (execution) from the `environment` endpoint and dive into historical runs using job-based and `modelByEnvironment` endpoints. Example query The API returns full identifier information (`database.schema.alias`) and the `executionInfo` for both the most recent run and most recent successful run from the database: query ($environmentId: BigInt!, $first: Int!) { environment(id: $environmentId) { applied { models(first: $first) { edges { node { uniqueId compiledCode database schema alias materializedType executionInfo { executeCompletedAt lastJobDefinitionId lastRunGeneratedAt lastRunId lastRunStatus lastRunError lastSuccessJobDefinitionId runGeneratedAt lastSuccessRunId } } } } } }} ### What happened with my job run?[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-use-cases-and-examples#what-happened-with-my-job-run "Direct link to What happened with my job run?") You can query the metadata at the job level to review results for specific runs. This is helpful for historical analysis of deployment performance or optimizing particular jobs. Example query Deprecated example: query ($jobId: Int!, $runId: Int!) { models(jobId: $jobId, runId: $runId) { name status tests { name status } }} New example: query ($jobId: BigInt!, $runId: BigInt!) { job(id: $jobId, runId: $runId) { models { name status tests { name status } } }} ### What’s changed since the last run?[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-use-cases-and-examples#whats-changed-since-the-last-run "Direct link to What’s changed since the last run?") Unnecessary runs incur higher infrastructure costs and load on the data team and their systems. A model doesn’t need to be run if it’s a view and there's no code change since the last run, or if it’s a table/incremental with no code change since last run and source data has not been updated since the last run. Example query With the API, you can compare the `rawCode` between the definition and applied state, and review when the sources were last loaded (source `maxLoadedAt` relative to model `executeCompletedAt`) given the `materializedType` of the model: query ($environmentId: BigInt!, $first: Int!) { environment(id: $environmentId) { applied { models( first: $first filter: { uniqueIds: "MODEL.PROJECT.MODEL_NAME" } ) { edges { node { rawCode ancestors(types: [Source]) { ... on SourceAppliedStateNestedNode { freshness { maxLoadedAt } } } executionInfo { runGeneratedAt executeCompletedAt } materializedType } } } } definition { models( first: $first filter: { uniqueIds: "MODEL.PROJECT.MODEL_NAME" } ) { edges { node { rawCode runGeneratedAt materializedType } } } } }} Quality[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-use-cases-and-examples#quality "Direct link to Quality") -------------------------------------------------------------------------------------------------------------------------- You can use the Discovery API to monitor data source freshness and test results to diagnose and resolve issues and drive trust in data. When used with [webhooks](https://docs.getdbt.com/docs/deploy/webhooks) , can also help with detecting, investigating, and alerting issues. Below lists example questions the API can help you answer. Below are example questions and queries you can run. For quality use cases, people typically query the historical or latest applied state, often in the upstream part of the DAG (for example, sources), using the `environment` or `environment { applied { modelHistoricalRuns } }` endpoints. ### Which models and tests failed to run?[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-use-cases-and-examples#which-models-and-tests-failed-to-run "Direct link to Which models and tests failed to run?") By filtering on the latest status, you can get lists of models that failed to build and tests that failed during their most recent execution. This is helpful when diagnosing issues with the deployment that result in delayed or incorrect data. Example query with code 1. Get the latest run results across all jobs in the environment and return only the models and tests that errored/failed. query ($environmentId: BigInt!, $first: Int!) { environment(id: $environmentId) { applied { models(first: $first, filter: { lastRunStatus: error }) { edges { node { name executionInfo { lastRunId } } } } tests(first: $first, filter: { status: "fail" }) { edges { node { name executionInfo { lastRunId } } } } } }} 2. Review the historical execution and test failure rate (up to 20 runs) for a given model, such as a frequently used and important dataset. query ($environmentId: BigInt!, $uniqueId: String!, $lastRunCount: Int) { environment(id: $environmentId) { applied { modelHistoricalRuns(uniqueId: $uniqueId, lastRunCount: $lastRunCount) { name executeStartedAt status tests { name status } } } }} 3. Identify the runs and plot the historical trends of failure/error rates. ### When was the data my model uses last refreshed?[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-use-cases-and-examples#when-was-the-data-my-model-uses-last-refreshed "Direct link to When was the data my model uses last refreshed?") You can get the metadata on the latest execution for a particular model or across all models in your project. For instance, investigate when each model or snapshot that's feeding into a given model was last executed or the source or seed was last loaded to gauge the _freshness_ of the data. Example query with code query ($environmentId: BigInt!, $first: Int!) { environment(id: $environmentId) { applied { models( first: $first filter: { uniqueIds: "MODEL.PROJECT.MODEL_NAME" } ) { edges { node { name ancestors(types: [Model, Source, Seed, Snapshot]) { ... on ModelAppliedStateNestedNode { name resourceType materializedType executionInfo { executeCompletedAt } } ... on SourceAppliedStateNestedNode { sourceName name resourceType freshness { maxLoadedAt } } ... on SnapshotAppliedStateNestedNode { name resourceType executionInfo { executeCompletedAt } } ... on SeedAppliedStateNestedNode { name resourceType executionInfo { executeCompletedAt } } } } } } } }} # Extract graph nodes from responsedef extract_nodes(data): models = [] sources = [] groups = [] for model_edge in data["applied"]["models"]["edges"]: models.append(model_edge["node"]) for source_edge in data["applied"]["sources"]["edges"]: sources.append(source_edge["node"]) for group_edge in data["definition"]["groups"]["edges"]: groups.append(group_edge["node"]) models_df = pd.DataFrame(models) sources_df = pd.DataFrame(sources) groups_df = pd.DataFrame(groups) return models_df, sources_df, groups_df# Construct a lineage graph with freshness infodef create_freshness_graph(models_df, sources_df): G = nx.DiGraph() current_time = datetime.now(timezone.utc) for _, model in models_df.iterrows(): max_freshness = pd.Timedelta.min if "meta" in models_df.columns: freshness_sla = model["meta"]["freshness_sla"] else: freshness_sla = None if model["executionInfo"]["executeCompletedAt"] is not None: model_freshness = current_time - pd.Timestamp(model["executionInfo"]["executeCompletedAt"]) for ancestor in model["ancestors"]: if ancestor["resourceType"] == "SourceAppliedStateNestedNode": ancestor_freshness = current_time - pd.Timestamp(ancestor["freshness"]['maxLoadedAt']) elif ancestor["resourceType"] == "ModelAppliedStateNestedNode": ancestor_freshness = current_time - pd.Timestamp(ancestor["executionInfo"]["executeCompletedAt"]) if ancestor_freshness > max_freshness: max_freshness = ancestor_freshness G.add_node(model["uniqueId"], name=model["name"], type="model", max_ancestor_freshness = max_freshness, freshness = model_freshness, freshness_sla=freshness_sla) for _, source in sources_df.iterrows(): if source["maxLoadedAt"] is not None: G.add_node(source["uniqueId"], name=source["name"], type="source", freshness=current_time - pd.Timestamp(source["maxLoadedAt"])) for _, model in models_df.iterrows(): for parent in model["parents"]: G.add_edge(parent["uniqueId"], model["uniqueId"]) return G Graph example: [![A lineage graph with source freshness information](https://docs.getdbt.com/img/docs/dbt-cloud/discovery-api/lineage-graph-with-freshness-info.png?v=2 "A lineage graph with source freshness information")](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-use-cases-and-examples#) A lineage graph with source freshness information ### Are my data sources fresh?[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-use-cases-and-examples#are-my-data-sources-fresh "Direct link to Are my data sources fresh?") Checking [source freshness](https://docs.getdbt.com/docs/build/sources#source-data-freshness) allows you to ensure that sources loaded and used in your dbt project are compliant with expectations. The API provides the latest metadata about source loading and information about the freshness check criteria. [![Source freshness page in dbt](https://docs.getdbt.com/img/docs/dbt-cloud/discovery-api/source-freshness-page.png?v=2 "Source freshness page in dbt")](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-use-cases-and-examples#) Source freshness page in dbt Example query query ($environmentId: BigInt!, $first: Int!) { environment(id: $environmentId) { applied { sources( first: $first filter: { freshnessChecked: true, database: "production" } ) { edges { node { sourceName name identifier loader freshness { freshnessJobDefinitionId freshnessRunId freshnessRunGeneratedAt freshnessStatus freshnessChecked maxLoadedAt maxLoadedAtTimeAgoInS snapshottedAt criteria { errorAfter { count period } warnAfter { count period } } } } } } } }} ### What’s the test coverage and status?[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-use-cases-and-examples#whats-the-test-coverage-and-status "Direct link to What’s the test coverage and status?") [Data tests](https://docs.getdbt.com/docs/build/data-tests) are an important way to ensure that your stakeholders are reviewing high-quality data. You can execute tests during a dbt run. The Discovery API provides complete test results for a given environment or job, which it represents as the `children` of a given node that’s been tested (for example, a `model`). Example query For the following example, the `parents` are the nodes (code) that's being tested and `executionInfo` describes the latest test results: query ($environmentId: BigInt!, $first: Int!) { environment(id: $environmentId) { applied { tests(first: $first) { edges { node { name columnName parents { name resourceType } executionInfo { lastRunStatus lastRunError executeCompletedAt executionTime } } } } } }} ### How is this model contracted and versioned?[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-use-cases-and-examples#how-is-this-model-contracted-and-versioned "Direct link to How is this model contracted and versioned?") To enforce the shape of a model's definition, you can define contracts on models and their columns. You can also specify model versions to keep track of discrete stages in its evolution and use the appropriate one. Example query query { environment(id: 123) { applied { models(first: 100, filter: { access: public }) { edges { node { name latestVersion contractEnforced constraints { name type expression columns } catalog { columns { name type } } } } } } }} Discovery[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-use-cases-and-examples#discovery "Direct link to Discovery") -------------------------------------------------------------------------------------------------------------------------------- You can use the Discovery API to find and understand relevant datasets and semantic nodes with rich context and metadata. Below are example questions and queries you can run. For discovery use cases, people typically query the latest applied or definition state, often in the downstream part of the DAG (for example, mart models or metrics), using the `environment` endpoint. ### What does this dataset and its columns mean?[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-use-cases-and-examples#what-does-this-dataset-and-its-columns-mean "Direct link to What does this dataset and its columns mean?") Query the Discovery API to map a table/view in the data platform to the model in the dbt project; then, retrieve metadata about its meaning, including descriptive metadata from its YAML file and catalog information from its YAML file and the schema. Example query query ($environmentId: BigInt!, $first: Int!) { environment(id: $environmentId) { applied { models( first: $first filter: { database: "analytics" schema: "prod" identifier: "customers" } ) { edges { node { name description tags meta catalog { columns { name description type } } } } } } }} ### What's the full data lineage at a model level?[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-use-cases-and-examples#whats-the-full-data-lineage-at-a-model-level "Direct link to What's the full data lineage at a model level?") The Discovery API enables access to comprehensive model-level data lineage by exposing: * Upstream dependencies of models, including relationships to [sources](https://docs.getdbt.com/docs/build/sources) , [seeds](https://docs.getdbt.com/docs/build/seeds) , and [snapshots](https://docs.getdbt.com/docs/build/snapshots) * Model execution metadata such as run status, execution time, and freshness * Column-level details, including tests and descriptions * References between models to reconstruct lineage across your project Example query Here's a GraphQL query example that retrieves full model-level data lineage using the Discovery API: query ($environmentId: BigInt!, $first: Int!) { environment(id: $environmentId) { applied { models(first: $first) { edges { node { name ancestors(types: [Model, Source, Seed, Snapshot]) { ... on ModelAppliedStateNestedNode { name resourceType } ... on SourceAppliedStateNestedNode { sourceName name resourceType } } } } } } }} ### Which metrics are available?[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-use-cases-and-examples#which-metrics-are-available "Direct link to Which metrics are available?") You can define and query metrics using the [Semantic Layer](https://docs.getdbt.com/docs/build/about-metricflow) , use them for documentation purposes (like for a data catalog), and calculate aggregations (like in a BI tool that doesn’t query the SL). Example query query ($environmentId: BigInt!, $first: Int!) { environment(id: $environmentId) { definition { metrics(first: $first) { edges { node { name description type formula filter tags parents { name resourceType } } } } } }} Governance[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-use-cases-and-examples#governance "Direct link to Governance") ----------------------------------------------------------------------------------------------------------------------------------- You can use the Discovery API to audit data development and facilitate collaboration within and between teams. For governance use cases, people tend to query the latest definition state, often in the downstream part of the DAG (for example, public models), using the `environment` endpoint. ### Who is responsible for this model?[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-use-cases-and-examples#who-is-responsible-for-this-model "Direct link to Who is responsible for this model?") You can define and surface the groups each model is associated with. Groups contain information like owner. This can help you identify which team owns certain models and who to contact about them. Example query query ($environmentId: BigInt!, $first: Int!) { environment(id: $environmentId) { applied { models(first: $first, filter: { uniqueIds: ["MODEL.PROJECT.NAME"] }) { edges { node { name description resourceType access group } } } } definition { groups(first: $first) { edges { node { name resourceType models { name } ownerName ownerEmail } } } } }} ### Who can use this model?[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-use-cases-and-examples#who-can-use-this-model "Direct link to Who can use this model?") You can enable people the ability to specify the level of access for a given model. In the future, public models will function like APIs to unify project lineage and enable reuse of models using cross-project refs. Example query query ($environmentId: BigInt!, $first: Int!) { environment(id: $environmentId) { definition { models(first: $first) { edges { node { name access } } } } }} * * * query ($environmentId: BigInt!, $first: Int!) { environment(id: $environmentId) { definition { models(first: $first, filter: { access: public }) { edges { node { name } } } } }} Development[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-use-cases-and-examples#development "Direct link to Development") -------------------------------------------------------------------------------------------------------------------------------------- You can use the Discovery API to understand dataset changes and usage and gauge impacts to inform project definition. Below are example questions and queries you can run. For development use cases, people typically query the historical or latest definition or applied state across any part of the DAG using the `environment` endpoint. ### How is this model or metric used in downstream tools?[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-use-cases-and-examples#how-is-this-model-or-metric-used-in-downstream-tools "Direct link to How is this model or metric used in downstream tools?") [Exposures](https://docs.getdbt.com/docs/build/exposures) provide a method to define how a model or metric is actually used in dashboards and other analytics tools and use cases. You can query an exposure’s definition to see how project nodes are used and query its upstream lineage results to understand the state of the data used in it, which powers use cases like a freshness and quality status tile. [![Embed data health tiles in your dashboards to distill trust signals for data consumers.](https://docs.getdbt.com/img/docs/collaborate/dbt-explorer/data-tile-pass.jpg?v=2 "Embed data health tiles in your dashboards to distill trust signals for data consumers.")](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-use-cases-and-examples#) Embed data health tiles in your dashboards to distill trust signals for data consumers. Example query Below is an example that reviews an exposure and the models used in it including when they were last executed. query ($environmentId: BigInt!, $first: Int!) { environment(id: $environmentId) { applied { exposures(first: $first) { edges { node { name description ownerName url parents { name resourceType ... on ModelAppliedStateNestedNode { executionInfo { executeCompletedAt lastRunStatus } } } } } } } }} ### How has this model changed over time?[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-use-cases-and-examples#how-has-this-model-changed-over-time "Direct link to How has this model changed over time?") The Discovery API provides historical information about any resource in your project. For instance, you can view how a model has evolved over time (across recent runs) given changes to its shape and contents. Example query Review the differences in `compiledCode` or `columns` between runs or plot the “Approximate Size” and “Row Count” `stats` over time: query ( $environmentId: BigInt! $uniqueId: String! $lastRunCount: Int! $withCatalog: Boolean!) { environment(id: $environmentId) { applied { modelHistoricalRuns( uniqueId: $uniqueId lastRunCount: $lastRunCount withCatalog: $withCatalog ) { name compiledCode columns { name } stats { label value } } } }} ### Which nodes depend on this data source?[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-use-cases-and-examples#which-nodes-depend-on-this-data-source "Direct link to Which nodes depend on this data source?") dbt lineage begins with data sources. For a given source, you can look at which nodes are its children then iterate downstream to get the full list of dependencies. Currently, querying beyond 1 generation (defined as a direct parent-to-child) is not supported. To see the grandchildren of a node, you need to make two queries: one to get the node and its children, and another to get the children nodes and their children. Example query query ($environmentId: BigInt!, $first: Int!) { environment(id: $environmentId) { applied { sources( first: $first filter: { uniqueIds: ["SOURCE_NAME.TABLE_NAME"] } ) { edges { node { loader children { uniqueId resourceType ... on ModelAppliedStateNestedNode { database schema alias } } } } } } }} Related docs[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-use-cases-and-examples#related-docs "Direct link to Related docs") ----------------------------------------------------------------------------------------------------------------------------------------- * [Query Discovery API](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-querying) Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Performance](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-use-cases-and-examples#performance) * [How long did each model take to run?](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-use-cases-and-examples#how-long-did-each-model-take-to-run) * [What’s the latest state of each model?](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-use-cases-and-examples#whats-the-latest-state-of-each-model) * [What happened with my job run?](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-use-cases-and-examples#what-happened-with-my-job-run) * [What’s changed since the last run?](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-use-cases-and-examples#whats-changed-since-the-last-run) * [Quality](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-use-cases-and-examples#quality) * [Which models and tests failed to run?](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-use-cases-and-examples#which-models-and-tests-failed-to-run) * [When was the data my model uses last refreshed?](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-use-cases-and-examples#when-was-the-data-my-model-uses-last-refreshed) * [Are my data sources fresh?](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-use-cases-and-examples#are-my-data-sources-fresh) * [What’s the test coverage and status?](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-use-cases-and-examples#whats-the-test-coverage-and-status) * [How is this model contracted and versioned?](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-use-cases-and-examples#how-is-this-model-contracted-and-versioned) * [Discovery](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-use-cases-and-examples#discovery) * [What does this dataset and its columns mean?](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-use-cases-and-examples#what-does-this-dataset-and-its-columns-mean) * [What's the full data lineage at a model level?](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-use-cases-and-examples#whats-the-full-data-lineage-at-a-model-level) * [Which metrics are available?](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-use-cases-and-examples#which-metrics-are-available) * [Governance](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-use-cases-and-examples#governance) * [Who is responsible for this model?](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-use-cases-and-examples#who-is-responsible-for-this-model) * [Who can use this model?](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-use-cases-and-examples#who-can-use-this-model) * [Development](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-use-cases-and-examples#development) * [How is this model or metric used in downstream tools?](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-use-cases-and-examples#how-is-this-model-or-metric-used-in-downstream-tools) * [How has this model changed over time?](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-use-cases-and-examples#how-has-this-model-changed-over-time) * [Which nodes depend on this data source?](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-use-cases-and-examples#which-nodes-depend-on-this-data-source) * [Related docs](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-use-cases-and-examples#related-docs) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/dbt-cloud-apis/discovery-use-cases-and-examples.md) --- # About installing Fusion | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/fusion/about-fusion-install#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page important The dbt Fusion Engine is currently available for installation in: * [Local command line interface (CLI) tools](https://docs.getdbt.com/docs/fusion/install-fusion-cli) [preview](https://docs.getdbt.com/docs/dbt-versions/product-lifecycles "Go to https://docs.getdbt.com/docs/dbt-versions/product-lifecycles") * [VS Code and Cursor with the dbt extension](https://docs.getdbt.com/docs/install-dbt-extension) [preview](https://docs.getdbt.com/docs/dbt-versions/product-lifecycles "Go to https://docs.getdbt.com/docs/dbt-versions/product-lifecycles") * [dbt platform environments](https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-version-in-cloud#dbt-fusion-engine) [beta](https://docs.getdbt.com/docs/dbt-versions/product-lifecycles "Go to https://docs.getdbt.com/docs/dbt-versions/product-lifecycles") Join the conversation in our Community Slack channel [`#dbt-fusion-engine`](https://getdbt.slack.com/archives/C088YCAB6GH) . Read the [Fusion Diaries](https://github.com/dbt-labs/dbt-fusion/discussions/categories/announcements) for the latest updates. Learn more about installing Fusion locally, along with important prerequisites, step-by-step installation instructions, troubleshooting common issues, and configuration guidance. Prerequisites[​](https://docs.getdbt.com/docs/fusion/about-fusion-install#prerequisites "Direct link to Prerequisites") ------------------------------------------------------------------------------------------------------------------------ Before installing Fusion, ensure that you: * Have administrative privileges to install software on your local machine. * Are comfortable using a command-line interface (Terminal on macOS/Linux, PowerShell on Windows). * Use a supported data warehouse and authentication method and configure permissions as needed:  BigQuery * Service Account / User Token * Native OAuth * External OAuth * [Required permissions](https://docs.getdbt.com/docs/core/connect-data-platform/bigquery-setup#required-permissions) Databricks * Service Account / User Token * Native OAuth Redshift * Username / Password Snowflake * Username / Password * Native OAuth * External OAuth * Key pair * MFA * Use a supported operating system: 🟢 - Supported 🟡 - Not yet supported | Operating System | X86-64 | ARM | | --- | --- | --- | | macOS | 🟢 | 🟢 | | Linux | 🟢 | 🟢 | | Windows | 🟢 | 🟡 | [![](https://docs.getdbt.com/img/icons/dbt-bit.svg)\ \ #### dbt VS Code Extension\ \ Learn how to connect to a data platform, integrate with secure authentication methods, and configure a sync with a git repo.](https://docs.getdbt.com/docs/fusion/install-dbt-extension) [![](https://docs.getdbt.com/img/icons/dbt-bit.svg)\ \ #### dbt Fusion engine from the CLI\ \ Learn how to install the dbt Fusion engine on the command line interface (CLI).](https://docs.getdbt.com/docs/fusion/install-fusion-cli) [![](https://docs.getdbt.com/img/icons/dbt-bit.svg)\ \ #### dbt Fusion engine upgrade\ \ Learn how you can upgrade and leverage the speed and scale of the dbt Fusion engine](https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-version-in-cloud#dbt-fusion-engine) Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Prerequisites](https://docs.getdbt.com/docs/fusion/about-fusion-install#prerequisites) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/fusion/about-fusion-install.md) --- # Continuous integration jobs in dbt | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/deploy/ci-jobs#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page You can set up [continuous integration](https://docs.getdbt.com/docs/deploy/continuous-integration) (CI) jobs to run when someone opens a new pull request (PR) in your Git repository. By running and testing only _modified_ models, dbt ensures these jobs are as efficient and resource conscientious as possible on your data platform. Triggering CI jobs in monorepos If you have a monorepo with several dbt projects, opening a single pull request in one of your projects will trigger jobs for all projects connected to the monorepo. To address this, you can use separate target branches per project (for example, `main-project-a`, `main-project-b`) to separate CI triggers. Prerequisites[​](https://docs.getdbt.com/docs/deploy/ci-jobs#prerequisites "Direct link to Prerequisites") ----------------------------------------------------------------------------------------------------------- * You have a dbt account. * CI features: * For both the [concurrent CI checks](https://docs.getdbt.com/docs/deploy/continuous-integration#concurrent-ci-checks) and [smart cancellation of stale builds](https://docs.getdbt.com/docs/deploy/continuous-integration#smart-cancellation) features, your dbt account must be on the [Starter, Enterprise, or Enterprise+ plan](https://www.getdbt.com/pricing/) . * [SQL linting](https://docs.getdbt.com/docs/deploy/continuous-integration#sql-linting) is available on [dbt release tracks](https://docs.getdbt.com/docs/dbt-versions/cloud-release-tracks) and to dbt [Starter, Enterprise, or Enterprise+](https://www.getdbt.com/pricing/) accounts. You should have [SQLFluff configured](https://docs.getdbt.com/docs/deploy/continuous-integration#to-configure-sqlfluff-linting) in your project. * [Advanced CI](https://docs.getdbt.com/docs/deploy/advanced-ci) features: * For the [compare changes](https://docs.getdbt.com/docs/deploy/advanced-ci#compare-changes) feature, your dbt account must be on an [Enterprise-tier plan](https://www.getdbt.com/pricing/) and have enabled Advanced CI features. Please ask your [dbt administrator to enable](https://docs.getdbt.com/docs/cloud/account-settings#account-access-to-advanced-ci-features) this feature for you. After enablement, the **dbt compare** option becomes available in the CI job settings. * Set up a [connection with your Git provider](https://docs.getdbt.com/docs/cloud/git/git-configuration-in-dbt-cloud) . This integration lets dbt run jobs on your behalf for job triggering. * If you're using a native [GitLab](https://docs.getdbt.com/docs/cloud/git/connect-gitlab) integration, you need a paid or self-hosted account that includes support for GitLab webhooks and [project access tokens](https://docs.gitlab.com/ee/user/project/settings/project_access_tokens.html) . If you're using GitLab Free, merge requests will trigger CI jobs but CI job status updates (success or failure of the job) will not be reported back to GitLab. Availability of features by Git provider[​](https://docs.getdbt.com/docs/deploy/ci-jobs#availability-of-features-by-git-provider "Direct link to Availability of features by Git provider") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- * If your git provider has a [native dbt integration](https://docs.getdbt.com/docs/cloud/git/git-configuration-in-dbt-cloud) , you can seamlessly set up [continuous integration (CI)](https://docs.getdbt.com/docs/deploy/ci-jobs) jobs directly within dbt. * For providers without native integration, you can still use the [Git clone method](https://docs.getdbt.com/docs/cloud/git/import-a-project-by-git-url) to import your git URL and leverage the [dbt Administrative API](https://docs.getdbt.com/docs/dbt-cloud-apis/admin-cloud-api) to trigger a CI job to run. The following table outlines the available integration options and their corresponding capabilities. | **Git provider** | **Native dbt integration** | **Automated CI job** | **Git clone** | **Information** | **Supported plans** | | --- | --- | --- | --- | --- | --- | | [Azure DevOps](https://docs.getdbt.com/docs/cloud/git/connect-azure-devops) | ✅ | ✅ | ✅ | Organizations on the Starter and Developer plans can connect to Azure DevOps using a deploy key. Note, you won’t be able to configure automated CI jobs but you can still develop. | Enterprise, Enterprise+ | | [GitHub](https://docs.getdbt.com/docs/cloud/git/connect-github) | ✅ | ✅ | | | All dbt plans | | [GitLab](https://docs.getdbt.com/docs/cloud/git/connect-gitlab) | ✅ | ✅ | ✅ | | All dbt plans | | All other git providers using [Git clone](https://docs.getdbt.com/docs/cloud/git/import-a-project-by-git-url)
([BitBucket](https://docs.getdbt.com/docs/cloud/git/import-a-project-by-git-url#bitbucket)
, [AWS CodeCommit](https://docs.getdbt.com/docs/cloud/git/import-a-project-by-git-url#aws-codecommit)
, and others) | ❌ | ❌ | ✅ | Refer to the [Customizing CI/CD with custom pipelines](https://docs.getdbt.com/guides/custom-cicd-pipelines?step=1)
guide to set up continuous integration and continuous deployment (CI/CD). | | Set up CI jobs[​](https://docs.getdbt.com/docs/deploy/ci-jobs#set-up-ci-jobs "Direct link to Set up CI jobs") -------------------------------------------------------------------------------------------------------------- dbt Labs recommends that you create your CI job in a dedicated dbt [deployment environment](https://docs.getdbt.com/docs/deploy/deploy-environments#create-a-deployment-environment) that's connected to a staging database. Having a separate environment dedicated for CI will provide better isolation between your temporary CI schema builds and your production data builds. Additionally, sometimes teams need their CI jobs to be triggered when a PR is made to a branch other than main. If your team maintains a staging branch as part of your release process, having a separate environment will allow you to set a [custom branch](https://docs.getdbt.com/faqs/Environments/custom-branch-settings) and, accordingly, the CI job in that dedicated environment will be triggered only when PRs are made to the specified custom branch. To learn more, refer to [Get started with CI tests](https://docs.getdbt.com/guides/set-up-ci) . To make CI job creation easier, many options on the **CI job** page are set to default values that dbt Labs recommends that you use. If you don't want to use the defaults, you can change them. 1. On your deployment environment page, click **Create job** > **Continuous integration job** to create a new CI job. 2. Options in the **Job settings** section: * **Job name** — Specify the name for this CI job. * **Description** — Provide a description about the CI job. * **Environment** — By default, this will be set to the environment you created the CI job from. Use the dropdown to change the default setting. 3. Options in the **Git trigger** section: * **Triggered by pull requests** — By default, it’s enabled. Every time a developer opens up a pull request or pushes a commit to an existing pull request, this job will get triggered to run. * **Run on draft pull request** — Enable this option if you want to also trigger the job to run every time a developer opens up a draft pull request or pushes a commit to that draft pull request. 4. Options in the **Execution settings** section: * **Commands** — By default, this includes the `dbt build --select state:modified+` command. This informs dbt to build only new or changed models and their downstream dependents. Importantly, state comparison can only happen when there is a deferred environment selected to compare state to. Click **Add command** to add more [commands](https://docs.getdbt.com/docs/deploy/job-commands) that you want to be invoked when this job runs. * **Linting** — Enable this option for dbt to [lint the SQL files](https://docs.getdbt.com/docs/deploy/continuous-integration#sql-linting) in your project as the first step in `dbt run`. If this check runs into an error, dbt can either **Stop running on error** or **Continue running on error**. * **dbt compare**[Enterprise](https://www.getdbt.com/pricing "Go to https://www.getdbt.com/pricing") [Enterprise +](https://www.getdbt.com/pricing "Go to https://www.getdbt.com/pricing") — Enable this option to compare the last applied state of the production environment (if one exists) with the latest changes from the pull request, and identify what those differences are. To enable record-level comparison and primary key analysis, you must add a [primary key constraint](https://docs.getdbt.com/reference/resource-properties/constraints) or [uniqueness test](https://docs.getdbt.com/reference/resource-properties/data-tests#unique) . Otherwise, you'll receive a "Primary key missing" error message in dbt. To review the comparison report, navigate to the [Compare tab](https://docs.getdbt.com/docs/deploy/run-visibility#compare-tab) in the job run's details. A summary of the report is also available from the pull request in your Git provider (see the [CI report example](https://docs.getdbt.com/docs/deploy/ci-jobs#example-ci-report) ). Optimization tip When you enable the **dbt compare** checkbox, you can customize the comparison command to optimize your CI job. For example, if you have large models that take a long time to compare, you can exclude them to speed up the process using the [`--exclude` flag](https://docs.getdbt.com/reference/node-selection/exclude) . Refer to [compare changes custom commands](https://docs.getdbt.com/docs/deploy/job-commands#compare-changes-custom-commands) for more details. Additionally, if you set [`event_time`](https://docs.getdbt.com/reference/resource-configs/event-time) in your models/seeds/snapshots/sources, it allows you to compare matching date ranges between tables by filtering to overlapping date ranges. This is useful for faster CI workflow or custom sampling set ups. * **Compare changes against an environment (Deferral)** — By default, it’s set to the **Production** environment if you created one. This option allows dbt to check the state of the code in the PR against the code running in the deferred environment, so as to only check the modified code, instead of building the full table or the entire DAG. info Older versions of dbt only allow you to defer to a specific job instead of an environment. Deferral to a job compares state against the project code that was run in the deferred job's last successful run. Deferral to an environment is more efficient as dbt will compare against the project representation (which is stored in the `manifest.json`) of the last successful deploy job run that executed in the deferred environment. By considering _all_ [deploy jobs](https://docs.getdbt.com/docs/deploy/deploy-jobs) that run in the deferred environment, dbt will get a more accurate, latest project representation state. * **Run timeout** — Cancel the CI job if the run time exceeds the timeout value. You can use this option to help ensure that a CI check doesn't consume too much of your warehouse resources. If you enable the **dbt compare** option, the timeout value defaults to `3600` (one hour) to prevent long-running comparisons. 5. (optional) Options in the **Advanced settings** section: * **Environment variables** — Define [environment variables](https://docs.getdbt.com/docs/build/environment-variables) to customize the behavior of your project when this CI job runs. You can specify that a CI job is running in a _Staging_ or _CI_ environment by setting an environment variable and modifying your project code to behave differently, depending on the context. It's common for teams to process only a subset of data for CI runs, using environment variables to branch logic in their dbt project code. * **Target name** — Define the [target name](https://docs.getdbt.com/docs/build/custom-target-names) . Similar to **Environment Variables**, this option lets you customize the behavior of the project. You can use this option to specify that a CI job is running in a _Staging_ or _CI_ environment by setting the target name and modifying your project code to behave differently, depending on the context. * **dbt version** — By default, it’s set to inherit the [dbt version](https://docs.getdbt.com/docs/dbt-versions/core) from the environment. dbt Labs strongly recommends that you don't change the default setting. This option to change the version at the job level is useful only when you upgrade a project to the next dbt version; otherwise, mismatched versions between the environment and job can lead to confusing behavior. * **Threads** — By default, it’s set to 4 [threads](https://docs.getdbt.com/docs/core/connect-data-platform/connection-profiles#understanding-threads) . Increase the thread count to increase model execution concurrency. * **Generate docs on run** — Enable this if you want to [generate project docs](https://docs.getdbt.com/docs/explore/build-and-view-your-docs) when this job runs. This is disabled by default since testing doc generation on every CI check is not a recommended practice. * **Run source freshness** — Enable this option to invoke the `dbt source freshness` command before running this CI job. Refer to [Source freshness](https://docs.getdbt.com/docs/deploy/source-freshness) for more details. [![Example of CI Job page in the dbt UI](https://docs.getdbt.com/img/docs/dbt-cloud/using-dbt-cloud/create-ci-job.png?v=2 "Example of CI Job page in the dbt UI")](https://docs.getdbt.com/docs/deploy/ci-jobs#) Example of CI Job page in the dbt UI ### Example of CI check in pull request[​](https://docs.getdbt.com/docs/deploy/ci-jobs#example-ci-check "Direct link to Example of CI check in pull request") The following is an example of a CI check in a GitHub pull request. The green checkmark means the dbt build and tests were successful. Clicking on the dbt section takes you to the relevant CI run in dbt. [![Example of CI check in GitHub pull request](https://docs.getdbt.com/img/docs/dbt-cloud/using-dbt-cloud/example-github-pr.png?v=2 "Example of CI check in GitHub pull request")](https://docs.getdbt.com/docs/deploy/ci-jobs#) Example of CI check in GitHub pull request ### Example of CI report in pull request [preview](https://docs.getdbt.com/docs/dbt-versions/product-lifecycles "Go to https://docs.getdbt.com/docs/dbt-versions/product-lifecycles") [​](https://docs.getdbt.com/docs/deploy/ci-jobs#example-ci-report "Direct link to example-ci-report") The following is an example of a CI report in a GitHub pull request, which is shown when the **dbt compare** option is enabled for the CI job. It displays a high-level summary of the models that changed from the pull request. [![Example of CI report comment in GitHub pull request](https://docs.getdbt.com/img/docs/dbt-cloud/using-dbt-cloud/example-github-ci-report.png?v=2 "Example of CI report comment in GitHub pull request")](https://docs.getdbt.com/docs/deploy/ci-jobs#) Example of CI report comment in GitHub pull request Trigger a CI job with the API [Enterprise](https://www.getdbt.com/pricing "Go to https://www.getdbt.com/pricing") [Enterprise +](https://www.getdbt.com/pricing "Go to https://www.getdbt.com/pricing") [​](https://docs.getdbt.com/docs/deploy/ci-jobs#trigger-a-ci-job-with-the-api- "Direct link to trigger-a-ci-job-with-the-api-") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- If you're not using dbt’s native Git integration with [GitHub](https://docs.getdbt.com/docs/cloud/git/connect-github) , [GitLab](https://docs.getdbt.com/docs/cloud/git/connect-gitlab) , or [Azure DevOps](https://docs.getdbt.com/docs/cloud/git/connect-azure-devops) , you can use the [Administrative API](https://docs.getdbt.com/docs/dbt-cloud-apis/admin-cloud-api) to trigger a CI job to run. However, dbt will not automatically delete the temporary schema for you. This is because automatic deletion relies on incoming webhooks from Git providers, which is only available through the native integrations. ### Prerequisites[​](https://docs.getdbt.com/docs/deploy/ci-jobs#prerequisites-1 "Direct link to Prerequisites") * You have a dbt account. * You have a dbt [Enterprise or Enterprise+ plan](https://www.getdbt.com/pricing/) . Legacy Team plans also retain access. * For the [Concurrent CI checks](https://docs.getdbt.com/docs/deploy/continuous-integration#concurrent-ci-checks) and [Smart cancellation of stale builds](https://docs.getdbt.com/docs/deploy/continuous-integration#smart-cancellation) features, your dbt account must be on the [Enterprise or Enterprise+ plan](https://www.getdbt.com/pricing/) , and legacy Team plans. Starter plans do not have access to these features when triggering a CI job with the API. 1. Set up a CI job with the [Create Job](https://docs.getdbt.com/dbt-cloud/api-v2#/operations/Create%20Job) API endpoint using `"job_type": ci` or from the [dbt UI](https://docs.getdbt.com/docs/deploy/ci-jobs#set-up-ci-jobs) . 2. Call the [Trigger Job Run](https://docs.getdbt.com/dbt-cloud/api-v2#/operations/Trigger%20Job%20Run) API endpoint to trigger the CI job. You must include both of these fields to the payload: * Provide the pull request (PR) ID using one of these fields: * `github_pull_request_id` * `gitlab_merge_request_id` * `azure_devops_pull_request_id` * `non_native_pull_request_id` (for example, BitBucket) * Provide the `git_sha` or `git_branch` to target the correct commit or branch to run the job against. Semantic validations in CI [Starter](https://www.getdbt.com/pricing "Go to https://www.getdbt.com/pricing") [Enterprise](https://www.getdbt.com/pricing "Go to https://www.getdbt.com/pricing") [Enterprise +](https://www.getdbt.com/pricing "Go to https://www.getdbt.com/pricing") [​](https://docs.getdbt.com/docs/deploy/ci-jobs#semantic-validations-in-ci-- "Direct link to semantic-validations-in-ci--") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ Automatically test your semantic nodes (metrics, semantic models, and saved queries) during code reviews by adding warehouse validation checks in your CI job, guaranteeing that any code changes made to dbt models don't break these metrics. To do this, add the command `dbt sl validate --select state:modified+` in the CI job. This ensures the validation of modified semantic nodes and their downstream dependencies. [![Semantic validations in CI workflow](https://docs.getdbt.com/img/docs/dbt-cloud/deployment/sl-ci-job.png?v=2 "Semantic validations in CI workflow")](https://docs.getdbt.com/docs/deploy/ci-jobs#) Semantic validations in CI workflow #### Benefits[​](https://docs.getdbt.com/docs/deploy/ci-jobs#benefits "Direct link to Benefits") * Testing semantic nodes in a CI job supports deferral and selection of semantic nodes. * It allows you to catch issues early in the development process and deliver high-quality data to your end users. * Semantic validation executes an explain query in the data warehouse for semantic nodes to ensure the generated SQL will execute. * For semantic nodes and models that aren't downstream of modified models, dbt defers to the production models ### Set up semantic validations in your CI job[​](https://docs.getdbt.com/docs/deploy/ci-jobs#set-up-semantic-validations-in-your-ci-job "Direct link to Set up semantic validations in your CI job") To learn how to set this up, refer to the following steps: 1. Navigate to the **Job setting** page and click **Edit**. 2. Add the `dbt sl validate --select state:modified+` command under **Commands** in the **Execution settings** section. The command uses state selection and deferral to run validation on any semantic nodes downstream of model changes. To reduce job times, we recommend only running CI on modified semantic models. 3. Click **Save** to save your changes. There are additional commands and use cases described in the [next section](https://docs.getdbt.com/docs/deploy/ci-jobs#use-cases) , such as validating all semantic nodes, validating specific semantic nodes, and so on. [![Validate semantic nodes downstream of model changes in your CI job.](https://docs.getdbt.com/img/docs/dbt-cloud/deployment/ci-dbt-sl-validate-downstream.png?v=2 "Validate semantic nodes downstream of model changes in your CI job.")](https://docs.getdbt.com/docs/deploy/ci-jobs#) Validate semantic nodes downstream of model changes in your CI job. ### Use cases[​](https://docs.getdbt.com/docs/deploy/ci-jobs#use-cases "Direct link to Use cases") Use or combine different selectors or commands to validate semantic nodes in your CI job. Semantic validations in CI supports the following use cases:  Semantic nodes downstream of model changes (recommended) To validate semantic nodes that are downstream of a model change, add the two commands in your job **Execution settings** section: dbt build --select state:modified+dbt sl validate --select state:modified+ * The first command builds the modified models. * The second command validates the semantic nodes downstream of the modified models. Before running semantic validations, dbt must build the modified models. This process ensures that downstream semantic nodes are validated using the CI schema through the dbt Semantic Layer API. For semantic nodes and models that aren't downstream of modified models, dbt defers to the production models. [![Validate semantic nodes downstream of model changes in your CI job.](https://docs.getdbt.com/img/docs/dbt-cloud/deployment/ci-dbt-sl-validate-downstream.png?v=2 "Validate semantic nodes downstream of model changes in your CI job.")](https://docs.getdbt.com/docs/deploy/ci-jobs#) Validate semantic nodes downstream of model changes in your CI job. Semantic nodes that are modified or affected by downstream modified nodes. To only validate modified semantic nodes, use the following command (with [state selection](https://docs.getdbt.com/reference/node-selection/state-selection) ): dbt sl validate --select state:modified+ [![Use state selection to validate modified metric definition models in your CI job.](https://docs.getdbt.com/img/docs/dbt-cloud/deployment/ci-dbt-sl-validate-modified.png?v=2 "Use state selection to validate modified metric definition models in your CI job.")](https://docs.getdbt.com/docs/deploy/ci-jobs#) Use state selection to validate modified metric definition models in your CI job. This will only validate semantic nodes. It will use the defer state set configured in your orchestration job, deferring to your production models. Select specific semantic nodes Use the selector syntax to select the _specific_ semantic node(s) you want to validate: dbt sl validate --select metric:revenue [![Use state selection to validate modified metric definition models in your CI job.](https://docs.getdbt.com/img/docs/dbt-cloud/deployment/ci-dbt-sl-validate-select.png?v=2 "Use state selection to validate modified metric definition models in your CI job.")](https://docs.getdbt.com/docs/deploy/ci-jobs#) Use state selection to validate modified metric definition models in your CI job. In this example, the CI job will validate the selected `metric:revenue` semantic node. To select multiple semantic nodes, use the selector syntax: `dbt sl validate --select metric:revenue metric:customers`. If you don't specify a selector, dbt will validate all semantic nodes in your project. Select all semantic nodes To validate _all_ semantic nodes in your project, add the following command to defer to your production schema when generating the warehouse validation queries: dbt sl validate [![Validate all semantic nodes in your CI job by adding the command: 'dbt sl validate' in your job execution settings.](https://docs.getdbt.com/img/docs/dbt-cloud/deployment/ci-dbt-sl-validate-all.png?v=2 "Validate all semantic nodes in your CI job by adding the command: 'dbt sl validate' in your job execution settings.")](https://docs.getdbt.com/docs/deploy/ci-jobs#) Validate all semantic nodes in your CI job by adding the command: 'dbt sl validate' in your job execution settings. Troubleshooting[​](https://docs.getdbt.com/docs/deploy/ci-jobs#troubleshooting "Direct link to Troubleshooting") ----------------------------------------------------------------------------------------------------------------- Unable to trigger a CI job with GitLab When you connect dbt to a GitLab repository, GitLab automatically registers a webhook in the background, viewable under the repository settings. This webhook is also used to trigger [CI jobs](https://docs.getdbt.com/docs/deploy/ci-jobs) when you push to the repository. If you're unable to trigger a CI job, this usually indicates that the webhook registration is missing or incorrect. To resolve this issue, navigate to the repository settings in GitLab and view the webhook registrations by navigating to GitLab --> **Settings** --> **Webhooks**. Some things to check: * The webhook registration is enabled in GitLab. * The webhook registration is configured with the correct URL and secret. If you're still experiencing this issue, reach out to the Support team at [support@getdbt.com](mailto:support@getdbt.com) and we'll be happy to help!  CI jobs aren't triggering occasionally when opening a PR using the Azure DevOps (ADO) integration dbt won't trigger a CI job run if the latest commit in a pull or merge request has already triggered a run for that job. However, some providers (like GitHub) will enforce the result of the existing run on multiple pull/merge requests. Scenarios where dbt does not trigger a CI job with Azure DevOps: 1. Reusing a branch in a new PR * If you abandon a previous PR (PR 1) that triggered a CI job for the same branch (`feature-123`) merging into `main`, and then open a new PR (PR 2) with the same branch merging into`main` — dbt won't trigger a new CI job for PR 2. 2. Reusing the same commit * If you create a new PR (PR 2) on the same commit (`#4818ceb`) as a previous PR (PR 1) that triggered a CI job — dbt won't trigger a new CI job for PR 2.  Temporary schemas aren't dropping If your temporary schemas aren't dropping after a PR merges or closes, this typically indicates one of these issues: * You have overridden the `generate_schema_name` macro and it isn't using `dbt_cloud_pr_` as the prefix. To resolve this, change your macro so that the temporary PR schema name contains the required prefix. For example: * ✅ Temporary PR schema name contains the prefix `dbt_cloud_pr_` (like `dbt_cloud_pr_123_456_marketing`). * ❌ Temporary PR schema name doesn't contain the prefix `dbt_cloud_pr_` (like `marketing`). A macro is creating a schema but there are no dbt models writing to that schema. dbt doesn't drop temporary schemas that weren't written to as a result of running a dbt model.  Error messages that refer to schemas from previous PRs If you receive a schema-related error message referencing a _previous_ PR, this is usually an indicator that you are not using a production job for your deferral and are instead using _self_. If the prior PR has already been merged, the prior PR's schema may have been dropped by the time the CI job for the current PR is kicked off. To fix this issue, select a production job run to defer to instead of self.  Production job runs failing at the 'Clone Git Repository step' dbt can only check out commits that belong to the original repository. dbt _cannot_ checkout commits that belong to a fork of that repository. If you receive the following error message at the **Clone Git Repository** step of your job run: Error message:Cloning into '/tmp/jobs/123456/target'...Successfully cloned repository.Checking out to e845be54e6dc72342d5a8f814c8b3316ee220312...>Failed to checkout to specified revision.git checkout e845be54e6dc72342d5a8f814c8b3316ee220312fatal: reference is not a tree: e845be54e6dc72342d5a8f814c8b3316ee220312 Double-check that your PR isn't trying to merge using a commit that belongs to a fork of the repository attached to your dbt project.  CI job not triggering for Virtual Private dbt users To trigger jobs on dbt using the [API](https://docs.getdbt.com/docs/dbt-cloud-apis/admin-cloud-api) , your Git provider needs to connect to your dbt account. If you're on a Virtual Private dbt Enterprise plan using security features like ingress PrivateLink or IP Allowlisting, registering CI hooks may not be available and can cause the job to fail silently.  PR status for CI job stays in 'pending' in Azure DevOps after job run finishes When you start a CI job, the pull request status should show as `pending` while it waits for an update from dbt. Once the CI job finishes, dbt sends the status to Azure DevOps (ADO), and the status will change to either `succeeded` or `failed`. If the status doesn't get updated after the job runs, check if there are any git branch policies in place blocking ADO from receiving these updates. One potential issue is the **Reset conditions** under **Status checks** in the ADO repository branch policy. If you enable the **Reset status whenever there are new changes** checkbox (under **Reset conditions**), it can prevent dbt from updating ADO about your CI job run status. You can find relevant information here: * [Azure DevOps Services Status checks](https://learn.microsoft.com/en-us/azure/devops/repos/git/branch-policies?view=azure-devops&tabs=browser#status-checks) * [Azure DevOps Services Pull Request Stuck Waiting on Status Update](https://support.hashicorp.com/hc/en-us/articles/18670331556627-Azure-DevOps-Services-Pull-Request-Stuck-Waiting-on-Status-Update-from-Terraform-Cloud-Enterprise-Run) * [Pull request status](https://learn.microsoft.com/en-us/azure/devops/repos/git/pull-request-status?view=azure-devops#pull-request-status) Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Prerequisites](https://docs.getdbt.com/docs/deploy/ci-jobs#prerequisites) * [Availability of features by Git provider](https://docs.getdbt.com/docs/deploy/ci-jobs#availability-of-features-by-git-provider) * [Set up CI jobs](https://docs.getdbt.com/docs/deploy/ci-jobs#set-up-ci-jobs) * [Example of CI check in pull request](https://docs.getdbt.com/docs/deploy/ci-jobs#example-ci-check) * [Example of CI report in pull request](https://docs.getdbt.com/docs/deploy/ci-jobs#example-ci-report) * [Trigger a CI job with the API](https://docs.getdbt.com/docs/deploy/ci-jobs#trigger-a-ci-job-with-the-api-) * [Prerequisites](https://docs.getdbt.com/docs/deploy/ci-jobs#prerequisites-1) * [Semantic validations in CI](https://docs.getdbt.com/docs/deploy/ci-jobs#semantic-validations-in-ci--) * [Set up semantic validations in your CI job](https://docs.getdbt.com/docs/deploy/ci-jobs#set-up-semantic-validations-in-your-ci-job) * [Use cases](https://docs.getdbt.com/docs/deploy/ci-jobs#use-cases) * [Troubleshooting](https://docs.getdbt.com/docs/deploy/ci-jobs#troubleshooting) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/deploy/ci-jobs.md) --- # Deploy jobs | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/deploy/deploy-jobs#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page You can use deploy jobs to build production data assets. Deploy jobs make it easy to run dbt commands against a project in your cloud data platform, triggered either by schedule or events. Each job run in dbt will have an entry in the job's run history and a detailed run overview, which provides you with: * Job trigger type * Commit SHA * Environment name * Sources and documentation info, if applicable * Job run details, including run timing, [model timing data](https://docs.getdbt.com/docs/deploy/run-visibility#model-timing) , and [artifacts](https://docs.getdbt.com/docs/deploy/artifacts) * Detailed run steps with logs and their run step statuses You can create a deploy job and configure it to run on [scheduled days and times](https://docs.getdbt.com/docs/deploy/deploy-jobs#schedule-days) , enter a [custom cron schedule](https://docs.getdbt.com/docs/deploy/deploy-jobs#cron-schedule) , or [trigger the job after another job completes](https://docs.getdbt.com/docs/deploy/deploy-jobs#trigger-on-job-completion) . Prerequisites[​](https://docs.getdbt.com/docs/deploy/deploy-jobs#prerequisites "Direct link to Prerequisites") --------------------------------------------------------------------------------------------------------------- * You must have a [dbt account](https://www.getdbt.com/signup/) and [Developer seat license](https://docs.getdbt.com/docs/cloud/manage-access/seats-and-users) . * For the [Trigger on job completion](https://docs.getdbt.com/docs/deploy/deploy-jobs#trigger-on-job-completion) feature, your dbt account must be on the [Starter or an Enterprise-tier](https://www.getdbt.com/pricing/) plan. * You must have a dbt project connected to a [data platform](https://docs.getdbt.com/docs/cloud/connect-data-platform/about-connections) . * You must have [access permission](https://docs.getdbt.com/docs/cloud/manage-access/about-user-access) to view, create, modify, or run jobs. * You must set up a [deployment environment](https://docs.getdbt.com/docs/deploy/deploy-environments) . Create and schedule jobs[​](https://docs.getdbt.com/docs/deploy/deploy-jobs#create-and-schedule-jobs "Direct link to Create and schedule jobs") ------------------------------------------------------------------------------------------------------------------------------------------------ 1. On your deployment environment page, click **Create job** > **Deploy job** to create a new deploy job. 2. Options in the **Job settings** section: * **Job name** — Specify the name for the deploy job. For example, `Daily build`. * (Optional) **Description** — Provide a description of what the job does (for example, what the job consumes and what the job produces). * **Environment** — By default, it’s set to the deployment environment you created the deploy job from. 3. Options in the **Execution settings** section: * [**Commands**](https://docs.getdbt.com/docs/deploy/job-commands#built-in-commands) — By default, it includes the `dbt build` command. Click **Add command** to add more [commands](https://docs.getdbt.com/docs/deploy/job-commands) that you want to be invoked when the job runs. During a job run, [built-in commands](https://docs.getdbt.com/docs/deploy/job-commands#built-in-commands) are "chained" together and if one run step fails, the entire job fails with an "Error" status. * [**Generate docs on run**](https://docs.getdbt.com/docs/deploy/job-commands#checkbox-commands) — Enable this option if you want to [generate project docs](https://docs.getdbt.com/docs/explore/build-and-view-your-docs) when this deploy job runs. If the step fails, the job can succeed if subsequent steps pass. * [**Run source freshness**](https://docs.getdbt.com/docs/deploy/job-commands#checkbox-commands) — Enable this option to invoke the `dbt source freshness` command before running the deploy job. If the step fails, the job can succeed if subsequent steps pass. Refer to [Source freshness](https://docs.getdbt.com/docs/deploy/source-freshness) for more details. 4. Options in the **Triggers** section: * **Run on schedule** — Run the deploy job on a set schedule. * **Timing** — Specify whether to [schedule](https://docs.getdbt.com/docs/deploy/deploy-jobs#schedule-days) the deploy job using **Intervals** that run the job every specified number of hours, **Specific hours** that run the job at specific times of day, or **Cron schedule** that run the job specified using [cron syntax](https://docs.getdbt.com/docs/deploy/deploy-jobs#cron-schedule) . * **Days of the week** — By default, it’s set to every day when **Intervals** or **Specific hours** is chosen for **Timing**. * **Run when another job finishes** — Run the deploy job when another _upstream_ deploy [job completes](https://docs.getdbt.com/docs/deploy/deploy-jobs#trigger-on-job-completion) . * **Project** — Specify the parent project that has that upstream deploy job. * **Job** — Specify the upstream deploy job. * **Completes on** — Select the job run status(es) that will [enqueue](https://docs.getdbt.com/docs/deploy/job-scheduler#scheduler-queue) the deploy job. [![Example of Triggers on the Deploy Job page](https://docs.getdbt.com/img/docs/dbt-cloud/using-dbt-cloud/example-triggers-section.png?v=2 "Example of Triggers on the Deploy Job page")](https://docs.getdbt.com/docs/deploy/deploy-jobs#) Example of Triggers on the Deploy Job page 5. (Optional) Options in the **Advanced settings** section: * **Environment variables** — Define [environment variables](https://docs.getdbt.com/docs/build/environment-variables) to customize the behavior of your project when the deploy job runs. * **Target name** — Define the [target name](https://docs.getdbt.com/docs/build/custom-target-names) to customize the behavior of your project when the deploy job runs. Environment variables and target names are often used interchangeably. * **Run timeout** — Cancel the deploy job if the run time exceeds the timeout value. * **Compare changes against** — By default, it’s set to **No deferral**. Select either **Environment** or **This Job** to let dbt know what it should compare the changes against. info Older versions of dbt only allow you to defer to a specific job instead of an environment. Deferral to a job compares state against the project code that was run in the deferred job's last successful run. While deferral to an environment is more efficient as dbt will compare against the project representation (which is stored in the `manifest.json`) of the last successful deploy job run that executed in the deferred environment. By considering _all_ deploy jobs that run in the deferred environment, dbt will get a more accurate, latest project representation state. * **dbt version** — By default, it’s set to inherit the [dbt version](https://docs.getdbt.com/docs/dbt-versions/core) from the environment. dbt Labs strongly recommends that you don't change the default setting. This option to change the version at the job level is useful only when you upgrade a project to the next dbt version; otherwise, mismatched versions between the environment and job can lead to confusing behavior. * **Threads** — By default, it’s set to 4 [threads](https://docs.getdbt.com/docs/core/connect-data-platform/connection-profiles#understanding-threads) . Increase the thread count to increase model execution concurrency. [![Example of Advanced Settings on the Deploy Job page](https://docs.getdbt.com/img/docs/dbt-cloud/using-dbt-cloud/deploy-job-adv-settings.png?v=2 "Example of Advanced Settings on the Deploy Job page")](https://docs.getdbt.com/docs/deploy/deploy-jobs#) Example of Advanced Settings on the Deploy Job page ### Schedule days[​](https://docs.getdbt.com/docs/deploy/deploy-jobs#schedule-days "Direct link to Schedule days") To set your job's schedule, use the **Run on schedule** option to choose specific days of the week, and select customized hours or intervals. Under **Timing**, you can either use regular intervals for jobs that need to run frequently throughout the day or customizable hours for jobs that need to run at specific times: * **Intervals** — Use this option to set how often your job runs, in hours. For example, if you choose **Every 2 hours**, the job will run every 2 hours from midnight UTC. This doesn't mean that it will run at exactly midnight UTC. However, subsequent runs will always be run with the same amount of time between them. For example, if the previous scheduled pipeline ran at 00:04 UTC, the next run will be at 02:04 UTC. This option is useful if you need to run jobs multiple times per day at regular intervals. * **Specific hours** — Use this option to set specific times when your job should run. You can enter a comma-separated list of hours (in UTC) when you want the job to run. For example, if you set it to `0,12,23,` the job will run at midnight, noon, and 11 PM UTC. Job runs will always be consistent between both hours and days, so if your job runs at 00:05, 12:05, and 23:05 UTC, it will run at these same hours each day. This option is useful if you want your jobs to run at specific times of day and don't need them to run more frequently than once a day. info dbt uses [Coordinated Universal Time](https://en.wikipedia.org/wiki/Coordinated_Universal_Time) (UTC) and does not account for translations to your specific timezone or take into consideration daylight savings time. For example: * 0 means 12am (midnight) UTC * 12 means 12pm (afternoon) UTC * 23 means 11pm UTC ### Cron schedule[​](https://docs.getdbt.com/docs/deploy/deploy-jobs#cron-schedule "Direct link to Cron schedule") To fully customize the scheduling of your job, choose the **Cron schedule** option and use cron syntax. With this syntax, you can specify the minute, hour, day of the month, month, and day of the week, allowing you to set up complex schedules like running a job on the first Monday of each month. **Cron frequency** To enhance performance, job scheduling frequencies vary by dbt plan: * Developer plans: dbt sets a minimum interval of every 10 minutes for scheduling jobs. This means scheduling jobs to run more frequently, or at less than 10 minute intervals, is not supported. * Starter, Enterprise, and Enterprise+ plans: No restrictions on job execution frequency. **Examples** Use tools such as [crontab.guru](https://crontab.guru/) to generate the correct cron syntax. This tool allows you to input cron snippets and return their plain English translations. The dbt job scheduler supports using `L` to schedule jobs on the last day of the month. Examples of cron job schedules: * `0 * * * *`: Every hour, at minute 0. * `*/5 * * * *`: Every 5 minutes. (Not available on Developer plans) * `5 4 * * *`: At exactly 4:05 AM UTC. * `30 */4 * * *`: At minute 30 past every 4th hour (such as 4:30 AM, 8:30 AM, 12:30 PM, and so on, all UTC). * `0 0 */2 * *`: At 12:00 AM (midnight) UTC every other day. * `0 0 * * 1`: At midnight UTC every Monday. * `0 0 L * *`: At 12:00 AM (midnight), on the last day of the month. * `0 0 L 1,2,3,4,5,6,8,9,10,11,12 *`: At 12:00 AM, on the last day of the month, only in January, February, March, April, May, June, August, September, October, November, and December. * `0 0 L 7 *`: At 12:00 AM, on the last day of the month, only in July. * `0 0 L * FRI,SAT`: At 12:00 AM, on the last day of the month, and on Friday and Saturday. * `0 12 L * *`: At 12:00 PM (afternoon), on the last day of the month. * `0 7 L * 5`: At 07:00 AM, on the last day of the month, and on Friday. * `30 14 L * *`: At 02:30 PM, on the last day of the month. ### Trigger on job completion [Starter](https://www.getdbt.com/pricing "Go to https://www.getdbt.com/pricing") [Enterprise](https://www.getdbt.com/pricing "Go to https://www.getdbt.com/pricing") [Enterprise +](https://www.getdbt.com/pricing "Go to https://www.getdbt.com/pricing") [​](https://docs.getdbt.com/docs/deploy/deploy-jobs#trigger-on-job-completion-- "Direct link to trigger-on-job-completion--") To _chain_ deploy jobs together: 1. In the **Triggers** section, enable the **Run when another job finishes** option. 2. Select the project that has the deploy job you want to run after completion. 3. Specify the upstream (parent) job that, when completed, will trigger your job. * You can also use the [Create Job API](https://docs.getdbt.com/dbt-cloud/api-v2#/operations/Create%20Job) to do this. 4. In the **Completes on** option, select the job run status(es) that will [enqueue](https://docs.getdbt.com/docs/deploy/job-scheduler#scheduler-queue) the deploy job. [![Example of Trigger on job completion on the Deploy job page](https://docs.getdbt.com/img/docs/deploy/deploy-job-completion.jpg?v=2 "Example of Trigger on job completion on the Deploy job page")](https://docs.getdbt.com/docs/deploy/deploy-jobs#) Example of Trigger on job completion on the Deploy job page 5. You can set up a configuration where an upstream job triggers multiple downstream (child) jobs and jobs in other projects. You must have proper [permissions](https://docs.getdbt.com/docs/cloud/manage-access/enterprise-permissions#project-role-permissions) to the project and job to configure the trigger. If another job triggers your job to run, you can find a link to the upstream job in the [run details section](https://docs.getdbt.com/docs/deploy/run-visibility#job-run-details) . Delete a job[​](https://docs.getdbt.com/docs/deploy/deploy-jobs#delete-a-job "Direct link to Delete a job") ------------------------------------------------------------------------------------------------------------ To delete a job or multiple jobs in dbt: 1. Click **Deploy** on the navigation header. 2. Click **Jobs** and select the job you want to delete. 3. Click **Settings** on the top right of the page and then click **Edit**. 4. Scroll to the bottom of the page and click **Delete** to delete the job. [![Delete a job](https://docs.getdbt.com/img/docs/dbt-cloud/cloud-configuring-dbt-cloud/delete-job.png?v=2 "Delete a job")](https://docs.getdbt.com/docs/deploy/deploy-jobs#) Delete a job 5. Confirm your action in the pop-up by clicking **Confirm delete** in the bottom right to delete the job immediately. This action cannot be undone. However, you can create a new job with the same information if the deletion was made in error. 6. Refresh the page, and the deleted job should now be gone. If you want to delete multiple jobs, you'll need to perform these steps for each job. If you're having any issues, feel free to [contact us](mailto:support@getdbt.com) for additional help. Job settings history[​](https://docs.getdbt.com/docs/deploy/deploy-jobs#job-settings-history "Direct link to Job settings history") ------------------------------------------------------------------------------------------------------------------------------------ You can view historical job settings changes over the last 90 days. To view the change history: 1. Navigate to **Orchestration** from the main menu and click **Jobs**. 2. Click a **job name**. 3. Click **Settings**. 4. Click **History**. [![Example of the job settings history.](https://docs.getdbt.com/img/docs/deploy/job-history.png?v=2 "Example of the job settings history.")](https://docs.getdbt.com/docs/deploy/deploy-jobs#) Example of the job settings history. Related docs[​](https://docs.getdbt.com/docs/deploy/deploy-jobs#related-docs "Direct link to Related docs") ------------------------------------------------------------------------------------------------------------ * [Artifacts](https://docs.getdbt.com/docs/deploy/artifacts) * [Continuous integration (CI) jobs](https://docs.getdbt.com/docs/deploy/ci-jobs) * [Webhooks](https://docs.getdbt.com/docs/deploy/webhooks) Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Prerequisites](https://docs.getdbt.com/docs/deploy/deploy-jobs#prerequisites) * [Create and schedule jobs](https://docs.getdbt.com/docs/deploy/deploy-jobs#create-and-schedule-jobs) * [Schedule days](https://docs.getdbt.com/docs/deploy/deploy-jobs#schedule-days) * [Cron schedule](https://docs.getdbt.com/docs/deploy/deploy-jobs#cron-schedule) * [Trigger on job completion](https://docs.getdbt.com/docs/deploy/deploy-jobs#trigger-on-job-completion--) * [Delete a job](https://docs.getdbt.com/docs/deploy/deploy-jobs#delete-a-job) * [Job settings history](https://docs.getdbt.com/docs/deploy/deploy-jobs#job-settings-history) * [Related docs](https://docs.getdbt.com/docs/deploy/deploy-jobs#related-docs) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/deploy/deploy-jobs.md) --- # External metadata ingestion | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/explore/external-metadata-ingestion#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page With external metadata ingestion, you can connect directly to your data warehouse, giving you visibility into tables, views, and other resources that aren't defined in dbt with Catalog. External metadata ingestion support Currently, external metadata ingestion is supported for Snowflake only. External metadata credentials enable ingestion of metadata that exists _outside_ your dbt runs like tables, views, or cost information; typically at a higher level than what dbt environments access. This is useful for enriching Catalog with warehouse-native insights (for example, Snowflake views or access patterns) and creating a unified discovery experience. These credentials are configured separately from dbt environment credentials and are scoped at the account level, not the project level. Prerequisites[​](https://docs.getdbt.com/docs/explore/external-metadata-ingestion#prerequisites "Direct link to Prerequisites") -------------------------------------------------------------------------------------------------------------------------------- * Have a dbt account on the [Enterprise or Enterprise+](https://www.getdbt.com/pricing)  plan. * You must be an [account admin with permission](https://docs.getdbt.com/docs/cloud/manage-access/enterprise-permissions#account-admin) to edit connections. * The credentials must have [sufficient read-level access to fetch metadata](https://docs.getdbt.com/docs/explore/external-metadata-ingestion#configuration-instructions) . * Have [**global navigation**](https://docs.getdbt.com/docs/explore/explore-projects#catalog-overview) enabled. * Use Snowflake as your data platform. * Stayed tuned! Coming very soon, there’ll be support in future for other adapters! Configuration instructions[​](https://docs.getdbt.com/docs/explore/external-metadata-ingestion#configuration-instructions "Direct link to Configuration instructions") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### Enable external metadata ingestion[​](https://docs.getdbt.com/docs/explore/external-metadata-ingestion#enable-external-metadata-ingestion "Direct link to Enable external metadata ingestion") 1. Click your account name at the bottom of the left-side menu and click **[Account settings](https://docs.getdbt.com/docs/cloud/account-settings) **. 2. Under Account information, go to **Settings** and click **Edit** at the top right corner of the page. 3. Select the **Ingest external metadata in dbt Catalog (formerly dbt Explorer)** option (if not already enabled). ### Configure the warehouse connection[​](https://docs.getdbt.com/docs/explore/external-metadata-ingestion#configure-the-warehouse-connection "Direct link to Configure the warehouse connection") 1. Go to **Account settings**. 2. Click **Connections** from the left-hand side panel. 3. Select an existing connection or create a [**New connection**](https://docs.getdbt.com/docs/cloud/connect-data-platform/connect-snowflake) where you want to ingest metadata from. 4. Scroll to the bottom of the page and click **Add credentials** in **Platform metadata credentials**. * Enter the necessary credentials. These should have warehouse-level visibility across relevant databases and schemas. 5. Select the **External metadata ingestion** option. * This allows metadata from this connection to populate the Catalog. * _Optional_: Enable additional features such as **cost optimization** in the **Features** section under **Platform metadata credentials**. 6. Under **Catalog filters**, apply filters to restrict which metadata is ingested: * You can filter by **database**, **schema**, **table**, or **view**. * **Note:** To include all databases or schemas, enter `.*` in the **Allow** field. * It is strongly recommend to filter by certain schemas. See [Important considerations](https://docs.getdbt.com/docs/explore/external-metadata-ingestion#important-considerations) for more information. * These fields accept CSV-formatted regular expressions: * Example: `DIM` matches `DIM_ORDERS` and `DIMENSION_TABLE` (basic "contains" match). * Wildcards are supported. For example: `DIM*` matches `DIM_ORDERS` and `DIM_PRODUCTS`. Required credentials[​](https://docs.getdbt.com/docs/explore/external-metadata-ingestion#required-credentials "Direct link to Required credentials") ----------------------------------------------------------------------------------------------------------------------------------------------------- This section sets up the foundational access for dbt in Snowflake. It creates a role (`dbt_metadata_role`) with minimal permissions and a user (`dbt_metadata_user`) dedicated to dbt’s metadata access. This ensures a clear, controlled separation of access, so dbt can read metadata without broader permissions. This setup ensures dbt can read metadata for profiling, documentation, and lineage, without the ability to modify data or manage resources. 1. Create role: CREATE OR REPLACE ROLE dbt_metadata_role; 2. Grant access to a warehouse to run queries to view metadata: GRANT USAGE ON WAREHOUSE "" TO ROLE dbt_metadata_role; If your warehouse needs to be restarted for metadata ingestions (doesn't have auto-resume enabled), you may need to grant `OPERATE` permissions to the role as well. If you do not already have a user, create a dbt-specific user for metadata access. Replace `` with a strong password and `` with the warehouse name used above: CREATE USER dbt_metadata_user DISPLAY_NAME = 'dbt Metadata Integration' PASSWORD = 'our-password>' DEFAULT_ROLE = dbt_metadata_role TYPE = 'LEGACY_SERVICE' DEFAULT_WAREHOUSE = ''; 3. Grant the role to the user: GRANT ROLE dbt_metadata_role TO USER dbt_metadata_user; Note: Use read-only service accounts for least privilege and better auditing. Assign metadata access privileges[​](https://docs.getdbt.com/docs/explore/external-metadata-ingestion#assign-metadata-access-privileges "Direct link to Assign metadata access privileges") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- This section outlines the minimum necessary privileges to read metadata from each required Snowflake database. It provides access to schemas, tables, views, and lineage information, ensuring dbt can profile and document your data while preventing any modifications. Replace `your-database` with the name of a Snowflake database to grant metadata access. Repeat this block for each relevant database: SET db_var = '""';-- Grant access to view the database and its schemasGRANT USAGE ON DATABASE IDENTIFIER($db_var) TO ROLE dbt_metadata_role;GRANT USAGE ON ALL SCHEMAS IN DATABASE IDENTIFIER($db_var) TO ROLE dbt_metadata_role;GRANT USAGE ON FUTURE SCHEMAS IN DATABASE IDENTIFIER($db_var) TO ROLE dbt_metadata_role;-- Grant REFERENCES to enable lineage and dependency analysisGRANT REFERENCES ON ALL TABLES IN DATABASE IDENTIFIER($db_var) TO ROLE dbt_metadata_role;GRANT REFERENCES ON FUTURE TABLES IN DATABASE IDENTIFIER($db_var) TO ROLE dbt_metadata_role;GRANT REFERENCES ON ALL EXTERNAL TABLES IN DATABASE IDENTIFIER($db_var) TO ROLE dbt_metadata_role;GRANT REFERENCES ON FUTURE EXTERNAL TABLES IN DATABASE IDENTIFIER($db_var) TO ROLE dbt_metadata_role;GRANT REFERENCES ON ALL VIEWS IN DATABASE IDENTIFIER($db_var) TO ROLE dbt_metadata_role;GRANT REFERENCES ON FUTURE VIEWS IN DATABASE IDENTIFIER($db_var) TO ROLE dbt_metadata_role;-- Recommended grant SELECT for privileges to enable metadata introspection and profilingGRANT SELECT ON ALL TABLES IN DATABASE IDENTIFIER($db_var) TO ROLE dbt_metadata_role;GRANT SELECT ON FUTURE TABLES IN DATABASE IDENTIFIER($db_var) TO ROLE dbt_metadata_role;GRANT SELECT ON ALL EXTERNAL TABLES IN DATABASE IDENTIFIER($db_var) TO ROLE dbt_metadata_role;GRANT SELECT ON FUTURE EXTERNAL TABLES IN DATABASE IDENTIFIER($db_var) TO ROLE dbt_metadata_role;GRANT SELECT ON ALL VIEWS IN DATABASE IDENTIFIER($db_var) TO ROLE dbt_metadata_role;GRANT SELECT ON FUTURE VIEWS IN DATABASE IDENTIFIER($db_var) TO ROLE dbt_metadata_role;GRANT SELECT ON ALL DYNAMIC TABLES IN DATABASE IDENTIFIER($db_var) TO ROLE dbt_metadata_role;GRANT SELECT ON FUTURE DYNAMIC TABLES IN DATABASE IDENTIFIER($db_var) TO ROLE dbt_metadata_role;-- Grant MONITOR on dynamic tables (e.g., for freshness or status checks)GRANT MONITOR ON ALL DYNAMIC TABLES IN DATABASE IDENTIFIER($db_var) TO ROLE dbt_metadata_role;GRANT MONITOR ON FUTURE DYNAMIC TABLES IN DATABASE IDENTIFIER($db_var) TO ROLE dbt_metadata_role; Grant access to Snowflake metadata[​](https://docs.getdbt.com/docs/explore/external-metadata-ingestion#grant-access-to-snowflake-metadata "Direct link to Grant access to Snowflake metadata") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- This step grants the dbt role (`dbt_metadata_role`) access to Snowflake’s system-level database, enabling it to read usage statistics, query histories, and lineage information required for comprehensive metadata insights. Grant privileges to read usage stats and lineage from Snowflake’s system-level database: GRANT IMPORTED PRIVILEGES ON DATABASE SNOWFLAKE TO ROLE dbt_metadata_role; Important considerations[​](https://docs.getdbt.com/docs/explore/external-metadata-ingestion#important-considerations "Direct link to Important considerations") ----------------------------------------------------------------------------------------------------------------------------------------------------------------- The following are best practices for external metadata ingestion, designed to ensure consistent, reliable, and scalable integration of metadata from third-party systems. * Catalog unifies the shared resources between dbt and Snowflake. For example, if there’s a Snowflake table that represents a dbt model, these are represented as a single resource in Catalog. In order for proper unification to occur, the same connection must be used by both the [production environment](https://docs.getdbt.com/docs/deploy/deploy-environments#set-as-production-environment) and the external metadata ingestion credential. * Avoid duplicates: Use one metadata connection per platform if possible (for example, one for Snowflake, one for BigQuery). * Having multiple connections pointing to the same warehouse can cause duplicate metadata. * Align with dbt environment: To unify asset lineage and metadata, ensure the same warehouse connection is used by both the dbt environment and the external metadata ingestion. * Use filters to limit ingestion to relevant assets: * For example: restrict to production schemas only, or ignore transient/temp schemas. External metadata ingestion runs daily at 5 PM UTC, and also runs immediately each time you update and save credentials. Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Prerequisites](https://docs.getdbt.com/docs/explore/external-metadata-ingestion#prerequisites) * [Configuration instructions](https://docs.getdbt.com/docs/explore/external-metadata-ingestion#configuration-instructions) * [Enable external metadata ingestion](https://docs.getdbt.com/docs/explore/external-metadata-ingestion#enable-external-metadata-ingestion) * [Configure the warehouse connection](https://docs.getdbt.com/docs/explore/external-metadata-ingestion#configure-the-warehouse-connection) * [Required credentials](https://docs.getdbt.com/docs/explore/external-metadata-ingestion#required-credentials) * [Assign metadata access privileges](https://docs.getdbt.com/docs/explore/external-metadata-ingestion#assign-metadata-access-privileges) * [Grant access to Snowflake metadata](https://docs.getdbt.com/docs/explore/external-metadata-ingestion#grant-access-to-snowflake-metadata) * [Important considerations](https://docs.getdbt.com/docs/explore/external-metadata-ingestion#important-considerations) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/explore/external-metadata-ingestion.md) --- # Data health tile | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/explore/data-tile#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page With data health tiles, stakeholders will get an at-a-glance confirmation on whether the data they’re looking at is stale or degraded. It allows teams to immediately go back into Catalog to see more details and investigate issues. The data health tile: * Distills [data health signals](https://docs.getdbt.com/docs/explore/data-health-signals) for data consumers. * Deep links you into Catalog where you can further dive into upstream data issues. * Provides richer information and makes it easier to debug. * Revamps the existing, [job-based tiles](https://docs.getdbt.com/docs/explore/data-tile#job-based-data-health) . Data health tiles rely on [exposures](https://docs.getdbt.com/docs/build/exposures) to surface data health signals in your dashboards. An exposure defines how specific outputs — like dashboards or reports — depend on your data models. Exposures in dbt can be configured in two ways: * Manual — Defined [manually](https://docs.getdbt.com/docs/build/exposures#declaring-an-exposure) and explicitly in your project’s YAML files. * Automatic — Pulled automatically for supported dbt integrations. dbt automatically [creates and visualizes downstream exposures](https://docs.getdbt.com/docs/cloud-integrations/downstream-exposures) , removing the need for manual YAML definitions. These downstream exposures are stored in dbt’s metadata system, appear in [Catalog](https://docs.getdbt.com/docs/explore/explore-projects) , and behave like manual exposures, however they don’t exist in YAML files. [![Example of passing Data health tile in your dashboard.](https://docs.getdbt.com/img/docs/collaborate/dbt-explorer/data-tile-pass.jpg?v=2 "Example of passing Data health tile in your dashboard.")](https://docs.getdbt.com/docs/explore/data-tile#) Example of passing Data health tile in your dashboard. [![Embed data health tiles in your dashboards to distill data health signals for data consumers.](https://docs.getdbt.com/img/docs/collaborate/dbt-explorer/data-tiles.png?v=2 "Embed data health tiles in your dashboards to distill data health signals for data consumers.")](https://docs.getdbt.com/docs/explore/data-tile#) Embed data health tiles in your dashboards to distill data health signals for data consumers. Prerequisites[​](https://docs.getdbt.com/docs/explore/data-tile#prerequisites "Direct link to Prerequisites") -------------------------------------------------------------------------------------------------------------- * You must have a dbt account on an [Enterprise-tier plan](https://www.getdbt.com/pricing/) . * You must be an account admin to set up [service tokens](https://docs.getdbt.com/docs/dbt-cloud-apis/service-tokens#permissions-for-service-account-tokens) . * You must have [develop permissions](https://docs.getdbt.com/docs/cloud/manage-access/seats-and-users) . * You have [exposures](https://docs.getdbt.com/docs/build/exposures) defined in your project: * If using manual exposures, they must be explicitly defined in your YAML files. * If using automatic downstream exposures, ensure your BI tool is [configured](https://docs.getdbt.com/docs/cloud-integrations/downstream-exposures-tableau) with dbt. * You have [source freshness](https://docs.getdbt.com/docs/deploy/source-freshness) enabled in the job that generates this exposure. * The exposure used for the data health tile must have the [`type` property](https://docs.getdbt.com/docs/build/exposures#available-properties) set to `dashboard`. Otherwise, you won't be able to view the **Embed data health tile in your dashboard** dropdown in Catalog. View exposure in dbt Catalog[​](https://docs.getdbt.com/docs/explore/data-tile#view-exposure-in-dbt-catalog "Direct link to View exposure in dbt Catalog") ----------------------------------------------------------------------------------------------------------------------------------------------------------- First, be sure to enable [source freshness](https://docs.getdbt.com/docs/deploy/source-freshness)  in the job that generates this exposure. 1. Navigate to Catalog by clicking on the **Explore** link in the navigation. 2. In the main **Overview** page, go to the left navigation. 3. Under the **Resources** tab, click on **Exposures** to view the [exposures](https://docs.getdbt.com/docs/build/exposures) list. 4. Select a dashboard exposure and go to the **General** tab to view the data health information. 5. In this tab, you’ll see: * Name of the exposure. * Data health status: Data freshness passed, Data quality passed, Data may be stale, Data quality degraded. * Resource type (model, source, and so on). * Dashboard status: Failure, Pass, Stale. * You can also see the last check completed, the last check time, and the last check duration. 6. You can click the **Open Dashboard** button on the upper right to immediately view this in your analytics tool. [![View an exposure in dbt Catalog.](https://docs.getdbt.com/img/docs/collaborate/dbt-explorer/data-tile-exposures.jpg?v=2 "View an exposure in dbt Catalog.")](https://docs.getdbt.com/docs/explore/data-tile#) View an exposure in dbt Catalog. Embed in your dashboard[​](https://docs.getdbt.com/docs/explore/data-tile#embed-in-your-dashboard "Direct link to Embed in your dashboard") -------------------------------------------------------------------------------------------------------------------------------------------- Once you’ve navigated to the exposure in Catalog, you’ll need to set up your data health tile and [service token](https://docs.getdbt.com/docs/dbt-cloud-apis/service-tokens) . You can embed data health tile to any analytics tool that supports URL or iFrame embedding. Follow these steps to set up your data health tile: 1. Go to **Account settings** in dbt. 2. Select **API tokens** in the left sidebar and then **Service tokens**. 3. Click on **Create service token** and give it a name. 4. Select the [**Metadata Only**](https://docs.getdbt.com/docs/dbt-cloud-apis/service-tokens) permission. This token will be used to embed the tile in your dashboard in the later steps. [![Set up your dashboard status tile and service token to embed a data health tile](https://docs.getdbt.com/img/docs/collaborate/dbt-explorer/data-tile-setup.jpg?v=2 "Set up your dashboard status tile and service token to embed a data health tile")](https://docs.getdbt.com/docs/explore/data-tile#) Set up your dashboard status tile and service token to embed a data health tile 5. Copy the **Metadata Only** token and save it in a secure location. You'll need it token in the next steps. 6. Navigate back to Catalog and select an exposure. tip The exposure used for the data health tile must have the [`type` property](https://docs.getdbt.com/docs/build/exposures#available-properties) set to `dashboard`. Otherwise, you won't be able to view the **Embed data health tile in your dashboard** dropdown in Catalog. 7. Below the **Data health** section, expand on the toggle for instructions on how to embed the exposure tile (if you're an account admin with develop permissions). 8. In the expanded toggle, you'll see a text field where you can paste your **Metadata Only token**. [![Expand the toggle to embed data health tile into your dashboard.](https://docs.getdbt.com/img/docs/collaborate/dbt-explorer/data-tile-example.jpg?v=2 "Expand the toggle to embed data health tile into your dashboard.")](https://docs.getdbt.com/docs/explore/data-tile#) Expand the toggle to embed data health tile into your dashboard. 9. Once you’ve pasted your token, you can select either **URL** or **iFrame** depending on which you need to add to your dashboard. If your analytics tool supports iFrames, you can embed the dashboard tile within it. Examples[​](https://docs.getdbt.com/docs/explore/data-tile#examples "Direct link to Examples") ----------------------------------------------------------------------------------------------- The following examples show how to embed the data health tile in PowerBI, Tableau, and Sigma. * PowerBI example * Tableau example * Sigma example You can embed the data health tile iFrame in PowerBI using PowerBI Pro Online, Fabric PowerBI, or PowerBI Desktop. [![Embed data health tile iFrame in PowerBI](https://docs.getdbt.com/img/docs/collaborate/dbt-explorer/power-bi.png?v=2 "Embed data health tile iFrame in PowerBI")](https://docs.getdbt.com/docs/explore/data-tile#) Embed data health tile iFrame in PowerBI Follow these steps to embed the data health tile in PowerBI: 1. Create a dashboard in PowerBI and connect to your database to pull in the data. 2. Create a new PowerBI measure by right-clicking on your **Data**, **More options**, and then **New measure**. [![Create a new PowerBI measure.](https://docs.getdbt.com/img/docs/collaborate/dbt-explorer/power-bi-measure.png?v=2 "Create a new PowerBI measure.")](https://docs.getdbt.com/docs/explore/data-tile#) Create a new PowerBI measure. 3. Navigate to Catalog, select the exposure, and expand the [**Embed data health into your dashboard**](https://docs.getdbt.com/docs/explore/data-tile#embed-in-your-dashboard) toggle. 4. Go to the **iFrame** tab and copy the iFrame code. Make sure the Metadata Only token is already set up. 5. In PowerBI, paste the iFrame code you copied into your measure calculation window. The iFrame code should look like this: [![In the 'Measure tools' tab, replace your values with the iFrame code.](https://docs.getdbt.com/img/docs/collaborate/dbt-explorer/power-bi-measure-tools.png?v=2 "In the 'Measure tools' tab, replace your values with the iFrame code.")](https://docs.getdbt.com/docs/explore/data-tile#) In the 'Measure tools' tab, replace your values with the iFrame code. 6. PowerBI desktop doesn't support HTML rendering by default, so you need to install an HTML component from the PowerBI Visuals Store. 7. To do this, go to **Build visuals** and then **Get more visuals**. 8. Login with your PowerBI account. 9. There are several third-party HTML visuals. The one tested for this guide is [HTML content](https://appsource.microsoft.com/en-us/product/power-bi-visuals/WA200001930?tab=Overview) . Install it, but please keep in mind it's a third-party plugin not created or supported by dbt Labs. 10. Drag the metric with the iFrame code into the HTML content widget in PowerBI. This should now display your data health tile. [![Drag the metric with the iFrame code into the HTML content widget in PowerBI. This should now display your data health tile.](https://docs.getdbt.com/img/docs/collaborate/dbt-explorer/power-bi-final.png?v=2 "Drag the metric with the iFrame code into the HTML content widget in PowerBI. This should now display your data health tile.")](https://docs.getdbt.com/docs/explore/data-tile#) Drag the metric with the iFrame code into the HTML content widget in PowerBI. This should now display your data health tile. _Refer to [this tutorial](https://www.youtube.com/watch?v=SUm9Hnq8Th8) for additional information on embedding a website into your Power BI report._ Follow these steps to embed the data health tile in Tableau: [![Embed data health tile iFrame in Tableau](https://docs.getdbt.com/img/docs/collaborate/dbt-explorer/tableau-example.png?v=2 "Embed data health tile iFrame in Tableau")](https://docs.getdbt.com/docs/explore/data-tile#) Embed data health tile iFrame in Tableau 1. Create a dashboard in Tableau and connect to your database to pull in the data. 2. Ensure you've copied the URL or iFrame snippet available in Catalog's **Data health** section, under the **Embed data health into your dashboard** toggle. 3. Insert a **Web Page** object. 4. Insert the URL and click **Ok**. https://metadata.ACCESS_URL/exposure-tile?uniqueId=exposure.EXPOSURE_NAME&environmentType=production&environmentId=220370&token= _Note, replace the placeholders with your actual values._ 5. You should now see the data health tile embedded in your Tableau dashboard. Follow these steps to embed the data health tile in Sigma: [![Embed data health tile in Sigma](https://docs.getdbt.com/img/docs/collaborate/dbt-explorer/sigma-example.jpg?v=2 "Embed data health tile in Sigma")](https://docs.getdbt.com/docs/explore/data-tile#) Embed data health tile in Sigma 1. Create a dashboard in Sigma and connect to your database to pull in the data. 2. Ensure you've copied the URL or iFrame snippet available in Catalog's **Data health** section, under the **Embed data health into your dashboard** toggle. 3. Add a new embedded UI element in your Sigma Workbook in the following format: https://metadata.ACCESS_URL/exposure-tile?uniqueId=exposure.EXPOSURE_NAME&environmentType=production&environmentId=ENV_ID_NUMBER&token= _Note, replace the placeholders with your actual values._ 4. You should now see the data health tile embedded in your Sigma dashboard. Job-based data health Legacy[​](https://docs.getdbt.com/docs/explore/data-tile#job-based-data-health- "Direct link to job-based-data-health-") ----------------------------------------------------------------------------------------------------------------------------------------------- The default experience is the [environment-based data health tile](https://docs.getdbt.com/docs/explore/data-tile#view-exposure-in-dbt-explorer) with Catalog. This section is for legacy job-based data health tiles. If you're using the revamped environment-based exposure tile, refer to the previous section. Expand the following to learn more about the legacy job-based data health tile.  Job-based data health In dbt, the [Discovery API](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-api) can power dashboard status tiles, which are job-based. A dashboard status tile is placed on a dashboard (specifically: anywhere you can embed an iFrame) to give insight into the quality and freshness of the data feeding into that dashboard. This is done in dbt [exposures](https://docs.getdbt.com/docs/build/exposures) . #### Functionality[​](https://docs.getdbt.com/docs/explore/data-tile#functionality "Direct link to Functionality") The dashboard status tile looks like this: [![](https://docs.getdbt.com/img/docs/dbt-cloud/using-dbt-cloud/dashboard-status-tiles/passing-tile.jpeg?v=2)](https://docs.getdbt.com/docs/explore/data-tile#) The data freshness check fails if any sources feeding into the exposure are stale. The data quality check fails if any dbt tests fail. A failure state could look like this: [![](https://docs.getdbt.com/img/docs/dbt-cloud/using-dbt-cloud/dashboard-status-tiles/failing-tile.jpeg?v=2)](https://docs.getdbt.com/docs/explore/data-tile#) Clicking into **see details** from the Dashboard Status Tile takes you to a landing page where you can learn more about the specific sources, models, and tests feeding into this exposure. #### Setup[​](https://docs.getdbt.com/docs/explore/data-tile#setup "Direct link to Setup") First, be sure to enable [source freshness](https://docs.getdbt.com/docs/deploy/source-freshness) in the job that generates this exposure. In order to set up your dashboard status tile, here is what you need: 1. **Metadata Only token.** You can learn how to set up a Metadata-Only token [here](https://docs.getdbt.com/docs/dbt-cloud-apis/service-tokens) . 2. **Exposure name.** You can learn more about how to set up exposures [here](https://docs.getdbt.com/docs/build/exposures) . 3. **Job iD.** Remember that you can select your job ID directly from the URL when looking at the relevant job in dbt. You can insert these three fields into the following iFrame, and then embed it **anywhere that you can embed an iFrame**: Replace `YOUR_ACCESS_URL` with your region and plan's Access URL dbt is hosted in multiple regions in the world and each region has a different access URL. Replace `YOUR_ACCESS_URL` with the appropriate [Access URL](https://docs.getdbt.com/docs/cloud/about-cloud/access-regions-ip-addresses) for your region and plan. For example, if your account is hosted in the EMEA region, you would use the following iFrame code: #### Embedding with BI tools[​](https://docs.getdbt.com/docs/explore/data-tile#embedding-with-bi-tools "Direct link to Embedding with BI tools") The dashboard status tile should work anywhere you can embed an iFrame. But below are some tactical tips on how to integrate with common BI tools. * Mode * Looker * Tableau * Sigma #### Mode[​](https://docs.getdbt.com/docs/explore/data-tile#mode "Direct link to Mode") Mode allows you to directly [edit the HTML](https://mode.com/help/articles/report-layout-and-presentation/#html-editor) of any given report, where you can embed the iFrame. Note that Mode has also built its own [integration](https://mode.com/get-dbt/) with the dbt Discovery API! #### Looker[​](https://docs.getdbt.com/docs/explore/data-tile#looker "Direct link to Looker") Looker does not allow you to directly embed HTML and instead requires creating a [custom visualization](https://docs.looker.com/admin-options/platform/visualizations) . One way to do this for admins is to: * Add a [new visualization](https://fishtown.looker.com/admin/visualizations) on the visualization page for Looker admins. You can use [this URL](https://metadata.cloud.getdbt.com/static/looker-viz.js) to configure a Looker visualization powered by the iFrame. It will look like this: [![Configure a Looker visualization powered by the iFrame](https://docs.getdbt.com/img/docs/dbt-cloud/using-dbt-cloud/dashboard-status-tiles/looker-visualization.jpeg?v=2 "Configure a Looker visualization powered by the iFrame")](https://docs.getdbt.com/docs/explore/data-tile#) Configure a Looker visualization powered by the iFrame * Once you have set up your custom visualization, you can use it on any dashboard! You can configure it with the exposure name, job ID, and token relevant to that dashboard. [![](https://docs.getdbt.com/img/docs/dbt-cloud/using-dbt-cloud/dashboard-status-tiles/custom-looker.jpeg%20?v=2)](https://docs.getdbt.com/docs/explore/data-tile#) #### Tableau[​](https://docs.getdbt.com/docs/explore/data-tile#tableau "Direct link to Tableau") Tableau does not require you to embed an iFrame. You only need to use a Web Page object on your Tableau Dashboard and a URL in the following format: https://metadata.YOUR_ACCESS_URL/exposure-tile?name=&jobId=&token= Replace `YOUR_ACCESS_URL` with your region and plan's Access URL dbt is hosted in multiple regions in the world and each region has a different access URL. Replace `YOUR_ACCESS_URL` with the appropriate [Access URL](https://docs.getdbt.com/docs/cloud/about-cloud/access-regions-ip-addresses) for your region and plan. For example, if your account is hosted in the North American region, you would use the following code: https://metadata.cloud.getdbt.com/exposure-tile?name=&jobId=&token= [![Configure Tableau by using a Web page object.](https://docs.getdbt.com/img/docs/dbt-cloud/using-dbt-cloud/dashboard-status-tiles/tableau-object.png?v=2 "Configure Tableau by using a Web page object.")](https://docs.getdbt.com/docs/explore/data-tile#) Configure Tableau by using a Web page object. #### Sigma[​](https://docs.getdbt.com/docs/explore/data-tile#sigma "Direct link to Sigma") Sigma does not require you to embed an iFrame. Add a new embedded UI element in your Sigma Workbook in the following format: https://metadata.YOUR_ACCESS_URL/exposure-tile?name=&jobId=&token= Replace `YOUR_ACCESS_URL` with your region and plan's Access URL dbt is hosted in multiple regions in the world and each region has a different access URL. Replace `YOUR_ACCESS_URL` with the appropriate [Access URL](https://docs.getdbt.com/docs/cloud/about-cloud/access-regions-ip-addresses) for your region and plan. For example, if your account is hosted in the APAC region, you would use the following code: https://metadata.au.dbt.com/exposure-tile?name=&jobId=&token= [![Configure Sigma by using an embedded UI element.](https://docs.getdbt.com/img/docs/dbt-cloud/using-dbt-cloud/dashboard-status-tiles/sigma-embed.gif?v=2 "Configure Sigma by using an embedded UI element.")](https://docs.getdbt.com/docs/explore/data-tile#) Configure Sigma by using an embedded UI element. Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Prerequisites](https://docs.getdbt.com/docs/explore/data-tile#prerequisites) * [View exposure in dbt Catalog](https://docs.getdbt.com/docs/explore/data-tile#view-exposure-in-dbt-catalog) * [Embed in your dashboard](https://docs.getdbt.com/docs/explore/data-tile#embed-in-your-dashboard) * [Examples](https://docs.getdbt.com/docs/explore/data-tile#examples) * [Job-based data health](https://docs.getdbt.com/docs/explore/data-tile#job-based-data-health-) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/explore/data-tile.md) --- # Upgrade dbt version in Cloud | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-version-in-cloud#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page In dbt, both [jobs](https://docs.getdbt.com/docs/deploy/jobs) and [environments](https://docs.getdbt.com/docs/dbt-cloud-environments) are configured to use a specific version of dbt Core. The version can be upgraded at any time. Environments[​](https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-version-in-cloud#environments "Direct link to Environments") ----------------------------------------------------------------------------------------------------------------------------------- Navigate to the settings page of an environment, then click **Edit**. Click the **dbt version** dropdown bar and make your selection. You can select a [release track](https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-version-in-cloud#release-tracks) to receive ongoing updates (recommended), or a legacy version of dbt Core. Be sure to save your changes before navigating away. [![Example environment settings in dbt](https://docs.getdbt.com/img/docs/dbt-cloud/cloud-configuring-dbt-cloud/choosing-dbt-version/example-environment-settings.png?v=2 "Example environment settings in dbt")](https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-version-in-cloud#) Example environment settings in dbt ### Release Tracks[​](https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-version-in-cloud#release-tracks "Direct link to Release Tracks") Starting in 2024, your project will be upgraded automatically on a cadence that you choose The **Latest** track ensures you have up-to-date dbt functionality, and early access to new features of the dbt framework. The **Compatible** and **Extended** tracks are designed for customers who need a less-frequent release cadence, the ability to test new dbt releases before they go live in production, and/or ongoing compatibility with the latest open source releases of dbt Core. As a best practice, dbt Labs recommends that you test the upgrade in development first; use the [Override dbt version](https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-version-in-cloud#override-dbt-version) setting to test _your_ project on the latest dbt version before upgrading your deployment environments and the default development environment for all your colleagues. To upgrade an environment in the [dbt Admin API](https://docs.getdbt.com/docs/dbt-cloud-apis/admin-cloud-api) or [Terraform](https://registry.terraform.io/providers/dbt-labs/dbtcloud/latest) , set `dbt_version` to the name of your release track: * `latest` (formerly called `versionless`; the old name is still supported) * `compatible` (available to Starter, Enterprise, Enterprise+ plans) * `extended` (available to all Enterprise plans) ### Override dbt version[​](https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-version-in-cloud#override-dbt-version "Direct link to Override dbt version") Configure your project to use a different dbt version than what's configured in your [development environment](https://docs.getdbt.com/docs/dbt-cloud-environments#types-of-environments) . This _override_ only affects your user account, no one else's. Use this to safely test new dbt features before upgrading the dbt version for your projects. 1. Click your account name from the left side panel and select **Account settings**. 2. Choose **Credentials** from the sidebar and select a project. This opens a side panel. 3. In the side panel, click **Edit** and scroll to the **User development settings** section. 4. Choose a version from the **dbt version** dropdown and click **Save**. An example of overriding the configured version to ["Latest" release track](https://docs.getdbt.com/docs/dbt-versions/cloud-release-tracks) for the selected project: [![Example of overriding the dbt version on your user account](https://docs.getdbt.com/img/docs/dbt-cloud/cloud-configuring-dbt-cloud/choosing-dbt-version/example-override-version.png?v=2 "Example of overriding the dbt version on your user account")](https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-version-in-cloud#) Example of overriding the dbt version on your user account 5. (Optional) Verify that dbt will use your override setting to build the project by invoking a `dbt build` command in the Studio IDE's command bar. Expand the **System Logs** section and find the output's first line. It should begin with `Running with dbt=` and list the version dbt is using. For users on Release tracks, the output will display `Running dbt...` instead of a specific version, reflecting the flexibility and continuous automatic updates provided by the release track functionality. Jobs[​](https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-version-in-cloud#jobs "Direct link to Jobs") ----------------------------------------------------------------------------------------------------------- Each job in dbt can be configured to inherit parameters from the environment it belongs to. [![Settings of a dbt job](https://docs.getdbt.com/img/docs/dbt-cloud/cloud-configuring-dbt-cloud/choosing-dbt-version/job-settings.png?v=2 "Settings of a dbt job")](https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-version-in-cloud#) Settings of a dbt job The example job seen in the screenshot above belongs to the environment "Prod". It inherits the dbt version of its environment as shown by the **Inherited from ENVIRONMENT\_NAME (DBT\_VERSION)** selection. You may also manually override the dbt version of a specific job to be any of the current Core releases supported by Cloud by selecting another option from the dropdown. Supported versions[​](https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-version-in-cloud#supported-versions "Direct link to Supported versions") ----------------------------------------------------------------------------------------------------------------------------------------------------- dbt Labs has always encouraged users to upgrade dbt Core versions whenever a new minor version is released. We released our first major version of dbt - `dbt 1.0` - in December 2021. Alongside this release, we updated our policy on which versions of dbt Core we will support in the dbt platform. > **Starting with v1.0, all subsequent minor versions are available in dbt. Versions are actively supported, with patches and bug fixes, for 1 year after their initial release. At the end of the 1-year window, we encourage all users to upgrade to a newer version for better ongoing maintenance and support.** We provide different support levels for different versions, which may include new features, bug fixes, or security patches: * **[Active](https://docs.getdbt.com/docs/dbt-versions/core#ongoing-patches) ** — We will patch regressions, new bugs, and include fixes for older bugs / quality-of-life improvements. We implement these changes when we have high confidence that they're narrowly scoped and won't cause unintended side effects. * **[Critical](https://docs.getdbt.com/docs/dbt-versions/core#ongoing-patches) ** — Newer minor versions transition the previous minor version into "Critical Support" with limited "security" releases for critical security and installation fixes. * **[End of Life](https://docs.getdbt.com/docs/dbt-versions/core#eol-version-support) ** — Minor versions that have reached EOL no longer receive new patch releases. * **Deprecated** — dbt Core versions older than v1.0 are no longer maintained by dbt Labs, nor supported in dbt platform. We'll continue to update the following release table so that users know when we plan to stop supporting different versions of Core in dbt. ### Latest releases[​](https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-version-in-cloud#latest-releases "Direct link to Latest releases") | dbt Core | Initial release | Support level and end date | | --- | --- | --- | | [**v1.10**](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.10) | Jun 16, 2025 | **Active Support — Jun 15, 2026** | | [**v1.9**](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.9) | Dec 9, 2024 | **Critical — Dec 8, 2025** | | [**v1.8**](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.8) | May 9, 2024 | End of Life ⚠️ | | [**v1.7**](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.7) | Nov 2, 2023 | End of Life ⚠️ | | [**v1.6**](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.6) | Jul 31, 2023 | End of Life ⚠️ | | [**v1.5**](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.5) | Apr 27, 2023 | End of Life ⚠️ | | [**v1.4**](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.4) | Jan 25, 2023 | End of Life ⚠️ | | [**v1.3**](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.3) | Oct 12, 2022 | End of Life ⚠️ | | [**v1.2**](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.2) | Jul 26, 2022 | Deprecated ⛔️ | | [**v1.1**](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.1) | Apr 28, 2022 | Deprecated ⛔️ | | [**v1.0**](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.0) | Dec 3, 2021 | Deprecated ⛔️ | | **v0.X** ⛔️ | (Various dates) | Deprecated ⛔️ | All functionality in dbt Core since the v1.7 release is available in [dbt release tracks](https://docs.getdbt.com/docs/dbt-versions/cloud-release-tracks) , which provide automated upgrades at a cadence appropriate for your team. 1 Release tracks are required for the Developer and Starter plans on dbt. Accounts using older dbt versions will be migrated to the "Latest" release track. For customers of dbt: dbt Labs strongly recommends migrating environments on older and unsupported versions to [release tracks](https://docs.getdbt.com/docs/dbt-versions/cloud-release-tracks) or a supported version. In 2025, dbt Labs will remove the oldest dbt Core versions from availability in dbt platform, starting with v1.0 -- v1.2. Starting with v1.0, dbt will ensure that you're always using the latest compatible patch release of `dbt-core` and plugins, including all the latest fixes. You may also choose to try prereleases of those patch releases before they are generally available. For more on version support and future releases, see [Understanding dbt Core versions](https://docs.getdbt.com/docs/dbt-versions/core) . ### dbt Fusion engine [beta](https://docs.getdbt.com/docs/dbt-versions/product-lifecycles "Go to https://docs.getdbt.com/docs/dbt-versions/product-lifecycles") [​](https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-version-in-cloud#dbt-fusion-engine- "Direct link to dbt-fusion-engine-") dbt Labs has introduced the new [dbt Fusion Engine](https://docs.getdbt.com/docs/fusion/about-fusion) , a ground-up rebuild of dbt. This is currently in beta on the dbt platform. Eligible customers can update environments to Fusion using the same workflows as v1.x, but there are a few things to keep in mind: * **To gain access to the Fusion Latest release track, you must reach out to your dbt Labs account team to request it. Week by week we'll expand the beta cohort based on project eligibility, including Starter plans**. Once we transition from Beta to Preview, all users will see it as an option for their environments, projects, jobs, etc. To increase the compatibility of your project, update all jobs and environments to the `Latest` release track and follow our [upgrade guide](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-fusion) . * There are some significant changes, these can also be found in the [upgrade guide](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-fusion) . * Make sure you're using a supported adapter and authentication method:  BigQuery * Service Account / User Token * Native OAuth * External OAuth * [Required permissions](https://docs.getdbt.com/docs/core/connect-data-platform/bigquery-setup#required-permissions) Databricks * Service Account / User Token * Native OAuth Redshift * Username / Password Snowflake * Username / Password * Native OAuth * External OAuth * Key pair * MFA * When you change your development environment(s) to `Fusion Latest`, every user will have to restart the IDE. [![Upgrade to the Fusion engine in your environment settings.](https://docs.getdbt.com/img/docs/dbt-cloud/cloud-configuring-dbt-cloud/cloud-upgrading-dbt-versions/upgrade-fusion.png?v=2 "Upgrade to the Fusion engine in your environment settings.")](https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-version-in-cloud#) Upgrade to the Fusion engine in your environment settings. ### Need help upgrading?[​](https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-version-in-cloud#need-help-upgrading "Direct link to Need help upgrading?") If you want more advice on how to upgrade your dbt projects, check out our [migration guides](https://docs.getdbt.com/docs/dbt-versions/core-upgrade) and our [upgrading Q&A page](https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-version-in-cloud#upgrading-legacy-versions-under-10) . ### Testing your changes before upgrading[​](https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-version-in-cloud#testing-your-changes-before-upgrading "Direct link to Testing your changes before upgrading") Once you know what code changes you'll need to make, you can start implementing them. We recommend you: * Create a separate dbt project, "Upgrade project", to test your changes before making them live in your main dbt project. * In your "Upgrade project", connect to the same repository you use for your production project. * Set the development environment [settings](https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-version-in-cloud) to run the latest version of dbt Core. * Check out a branch `dbt-version-upgrade`, make the appropriate updates to your project, and verify your dbt project compiles and runs with the new version in the Studio IDE. * If upgrading directly to the latest version results in too many issues, try testing your project iteratively on successive minor versions. There are years of development and a few breaking changes between distant versions of dbt Core (for example, 1.0 --> 1.10). The likelihood of experiencing problems upgrading between successive minor versions is much lower, which is why upgrading regularly is recommended. * Once you have your project compiling and running on the latest version of dbt in the development environment for your `dbt-version-upgrade` branch, try replicating one of your production jobs to run off your branch's code. * You can do this by creating a new deployment environment for testing, setting the custom branch to 'ON' and referencing your `dbt-version-upgrade` branch. You'll also need to set the dbt version in this environment to the latest dbt Core version. [![Setting your testing environment](https://docs.getdbt.com/img/docs/dbt-cloud/cloud-configuring-dbt-cloud/cloud-upgrading-dbt-versions/upgrade-environment.png?v=2 "Setting your testing environment")](https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-version-in-cloud#) Setting your testing environment * Then add a job to the new testing environment that replicates one of the production jobs your team relies on. * If that job runs smoothly, you should be all set to merge your branch into main. * Then change your development and deployment environments in your main dbt project to run off the newest version of dbt Core. Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Environments](https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-version-in-cloud#environments) * [Release Tracks](https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-version-in-cloud#release-tracks) * [Override dbt version](https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-version-in-cloud#override-dbt-version) * [Jobs](https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-version-in-cloud#jobs) * [Supported versions](https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-version-in-cloud#supported-versions) * [dbt Fusion engine](https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-version-in-cloud#dbt-fusion-engine-) * [Need help upgrading?](https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-version-in-cloud#need-help-upgrading) * [Testing your changes before upgrading](https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-version-in-cloud#testing-your-changes-before-upgrading) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/dbt-versions/upgrade-dbt-version-in-cloud.md) --- # About dbt Core versions | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/dbt-versions/core#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page dbt Core releases follow [semantic versioning](https://semver.org/) guidelines. For more on how we use semantic versions, see [How dbt Core uses semantic versioning](https://docs.getdbt.com/docs/dbt-versions/core#how-dbt-core-uses-semantic-versioning) . Release Tracks keep you up to date, always _Did you know that you can always be working with the latest features and functionality?_ With dbt, you can get early access to new functionality before it becomes available in dbt Core and without the need of managing your own version upgrades. Refer to the ["Latest" Release Track](https://docs.getdbt.com/docs/dbt-versions/cloud-release-tracks) setting for details. dbt Labs provides different support levels for different versions, which may include new features, bug fixes, or security patches: * **[Active](https://docs.getdbt.com/docs/dbt-versions/core#ongoing-patches) ** — We will patch regressions, new bugs, and include fixes for older bugs / quality-of-life improvements. We implement these changes when we have high confidence that they're narrowly scoped and won't cause unintended side effects. * **[Critical](https://docs.getdbt.com/docs/dbt-versions/core#ongoing-patches) ** — Newer minor versions transition the previous minor version into "Critical Support" with limited "security" releases for critical security and installation fixes. * **[End of Life](https://docs.getdbt.com/docs/dbt-versions/core#eol-version-support) ** — Minor versions that have reached EOL no longer receive new patch releases. * **Deprecated** — dbt Core versions older than v1.0 are no longer maintained by dbt Labs, nor supported in dbt platform. ### Latest releases[​](https://docs.getdbt.com/docs/dbt-versions/core#latest-releases "Direct link to Latest releases") | dbt Core | Initial release | Support level and end date | | --- | --- | --- | | [**v1.10**](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.10) | Jun 16, 2025 | **Active Support — Jun 15, 2026** | | [**v1.9**](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.9) | Dec 9, 2024 | **Critical — Dec 8, 2025** | | [**v1.8**](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.8) | May 9, 2024 | End of Life ⚠️ | | [**v1.7**](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.7) | Nov 2, 2023 | End of Life ⚠️ | | [**v1.6**](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.6) | Jul 31, 2023 | End of Life ⚠️ | | [**v1.5**](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.5) | Apr 27, 2023 | End of Life ⚠️ | | [**v1.4**](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.4) | Jan 25, 2023 | End of Life ⚠️ | | [**v1.3**](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.3) | Oct 12, 2022 | End of Life ⚠️ | | [**v1.2**](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.2) | Jul 26, 2022 | Deprecated ⛔️ | | [**v1.1**](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.1) | Apr 28, 2022 | Deprecated ⛔️ | | [**v1.0**](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.0) | Dec 3, 2021 | Deprecated ⛔️ | | **v0.X** ⛔️ | (Various dates) | Deprecated ⛔️ | All functionality in dbt Core since the v1.7 release is available in [dbt release tracks](https://docs.getdbt.com/docs/dbt-versions/cloud-release-tracks) , which provide automated upgrades at a cadence appropriate for your team. 1 Release tracks are required for the Developer and Starter plans on dbt. Accounts using older dbt versions will be migrated to the "Latest" release track. For customers of dbt: dbt Labs strongly recommends migrating environments on older and unsupported versions to [release tracks](https://docs.getdbt.com/docs/dbt-versions/cloud-release-tracks) or a supported version. In 2025, dbt Labs will remove the oldest dbt Core versions from availability in dbt platform, starting with v1.0 -- v1.2. ### Further reading[​](https://docs.getdbt.com/docs/dbt-versions/core#further-reading "Direct link to Further reading") * To learn how you can use dbt Core versions in dbt, see [Choosing a dbt Core version](https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-version-in-cloud) . * To learn about installing dbt Core, see "[How to install dbt Core](https://docs.getdbt.com/docs/core/installation-overview) ." * To restrict your project to only work with a range of dbt Core versions, or use the currently running dbt Core version, see [`require-dbt-version`](https://docs.getdbt.com/reference/project-configs/require-dbt-version) and [`dbt_version`](https://docs.getdbt.com/reference/dbt-jinja-functions/dbt_version) . Version support prior to v1.0[​](https://docs.getdbt.com/docs/dbt-versions/core#version-support-prior-to-v10 "Direct link to Version support prior to v1.0") ------------------------------------------------------------------------------------------------------------------------------------------------------------- All dbt Core versions released prior to 1.0 and their version-specific documentation have been deprecated. If upgrading to a currently supported version, reference our [best practices for upgrading](https://docs.getdbt.com/docs/dbt-versions/core#best-practices-for-upgrading) EOL version support[​](https://docs.getdbt.com/docs/dbt-versions/core#eol-version-support "Direct link to EOL version support") -------------------------------------------------------------------------------------------------------------------------------- All dbt Core minor versions that have reached end-of-life (EOL) will have no new patch releases. This means they will no longer receive any fixes, including for known bugs that have been identified. Fixes for those bugs will instead be made in newer minor versions that are still under active support. We recommend upgrading to a newer version in [dbt](https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-version-in-cloud) or [dbt Core](https://docs.getdbt.com/docs/core/installation-overview#upgrading-dbt-core) to continue receiving support. All dbt Core v1.0 and later are available in dbt until further notice. In the future, we intend to align dbt availability with dbt Core ongoing support. You will receive plenty of advance notice before any changes take place. Current version support[​](https://docs.getdbt.com/docs/dbt-versions/core#current-version-support "Direct link to Current version support") -------------------------------------------------------------------------------------------------------------------------------------------- ### Minor versions[​](https://docs.getdbt.com/docs/dbt-versions/core#minor-versions "Direct link to Minor versions") Minor versions include new features and capabilities. They will be supported for one year from their initial release date. _dbt Labs is committed to this 12-month support timeframe._ Our mechanism for continuing to support a minor version is by releasing new patches: small, targeted bug fixes. Whenever we refer to a minor version, such as v1.0, we always mean its latest available patch release (v1.0.x). While a minor version is officially supported: * You can use it in dbt. For more on dbt versioning, see [Choosing a dbt version](https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-version-in-cloud) . * You can select it from the version dropdown on this website, to see documentation that is accurate for use with that minor version. ### Ongoing patches[​](https://docs.getdbt.com/docs/dbt-versions/core#ongoing-patches "Direct link to Ongoing patches") During the 12-month support window, we will continue to release new patch versions that include fixes. **Active Support:** In the first few months after a minor version's initial release, we will patch it with "bugfix" releases. These will include fixes for regressions and net-new bugs that were present in the minor version's original release. **Critical Support:** When a newer minor version is available, we will transition the previous minor version into "Critical Support." Subsequent patches to that older minor version will be "security" releases only, limited to critical fixes related to security and installation. After a minor version reaches the end of its critical support period, one year after its initial release, no new patches will be released. ### Future versions[​](https://docs.getdbt.com/docs/dbt-versions/core#future-versions "Direct link to Future versions") For the latest information about upcoming releases, including planned release dates and which features and fixes might be included, consult the [`dbt-core` repository milestones](https://github.com/dbt-labs/dbt-core/milestones) and [product roadmaps](https://github.com/dbt-labs/dbt-core/tree/main/docs/roadmap) . Best practices for upgrading[​](https://docs.getdbt.com/docs/dbt-versions/core#best-practices-for-upgrading "Direct link to Best practices for upgrading") ----------------------------------------------------------------------------------------------------------------------------------------------------------- Because of our new version practice, we've outlined best practices and expectations for dbt users to upgrade as we continue to release new versions of dbt Core. ### Upgrading to new patch versions[​](https://docs.getdbt.com/docs/dbt-versions/core#upgrading-to-new-patch-versions "Direct link to Upgrading to new patch versions") We expect users to upgrade to patches as soon as they're available. When we refer to a "minor version" of dbt Core, such as v1.0, we are always referring to the latest available patch release for that minor version. We encourage you to structure your development and production environments so that you can always install the latest patches of `dbt-core` and any adapter plugins. (Note that patch numbers may be different between dbt-core and plugins. [See below](https://docs.getdbt.com/docs/dbt-versions/core#how-we-version-adapter-plugins) for an explanation.) ### Upgrading to new minor versions[​](https://docs.getdbt.com/docs/dbt-versions/core#upgrading-to-new-minor-versions "Direct link to Upgrading to new minor versions") During the official support period, minor versions will remain available in dbt and the version dropdown on the docs site. While we do not expect users to immediately upgrade to newer minor versions as soon as they're available, there will always be some features and fixes only available for users of the latest minor version. ### Trying prereleases[​](https://docs.getdbt.com/docs/dbt-versions/core#trying-prereleases "Direct link to Trying prereleases") All dbt Core versions are available as _prereleases_ before the final release. "Release candidates" are available for testing, in production-like environments, two weeks before the final release. For minor versions, we also aim to release one or more "betas," which include new features and invite community feedback, 4+ weeks before the final release. It is in your interest to help us test prereleases—we need your help! How dbt Core uses semantic versioning[​](https://docs.getdbt.com/docs/dbt-versions/core#how-dbt-core-uses-semantic-versioning "Direct link to How dbt Core uses semantic versioning") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Like many software projects, dbt Core releases follow [semantic versioning](https://semver.org/) , which defines three types of version releases. * **Major versions:** To date, dbt Core has had one major version release: v1.0.0. When v2.0.0 is released, it will introduce new features, and functionality that has been announced for deprecation will stop working. * **Minor versions**, also called "feature" releases, include a mix of new features, behind-the-scenes improvements, and changes to existing capabilities that are **backwards compatible** with previous minor versions. They will not break code in your project that relies on documented functionality. * **Patch versions**, also called "bugfix" or "security" releases, include **fixes _only_**. These fixes could be needed to restore previous (documented) behavior, fix obvious shortcomings of new features, or offer critical fixes for security or installation issues. We are judicious about which fixes are included in patch releases, to minimize the surface area of changes. We are committed to avoiding breaking changes in minor versions for end users of dbt. There are two types of breaking changes that may be included in minor versions: * Changes to the Python interface for adapter plugins. These changes are relevant _only_ to adapter maintainers, and they will be clearly communicated in documentation and release notes. For more information, refer to [Build, test, document, and promote adapters](https://docs.getdbt.com/guides/adapter-creation) guide. * Changes to metadata interfaces, including [artifacts](https://docs.getdbt.com/docs/deploy/artifacts) and [logging](https://docs.getdbt.com/reference/events-logging) , signalled by a version bump. Those version upgrades may require you to update external code that depends on these interfaces, or to coordinate upgrades between dbt orchestrations that share metadata, such as [state-powered selection](https://docs.getdbt.com/reference/node-selection/syntax#about-node-selection) . ### How we version adapter plugins[​](https://docs.getdbt.com/docs/dbt-versions/core#how-we-version-adapter-plugins "Direct link to How we version adapter plugins") When you use dbt, you use a combination of `dbt-core` and an adapter plugin specific to your database. You can see the current list in [Supported Data Platforms](https://docs.getdbt.com/docs/supported-data-platforms) . Both `dbt-core` and dbt adapter plugins follow semantic versioning. `dbt-core` and adapter plugins use the `dbt-adapters` interface to coordinate new features and behind-the-scenes changes. New adapter features are defined in `dbt-adapters` (which `dbt-core` will use). These features are opt-in, meaning they only impact adapters that explicitly implement them. This allows us to independently release adapters, `dbt-adapters`, and `dbt-core` without creating a broken experience for users. Unlike `dbt-core` versions before 1.8, the minor and patch version numbers might not match between `dbt-core` and the adapter plugin(s) you've installed. For example, you might find you're using `dbt-core==1.8.0` with `dbt-snowflake==1.9.0`. Even though these don't have the same minor version, they can still work together as they both work with `dbt-adapters==1.8.0`. Patch releases can contain important bug or security fixes so it’s critical to stay up to date. You can use the `dbt --version` command to see which versions you have installed: $ dbt --versionCore: - installed: 1.8.0 - latest: 1.8.0 - Up to date!Plugins: - snowflake: 1.9.0 - Up to date! You can see which version of the registered adapter that's being invoked in the [logs](https://docs.getdbt.com/reference/global-configs/logs) . Below is an example of the message in the `logs/dbt.log` file: [0m13:13:48.572182 [info ] [MainThread]: Registered adapter: snowflake=1.9.0\ \ It's likely that newer patches have become available since then, so it's always important to check and make sure you're up to date!\ \ Was this page helpful?\ ----------------------\ \ YesNo\ \ [Privacy policy](https://www.getdbt.com/cloud/privacy-policy)\ [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues)\ \ This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy)\ and [Terms of Service](https://policies.google.com/terms)\ apply.\ \ 0\ \ * [Further reading](https://docs.getdbt.com/docs/dbt-versions/core#further-reading)\ \ * [Version support prior to v1.0](https://docs.getdbt.com/docs/dbt-versions/core#version-support-prior-to-v10)\ \ * [EOL version support](https://docs.getdbt.com/docs/dbt-versions/core#eol-version-support)\ \ * [Current version support](https://docs.getdbt.com/docs/dbt-versions/core#current-version-support)\ * [Minor versions](https://docs.getdbt.com/docs/dbt-versions/core#minor-versions)\ \ * [Ongoing patches](https://docs.getdbt.com/docs/dbt-versions/core#ongoing-patches)\ \ * [Future versions](https://docs.getdbt.com/docs/dbt-versions/core#future-versions)\ \ * [Best practices for upgrading](https://docs.getdbt.com/docs/dbt-versions/core#best-practices-for-upgrading)\ * [Upgrading to new patch versions](https://docs.getdbt.com/docs/dbt-versions/core#upgrading-to-new-patch-versions)\ \ * [Upgrading to new minor versions](https://docs.getdbt.com/docs/dbt-versions/core#upgrading-to-new-minor-versions)\ \ * [Trying prereleases](https://docs.getdbt.com/docs/dbt-versions/core#trying-prereleases)\ \ * [How dbt Core uses semantic versioning](https://docs.getdbt.com/docs/dbt-versions/core#how-dbt-core-uses-semantic-versioning)\ * [How we version adapter plugins](https://docs.getdbt.com/docs/dbt-versions/core#how-we-version-adapter-plugins)\ \ \ [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/dbt-versions/core-versions.md) --- # Discover data with Catalog | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/explore/explore-projects#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page With Catalog, you can view your project's [resources](https://docs.getdbt.com/docs/build/projects) (such as models, tests, and metrics), their lineage, and [model consumption](https://docs.getdbt.com/docs/explore/view-downstream-exposures) to gain a better understanding of its latest production state. Use Catalog to navigate and manage your projects within dbt to help you and other data developers, analysts, and consumers discover and leverage your dbt resources. Catalog integrates with the [Studio IDE](https://docs.getdbt.com/docs/cloud/dbt-cloud-ide/develop-in-the-cloud) , [dbt Insights](https://docs.getdbt.com/docs/explore/dbt-insights) , [Orchestrator](https://docs.getdbt.com/docs/deploy/deployments) , and [Canvas](https://docs.getdbt.com/docs/cloud/canvas) to help you develop or view your dbt resources. Prerequisites[​](https://docs.getdbt.com/docs/explore/explore-projects#prerequisites "Direct link to Prerequisites") --------------------------------------------------------------------------------------------------------------------- * You have a dbt account on the [Starter, Enterprise, or Enterprise+ plan](https://www.getdbt.com/pricing/) . * You have set up a [production](https://docs.getdbt.com/docs/deploy/deploy-environments#set-as-production-environment) or [staging](https://docs.getdbt.com/docs/deploy/deploy-environments#create-a-staging-environment) deployment environment for each project you want to explore. * You have at least one successful job run in the deployment environment. Note that [CI jobs](https://docs.getdbt.com/docs/deploy/ci-jobs) do not update Catalog. * You are on the Catalog page. To do this, select **Explore** from the navigation in dbt. Generate metadata[​](https://docs.getdbt.com/docs/explore/explore-projects#generate-metadata "Direct link to Generate metadata") --------------------------------------------------------------------------------------------------------------------------------- Catalog uses the metadata provided by the [Discovery API](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-api) to display the details about [the state of your dbt project](https://docs.getdbt.com/docs/dbt-cloud-apis/project-state) . The metadata that's available depends on the [deployment environment](https://docs.getdbt.com/docs/deploy/deploy-environments) you've designated as _production_ or _staging_ in your dbt project. Catalog also allows you to ingest external metadata from Snowflake, giving you visibility into tables, views, and other resources that aren't defined in dbt with Catalog. dbt metadata[​](https://docs.getdbt.com/docs/explore/explore-projects#dbt-metadata "Direct link to dbt metadata") ------------------------------------------------------------------------------------------------------------------ If you're using a [hybrid project setup](https://docs.getdbt.com/docs/deploy/hybrid-setup) and uploading artifacts from dbt Core, make sure to follow the [setup instructions](https://docs.getdbt.com/docs/deploy/hybrid-setup#connect-project-in-dbt-cloud) to connect your project in dbt. This enables Catalog to access and display your metadata correctly. * To ensure all metadata is available in Catalog, run `dbt build` and `dbt docs generate` as part of your job in your production or staging environment. Running those two commands ensure all relevant metadata (like lineage, test results, documentation, and more) is available in Catalog. * Catalog automatically retrieves the metadata updates after each job run in the production or staging deployment environment so it always has the latest results for your project. This includes deploy and merge jobs. * Note that CI jobs don't update Catalog. This is because they don't reflect the production state and don't provide the necessary metadata updates. * To view a resource and its metadata, you must define the resource in your project and run a job in the production or staging environment. * The resulting metadata depends on the [commands](https://docs.getdbt.com/docs/deploy/job-commands) executed by the jobs. Note that Catalog automatically deletes stale metadata after 3 months if no jobs were run to refresh it. To avoid this, make sure you schedule jobs to run more frequently than 3 months with the necessary commands. | To view in Catalog | You must successfully run | | --- | --- | | All metadata | [dbt build](https://docs.getdbt.com/reference/commands/build)
, [dbt docs generate](https://docs.getdbt.com/reference/commands/cmd-docs)
, and [dbt source freshness](https://docs.getdbt.com/reference/commands/source#dbt-source-freshness)
together as part of the same job in the environment | | Model lineage, details, or results | [dbt run](https://docs.getdbt.com/reference/commands/run)
or [dbt build](https://docs.getdbt.com/reference/commands/build)
on a given model within a job in the environment | | Columns and statistics for models, sources, and snapshots | [dbt docs generate](https://docs.getdbt.com/reference/commands/cmd-docs)
 within [a job](https://docs.getdbt.com/docs/explore/build-and-view-your-docs)
in the environment | | Test results | [dbt test](https://docs.getdbt.com/reference/commands/test)
 or [dbt build](https://docs.getdbt.com/reference/commands/build)
 within a job in the environment | | Source freshness results | [dbt source freshness](https://docs.getdbt.com/reference/commands/source#dbt-source-freshness)
 within a job in the environment | | Snapshot details | [dbt snapshot](https://docs.getdbt.com/reference/commands/snapshot)
or [dbt build](https://docs.getdbt.com/reference/commands/build)
within a job in the environment | | Seed details | [dbt seed](https://docs.getdbt.com/reference/commands/seed)
or [dbt build](https://docs.getdbt.com/reference/commands/build)
within a job in the environment | Richer and more timely metadata will become available as dbt evolves. tip If your organization works in both dbt Core and Cloud, you can unify these workflows by automatically uploading dbt Core artifacts into dbt Cloud and viewing them in Catalog for a more connected dbt experience. To learn more, visit [hybrid projects](https://docs.getdbt.com/docs/deploy/hybrid-projects) . ### External metadata ingestion [preview](https://docs.getdbt.com/docs/dbt-versions/product-lifecycles "Go to https://docs.getdbt.com/docs/dbt-versions/product-lifecycles") [​](https://docs.getdbt.com/docs/explore/explore-projects#external-metadata-ingestion- "Direct link to external-metadata-ingestion-") Connect directly to your data warehouse with [external metadata ingestion](https://docs.getdbt.com/docs/explore/external-metadata-ingestion) , giving you visibility into tables, views, and other resources that aren't defined in dbt with Catalog. We create dbt metadata and pull external metadata. Catalog uses the metadata provided by the [Discovery API](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-api) to display details about the state of your project. The available metadata depends on which [deployment environment](https://docs.getdbt.com/docs/deploy/deploy-environments) you’ve designated as production or staging in your dbt project. Catalog overview[​](https://docs.getdbt.com/docs/explore/explore-projects#catalog-overview "Direct link to Catalog overview") ------------------------------------------------------------------------------------------------------------------------------ [Global navigation](https://docs.getdbt.com/docs/explore/global-navigation) [Starter](https://www.getdbt.com/pricing "Go to https://www.getdbt.com/pricing") [Enterprise](https://www.getdbt.com/pricing "Go to https://www.getdbt.com/pricing") [Enterprise +](https://www.getdbt.com/pricing "Go to https://www.getdbt.com/pricing") [preview](https://docs.getdbt.com/docs/dbt-versions/product-lifecycles "Go to https://docs.getdbt.com/docs/dbt-versions/product-lifecycles") Catalog introduces the ability to widen your search by including dbt resources (models, seeds, snapshots, sources, exposures, and more) across your entire account. This broadens the results returned and gives you greater insight into all the assets across your dbt projects. Learn more in [Global navigation](https://docs.getdbt.com/docs/explore/global-navigation) or in our [video overview](https://www.loom.com/share/ae93b3d241cd439fbe5f98f5e6872113?) . Navigate the Catalog overview page to access your project's resources and metadata. The page includes the following sections: * **Search bar** — [Search](https://docs.getdbt.com/docs/explore/explore-projects#search-resources) for resources in your project by keyword. You can also use filters to refine your search results. * **Sidebar** — Use the left sidebar to access model [performance](https://docs.getdbt.com/docs/explore/model-performance) , [project recommendations](https://docs.getdbt.com/docs/explore/project-recommendations) in the **Project details** section. Browse your project's [resources, file tree, and database](https://docs.getdbt.com/docs/explore/explore-projects#browse-with-the-sidebar) in the lower section of the sidebar. * Find your project recommendations within your project's landing page.\* * **Lineage graph** — Explore your project's or account's [lineage graph](https://docs.getdbt.com/docs/explore/explore-projects#project-lineage) to visualize the relationships between resources. * **Latest updates** — View the latest changes or issues related to your project's resources, including the most recent job runs, changed properties, lineage, and issues. * **Marts and public models** — View the [marts](https://docs.getdbt.com/best-practices/how-we-structure/1-guide-overview#guide-structure-overview) and [public models](https://docs.getdbt.com/docs/mesh/govern/model-access#access-modifiers) in your project. You can also navigate to all public models in your account through this view. * **Model query history** — Use [model query history](https://docs.getdbt.com/docs/explore/model-query-history) to track consumption queries on your models for deeper insights. * **Visualize downstream exposures** — [Set up](https://docs.getdbt.com/docs/cloud-integrations/downstream-exposures-tableau) and [visualize downstream exposures](https://docs.getdbt.com/docs/explore/view-downstream-exposures) to automatically expose relevant data models from Tableau to enhance visibility. * **Data health signals** — View the [data-health-signals](https://docs.getdbt.com/docs/explore/data-health-signals) for each resource to understand its health and performance. ### Catalog permissions[​](https://docs.getdbt.com/docs/explore/explore-projects#catalog-permissions "Direct link to Catalog permissions") When using global navigation and searching across your projects, the following permissions apply. * Your project access permissions determine which dbt projects appear in the left-hand menu of the global navigation. * In Catalog searches, we use soft access controls, you'll see all matching resources in search results, with clear indicators for items you don't have access to. * For external metadata, the global platform credential controls which resources metadata users can discover. See [External metadata ingestion](https://docs.getdbt.com/docs/explore/external-metadata-ingestion) for more details. On-demand learning If you enjoy video courses, check out our [dbt Catalog on-demand course](https://learn.getdbt.com/courses/dbt-catalog) and learn how to best explore your dbt project(s)! Explore your project's lineage graph[​](https://docs.getdbt.com/docs/explore/explore-projects#project-lineage "Direct link to Explore your project's lineage graph") --------------------------------------------------------------------------------------------------------------------------------------------------------------------- Catalog provides a visualization of your project's DAG that you can interact with. To access the project's full lineage graph, select **Overview** in the left sidebar and click the **Explore Lineage** button on the main (center) section of the page. If you don't see the project lineage graph immediately, click **Render Lineage**. It can take some time for the graph to render depending on the size of your project and your computer's available memory. The graph of very large projects might not render so you can select a subset of nodes by using selectors, instead. The nodes in the lineage graph represent the project's resources and the edges represent the relationships between the nodes. Nodes are color-coded and include iconography according to their resource type. By default, Catalog shows the project's [applied state](https://docs.getdbt.com/docs/dbt-cloud-apis/project-state#definition-logical-vs-applied-state-of-dbt-nodes) lineage. That is, it shows models that have been successfully built and are available to query, not just the models defined in the project. To explore the lineage graphs of tests and macros, view [their resource details pages](https://docs.getdbt.com/docs/explore/explore-projects#view-resource-details) . By default, Catalog excludes these resources from the full lineage graph unless a search query returns them as results.  How can I interact with the full lineage graph? * Hover over any item in the graph to display the resource's name and type. * Zoom in and out on the graph by mouse-scrolling. * Grab and move the graph and the nodes. * Right-click on a node (context menu) to: * Refocus on the node, including its upstream and downstream nodes * Refocus on the node and its downstream nodes only * Refocus on the node and it upstream nodes only * View the node's [resource details](https://docs.getdbt.com/docs/explore/explore-projects#view-resource-details) page * Select a resource to highlight its relationship with other resources in your project. A panel opens on the graph's right-hand side that displays a high-level summary of the resource's details. The side panel includes a **General** tab for information like description, materialized type, and other details. In the side panel's upper right corner: * Click the View Resource icon to [view the resource details](https://docs.getdbt.com/docs/explore/explore-projects#view-resource-details) . * Click the [Open in IDE](https://docs.getdbt.com/docs/explore/explore-projects#open-in-ide) icon to examine the resource using the [Studio IDE](https://docs.getdbt.com/docs/cloud/dbt-cloud-ide/develop-in-the-cloud) . * Click the Copy Link to Page icon to copy the page's link to your clipboard. * Use [selectors](https://docs.getdbt.com/reference/node-selection/methods) (in the search bar) to select specific resources or a subset of the DAG. This can help narrow the focus on the resources that interest you. All selectors are available for use, except those requiring a state comparison (result, source status, and state). You can also use the `--exclude` and the `--select` flag (which is optional). Examples: * `resource_type:model [RESOURCE_NAME]` — Returns all models matching the name search * `resource_type:metric,tag:nightly` — Returns metrics with the tag `nightly` * Use [graph operators](https://docs.getdbt.com/reference/node-selection/graph-operators) (in the search bar) to select specific resources or a subset of the DAG. This can help narrow the focus on the resources that interest you. Examples: * `+orders` — Returns all the upstream nodes of `orders` * `+dim_customers,resource_type:source` — Returns all sources that are upstream of `dim_customers` * Use [set operators](https://docs.getdbt.com/reference/node-selection/set-operators) (in the search bar) to select specific resources or a subset of the DAG. This can help narrow the focus on the resources that interest you. For example: * `+snowplow_sessions +fct_orders` — Use space-delineated arguments for a union operation. Returns resources that are upstream nodes of either `snowplow_sessions` or `fct_orders`. * [View resource details](https://docs.getdbt.com/docs/explore/explore-projects#view-resource-details) by selecting a node (double-clicking) in the graph. * Click **Lenses** (lower right corner of the graph) to use Catalog [lenses](https://docs.getdbt.com/docs/explore/explore-projects#lenses) feature. ### Example of full lineage graph[​](https://docs.getdbt.com/docs/explore/explore-projects#example-of-full-lineage-graph "Direct link to Example of full lineage graph") Example of exploring a model in the project's lineage graph: [![Example of full lineage graph](https://docs.getdbt.com/img/docs/collaborate/dbt-explorer/example-project-lineage-graph.png?v=2 "Example of full lineage graph")](https://docs.getdbt.com/docs/explore/explore-projects#) Example of full lineage graph Lenses[​](https://docs.getdbt.com/docs/explore/explore-projects#lenses "Direct link to Lenses") ------------------------------------------------------------------------------------------------ The **Lenses** feature is available from your [project's lineage graph](https://docs.getdbt.com/docs/explore/explore-projects#project-lineage) (lower right corner). Lenses are like map layers for your DAG. Lenses make it easier to understand your project's contextual metadata at scale, especially to distinguish a particular model or a subset of models. When you apply a lens, tags become visible on the nodes in the lineage graph, indicating the layer value along with coloration based on that value. If you're significantly zoomed out, only the tags and their colors are visible in the graph. Lenses are helpful to analyze a subset of the DAG if you're zoomed in, or to find models/issues from a larger vantage point.  List of available lenses A resource in your project is characterized by resource type, materialization type, or model layer, as well as its latest run or latest test status. Lenses are available for the following metadata: * **Resource type**: Organizes resources by resource type, such as models, tests, seeds, saved query, and [more](https://docs.getdbt.com/docs/build/projects) . Resource type uses the `resource_type` selector. * **Materialization type**: Identifies the strategy for building the dbt models in your data platform. * **Latest status**: The status from the latest execution of the resource in the current environment. For example, diagnosing a failed DAG region. * **Model layer**: The modeling layer that the model belongs to according to [best practices guide](https://docs.getdbt.com/best-practices/how-we-structure/1-guide-overview#guide-structure-overview) . For example, discovering marts models to analyze. * **Marts** — A model with the prefix `fct_` or `dim_` or a model that lives in the `/marts/` subdirectory. * **Intermediate** — A model with the prefix `int_`. Or, a model that lives in the `/int/` or `/intermediate/` subdirectory. * **Staging** — A model with the prefix `stg_`. Or, a model that lives in the `/staging/` subdirectory. * **Test status**: The status from the latest execution of the tests that ran again this resource. In the case that a model has multiple tests with different results, the lens reflects the 'worst case' status. * **Consumption query history**: The number of queries against this resource over a given time period. ### Example of lenses[​](https://docs.getdbt.com/docs/explore/explore-projects#example-of-lenses "Direct link to Example of lenses") Example of applying the **Materialization type** _lens_ with the lineage graph zoomed out. In this view, each model name has a color according to the materialization type legend at the bottom, which specifies the materialization type. This color-coding helps to quickly identify the materialization types of different models. [![Example of the Materialization type lens](https://docs.getdbt.com/img/docs/collaborate/dbt-explorer/example-materialization-type.jpg?v=2 "Example of the Materialization type lens")](https://docs.getdbt.com/docs/explore/explore-projects#) Example of the Materialization type lens Example of applying the **Tests Status** _lens_, where each model name displays the tests status according to the legend at the bottom, which specifies the test status. [![Example of the Test Status lens](https://docs.getdbt.com/img/docs/collaborate/dbt-explorer/example-test-status.jpg?v=2 "Example of the Test Status lens")](https://docs.getdbt.com/docs/explore/explore-projects#) Example of the Test Status lens Keyword search[​](https://docs.getdbt.com/docs/explore/explore-projects#search-resources "Direct link to Keyword search") -------------------------------------------------------------------------------------------------------------------------- With Catalog, global navigation provides a search experience allowing you to find dbt resources across all your projects, as well as non-dbt resources in Snowflake. You can locate resources in your project by performing a keyword search in the search bar. All resource names, column names, resource descriptions, warehouse relations, and code matching your search criteria will be displayed as a list on the main (center) section of the page. When searching for an exact column name, the results show all relational nodes containing that column in their schemas. If there's a match, a notice in the search result indicates the resource contains the specified column. Also, you can apply filters to further refine your search results.  Search features * **Partial keyword search** — Also referred to as fuzzy search. Catalog uses a "contains" logic to improve your search results. This means you can search for partial terms without knowing the exact root word of your search term. * **Exclude keywords** — Prepend a minus sign (-) to the keyword you want to exclude from search results. For example, `-user` will exclude all matches of that keyword from search results. * **Boolean operators** — Use Boolean operators to enhance your keyword search. For example, the search results for `users OR github` will include matches for either keyword. * **Phrase search** — Surround a string of keywords with double quotation marks to search for that exact phrase (for example, `"stg users"`). To learn more, refer to [Phrase search](https://en.wikipedia.org/wiki/Phrase_search) on Wikipedia. * **SQL keyword search** — Use SQL keywords in your search. For example, the search results `int github users joined` will include matches that contain that specific string of keywords (similar to phrase searching). Filters side panel The **Filters** side panel becomes available after you perform a keyword search. Use this panel to further refine the results from your keyword search. By default, Catalog searches across all resources in the project. You can filter on: * [Resource type](https://docs.getdbt.com/docs/build/projects) (like models, sources, and so on) * [Model access](https://docs.getdbt.com/docs/mesh/govern/model-access) (like public, private) * [Model layer](https://docs.getdbt.com/best-practices/how-we-structure/1-guide-overview) (like marts, staging) * [Model materialization](https://docs.getdbt.com/docs/build/materializations) (like view, table) * [Tags](https://docs.getdbt.com/reference/resource-configs/tags) (supports multi-select) Under the **Models** option, you can filter on model properties (access or materialization type). Also available are **Advanced** options, where you can limit the search results to column name, model code, and more. Global navigation Catalog builds on the functionality of the old navigation and introduces exciting new capabilities to enhance your experience. For more information, refer to [Global navigation](https://docs.getdbt.com/docs/explore/global-navigation) . ### Example of keyword search[​](https://docs.getdbt.com/docs/explore/explore-projects#example-of-keyword-search "Direct link to Example of keyword search") Example of results from searching on the keyword `customers` and applying the filters models, description, and code. [Data health signals](https://docs.getdbt.com/docs/explore/data-health-signals) are visible to the right of the model name in the search results. Browse with the sidebar[​](https://docs.getdbt.com/docs/explore/explore-projects#browse-with-the-sidebar "Direct link to Browse with the sidebar") --------------------------------------------------------------------------------------------------------------------------------------------------- From the sidebar, you can browse your project's resources, its file tree, and the database. * **Resources** tab — All resources in the project organized by type. Select any resource type in the list and all those resources in the project will display as a table in the main section of the page. For a description on the different resource types (like models, metrics, and so on), refer to [About dbt projects](https://docs.getdbt.com/docs/build/projects) . * [Data health signals](https://docs.getdbt.com/docs/explore/data-health-signals) are visible to the right of the resource name under the **Health** column. * **File Tree** tab — All resources in the project organized by the file in which they are defined. This mirrors the file tree in your dbt project repository. * **Database** tab — All resources in the project organized by the database and schema in which they are built. This mirrors your data platform's structure that represents the [applied state](https://docs.getdbt.com/docs/dbt-cloud-apis/project-state) of your project. Integrated tool access[​](https://docs.getdbt.com/docs/explore/explore-projects#integrated-tool-access "Direct link to Integrated tool access") ------------------------------------------------------------------------------------------------------------------------------------------------ Users with a [developer license](https://docs.getdbt.com/docs/cloud/manage-access/about-user-access#license-based-access-control) or an analyst seat can open a resource directly from the Catalog in the Studio IDE to view its model files, in Insights to query it, or in Canvas for visual editing. View model versions[​](https://docs.getdbt.com/docs/explore/explore-projects#view-model-versions "Direct link to View model versions") --------------------------------------------------------------------------------------------------------------------------------------- If models in the project are versioned, you can see which [version of the model](https://docs.getdbt.com/docs/mesh/govern/model-versions) is being applied — `prerelease`, `latest`, and `old` — in the title of the model's details page and in the model list from the sidebar. View resource details[​](https://docs.getdbt.com/docs/explore/explore-projects#view-resource-details "Direct link to View resource details") --------------------------------------------------------------------------------------------------------------------------------------------- You can view the definition and latest run results of any resource in your project. To find a resource and view its details, you can interact with the lineage graph, use search, or browse the Catalog. The details (metadata) available to you depends on the resource's type, its definition, and the [commands](https://docs.getdbt.com/docs/deploy/job-commands) that run within jobs in the production environment. In the upper right corner of the resource details page, you can: * Click the [Open in Studio IDE](https://docs.getdbt.com/docs/explore/explore-projects#open-in-ide) icon to examine the resource using the [Studio IDE](https://docs.getdbt.com/docs/cloud/dbt-cloud-ide/develop-in-the-cloud) . * Click the Share icon to copy the page's link to your clipboard.  What details are available for a model? * **Data health signals** — [Data health signals](https://docs.getdbt.com/docs/explore/data-health-signals) offer a quick, at-a-glance view of data health. These icons indicate whether a model is Healthy, Caution, Degraded, or Unknown. Hover over an icon to view detailed information about the model's health. * **Status bar** (below the page title) — Information on the last time the model ran, whether the run was successful, how the data is materialized, number of rows, and the size of the model. * **General** tab includes: * **Lineage** graph — The model's lineage graph that you can interact with. The graph includes one upstream node and one downstream node from the model. Click the Expand icon in the graph's upper right corner to view the model in full lineage graph mode. * **Description** section — A [description of the model](https://docs.getdbt.com/docs/build/documentation#adding-descriptions-to-your-project) . * **Recent** section — Information on the last time the model ran, how long it ran for, whether the run was successful, the job ID, and the run ID. * **Tests** section — [Data tests](https://docs.getdbt.com/docs/build/data-tests) for the model, including a status indicator for the latest test status. A ✅ denotes a passing test. * **Details** section — Key properties like the model's relation name (for example, how it's represented and how you can query it in the data platform: `database.schema.identifier`); model governance attributes like access, group, and if contracted; and more. * **Relationships** section — The nodes the model **Depends On**, is **Referenced by**, and (if applicable) is **Used by** for projects that have declared the models' project as a dependency. * **Code** tab — The source code and compiled code for the model. * **Columns** tab — The available columns in the model. This tab also shows tests results (if any) that you can select to view the test's details page. A ✅ denotes a passing test. To filter the columns in the resource, you can use the search bar that's located at the top of the columns view. What details are available for an exposure? * **Status bar** (below the page title) — Information on the last time the exposure was updated. * **Data health signals** — [Data health signals](https://docs.getdbt.com/docs/explore/data-health-signals) offer a quick, at-a-glance view of data health. These icons indicate whether a resource is Healthy, Caution, or Degraded. Hover over an icon to view detailed information about the exposure's health. * **General** tab includes: * **Data health** — The status on data freshness and data quality. * **Status** section — The status on data freshness and data quality. * **Lineage** graph — The exposure's lineage graph. Click the **Expand** icon in the graph's upper right corner to view the exposure in full lineage graph mode. Integrates natively with Tableau and auto-generates downstream lineage. * **Description** section — A description of the exposure. * **Details** section — Details like exposure type, maturity, owner information, and more. * **Relationships** section — The nodes the exposure **Depends On**. What details are available for a test? * **Status bar** (below the page title) — Information on the last time the test ran, whether the test passed, test name, test target, and column name. Defaults to all if not specified. * **Test Type** (next to the Status bar) — Information on the different test types available: Unit test or Data test. Defaults to all if not specified. When you select a test, the following details are available: * **General** tab includes: * **Lineage** graph — The test's lineage graph that you can interact with. The graph includes one upstream node and one downstream node from the test resource. Click the Expand icon in the graph's upper right corner to view the test in full lineage graph mode. * **Description** section — A description of the test. * **Recent** section — Information on the last time the test ran, how long it ran for, whether the test passed, the job ID, and the run ID. * **Details** section — Details like schema, severity, package, and more. * **Relationships** section — The nodes the test **Depends On**. * **Code** tab — The source code and compiled code for the test. Example of the Tests view: What details are available for each source table within a source collection? * **Status bar** (below the page title) — Information on the last time the source was updated and the number of tables the source uses. * **Data health signals** — [Data health signals](https://docs.getdbt.com/docs/explore/data-health-signals) offer a quick, at-a-glance view of data health. These icons indicate whether a resource is Healthy, Caution, or Degraded. Hover over an icon to view detailed information about the source's health. * **General** tab includes: * **Lineage** graph — The source's lineage graph that you can interact with. The graph includes one upstream node and one downstream node from the source. Click the Expand icon in the graph's upper right corner to view the source in full lineage graph mode. * **Description** section — A description of the source. * **Source freshness** section — Information on whether refreshing the data was successful, the last time the source was loaded, the timestamp of when a run generated data, and the run ID. * **Details** section — Details like database, schema, and more. * **Relationships** section — A table that lists all the sources used with their freshness status, the timestamp of when freshness was last checked, and the timestamp of when the source was last loaded. * **Columns** tab — The available columns in the source. This tab also shows tests results (if any) that you can select to view the test's details page. A ✅ denotes a passing test. ### Example of model details[​](https://docs.getdbt.com/docs/explore/explore-projects#example-of-model-details "Direct link to Example of model details") Example of the details view for the model `customers`: [![Example of resource details](https://docs.getdbt.com/img/docs/collaborate/dbt-explorer/example-model-details.png?v=2 "Example of resource details")](https://docs.getdbt.com/docs/explore/explore-projects#) Example of resource details [![Example of downstream exposure details for Tableau.](https://docs.getdbt.com/img/docs/cloud-integrations/auto-exposures/explorer-lineage2.jpg?v=2 "Example of downstream exposure details for Tableau.")](https://docs.getdbt.com/docs/explore/explore-projects#) Example of downstream exposure details for Tableau. Staging environment[​](https://docs.getdbt.com/docs/explore/explore-projects#staging-environment "Direct link to Staging environment") --------------------------------------------------------------------------------------------------------------------------------------- Catalog supports views for [staging deployment environments](https://docs.getdbt.com/docs/deploy/deploy-environments#staging-environment) , in addition to the production environment. This gives you a unique view into your pre-production data workflows, with the same tools available in production, while providing an extra layer of scrutiny. You can explore the metadata from your production or staging environment to inform your data development lifecycle. Just [set a single environment](https://docs.getdbt.com/docs/deploy/deploy-environments) per dbt project as "production" or "staging," and ensure the proper metadata has been generated then you'll be able to view it in Catalog. Refer to [Generating metadata](https://docs.getdbt.com/docs/explore/explore-projects#generate-metadata) for more details. Related content[​](https://docs.getdbt.com/docs/explore/explore-projects#related-content "Direct link to Related content") --------------------------------------------------------------------------------------------------------------------------- * [Enterprise permissions](https://docs.getdbt.com/docs/cloud/manage-access/enterprise-permissions) * [About model governance](https://docs.getdbt.com/docs/mesh/govern/about-model-governance) * Blog on [What is data mesh?](https://www.getdbt.com/blog/what-is-data-mesh-the-definition-and-importance-of-data-mesh) Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Prerequisites](https://docs.getdbt.com/docs/explore/explore-projects#prerequisites) * [Generate metadata](https://docs.getdbt.com/docs/explore/explore-projects#generate-metadata) * [dbt metadata](https://docs.getdbt.com/docs/explore/explore-projects#dbt-metadata) * [External metadata ingestion](https://docs.getdbt.com/docs/explore/explore-projects#external-metadata-ingestion-) * [Catalog overview](https://docs.getdbt.com/docs/explore/explore-projects#catalog-overview) * [Catalog permissions](https://docs.getdbt.com/docs/explore/explore-projects#catalog-permissions) * [Explore your project's lineage graph](https://docs.getdbt.com/docs/explore/explore-projects#project-lineage) * [Example of full lineage graph](https://docs.getdbt.com/docs/explore/explore-projects#example-of-full-lineage-graph) * [Lenses](https://docs.getdbt.com/docs/explore/explore-projects#lenses) * [Example of lenses](https://docs.getdbt.com/docs/explore/explore-projects#example-of-lenses) * [Keyword search](https://docs.getdbt.com/docs/explore/explore-projects#search-resources) * [Example of keyword search](https://docs.getdbt.com/docs/explore/explore-projects#example-of-keyword-search) * [Browse with the sidebar](https://docs.getdbt.com/docs/explore/explore-projects#browse-with-the-sidebar) * [Integrated tool access](https://docs.getdbt.com/docs/explore/explore-projects#integrated-tool-access) * [View model versions](https://docs.getdbt.com/docs/explore/explore-projects#view-model-versions) * [View resource details](https://docs.getdbt.com/docs/explore/explore-projects#view-resource-details) * [Example of model details](https://docs.getdbt.com/docs/explore/explore-projects#example-of-model-details) * [Staging environment](https://docs.getdbt.com/docs/explore/explore-projects#staging-environment) * [Related content](https://docs.getdbt.com/docs/explore/explore-projects#related-content) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/explore/explore-projects.md) --- # Job object schema | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page The job object allows you to query information about a particular model based on `jobId` and, optionally, a `runId`. If you don't provide a `runId`, the API returns information on the latest runId of a job. The [example query](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job#example-query) illustrates a few fields you can query in this `job` object. Refer to [Fields](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job#fields) to see the entire schema, which provides all possible fields you can query. ### Arguments[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job#arguments "Direct link to Arguments") When querying for `job`, you can use the following arguments. Fetching data... ================ ### Example Query[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job#example-query "Direct link to Example Query") You can use your production job's `id`. query JobQueryExample { # Provide runId for looking at specific run, otherwise it defaults to latest run job(id: 940) { # Get all models from this job's latest run models(schema: "analytics") { uniqueId executionTime } # Or query a single node source(uniqueId: "source.jaffle_shop.snowplow.event") { uniqueId sourceName name state maxLoadedAt criteria { warnAfter { period count } errorAfter { period count } } maxLoadedAtTimeAgoInS } }} ### Fields[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job#fields "Direct link to Fields") When querying an `job`, you can use the following fields. Fetching data... ================ Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Arguments](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job#arguments) * [Example Query](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job#example-query) * [Fields](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job#fields) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/dbt-cloud-apis/schema-discovery-job.mdx) --- # dbt release notes | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/dbt-versions/dbt-cloud-release-notes#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page dbt release notes for recent and historical changes. Release notes fall into one of the following categories: * **New:** New products and features * **Enhancement:** Performance improvements and feature enhancements * **Fix:** Bug and security fixes * **Behavior change:** A change to existing behavior that doesn't fit into the other categories, such as feature deprecations or changes to default settings Release notes are grouped by month for both multi-tenant and virtual private cloud (VPC) environments. September 2025[​](https://docs.getdbt.com/docs/dbt-versions/dbt-cloud-release-notes#september-2025 "Direct link to September 2025") ------------------------------------------------------------------------------------------------------------------------------------ * **Fix**: Improved how [MetricFlow](https://docs.getdbt.com/docs/build/about-metricflow) handles [offset metrics](https://docs.getdbt.com/docs/build/derived) for more accurate results when querying time-based data. MetricFlow now joins data _after_ aggregation when the query grain matches the offset grain. Previously, when querying offset metrics, the offset join was applied _before_ aggregation, which could exclude some values from the total time period. August 2025[​](https://docs.getdbt.com/docs/dbt-versions/dbt-cloud-release-notes#august-2025 "Direct link to August 2025") --------------------------------------------------------------------------------------------------------------------------- * **Fix**: Resolved a bug that caused [saved query](https://docs.getdbt.com/docs/build/saved-queries) exports to fail during `dbt build` with `Unable to get saved_query` errors. * **New**: The Semantic Layer GraphQL API now has a [`queryRecords`](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-graphql#query-records) endpoint. With this endpoint, you can view the query history both for Insights and Semantic Layer queries. * **Fix**: Resolved a bug that caused Semantic Layer queries with a trailing whitespace to produce an error. This issue mostly affected [Push.ai](https://docs.push.ai/data-sources/semantic-layers/dbt) users and is fixed now. * **New**: You can now use [personal access tokens (PATs)](https://docs.getdbt.com/docs/dbt-cloud-apis/user-tokens) to authenticate in the Semantic Layer. This enables user-level authentication and reduces the need for sharing tokens between users. When you authenticate using PATs, queries are run using your personal development credentials. For more information, see [Set up the dbt Semantic Layer](https://docs.getdbt.com/docs/use-dbt-semantic-layer/setup-sl) . July 2025[​](https://docs.getdbt.com/docs/dbt-versions/dbt-cloud-release-notes#july-2025 "Direct link to July 2025") --------------------------------------------------------------------------------------------------------------------- * **New**: The [Tableau Cloud](https://www.tableau.com/products/cloud-bi) integration with Semantic Layer is now available. For more information, see [Tableau](https://docs.getdbt.com/docs/cloud-integrations/semantic-layer/tableau) . * **Preview**: The [Semantic Layer Power BI integration](https://docs.getdbt.com/docs/cloud-integrations/semantic-layer/power-bi) is now available in Preview. * **Enhancement:** You can now use `limit` and `order_by` parameters when creating [saved queries](https://docs.getdbt.com/docs/build/saved-queries) . * **Enhancement:** Users assigned IT [licenses](https://docs.getdbt.com/docs/cloud/manage-access/seats-and-users) can now edit and manage [global connections settings](https://docs.getdbt.com/docs/cloud/connect-data-platform/about-connections#connection-management) . * **New**: Paginated [GraphQL](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-graphql) endpoints for metadata queries in Semantic Layer are now available. This improves integration load times for large manifests. For more information, see [Metadata calls](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-graphql#metadata-calls) . June 2025[​](https://docs.getdbt.com/docs/dbt-versions/dbt-cloud-release-notes#june-2025 "Direct link to June 2025") --------------------------------------------------------------------------------------------------------------------- * **New**: [System for Cross-Domain Identity Management](https://docs.getdbt.com/docs/cloud/manage-access/scim#scim-configuration-for-entra-id) (SCIM) through Microsoft Entra ID is now GA. Also available on legacy Enterprise plans. * **Enhancement:** You can now set the [compilation environment](https://docs.getdbt.com/docs/explore/access-dbt-insights#set-jinja-environment) to control how Jinja functions are rendered in dbt Insights. * **Beta**: The dbt Fusion engine supports the BigQuery adapter in beta. * **New:** You can now view the history of settings changes for [projects](https://docs.getdbt.com/docs/cloud/account-settings) , [environments](https://docs.getdbt.com/docs/dbt-cloud-environments) , and [jobs](https://docs.getdbt.com/docs/deploy/deploy-jobs) . * **New:** Added support for the latest version of BigQuery credentials in Semantic Layer and MetricFlow. * **New:** Snowflake External OAuth is now supported for Semantic Layer queries. Snowflake connections that use External OAuth for user credentials can now emit queries for Insights, Cloud CLI, and Studio IDE through the Semantic Layer Gateway. This enables secure, identity-aware access via providers like Okta or Microsoft Entra ID. * **New:** You can now [download your managed Git repo](https://docs.getdbt.com/docs/cloud/git/managed-repository#download-managed-repository) from the dbt platform. * **New**: The Semantic Layer now supports Trino as a data platform. For more details, see [Set up the Semantic Layer](https://docs.getdbt.com/docs/use-dbt-semantic-layer/setup-sl) . * **New**: The dbt Fusion engine supports Databricks in beta. * **Enhancement**: Group owners can now specify multiple email addresses for model-level notifications, enabling broader team alerts. Previously, only a single email address was supported. Check out the [Configure groups](https://docs.getdbt.com/docs/deploy/model-notifications#configure-groups) section to learn more. * **New**: The Semantic Layer GraphQL API now has a [`List a saved query`](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-graphql#list-a-saved-query) endpoint. May 2025[​](https://docs.getdbt.com/docs/dbt-versions/dbt-cloud-release-notes#may-2025 "Direct link to May 2025") ------------------------------------------------------------------------------------------------------------------ ### 2025 dbt Launch Showcase[​](https://docs.getdbt.com/docs/dbt-versions/dbt-cloud-release-notes#2025-dbt-launch-showcase "Direct link to 2025 dbt Launch Showcase") The following features are new or enhanced as part of our [dbt Launch Showcase](https://www.getdbt.com/resources/webinars/2025-dbt-cloud-launch-showcase) on May 28th, 2025: * **New**: The dbt Fusion engine is the brand new dbt engine re-written from the ground up to provide incredible speed, cost-savings tools, and comprehensive SQL language tools. The dbt Fusion engine is now available in beta for Snowflake users. * Read more [about Fusion](https://docs.getdbt.com/docs/fusion/about-fusion) . * Understand what actions you need to take to get your projects Fusion-ready with the [upgrade guide](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-fusion) . * Begin testing today with the [quickstart guide](https://docs.getdbt.com/guides/fusion) . * Know [where we're headed with the dbt Fusion engine](https://getdbt.com/blog/where-we-re-headed-with-the-dbt-fusion-engine) . * **New**: The dbt VS Code extension is a powerful new tool that brings the speed and productivity of the dbt Fusion engine into your Visual Studio Code editor. This is a free download that will forever change your dbt development workflows. The dbt VS Code extension is now available as beta [alongside Fusion](https://getdbt.com/blog/get-to-know-the-new-dbt-fusion-engine-and-vs-code-extension) . Check out the [installation instructions](https://docs.getdbt.com/docs/install-dbt-extension) and read more [about the features](https://docs.getdbt.com/docs/about-dbt-extension) to get started enhancing your dbt workflows today! * **New**: dbt Explorer is now Catalog! Learn more about the change [here](https://getdbt.com/blog/updated-names-for-dbt-platform-and-features) . * dbt's Catalog, global navigation provides a search experience that lets you find dbt resources across all your projects, as well as non-dbt resources in Snowflake. * External metadata ingestion allows you to connect directly to your data warehouse, giving you visibility into tables, views, and other resources that aren't defined in dbt. * **New**: [dbt Canvas is now generally available](https://getdbt.com/blog/dbt-canvas-is-ga) (GA). Canvas is the intuitive visual editing tool that enables anyone to create dbt models with an easy to understand drag-and-drop interface. Read more [about Canvas](https://docs.getdbt.com/docs/cloud/canvas) to begin empowering your teams to build more, faster! * **New**: [State-aware orchestration](https://docs.getdbt.com/docs/deploy/state-aware-about) is now in beta! Every time a new job in Fusion runs, state-aware orchestration automatically determines which models to build by detecting changes in code or data. * **New**: With Hybrid Projects, your organization can adopt complementary dbt Core and dbt Cloud workflows and seamlessly integrate these workflows by automatically uploading dbt Core artifacts into dbt Cloud. [Hybrid Projects](https://docs.getdbt.com/docs/deploy/hybrid-projects) is now available as a preview to [dbt Enterprise accounts](https://www.getdbt.com/pricing) . * **New**: [System for Cross-Domain Identity Management (SCIM)](https://docs.getdbt.com/docs/cloud/manage-access/scim) through Okta is now GA. * **New**: dbt now acts as a [Model Context Protocol](https://docs.getdbt.com/docs/dbt-ai/about-mcp) (MCP) server, allowing seamless integration of AI tools with data warehouses through a standardized framework. * **New**: The [quickstart guide for data analysts](https://docs.getdbt.com/guides/analyze-your-data) is now available. With dbt, data analysts can use built-in, AI-powered tools to build governed data models, explore how they’re built, and run their own analysis. * **New**: You can view your [usage metering and limiting in dbt Copilot](https://docs.getdbt.com/docs/cloud/billing#dbt-copilot-usage-metering-and-limiting) on the billing page of your dbt Cloud account. * **New**: You can use Copilot to create a `dbt-styleguide.md` for dbt projects. The generated style guide template includes SQL style guidelines, model organization and naming conventions, model configurations and testing practices, and recommendations to enforce style rules. For more information, see [Copilot style guide](https://docs.getdbt.com/docs/cloud/copilot-styleguide) . * **New**: Copilot chat is an interactive interface within the Studio IDE where you can generate SQL code from natural language prompts and ask analytics-related questions. It integrates contextual understanding of your dbt project and assists in streamlining SQL development. For more information, see [Copilot chat](https://docs.getdbt.com/docs/cloud/copilot-chat-in-studio) . * **New**: Leverage dbt Copilot to generate SQL queries in [Insights](https://docs.getdbt.com/docs/explore/dbt-insights) from natural language prompts, enabling efficient data exploration within a context-aware interface. * **New**: The dbt platform Cost management dashboard is now available as a preview for Snowflake users on Enterprise and Enteprise Plus plans. Gain valuable insights into your warehouse spend with the comprehensive and interactive dashboard. Read more [about it](https://docs.getdbt.com/docs/cloud/cost-management) to get started with your cost savings analysis today! * **New**: Apache Iceberg catalog integration support is now available on Snowflake and BigQuery! This is essential to making your dbt Mesh interoperable across platforms, built on Iceberg. Read more about [Iceberg](https://docs.getdbt.com/docs/mesh/iceberg/apache-iceberg-support) to begin creating Iceberg tables. * **Update**: Product renaming and other changes. For more information, refer to [Updated names for dbt platform and features](https://getdbt.com/blog/updated-names-for-dbt-platform-and-features) .  Product names key * Canvas (previously Visual Editor) * Catalog (previously Explorer) * Copilot * Cost Management * dbt Fusion engine * Insights * Mesh * Orchestrator * Studio IDE (previously Cloud IDE) * Semantic Layer * Pricing plan changes. For more information, refer to [One dbt](https://www.getdbt.com/product/one-dbt) . April 2025[​](https://docs.getdbt.com/docs/dbt-versions/dbt-cloud-release-notes#april-2025 "Direct link to April 2025") ------------------------------------------------------------------------------------------------------------------------ * **Enhancement**: The [Python SDK](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-python) now supports lazy loading for large fields for `dimensions`, `entities`, and `measures` on `Metric` objects. For more information, see [Lazy loading for large fields](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-python#lazy-loading-for-large-fields) . * **Enhancement**: The Semantic Layer now supports [SSH tunneling for Postgres or Redshift](https://docs.getdbt.com/docs/cloud/connect-data-platform/connect-redshift-postgresql-alloydb) connections. Refer to [Set up the Semantic Layer](https://docs.getdbt.com/docs/use-dbt-semantic-layer/setup-sl) for more information. * **Behavior change**: Users assigned the [`job admin` permission set](https://docs.getdbt.com/docs/cloud/manage-access/enterprise-permissions#job-admin) now have access to set up integrations for projects, including the [Tableau](https://docs.getdbt.com/docs/cloud-integrations/downstream-exposures-tableau) integration to populate downstream exposures. March 2025[​](https://docs.getdbt.com/docs/dbt-versions/dbt-cloud-release-notes#march-2025 "Direct link to March 2025") ------------------------------------------------------------------------------------------------------------------------ * **Behavior change**: As of March 31st, 2025, dbt Core versions 1.0, 1.1, and 1.2 have been deprecated from dbt. They are no longer available to select as versions for dbt projects. Workloads currently on these versions will be automatically upgraded to v1.3, which may cause new failures. * **Enhancement**: [Semantic Layer](https://docs.getdbt.com/docs/use-dbt-semantic-layer/dbt-sl) users on single-tenant configurations no longer need to contact their account representative to enable this feature. Setup is now self-service and available across all tenant configurations. * **New**: The Semantic Layer now supports Postgres as a data platform. For more details on how to set up the Semantic Layer for Postgres, see [Set up the Semantic Layer](https://docs.getdbt.com/docs/use-dbt-semantic-layer/setup-sl) . * **New**: New [environment variable default](https://docs.getdbt.com/docs/build/environment-variables#dbt-cloud-context) `DBT_CLOUD_INVOCATION_CONTEXT`. * **Enhancement**: Users assigned [read-only licenses](https://docs.getdbt.com/docs/cloud/manage-access/about-user-access#licenses) are now able to view the [Deploy](https://docs.getdbt.com/docs/deploy/deployments) section of their dbt account and click into the individual sections but not edit or otherwise make any changes. #### dbt Developer day[​](https://docs.getdbt.com/docs/dbt-versions/dbt-cloud-release-notes#dbt-developer-day "Direct link to dbt Developer day") The following features are new or enhanced as part of our [dbt Developer day](https://www.getdbt.com/resources/webinars/dbt-developer-day) on March 19th and 20th, 2025: * **New**: The [`--sample` flag](https://docs.getdbt.com/docs/build/sample-flag) , now available for the `run` and `build` commands, helps reduce build times and warehouse costs by running dbt in sample mode. It generates filtered refs and sources using time-based sampling, allowing developers to validate outputs without building entire models. * **New**: Copilot, an AI-powered assistant, is now generally available in the Cloud IDE for all dbt Enterprise accounts. Check out [Copilot](https://docs.getdbt.com/docs/cloud/dbt-copilot) for more information. #### Also available this month[​](https://docs.getdbt.com/docs/dbt-versions/dbt-cloud-release-notes#also-available-this-month "Direct link to Also available this month") * **New**: Bringing your own [Azure OpenAI key](https://docs.getdbt.com/docs/cloud/enable-dbt-copilot#bringing-your-own-openai-api-key-byok) for [Copilot](https://docs.getdbt.com/docs/cloud/dbt-copilot) is now generally available. Your organization can configure Copilot to use your own Azure OpenAI keys, giving you more control over data governance and billing. * **New**: The Semantic Layer supports Power BI as a [partner integration](https://docs.getdbt.com/docs/cloud-integrations/avail-sl-integrations) , available in private beta. To join the private beta, please reach out to your account representative. Check out the [Power BI](https://docs.getdbt.com/docs/cloud-integrations/semantic-layer/power-bi) integration for more information. * **New**: [dbt release tracks](https://docs.getdbt.com/docs/dbt-versions/cloud-release-tracks) are Generally Available. Depending on their plan, customers may select among the Latest, Compatible, or Extended tracks to manage the update cadences for development and deployment environments. * **New:** The dbt\-native integration with Azure DevOps now supports [Entra ID service principals](https://docs.getdbt.com/docs/cloud/git/setup-service-principal) . Unlike a services user, which represents a real user object in Entra ID, the service principal is a secure identity associated with your dbt app to access resources in Azure unattended. Please [migrate your service user](https://docs.getdbt.com/docs/cloud/git/setup-service-principal#migrate-to-service-principal) to a service principal for Azure DevOps as soon as possible. February 2025[​](https://docs.getdbt.com/docs/dbt-versions/dbt-cloud-release-notes#february-2025 "Direct link to February 2025") --------------------------------------------------------------------------------------------------------------------------------- * **Enhancement**: The [Python SDK](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-python) added a new timeout parameter to Semantic Layer client and to underlying GraphQL clients to specify timeouts. Set a timeout number or use the `total_timeout` parameter in the global `TimeoutOptions` to control connect, execute and close timeouts granularly. `ExponentialBackoff.timeout_ms` is now deprecated. * **New**: The [Azure DevOps](https://docs.getdbt.com/docs/cloud/git/connect-azure-devops) integration for Git now supports [Entra service principal apps](https://docs.getdbt.com/docs/cloud/git/setup-service-principal) on dbt Enterprise accounts. Microsoft is enforcing MFA across user accounts, including service users, which will impact existing app integrations. This is a phased rollout, and dbt Labs recommends [migrating to a service principal](https://docs.getdbt.com/docs/cloud/git/setup-service-principal#migrate-to-service-principal) on existing integrations once the option becomes available in your account. * **New**: Added the `dbt invocation` command to the [dbt CLI](https://docs.getdbt.com/docs/cloud/cloud-cli-installation) . This command allows you to view and manage active invocations, which are long-running sessions in the dbt CLI. For more information, see [dbt invocation](https://docs.getdbt.com/reference/commands/invocation) . * **New**: Users can now switch themes directly from the user menu, available [in Preview](https://docs.getdbt.com/docs/dbt-versions/product-lifecycles#dbt-cloud) . We have added support for **Light mode** (default), **Dark mode**, and automatic theme switching based on system preferences. The selected theme is stored in the user profile and will follow users across all devices. * Dark mode is currently available on the Developer plan and will be available for all [plans](https://www.getdbt.com/pricing) in the future. We’ll be rolling it out gradually, so stay tuned for updates. For more information, refer to [Change your dbt theme](https://docs.getdbt.com/docs/cloud/about-cloud/change-your-dbt-cloud-theme) . * **Fix**: Semantic Layer errors in the Cloud IDE are now displayed with proper formatting, fixing an issue where newlines appeared broken or difficult to read. This fix ensures error messages are more user-friendly and easier to parse. * **Fix**: Fixed an issue where [saved queries](https://docs.getdbt.com/docs/build/saved-queries) with no [exports](https://docs.getdbt.com/docs/build/saved-queries#configure-exports) would fail with an `UnboundLocalError`. Previously, attempting to process a saved query without any exports would cause an error due to an undefined relation variable. Exports are optional, and this fix ensures saved queries without exports don't fail. * **New**: You can now query metric alias in Semantic Layer [GraphQL](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-graphql) and [JDBC](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc) APIs. * For the JDBC API, refer to [Query metric alias](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc#query-metric-alias) for more information. * For the GraphQL API, refer to [Query metric alias](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-graphql#query-metric-alias) for more information. * **Enhancement**: Added support to automatically refresh access tokens when Snowflake's SSO connection expires. Previously, users would get the following error: `Connection is not available, request timed out after 30000ms` and would have to wait 10 minutes to try again. * **Enhancement**: The [`dbt_version` format](https://docs.getdbt.com/reference/commands/version#versioning) in dbt Cloud now better aligns with [semantic versioning rules](https://semver.org/) . Leading zeroes have been removed from the month and day (`YYYY.M.D+`). For example: * New format: `2024.10.8+996c6a8` * Previous format: `2024.10.08+996c6a8` Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [September 2025](https://docs.getdbt.com/docs/dbt-versions/dbt-cloud-release-notes#september-2025) * [August 2025](https://docs.getdbt.com/docs/dbt-versions/dbt-cloud-release-notes#august-2025) * [July 2025](https://docs.getdbt.com/docs/dbt-versions/dbt-cloud-release-notes#july-2025) * [June 2025](https://docs.getdbt.com/docs/dbt-versions/dbt-cloud-release-notes#june-2025) * [May 2025](https://docs.getdbt.com/docs/dbt-versions/dbt-cloud-release-notes#may-2025) * [2025 dbt Launch Showcase](https://docs.getdbt.com/docs/dbt-versions/dbt-cloud-release-notes#2025-dbt-launch-showcase) * [April 2025](https://docs.getdbt.com/docs/dbt-versions/dbt-cloud-release-notes#april-2025) * [March 2025](https://docs.getdbt.com/docs/dbt-versions/dbt-cloud-release-notes#march-2025) * [February 2025](https://docs.getdbt.com/docs/dbt-versions/dbt-cloud-release-notes#february-2025) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/dbt-versions/release-notes.md) --- # Integrate with other orchestration tools | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/deploy/deployment-tools#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page Alongside [dbt](https://docs.getdbt.com/docs/deploy/jobs) , discover other ways to schedule and run your dbt jobs with the help of tools such as the ones described on this page. Build and install these tools to automate your data workflows, trigger dbt jobs (including those hosted on dbt), and enjoy a hassle-free experience, saving time and increasing efficiency. Airflow[​](https://docs.getdbt.com/docs/deploy/deployment-tools#airflow "Direct link to Airflow") -------------------------------------------------------------------------------------------------- If your organization uses [Airflow](https://airflow.apache.org/) , there are a number of ways you can run your dbt jobs, including: * dbt platform * dbt Core Installing the [dbt Provider](https://airflow.apache.org/docs/apache-airflow-providers-dbt-cloud/stable/index.html) to orchestrate dbt jobs. This package contains multiple Hooks, Operators, and Sensors to complete various actions within dbt. [![Airflow DAG using DbtCloudRunJobOperator](https://docs.getdbt.com/img/docs/running-a-dbt-project/airflow_dbt_connector.png?v=2 "Airflow DAG using DbtCloudRunJobOperator")](https://docs.getdbt.com/docs/deploy/deployment-tools#) Airflow DAG using DbtCloudRunJobOperator [![dbt job triggered by Airflow](https://docs.getdbt.com/img/docs/running-a-dbt-project/dbt_cloud_airflow_trigger.png?v=2 "dbt job triggered by Airflow")](https://docs.getdbt.com/docs/deploy/deployment-tools#) dbt job triggered by Airflow Invoking dbt Core jobs through the [BashOperator](https://registry.astronomer.io/providers/apache-airflow/modules/bashoperator) . In this case, be sure to install dbt into a virtual environment to avoid issues with conflicting dependencies between Airflow and dbt. For more details on both of these methods, including example implementations, check out [this guide](https://docs.astronomer.io/learn/airflow-dbt-cloud) . Automation servers[​](https://docs.getdbt.com/docs/deploy/deployment-tools#automation-servers "Direct link to Automation servers") ----------------------------------------------------------------------------------------------------------------------------------- Automation servers (such as CodeDeploy, GitLab CI/CD ([video](https://youtu.be/-XBIIY2pFpc?t=1301) ), Bamboo and Jenkins) can be used to schedule bash commands for dbt. They also provide a UI to view logging to the command line, and integrate with your git repository. Azure Data Factory[​](https://docs.getdbt.com/docs/deploy/deployment-tools#azure-data-factory "Direct link to Azure Data Factory") ----------------------------------------------------------------------------------------------------------------------------------- Integrate dbt and [Azure Data Factory](https://learn.microsoft.com/en-us/azure/data-factory/) (ADF) for a smooth data process from data ingestion to data transformation. You can seamlessly trigger dbt jobs upon completion of ingestion jobs by using the [dbt API](https://docs.getdbt.com/docs/dbt-cloud-apis/overview) in ADF. The following video provides you with a detailed overview of how to trigger a dbt job via the API in Azure Data Factory. To use the dbt API to trigger a job in dbt through ADF: 1. In dbt, go to the job settings of the daily production job and turn off the scheduled run in the **Trigger** section. 2. You'll want to create a pipeline in ADF to trigger a dbt job. 3. Securely fetch the dbt service token from a key vault in ADF, using a web call as the first step in the pipeline. 4. Set the parameters in the pipeline, including the dbt account ID and job ID, as well as the name of the key vault and secret that contains the service token. * You can find the dbt job and account id in the URL, for example, if your URL is `https://YOUR_ACCESS_URL/deploy/88888/projects/678910/jobs/123456`, the account ID is 88888 and the job ID is 123456 5. Trigger the pipeline in ADF to start the dbt job and monitor the status of the dbt job in ADF. 6. In dbt, you can check the status of the job and how it was triggered in dbt. Cron[​](https://docs.getdbt.com/docs/deploy/deployment-tools#cron "Direct link to Cron") ----------------------------------------------------------------------------------------- Cron is a decent way to schedule bash commands. However, while it may seem like an easy route to schedule a job, writing code to take care of all of the additional features associated with a production deployment often makes this route more complex compared to other options listed here. Dagster[​](https://docs.getdbt.com/docs/deploy/deployment-tools#dagster "Direct link to Dagster") -------------------------------------------------------------------------------------------------- If your organization uses [Dagster](https://dagster.io/) , you can use the [dagster\_dbt](https://docs.dagster.io/_apidocs/libraries/dagster-dbt) library to integrate dbt commands into your pipelines. This library supports the execution of dbt through dbt or dbt Core. Running dbt from Dagster automatically aggregates metadata about your dbt runs. Refer to the [example pipeline](https://dagster.io/blog/dagster-dbt) for details. Databricks workflows[​](https://docs.getdbt.com/docs/deploy/deployment-tools#databricks-workflows "Direct link to Databricks workflows") ----------------------------------------------------------------------------------------------------------------------------------------- Use Databricks workflows to call the dbt job API, which has several benefits such as integration with other ETL processes, utilizing dbt job features, separation of concerns, and custom job triggering based on custom conditions or logic. These advantages lead to more modularity, efficient debugging, and flexibility in scheduling dbt jobs. For more info, refer to the guide on [Databricks workflows and dbt jobs](https://docs.getdbt.com/guides/how-to-use-databricks-workflows-to-run-dbt-cloud-jobs) . Kestra[​](https://docs.getdbt.com/docs/deploy/deployment-tools#kestra "Direct link to Kestra") ----------------------------------------------------------------------------------------------- If your organization uses [Kestra](http://kestra.io/) , you can leverage the [dbt plugin](https://kestra.io/plugins/plugin-dbt)  to orchestrate dbt and dbt Core jobs. Kestra's user interface (UI) has built-in [Blueprints](https://kestra.io/docs/user-interface-guide/blueprints) , providing ready-to-use workflows. Navigate to the Blueprints page in the left navigation menu and [select the dbt tag](https://demo.kestra.io/ui/blueprints/community?selectedTag=36)  to find several examples of scheduling dbt Core commands and dbt jobs as part of your data pipelines. After each scheduled or ad-hoc workflow execution, the Outputs tab in the Kestra UI allows you to download and preview all dbt build artifacts. The Gantt and Topology view additionally render the metadata to visualize dependencies and runtimes of your dbt models and tests. The dbt task provides convenient links to easily navigate between Kestra and dbt UI. Orchestra[​](https://docs.getdbt.com/docs/deploy/deployment-tools#orchestra "Direct link to Orchestra") -------------------------------------------------------------------------------------------------------- If your organization uses [Orchestra](https://getorchestra.io/) , you can trigger dbt jobs using the dbt API. Create an API token from your dbt account and use this to authenticate Orchestra in the [Orchestra Portal](https://app.getorchestra.io/) . For details, refer to the [Orchestra docs on dbt](https://orchestra-1.gitbook.io/orchestra-portal/integrations/transformation/dbt-cloud) . Orchestra automatically collects metadata from your runs so you can view your dbt jobs in the context of the rest of your data stack. The following is an example of the run details in dbt for a job triggered by Orchestra: [![Example of Orchestra triggering a dbt job](https://docs.getdbt.com/img/docs/running-a-dbt-project/dbt_cloud_orchestra_trigger.png?v=2 "Example of Orchestra triggering a dbt job")](https://docs.getdbt.com/docs/deploy/deployment-tools#) Example of Orchestra triggering a dbt job The following is an example of viewing lineage in Orchestra for dbt jobs: [![Example of a lineage view for dbt jobs in Orchestra](https://docs.getdbt.com/img/docs/running-a-dbt-project/orchestra_lineage_dbt_cloud.png?v=2 "Example of a lineage view for dbt jobs in Orchestra")](https://docs.getdbt.com/docs/deploy/deployment-tools#) Example of a lineage view for dbt jobs in Orchestra Prefect[​](https://docs.getdbt.com/docs/deploy/deployment-tools#prefect "Direct link to Prefect") -------------------------------------------------------------------------------------------------- If your organization uses [Prefect](https://www.prefect.io/) , the way you will run your jobs depends on the dbt version you're on, and whether you're orchestrating dbt or dbt Core jobs. Refer to the following variety of options: [![Prefect DAG using a dbt job run flow](https://docs.getdbt.com/img/docs/running-a-dbt-project/prefect_dag_dbt_cloud.jpg?v=2 "Prefect DAG using a dbt job run flow")](https://docs.getdbt.com/docs/deploy/deployment-tools#) Prefect DAG using a dbt job run flow ### Prefect 2[​](https://docs.getdbt.com/docs/deploy/deployment-tools#prefect-2 "Direct link to Prefect 2") * dbt platform * dbt Core * Use the [trigger\_dbt\_cloud\_job\_run\_and\_wait\_for\_completion](https://prefecthq.github.io/prefect-dbt/cloud/jobs/#prefect_dbt.cloud.jobs.trigger_dbt_cloud_job_run_and_wait_for_completion) flow. * As jobs are executing, you can poll dbt to see whether or not the job completes without failures, through the [Prefect user interface (UI)](https://docs.prefect.io/ui/overview/) . [![dbt job triggered by Prefect](https://docs.getdbt.com/img/docs/running-a-dbt-project/dbt_cloud_job_prefect.jpg?v=2 "dbt job triggered by Prefect")](https://docs.getdbt.com/docs/deploy/deployment-tools#) dbt job triggered by Prefect * Use the [trigger\_dbt\_cli\_command](https://prefecthq.github.io/prefect-dbt/cli/commands/#prefect_dbt.cli.commands.trigger_dbt_cli_command) task. * For details on both of these methods, see [prefect-dbt docs](https://prefecthq.github.io/prefect-dbt/) . ### Prefect 1[​](https://docs.getdbt.com/docs/deploy/deployment-tools#prefect-1 "Direct link to Prefect 1") * dbt platform * dbt Core * Trigger dbt jobs with the [DbtCloudRunJob](https://docs.prefect.io/api/latest/tasks/dbt.html#dbtcloudrunjob) task. * Running this task will generate a markdown artifact viewable in the Prefect UI. * The artifact will contain links to the dbt artifacts generated as a result of the job run. * Use the [DbtShellTask](https://docs.prefect.io/api/latest/tasks/dbt.html#dbtshelltask) to schedule, execute, and monitor your dbt runs. * Use the supported [ShellTask](https://docs.prefect.io/api/latest/tasks/shell.html#shelltask) to execute dbt commands through the shell. Related docs[​](https://docs.getdbt.com/docs/deploy/deployment-tools#related-docs "Direct link to Related docs") ----------------------------------------------------------------------------------------------------------------- * [dbt plans and pricing](https://www.getdbt.com/pricing/) * [Quickstart guides](https://docs.getdbt.com/guides) * [Webhooks for your jobs](https://docs.getdbt.com/docs/deploy/webhooks) * [Orchestration guides](https://docs.getdbt.com/guides) * [Commands for your production deployment](https://discourse.getdbt.com/t/what-are-the-dbt-commands-you-run-in-your-production-deployment-of-dbt/366) Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Airflow](https://docs.getdbt.com/docs/deploy/deployment-tools#airflow) * [Automation servers](https://docs.getdbt.com/docs/deploy/deployment-tools#automation-servers) * [Azure Data Factory](https://docs.getdbt.com/docs/deploy/deployment-tools#azure-data-factory) * [Cron](https://docs.getdbt.com/docs/deploy/deployment-tools#cron) * [Dagster](https://docs.getdbt.com/docs/deploy/deployment-tools#dagster) * [Databricks workflows](https://docs.getdbt.com/docs/deploy/deployment-tools#databricks-workflows) * [Kestra](https://docs.getdbt.com/docs/deploy/deployment-tools#kestra) * [Orchestra](https://docs.getdbt.com/docs/deploy/deployment-tools#orchestra) * [Prefect](https://docs.getdbt.com/docs/deploy/deployment-tools#prefect) * [Prefect 2](https://docs.getdbt.com/docs/deploy/deployment-tools#prefect-2) * [Prefect 1](https://docs.getdbt.com/docs/deploy/deployment-tools#prefect-1) * [Related docs](https://docs.getdbt.com/docs/deploy/deployment-tools#related-docs) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/deploy/deployment-tools.md) --- # Deploy your metrics | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/use-dbt-semantic-layer/deploy-sl#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page This section explains how you can perform a job run in your deployment environment in dbt to materialize and deploy your metrics. Currently, the deployment environment is only supported. 1. Once you’ve [defined your semantic models and metrics](https://docs.getdbt.com/guides/sl-snowflake-qs?step=10) , commit and merge your metric changes in your dbt project. 2. In dbt, create a new [deployment environment](https://docs.getdbt.com/docs/deploy/deploy-environments#create-a-deployment-environment) or use an existing environment on dbt 1.6 or higher. * Note — Deployment environment is currently supported (_development experience coming soon_) 3. To create a new environment, navigate to **Deploy** in the navigation menu, select **Environments**, and then select **Create new environment**. 4. Fill in your deployment credentials with your Snowflake username and password. You can name the schema anything you want. Click **Save** to create your new production environment. 5. [Create a new deploy job](https://docs.getdbt.com/docs/deploy/deploy-jobs#create-and-schedule-jobs) that runs in the environment you just created. Go back to the **Deploy** menu, select **Jobs**, select **Create job**, and click **Deploy job**. 6. Set the job to run a `dbt parse` job to parse your projects and generate a [`semantic_manifest.json` artifact](https://docs.getdbt.com/reference/artifacts/sl-manifest) file. Although running `dbt build` isn't required, you can choose to do so if needed. note If you are on the dbt Fusion engine, add the `dbt docs generate` command to your job to successfully deploy your metrics. 7. Run the job by clicking the **Run now** button. Monitor the job's progress in real-time through the **Run summary** tab. Once the job completes successfully, your dbt project, including the generated documentation, will be fully deployed and available for use in your production environment. If any issues arise, review the logs to diagnose and address any errors. What’s happening internally? * Merging the code into your main branch allows dbt to pull those changes and build the definition in the manifest produced by the run. * Re-running the job in the deployment environment helps materialize the models, which the metrics depend on, in the data platform. It also makes sure that the manifest is up to date. * The Semantic Layer APIs pull in the most recent manifest and enables your integration to extract metadata from it. Next steps[​](https://docs.getdbt.com/docs/use-dbt-semantic-layer/deploy-sl#next-steps "Direct link to Next steps") -------------------------------------------------------------------------------------------------------------------- After you've executed a job and deployed your Semantic Layer: * [Set up your Semantic Layer](https://docs.getdbt.com/docs/use-dbt-semantic-layer/setup-sl) in dbt. * Discover the [available integrations](https://docs.getdbt.com/docs/cloud-integrations/avail-sl-integrations) , such as Tableau, Google Sheets, Microsoft Excel, and more. * Start querying your metrics with the [API query syntax](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc#querying-the-api-for-metric-metadata) . Related docs[​](https://docs.getdbt.com/docs/use-dbt-semantic-layer/deploy-sl#related-docs "Direct link to Related docs") -------------------------------------------------------------------------------------------------------------------------- * [Optimize querying performance](https://docs.getdbt.com/docs/use-dbt-semantic-layer/sl-cache) using declarative caching. * [Validate semantic nodes in CI](https://docs.getdbt.com/docs/deploy/ci-jobs#semantic-validations-in-ci) to ensure code changes made to dbt models don't break these metrics. * If you haven't already, learn how to [build your metrics and semantic models](https://docs.getdbt.com/docs/build/build-metrics-intro) in your development tool of choice. Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Next steps](https://docs.getdbt.com/docs/use-dbt-semantic-layer/deploy-sl#next-steps) * [Related docs](https://docs.getdbt.com/docs/use-dbt-semantic-layer/deploy-sl#related-docs) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/use-dbt-semantic-layer/deploy-sl.md) --- # dbt Semantic Layer architecture | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/use-dbt-semantic-layer/sl-architecture#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page The Semantic Layer allows you to define metrics and use various interfaces to query them. The Semantic Layer does the heavy lifting to find where the queried data exists in your data platform and generates the SQL to make the request (including performing joins). [![This diagram shows how the dbt Semantic Layer works with your data stack.](https://docs.getdbt.com/img/docs/dbt-cloud/semantic-layer/sl-concept.png?v=2 "This diagram shows how the dbt Semantic Layer works with your data stack.")](https://docs.getdbt.com/docs/use-dbt-semantic-layer/sl-architecture#) This diagram shows how the dbt Semantic Layer works with your data stack. [![The diagram displays how your data flows using the dbt Semantic Layer and the variety of integration tools it supports.](https://docs.getdbt.com/img/docs/dbt-cloud/semantic-layer/sl-architecture.jpg?v=2 "The diagram displays how your data flows using the dbt Semantic Layer and the variety of integration tools it supports.")](https://docs.getdbt.com/docs/use-dbt-semantic-layer/sl-architecture#) The diagram displays how your data flows using the dbt Semantic Layer and the variety of integration tools it supports. Components[​](https://docs.getdbt.com/docs/use-dbt-semantic-layer/sl-architecture#components "Direct link to Components") -------------------------------------------------------------------------------------------------------------------------- The Semantic Layer includes the following components: | Components | Information | dbt Core users | Developer plans | Starter plans | Enterprise-tier plans | License | | --- | --- | --- | --- | --- | --- | --- | | **[MetricFlow](https://docs.getdbt.com/docs/build/about-metricflow)
** | MetricFlow in dbt allows users to centrally define their semantic models and metrics with YAML specifications. | ✅ | ✅ | ✅ | ✅ | BSL package (code is source available) | | **dbt Semantic interfaces** | A configuration spec for defining metrics, dimensions, how they link to each other, and how to query them. The [dbt-semantic-interfaces](https://github.com/dbt-labs/dbt-semantic-interfaces)
is available under Apache 2.0. | ❌ | ❌ | ✅ | ✅ | Proprietary, Cloud (Starter & Enterprise) | | **Service layer** | Coordinates query requests and dispatching the relevant metric query to the target query engine. This is provided through dbt and is available to all users on dbt version 1.6 or later. The service layer includes a Gateway service for executing SQL against the data platform. | ❌ | ❌ | ✅ | ✅ | Proprietary, Cloud (Starter, Enterprise, Enterprise+) | | **[Semantic Layer APIs](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-api-overview)
** | The interfaces allow users to submit metric queries using GraphQL and JDBC APIs. They also serve as the foundation for building first-class integrations with various tools. | ❌ | ❌ | ✅ | ✅ | Proprietary, Cloud (Starter, Enterprise, Enterprise+) | Feature comparison[​](https://docs.getdbt.com/docs/use-dbt-semantic-layer/sl-architecture#feature-comparison "Direct link to Feature comparison") -------------------------------------------------------------------------------------------------------------------------------------------------- The following table compares the features available in dbt and source available in dbt Core: | Feature | MetricFlow Source available | Semantic Layer with dbt | | --- | --- | --- | | Define metrics and semantic models in dbt using the MetricFlow spec | ✅ | ✅ | | Generate SQL from a set of config files | ✅ | ✅ | | Query metrics and dimensions through the command line interface (CLI) | ✅ | ✅ | | Query dimension, entity, and metric metadata through the CLI | ✅ | ✅ | | Query metrics and dimensions through semantic APIs (ADBC, GQL) | ❌ | ✅ | | Connect to downstream integrations (Tableau, Hex, Mode, Google Sheets, and so on.) | ❌ | ✅ | | Create and run Exports to save metrics queries as tables in your data platform. | ❌ | ✅ | Related docs[​](https://docs.getdbt.com/docs/use-dbt-semantic-layer/sl-architecture#related-docs "Direct link to Related docs") -------------------------------------------------------------------------------------------------------------------------------- * [Semantic Layer FAQs](https://docs.getdbt.com/docs/use-dbt-semantic-layer/sl-faqs) Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Components](https://docs.getdbt.com/docs/use-dbt-semantic-layer/sl-architecture#components) * [Feature comparison](https://docs.getdbt.com/docs/use-dbt-semantic-layer/sl-architecture#feature-comparison) * [Related docs](https://docs.getdbt.com/docs/use-dbt-semantic-layer/sl-architecture#related-docs) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/use-dbt-semantic-layer/sl-architecture.md) --- # Write queries with exports | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/use-dbt-semantic-layer/exports#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page Exports enhance [saved queries](https://docs.getdbt.com/docs/build/saved-queries) by running your saved queries and writing the output to a table or view within your data platform. Saved queries are a way to save and reuse commonly used queries in MetricFlow, exports take this functionality a step further by: * Enabling you to write these queries within your data platform using the dbt job scheduler. * Proving an integration path for tools that don't natively support the Semantic Layer by exposing tables of metrics and dimensions. Essentially, exports are like any other table in your data platform — they enable you to query metric definitions through any SQL interface or connect to downstream tools without a first-class [Semantic Layer integration](https://docs.getdbt.com/docs/cloud-integrations/avail-sl-integrations) . Running an export counts towards [queried metrics](https://docs.getdbt.com/docs/cloud/billing#what-counts-as-a-queried-metric) usage. Querying the resulting table or view from the export does not count toward queried metric usage. Prerequisites[​](https://docs.getdbt.com/docs/use-dbt-semantic-layer/exports#prerequisites "Direct link to Prerequisites") --------------------------------------------------------------------------------------------------------------------------- * You have a dbt account on a [Starter or Enterprise-tier](https://www.getdbt.com/pricing/) plan. * You use one of the following data platforms: Snowflake, BigQuery, Databricks, Redshift, or Postgres. * You are on [dbt version](https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-version-in-cloud) 1.7 or newer. * You have the Semantic Layer [configured](https://docs.getdbt.com/docs/use-dbt-semantic-layer/setup-sl) in your dbt project. * You have a dbt environment with the [job scheduler](https://docs.getdbt.com/docs/deploy/job-scheduler) enabled. * You have a [saved query](https://docs.getdbt.com/docs/build/saved-queries) and [export configured](https://docs.getdbt.com/docs/build/saved-queries#configure-exports) in your dbt project. In your configuration, leverage [caching](https://docs.getdbt.com/docs/use-dbt-semantic-layer/sl-cache) to cache common queries, speed up performance, and reduce compute costs. * You have the [dbt CLI](https://docs.getdbt.com/docs/cloud/cloud-cli-installation) installed. Note, that exports aren't supported in Studio IDE yet. Benefits of exports[​](https://docs.getdbt.com/docs/use-dbt-semantic-layer/exports#benefits-of-exports "Direct link to Benefits of exports") --------------------------------------------------------------------------------------------------------------------------------------------- The following section explains the main benefits of using exports:  DRY representation Currently, creating tables often involves generating tens, hundreds, or even thousands of tables that denormalize data into summary or metric mart tables. The main benefit of exports is creating a "Don't Repeat Yourself (DRY)" representation of the logic to construct each metric, dimension, join, filter, and so on. This allows you to reuse those components for long-term scalability, even if you're replacing manually written SQL models with references to the metrics or dimensions in saved queries. Easier changes Exports ensure that changes to metrics and dimensions are made in one place and then cascade to those various destinations seamlessly. This prevents the problem of needing to update a metric across every model that references that same concept. Caching Use exports to pre-populate the cache, so that you're pre-computing what you need to serve users through the dynamic Semantic Layer APIs. #### Considerations[​](https://docs.getdbt.com/docs/use-dbt-semantic-layer/exports#considerations "Direct link to Considerations") Exports offer many benefits and it's important to note some use cases that fall outside the advantages: * Business users may still struggle to consume from tens, hundreds, or thousands of tables, and choosing the right one can be a challenge. * Business users may also make mistakes when aggregating and filtering from the pre-built tables. For these use cases, use the dynamic [Semantic Layer APIs](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-api-overview) instead of exports. Run exports[​](https://docs.getdbt.com/docs/use-dbt-semantic-layer/exports#run-exports "Direct link to Run exports") --------------------------------------------------------------------------------------------------------------------- Before you're able to run exports in development or production, you'll need to make sure you've [configured saved queries and exports](https://docs.getdbt.com/docs/build/saved-queries) in your dbt project. In your saved query config, you can also leverage [caching](https://docs.getdbt.com/docs/use-dbt-semantic-layer/sl-cache) with the dbt job scheduler to cache common queries, speed up performance, and reduce compute costs. There are two ways to run an export: * [Run exports in development](https://docs.getdbt.com/docs/use-dbt-semantic-layer/exports#exports-in-development) using the [dbt CLI](https://docs.getdbt.com/docs/cloud/cloud-cli-installation) to test the output before production (You can configure exports in the Studio IDE, however running them directly in the Studio IDE isn't supported yet). * If you're using the Studio IDE, use `dbt build` to run exports. Make sure you have the [environment variable](https://docs.getdbt.com/docs/use-dbt-semantic-layer/exports#set-environment-variable) enabled. * [Run exports in production](https://docs.getdbt.com/docs/use-dbt-semantic-layer/exports#exports-in-production) using the [dbt job scheduler](https://docs.getdbt.com/docs/deploy/job-scheduler) to write these queries within your data platform. Exports in development[​](https://docs.getdbt.com/docs/use-dbt-semantic-layer/exports#exports-in-development "Direct link to Exports in development") ------------------------------------------------------------------------------------------------------------------------------------------------------ You can run an export in your development environment using your development credentials if you want to test the output of the export before production. This section explains the different commands and options available to run exports in development. * Use the [`dbt sl export` command](https://docs.getdbt.com/docs/use-dbt-semantic-layer/exports#exports-for-single-saved-query) to test and generate exports in your development environment for a singular saved query. You can also use the `--select` flag to specify particular exports from a saved query. * Use the [`dbt sl export-all` command](https://docs.getdbt.com/docs/use-dbt-semantic-layer/exports#exports-for-multiple-saved-queries) to run exports for multiple saved queries at once. This command provides a convenient way to manage and execute exports for several queries simultaneously, saving time and effort. * If you're using the Studio IDE, use `dbt build` to run exports. Make sure you have the [environment variable](https://docs.getdbt.com/docs/use-dbt-semantic-layer/exports#set-environment-variable) enabled before running the command. ### Exports for single saved query[​](https://docs.getdbt.com/docs/use-dbt-semantic-layer/exports#exports-for-single-saved-query "Direct link to Exports for single saved query") Use the following command to run exports in the dbt CLI: dbt sl export The following table lists the options for `dbt sl export` command, using the `--` flag prefix to specify the parameters: | Parameters | Type | Required | Description | | --- | --- | --- | --- | | `name` | String | Required | Name of the `export` object. | | `saved-query` | String | Required | Name of a saved query that could be used. | | `select` | List or String | Optional | Specify the names of exports to select from the saved query. | | `exclude` | String | Optional | Specify the names of exports to exclude from the saved query. | | `export_as` | String | Optional | Type of export to create from the `export_as` types available in the config. Options available are `table` or `view`. | | `schema` | String | Optional | Schema to use for creating the table or view. | | `alias` | String | Optional | Table alias to use to write the table or view. | You can also run any export defined for the saved query and write the table or view in your development environment. Refer to the following command example and output: dbt sl export --saved-query sq_name The output would look something like this: Polling for export status - query_id: 2c1W6M6qGklo1LR4QqzsH7ASGFs..Export completed. ### Use the select flag[​](https://docs.getdbt.com/docs/use-dbt-semantic-layer/exports#use-the-select-flag "Direct link to Use the select flag") You can have multiple exports for a saved query and by default, all exports are run for a saved query. You can use the `select` flag in [development](https://docs.getdbt.com/docs/use-dbt-semantic-layer/exports#exports-in-development) to select specific or multiple exports. Note, you can’t sub-select metrics or dimensions from the saved query, it’s just to change the export configuration i.e table format or schema For example, the following command runs `export_1` and `export_2` and doesn't work with the `--alias` or `--export_as` flags: dbt sl export --saved-query sq_name --select export_1,export2 Overriding export configurations The `--select` flag is mainly used to include or exclude specific exports. If you need to change these settings, you can use the following flags to override export configurations: * `--export-as` — Defines the materialization type (table or view) for the export. This creates a new export with its own settings and is useful for testing in development. * `--schema` — Specifies the schema to use for the written table or view. * `--alias` — Assigns a custom alias to the written table or view. This overrides the default export name. Be careful. The `--select` flag _can't_ be used with `alias` or `schema`. For example, you can use the following command to create a new export named `new_export` as a table: dbt sl export --saved-query sq_number1 --export-as table --alias new_export ### Exports for multiple saved queries[​](https://docs.getdbt.com/docs/use-dbt-semantic-layer/exports#exports-for-multiple-saved-queries "Direct link to Exports for multiple saved queries") Use the command, `dbt sl export-all`, to run exports for multiple saved queries at once. This is different from the `dbt sl export` command, which only runs exports for a singular saved query. For example, to run exports for multiple saved queries, you can use: dbt sl export-all The output would look something like this: Exports completed:- Created TABLE at `DBT_SL_TEST.new_customer_orders`- Created VIEW at `DBT_SL_TEST.new_customer_orders_export_alias`- Created TABLE at `DBT_SL_TEST.order_data_key_metrics`- Created TABLE at `DBT_SL_TEST.weekly_revenue`Polling completed The command `dbt sl export-all` provides the flexibility to manage multiple exports in a single command. Exports in production[​](https://docs.getdbt.com/docs/use-dbt-semantic-layer/exports#exports-in-production "Direct link to Exports in production") --------------------------------------------------------------------------------------------------------------------------------------------------- Enabling and executing exports in dbt optimizes data workflows and ensures real-time data access. It enhances efficiency and governance for smarter decisions. Exports use the default credentials of the production environment. To enable exports to run saved queries and write them within your data platform, perform the following steps: 1. [Set an environment variable](https://docs.getdbt.com/docs/use-dbt-semantic-layer/exports#set-environment-variable) in dbt. 2. [Create and execute export](https://docs.getdbt.com/docs/use-dbt-semantic-layer/exports#create-and-execute-exports) job run. ### Set environment variable[​](https://docs.getdbt.com/docs/use-dbt-semantic-layer/exports#set-environment-variable "Direct link to Set environment variable") 1. Click **Deploy** in the top navigation bar and choose **Environments**. 2. Select **Environment variables**. 3. [Set the environment variable](https://docs.getdbt.com/docs/build/environment-variables#setting-and-overriding-environment-variables) key to `DBT_EXPORT_SAVED_QUERIES` and the environment variable's value to `TRUE` (`DBT_EXPORT_SAVED_QUERIES=TRUE`). Doing this ensures saved queries and exports are included in your dbt build job. For example, running `dbt build -s sq_name` runs the equivalent of `dbt sl export --saved-query sq_name` in the dbt Job scheduler. If exports aren't needed, you can set the value(s) to `FALSE` (`DBT_EXPORT_SAVED_QUERIES=FALSE`). [![Add an environment variable to run exports in your production run.](https://docs.getdbt.com/img/docs/dbt-cloud/semantic-layer/env-var-dbt-exports.png?v=2 "Add an environment variable to run exports in your production run.")](https://docs.getdbt.com/docs/use-dbt-semantic-layer/exports#) Add an environment variable to run exports in your production run. When you run a build job, any saved queries downstream of the dbt models in that job will also run. To make sure your export data is up-to-date, run the export as a downstream step (after the model). ### Create and execute exports[​](https://docs.getdbt.com/docs/use-dbt-semantic-layer/exports#create-and-execute-exports "Direct link to Create and execute exports") 1. Create a [deploy job](https://docs.getdbt.com/docs/deploy/deploy-jobs) and ensure the `DBT_EXPORT_SAVED_QUERIES=TRUE` environment variable is set, as described in [Set environment variable](https://docs.getdbt.com/docs/use-dbt-semantic-layer/exports#set-environment-variable) . * This enables you to run any export that needs to be refreshed after a model is built. * Use the [selector syntax](https://docs.getdbt.com/reference/node-selection/syntax) `--select` or `-s` option in your build command to specify a particular dbt model or saved query to run. For example, to run all saved queries downstream of the `orders` semantic model, use the following command: dbt build --select orders+ 2. After dbt finishes building the models, the MetricFlow Server processes the exports, compiles the necessary SQL, and executes this SQL against your data platform. It directly executes a "create table" statement so the data stays within your data platform. 3. Review the exports' execution details in the jobs logs and confirm the export was run successfully. This helps troubleshoot and to ensure accuracy. Since saved queries are integrated into the dbt DAG, all outputs related to exports are available in the job logs. 4. Your data is now available in the data platform for querying! 🎉 FAQs[​](https://docs.getdbt.com/docs/use-dbt-semantic-layer/exports#faqs "Direct link to FAQs") ------------------------------------------------------------------------------------------------  Can I have multiple exports in a single saved query? Yes, this is possible. However, the difference would be the name, schema, and materialization strategy of the export.  How do I run all exports for a saved query? * In production runs, you can build the saved query by calling it directly in the build command, or you build a model and any exports downstream of that model. * In development, you can run all exports by running `dbt sl export --saved-query sq_name`.  Will I run duplicate exports if multiple models are downstream of my saved query? dbt will only run each export once even if it builds multiple models that are downstream of the saved query. For example, you could have a saved query called `order_metrics`, which has metrics from both the `orders` and `order_items` semantic models. You can run a job that includes both models using `dbt build`. This runs both the `orders` and `order_items` models, however, it will only run the `order_metrics` export once.  Can I reference an export as a dbt model using ref() No, you won't be able to reference an export using `ref`. Exports are treated as leaf nodes in your DAG. Modifying an export could lead to inconsistencies with the original metrics from the Semantic Layer.  How can I select saved\_queries by their resource type? To include all saved queries in the dbt build run, use the [`--resource-type` flag](https://docs.getdbt.com/reference/global-configs/resource-type) and run the command `dbt build --resource-type saved_query`. Related docs[​](https://docs.getdbt.com/docs/use-dbt-semantic-layer/exports#related-docs "Direct link to Related docs") ------------------------------------------------------------------------------------------------------------------------ * [Validate semantic nodes in a CI job](https://docs.getdbt.com/docs/deploy/ci-jobs#semantic-validations-in-ci) * Configure [caching](https://docs.getdbt.com/docs/use-dbt-semantic-layer/sl-cache) * [Semantic Layer FAQs](https://docs.getdbt.com/docs/use-dbt-semantic-layer/sl-faqs) Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Prerequisites](https://docs.getdbt.com/docs/use-dbt-semantic-layer/exports#prerequisites) * [Benefits of exports](https://docs.getdbt.com/docs/use-dbt-semantic-layer/exports#benefits-of-exports) * [Run exports](https://docs.getdbt.com/docs/use-dbt-semantic-layer/exports#run-exports) * [Exports in development](https://docs.getdbt.com/docs/use-dbt-semantic-layer/exports#exports-in-development) * [Exports for single saved query](https://docs.getdbt.com/docs/use-dbt-semantic-layer/exports#exports-for-single-saved-query) * [Use the select flag](https://docs.getdbt.com/docs/use-dbt-semantic-layer/exports#use-the-select-flag) * [Exports for multiple saved queries](https://docs.getdbt.com/docs/use-dbt-semantic-layer/exports#exports-for-multiple-saved-queries) * [Exports in production](https://docs.getdbt.com/docs/use-dbt-semantic-layer/exports#exports-in-production) * [Set environment variable](https://docs.getdbt.com/docs/use-dbt-semantic-layer/exports#set-environment-variable) * [Create and execute exports](https://docs.getdbt.com/docs/use-dbt-semantic-layer/exports#create-and-execute-exports) * [FAQs](https://docs.getdbt.com/docs/use-dbt-semantic-layer/exports#faqs) * [Related docs](https://docs.getdbt.com/docs/use-dbt-semantic-layer/exports#related-docs) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/use-dbt-semantic-layer/exports.md) --- # Cache common queries | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/use-dbt-semantic-layer/sl-cache#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page The Semantic Layer allows you to cache common queries in order to speed up performance and reduce compute on expensive queries. There are two different types of caching: * [Result caching](https://docs.getdbt.com/docs/use-dbt-semantic-layer/sl-cache#result-caching) leverages your data platform's built-in caching layer. * [Declarative caching](https://docs.getdbt.com/docs/use-dbt-semantic-layer/sl-cache#declarative-caching) allows you to pre-warm the cache using saved queries configuration. While you can use caching to speed up your queries and reduce compute time, knowing the difference between the two depends on your use case: * Result caching happens automatically by leveraging your data platform's cache. * Declarative caching allows you to 'declare' the queries you specifically want to cache. With declarative caching, you need to anticipate which queries you want to cache. * Declarative caching also allows you to dynamically filter your dashboards without losing the performance benefits of caching. This works because filters on dimensions (that are already in a saved query config) will use the cache. Prerequisites[​](https://docs.getdbt.com/docs/use-dbt-semantic-layer/sl-cache#prerequisites "Direct link to Prerequisites") ---------------------------------------------------------------------------------------------------------------------------- * dbt [Enterprise or Enterprise+](https://www.getdbt.com/) plans. * dbt environments must be on [release tracks](https://docs.getdbt.com/docs/dbt-versions/cloud-release-tracks) and not legacy dbt Core versions. * A successful job run and [production environment](https://docs.getdbt.com/docs/deploy/deploy-environments#set-as-production-environment) . * For declarative caching, you need to have [exports](https://docs.getdbt.com/docs/use-dbt-semantic-layer/exports) defined in your [saved queries](https://docs.getdbt.com/docs/build/saved-queries) YAML configuration file. Result caching[​](https://docs.getdbt.com/docs/use-dbt-semantic-layer/sl-cache#result-caching "Direct link to Result caching") ------------------------------------------------------------------------------------------------------------------------------- Result caching leverages your data platform’s built-in caching layer and features. [MetricFlow](https://docs.getdbt.com/docs/build/about-metricflow) generates the same SQL for multiple query requests, this means it can take advantage of your data platform’s cache. Double-check your data platform's specifications. Here's how caching works, using Snowflake as an example, and should be similar across other data platforms: 1. **Run from cold cache** — When you run a semantic layer query from your BI tool that hasn't been executed in the past 24 hours, the query scans the entire dataset and doesn't use the cache. 2. **Run from warm cache** — If you rerun the same query after 1 hour, the SQL generated and executed on Snowflake remains the same. On Snowflake, the result cache is set per user for 24 hours, which allows the repeated query to use the cache and return results faster. Different data platforms might have different caching layers and cache invalidation rules. Here's a list of resources on how caching works on some common data platforms: * [BigQuery](https://cloud.google.com/bigquery/docs/cached-results) * [DataBricks](https://docs.databricks.com/en/optimizations/disk-cache.html) * [Microsoft Fabric](https://learn.microsoft.com/en-us/fabric/data-warehouse/caching) * [Redshift](https://docs.aws.amazon.com/redshift/latest/dg/c_challenges_achieving_high_performance_queries.html#result-caching) * [Snowflake](https://community.snowflake.com/s/article/Caching-in-the-Snowflake-Cloud-Data-Platform) * [Starburst Galaxy](https://docs.starburst.io/starburst-galaxy/data-engineering/optimization-performance-and-quality/workload-optimization/warp-speed-enabled.html) Declarative caching[​](https://docs.getdbt.com/docs/use-dbt-semantic-layer/sl-cache#declarative-caching "Direct link to Declarative caching") ---------------------------------------------------------------------------------------------------------------------------------------------- Declarative caching enables you to pre-warm the cache using [saved queries](https://docs.getdbt.com/docs/build/saved-queries) by setting the cache config to `true` in your `saved_queries` settings. This is useful for optimizing performance for key dashboards or common ad-hoc query requests. tip Declarative caching also allows you to dynamically filter your dashboards without losing the performance benefits of caching. This works because filters on dimensions (that are already in a saved query config) will use the cache. For example, if you filter a metric by geographical region on a dashboard, the query will hit the cache, ensuring faster results. This also removes the need to create separate saved queries with static filters. For configuration details, refer to [Declarative caching setup](https://docs.getdbt.com/docs/use-dbt-semantic-layer/sl-cache#declarative-caching-setup) . How declarative caching works: * Make sure your saved queries YAML configuration file has [exports](https://docs.getdbt.com/docs/use-dbt-semantic-layer/exports) defined. * Running a saved query triggers the Semantic Layer to: * Build a cached table from a saved query, with exports defined, into your data platform. * Make sure any query requests that match the saved query's inputs use the cache, returning data more quickly. * Automatically invalidates the cache when it detects new and fresh data in any upstream models related to the metrics in your cached table. * Refreshes (or rebuilds) the cache the next time you run the saved query. 📹 Check out this video demo to see how declarative caching works! This video demonstrates the concept of declarative caching, how to run it using the dbt scheduler, and how fast your dashboards load as a result. Refer to the following diagram, which illustrates what happens when the Semantic Layer receives a query request: [![Overview of the declarative cache query flow](https://docs.getdbt.com/img/docs/dbt-cloud/semantic-layer/declarative-cache-query-flow.jpg?v=2 "Overview of the declarative cache query flow")](https://docs.getdbt.com/docs/use-dbt-semantic-layer/sl-cache#) Overview of the declarative cache query flow ### Declarative caching setup[​](https://docs.getdbt.com/docs/use-dbt-semantic-layer/sl-cache#declarative-caching-setup "Direct link to Declarative caching setup") To populate the cache, you need to configure an export in your saved query YAML file configuration _and_ set the `cache config` to `true`. You can't cache a saved query without an export defined. semantic\_model.yml saved_queries: - name: my_saved_query ... # Rest of the saved queries configuration. config: cache: enabled: true # Set to true to enable, defaults to false. exports: - name: order_data_key_metrics config: export_as: table To enable saved queries at the project level, you can set the `saved-queries` configuration in the [`dbt_project.yml` file](https://docs.getdbt.com/reference/dbt_project.yml) . This saves you time in configuring saved queries in each file: dbt\_project.yml saved-queries: my_saved_query: config: +cache: enabled: true ### Run your declarative cache[​](https://docs.getdbt.com/docs/use-dbt-semantic-layer/sl-cache#run-your-declarative-cache "Direct link to Run your declarative cache") After setting up declarative caching in your YAML configuration, you can now run [exports](https://docs.getdbt.com/docs/use-dbt-semantic-layer/exports) with the dbt job scheduler to build a cached table from a saved query into your data platform. * Use [exports to set up a job](https://docs.getdbt.com/docs/use-dbt-semantic-layer/exports) to run a saved query dbt. * The dbt Semantic Layer builds a cache table in your data platform in a dedicated `dbt_sl_cache` schema. * The cache schema and tables are created using your deployment credentials. You need to grant read access to this schema for your Semantic Layer user. * The cache refreshes (or rebuilds) on the same schedule as the saved query job. [![Overview of the cache creation flow.](https://docs.getdbt.com/img/docs/dbt-cloud/semantic-layer/cache-creation-flow.jpg?v=2 "Overview of the cache creation flow.")](https://docs.getdbt.com/docs/use-dbt-semantic-layer/sl-cache#) Overview of the cache creation flow. After a successful job run, you can go back to your dashboard to experience the speed and benefits of declarative caching. Cache management[​](https://docs.getdbt.com/docs/use-dbt-semantic-layer/sl-cache#cache-management "Direct link to Cache management") ------------------------------------------------------------------------------------------------------------------------------------- dbt uses the metadata from your dbt model runs to intelligently manage cache invalidation. When you start a dbt job, it keeps track of the last model runtime and checks the freshness of the metrics upstream of your cache. If an upstream model has data in it that was created after the cache was created, dbt invalidates the cache. This means queries won't use outdated cases and will instead query directly from the source data. Stale, outdated cache tables are periodically dropped and dbt will write a new cache the next time your saved query runs. You can manually invalidate the cache through the [dbt Semantic Layer APIs](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-api-overview) using the `InvalidateCacheResult` field. FAQs[​](https://docs.getdbt.com/docs/use-dbt-semantic-layer/sl-cache#faqs "Direct link to FAQs") -------------------------------------------------------------------------------------------------  How does caching interact with access controls? Cached data is stored separately from the underlying models. If metrics are pulled from the cache, we don’t have the security context applied to those tables at query time. In the future, we plan to clone credentials, identify the minimum access level needed, and apply those permissions to cached tables. Related docs[​](https://docs.getdbt.com/docs/use-dbt-semantic-layer/sl-cache#related-docs "Direct link to Related docs") ------------------------------------------------------------------------------------------------------------------------- * [Validate semantic nodes in CI](https://docs.getdbt.com/docs/deploy/ci-jobs#semantic-validations-in-ci) * [Saved queries](https://docs.getdbt.com/docs/build/saved-queries) * [Semantic Layer FAQs](https://docs.getdbt.com/docs/use-dbt-semantic-layer/sl-faqs) Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Prerequisites](https://docs.getdbt.com/docs/use-dbt-semantic-layer/sl-cache#prerequisites) * [Result caching](https://docs.getdbt.com/docs/use-dbt-semantic-layer/sl-cache#result-caching) * [Declarative caching](https://docs.getdbt.com/docs/use-dbt-semantic-layer/sl-cache#declarative-caching) * [Declarative caching setup](https://docs.getdbt.com/docs/use-dbt-semantic-layer/sl-cache#declarative-caching-setup) * [Run your declarative cache](https://docs.getdbt.com/docs/use-dbt-semantic-layer/sl-cache#run-your-declarative-cache) * [Cache management](https://docs.getdbt.com/docs/use-dbt-semantic-layer/sl-cache#cache-management) * [FAQs](https://docs.getdbt.com/docs/use-dbt-semantic-layer/sl-cache#faqs) * [Related docs](https://docs.getdbt.com/docs/use-dbt-semantic-layer/sl-cache#related-docs) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/use-dbt-semantic-layer/sl-cache.md) --- # About state-aware orchestration | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/deploy/state-aware-about#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page Every time a job runs, state-aware orchestration automatically determines which models to build by detecting changes in code or data. important The dbt Fusion Engine is currently available for installation in: * [Local command line interface (CLI) tools](https://docs.getdbt.com/docs/fusion/install-fusion-cli) [preview](https://docs.getdbt.com/docs/dbt-versions/product-lifecycles "Go to https://docs.getdbt.com/docs/dbt-versions/product-lifecycles") * [VS Code and Cursor with the dbt extension](https://docs.getdbt.com/docs/install-dbt-extension) [preview](https://docs.getdbt.com/docs/dbt-versions/product-lifecycles "Go to https://docs.getdbt.com/docs/dbt-versions/product-lifecycles") * [dbt platform environments](https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-version-in-cloud#dbt-fusion-engine) [beta](https://docs.getdbt.com/docs/dbt-versions/product-lifecycles "Go to https://docs.getdbt.com/docs/dbt-versions/product-lifecycles") Join the conversation in our Community Slack channel [`#dbt-fusion-engine`](https://getdbt.slack.com/archives/C088YCAB6GH) . Read the [Fusion Diaries](https://github.com/dbt-labs/dbt-fusion/discussions/categories/announcements) for the latest updates. State-aware orchestration saves you compute costs and reduces runtime because when a job runs, it checks for new records and only builds the models that will change. [![Fusion powered state-aware orchestration](https://docs.getdbt.com/img/docs/deploy/sao.gif?v=2 "Fusion powered state-aware orchestration")](https://docs.getdbt.com/docs/deploy/state-aware-about#) Fusion powered state-aware orchestration We built dbt's state-aware orchestration on these four core principles: * **Real-time shared state:** All jobs write to a real-time shared model-level state, allowing dbt to rebuild only changed models regardless of which jobs the model is built in. * **Model-level queueing:** Jobs queue up at the model-level so you can avoid any 'collisions' and prevent rebuilding models that were just updated by another job. * **State-aware and state agnostic support:** You can build jobs dynamically (state-aware) or explicitly (state-agnostic). Both approaches update shared state so everything is kept in sync. * **Sensible defaults:** State-aware orchestration works out-of-the-box (natively), with an optional configuration setting for more advanced controls. For more information, refer to [state-aware advanced configurations](https://docs.getdbt.com/docs/deploy/state-aware-setup#advanced-configurations) . Optimizing builds with state-aware orchestration[​](https://docs.getdbt.com/docs/deploy/state-aware-about#optimizing-builds-with-state-aware-orchestration "Direct link to Optimizing builds with state-aware orchestration") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ State-aware orchestration uses shared state tracking to determine which models need to be built by detecting changes in code or data every time a job runs. It also supports custom refresh intervals and custom source freshness configurations, so dbt only rebuilds models when they're actually needed. For example, you can configure your project so that dbt skips rebuilding the dim\_wizards model (and its parents) if they’ve already been refreshed within the last 4 hours, even if the job itself runs more frequently. Without configuring anything, dbt's state-aware orchestration automatically knows to build your models either when the code has changed or if there’s any new data in a source (or upstream model in the case of [dbt Mesh](https://docs.getdbt.com/docs/mesh/about-mesh) ). Related docs[​](https://docs.getdbt.com/docs/deploy/state-aware-about#related-docs "Direct link to Related docs") ------------------------------------------------------------------------------------------------------------------ * [State-aware orchestration configuration](https://docs.getdbt.com/docs/deploy/state-aware-setup) * [Artifacts](https://docs.getdbt.com/docs/deploy/artifacts) * [Continuous integration (CI) jobs](https://docs.getdbt.com/docs/deploy/ci-jobs) * [`freshness`](https://docs.getdbt.com/reference/resource-configs/freshness) Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Optimizing builds with state-aware orchestration](https://docs.getdbt.com/docs/deploy/state-aware-about#optimizing-builds-with-state-aware-orchestration) * [Related docs](https://docs.getdbt.com/docs/deploy/state-aware-about#related-docs) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/deploy/state-aware-about.md) --- # Continuous deployment in dbt | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/deploy/continuous-deployment#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page To help you improve data transformations and ship data products faster, you can run [merge jobs](https://docs.getdbt.com/docs/deploy/merge-jobs) to implement a continuous deployment (CD) workflow in dbt. Merge jobs can automatically build modified models whenever a pull request (PR) merges, making sure the latest code changes are in production. You don't have to wait for the next scheduled job to run to get the latest updates. [![Workflow of continuous deployment in dbt](https://docs.getdbt.com/img/docs/dbt-cloud/using-dbt-cloud/cd-workflow.png?v=2 "Workflow of continuous deployment in dbt")](https://docs.getdbt.com/docs/deploy/continuous-deployment#) Workflow of continuous deployment in dbt You can also implement continuous integration (CI) in dbt, which can help further to reduce the time it takes to push changes to production and improve code quality. To learn more, refer to [Continuous integration in dbt](https://docs.getdbt.com/docs/deploy/continuous-integration) . How merge jobs work[​](https://docs.getdbt.com/docs/deploy/continuous-deployment#how-merge-jobs-work "Direct link to How merge jobs work") ------------------------------------------------------------------------------------------------------------------------------------------- When you set up merge jobs, dbt listens for notifications from your [Git provider](https://docs.getdbt.com/docs/cloud/git/git-configuration-in-dbt-cloud) indicating that a PR has been merged. When dbt receives one of these notifications, it enqueues a new run of the merge job. You can set up merge jobs to perform one of the following when a PR merges: | Command to run | Usage description | | --- | --- | | `dbt build --select state:modified+` | (Default) Build the modified data with every merge.

dbt builds only the changed data models and anything downstream of it, similar to CI jobs. This helps reduce computing costs and ensures that the latest code changes are always pushed to production. | | `dbt compile` | Refresh the applied state for performant (the slimmest) CI job runs.

dbt generates the executable SQL (from the source model, test, and analysis files) but does not run it. This ensures the changes are reflected in the manifest for the next time a CI job is run and keeps track of only the relevant changes. | Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [How merge jobs work](https://docs.getdbt.com/docs/deploy/continuous-deployment#how-merge-jobs-work) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/deploy/continuous-deployment.md) --- # About continuous integration (CI) in dbt | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/deploy/about-ci#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) Use [CI jobs](https://docs.getdbt.com/docs/deploy/ci-jobs) in dbt to set up automation for testing code changes before merging to production. Additionally, [enable Advanced CI features](https://docs.getdbt.com/docs/cloud/account-settings#account-access-to-advanced-ci-features) for these jobs to evaluate whether the code changes are producing the appropriate data changes you want by reviewing the comparison differences dbt provides. Refer to the guide [Get started with continuous integration tests](https://docs.getdbt.com/guides/set-up-ci?step=1) for more information. [![](https://docs.getdbt.com/img/icons/dbt-bit.svg)\ \ #### Continuous integration\ \ Set up CI checks to test every single change prior to deploying the code to production.](https://docs.getdbt.com/docs/deploy/continuous-integration) [![](https://docs.getdbt.com/img/icons/dbt-bit.svg)\ \ #### Advanced CI\ \ Compare the differences between what's in the production environment and the pull request before merging those changes, ensuring that you're always shipping trusted data products.](https://docs.getdbt.com/docs/deploy/advanced-ci) Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 --- # Monitor jobs and alerts | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/deploy/monitor-jobs#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) Monitor your dbt jobs to help identify improvement and set up alerts to proactively alert the right people or team. This portion of our documentation will go over dbt's various capabilities that help you monitor your jobs and set up alerts to ensure seamless orchestration, including: * [Visualize and orchestrate downstream exposures](https://docs.getdbt.com/docs/deploy/orchestrate-exposures) [Enterprise](https://www.getdbt.com/pricing "Go to https://www.getdbt.com/pricing") [Enterprise +](https://www.getdbt.com/pricing "Go to https://www.getdbt.com/pricing") — Automatically visualize and orchestrate exposures from dashboards and proactively refresh the underlying data sources during scheduled dbt jobs. * [Leverage artifacts](https://docs.getdbt.com/docs/deploy/artifacts) — dbt generates and saves artifacts for your project, which it uses to power features like creating docs for your project and reporting freshness of your sources. * [Job notifications](https://docs.getdbt.com/docs/deploy/job-notifications) — Receive email or Slack notifications when a job run succeeds, encounters warnings, fails, or is canceled. * [Model notifications](https://docs.getdbt.com/docs/deploy/model-notifications) — Receive email notifications about any issues encountered by your models and tests as soon as they occur while running a job. * [Retry jobs](https://docs.getdbt.com/docs/deploy/retry-jobs) — Rerun your errored jobs from start or the failure point. * [Run visibility](https://docs.getdbt.com/docs/deploy/run-visibility) — View your run history to help identify where improvements can be made to scheduled jobs. * [Source freshness](https://docs.getdbt.com/docs/deploy/source-freshness) — Monitor data governance by enabling snapshots to capture the freshness of your data sources. * [Webhooks](https://docs.getdbt.com/docs/deploy/webhooks) — Use webhooks to send events about your dbt jobs' statuses to other systems. To set up and add data health tiles to view data freshness and quality checks in your dashboard, refer to [data health tiles](https://docs.getdbt.com/docs/explore/data-tile) . [![An overview of a dbt job run which contains run summary, job trigger, run duration, and more.](https://docs.getdbt.com/img/docs/dbt-cloud/deployment/deploy-scheduler.png?v=2 "An overview of a dbt job run which contains run summary, job trigger, run duration, and more.")](https://docs.getdbt.com/docs/deploy/monitor-jobs#) An overview of a dbt job run which contains run summary, job trigger, run duration, and more. [![Run history dashboard allows you to monitor the health of your dbt project and displays jobs, job status, environment, timing, and more.](https://docs.getdbt.com/img/docs/dbt-cloud/deployment/run-history.png?v=2 "Run history dashboard allows you to monitor the health of your dbt project and displays jobs, job status, environment, timing, and more.")](https://docs.getdbt.com/docs/deploy/monitor-jobs#) Run history dashboard allows you to monitor the health of your dbt project and displays jobs, job status, environment, timing, and more. [![Access logs for run steps](https://docs.getdbt.com/img/docs/dbt-cloud/deployment/access-logs.gif?v=2 "Access logs for run steps")](https://docs.getdbt.com/docs/deploy/monitor-jobs#) Access logs for run steps Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 --- # About Hybrid projects | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/deploy/hybrid-projects#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page With Hybrid projects, your organization can adopt complementary dbt Core and dbt workflows (where some teams develop projects in dbt Core and others in dbt) and seamlessly integrate these workflows by automatically uploading dbt Core [artifacts](https://docs.getdbt.com/reference/artifacts/dbt-artifacts) into dbt. Available in public preview Hybrid projects is available in public preview to [dbt Enterprise accounts](https://www.getdbt.com/pricing) . dbt Core users can seamlessly upload [artifacts](https://docs.getdbt.com/reference/artifacts/dbt-artifacts) like [run results.json](https://docs.getdbt.com/reference/artifacts/run-results-json) , [manifest.json](https://docs.getdbt.com/reference/artifacts/manifest-json) , [catalog.json](https://docs.getdbt.com/reference/artifacts/catalog-json) , [sources.json](https://docs.getdbt.com/reference/artifacts/sources-json) , and so on — into dbt after executing a run in the dbt Core command line interface (CLI), which helps: * Collaborate with dbt + dbt Core users by enabling them to visualize and perform [cross-project references](https://docs.getdbt.com/docs/mesh/govern/project-dependencies#how-to-write-cross-project-ref) to dbt models that live in Core projects. * (Coming soon) New users interested in the [Canvas](https://docs.getdbt.com/docs/cloud/canvas) can build off of dbt models already created by a central data team in dbt Core rather than having to start from scratch. * dbt Core and dbt users can navigate to [Catalog](https://docs.getdbt.com/docs/explore/explore-projects) and view their models and assets. To view Catalog, you must have a [read-only seat](https://docs.getdbt.com/docs/cloud/manage-access/seats-and-users) . Prerequisites[​](https://docs.getdbt.com/docs/deploy/hybrid-projects#prerequisites "Direct link to Prerequisites") ------------------------------------------------------------------------------------------------------------------- To upload artifacts, make sure you meet these prerequisites: * Your organization is on a [dbt Enterprise+ plan](https://www.getdbt.com/pricing) * You're on [dbt's release tracks](https://docs.getdbt.com/docs/dbt-versions/cloud-release-tracks) and your dbt Core project is on dbt v1.10 or higher * [Configured](https://docs.getdbt.com/docs/deploy/hybrid-setup#connect-project-in-dbt-cloud) a hybrid project in dbt. * Updated your existing dbt Core project with latest changes and [configured it with model access](https://docs.getdbt.com/docs/deploy/hybrid-setup#make-dbt-core-models-public) : * Ensure models that you want to share with other dbt projects use `access: public` in their model configuration. This makes the models more discoverable and shareable * Learn more about [access modifier](https://docs.getdbt.com/docs/mesh/govern/model-access#access-modifiers) and how to set the [`access` config](https://docs.getdbt.com/reference/resource-configs/access) * Update [dbt permissions](https://docs.getdbt.com/docs/cloud/manage-access/enterprise-permissions) to create a new project in dbt **Note:** Uploading artifacts doesn't count against dbt run slots. Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Prerequisites](https://docs.getdbt.com/docs/deploy/hybrid-projects#prerequisites) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/deploy/hybrid-projects.md) --- # Job commands | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/deploy/job-commands#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page A dbt production job allows you to set up a system to run a dbt job and job commands on a schedule, rather than running dbt commands manually from the command line or [Studio IDE](https://docs.getdbt.com/docs/cloud/dbt-cloud-ide/develop-in-the-cloud) . A job consists of commands that are "chained" together and executed as run steps. Each run step can succeed or fail, which may determine the job's run status (Success, Cancel, or Error). Each job allows you to: * Configure job commands * View job run details, including timing, artifacts, and detailed run steps * Access logs to view or help debug issues and historical invocations of dbt * Set up notifications, and [more](https://docs.getdbt.com/docs/deploy/deployments#dbt-cloud) Job command types[​](https://docs.getdbt.com/docs/deploy/job-commands#job-command-types "Direct link to Job command types") ---------------------------------------------------------------------------------------------------------------------------- Job commands are specific tasks executed by the job, and you can configure them seamlessly by either adding [dbt commands](https://docs.getdbt.com/reference/dbt-commands) or using the checkbox option in the **Commands** section. During a job run, the commands are "chained" together and executed as run steps. When you add a dbt command in the **Commands** section, you can expect different outcomes compared to the checkbox option. [![Configuring checkbox and commands list](https://docs.getdbt.com/img/docs/dbt-cloud/using-dbt-cloud/job-commands.gif?v=2 "Configuring checkbox and commands list")](https://docs.getdbt.com/docs/deploy/job-commands#) Configuring checkbox and commands list ### Built-in commands[​](https://docs.getdbt.com/docs/deploy/job-commands#built-in-commands "Direct link to Built-in commands") Every job invocation automatically includes the [`dbt deps`](https://docs.getdbt.com/reference/commands/deps) command, meaning you don't need to add it to the **Commands** list in your job settings. You will also notice every job will include a run step to reclone your repository and connect to your data platform, which can affect your job status if these run steps aren't successful. **Job outcome** — During a job run, the built-in commands are "chained" together. This means if one of the run steps in the chain fails, then the next commands aren't executed, and the entire job fails with an "Error" job status. [![A failed job that had an error during the dbt deps run step.](https://docs.getdbt.com/img/docs/dbt-cloud/using-dbt-cloud/fail-dbtdeps.png?v=2 "A failed job that had an error during the dbt deps run step.")](https://docs.getdbt.com/docs/deploy/job-commands#) A failed job that had an error during the dbt deps run step. ### Checkbox commands[​](https://docs.getdbt.com/docs/deploy/job-commands#checkbox-commands "Direct link to Checkbox commands") For every job, you have the option to select the [Generate docs on run](https://docs.getdbt.com/docs/explore/build-and-view-your-docs) or [Run source freshness](https://docs.getdbt.com/docs/deploy/source-freshness) checkboxes, enabling you to run the commands automatically. **Job outcome Generate docs on run checkbox** — dbt executes the `dbt docs generate` command, _after_ the listed commands. If that particular run step in your job fails, the job can still succeed if all subsequent run steps are successful. Read [Set up documentation job](https://docs.getdbt.com/docs/explore/build-and-view-your-docs) for more info. **Job outcome Source freshness checkbox** — dbt executes the `dbt source freshness` command as the first run step in your job. If that particular run step in your job fails, the job can still succeed if all subsequent run steps are successful. Read [Source freshness](https://docs.getdbt.com/docs/deploy/source-freshness) for more info. ### Command list[​](https://docs.getdbt.com/docs/deploy/job-commands#command-list "Direct link to Command list") You can add or remove as many dbt commands as necessary for every job. However, you need to have at least one dbt command. There are few commands listed as "dbt CLI" or "dbt Core" in the [dbt Command reference page](https://docs.getdbt.com/reference/dbt-commands) page. This means they are meant for use in dbt Core or dbt CLI, and not in Studio IDE. Using selectors Use [selectors](https://docs.getdbt.com/reference/node-selection/syntax) as a powerful way to select and execute portions of your project in a job run. For example, to run tests for `one_specific_model`, use the selector: `dbt test --select one_specific_model`. The job will still run if a selector doesn't match any models. #### Compare changes custom commands[​](https://docs.getdbt.com/docs/deploy/job-commands#compare-changes-custom-commands "Direct link to Compare changes custom commands") For users that have Advanced CI's [compare changes](https://docs.getdbt.com/docs/deploy/advanced-ci#compare-changes) feature enabled and selected the **dbt compare** checkbox, you can add custom dbt commands to optimize running the comparison (for example, to exclude specific large models, or groups of models with tags). Running comparisons on large models can significantly increase the time it takes for CI jobs to complete. [![Add custom dbt commands to when using dbt compare.](https://docs.getdbt.com/img/docs/deploy/dbt-compare.jpg?v=2 "Add custom dbt commands to when using dbt compare.")](https://docs.getdbt.com/docs/deploy/job-commands#) Add custom dbt commands to when using dbt compare. The following examples highlight how you can customize the dbt compare command box: * Exclude the large `fct_orders` model from the comparison to run a CI job on fewer or smaller models and reduce job time/resource consumption. Use the following command: --select state:modified --exclude fct_orders * Exclude models based on tags for scenarios like when models share a common feature or function. Use the following command: --select state modified --exclude tag:tagname_a tag:tagname_b * Include models that were directly modified and also those one step downstream using the `modified+1` selector. Use the following command: --select state:modified+1 #### Job outcome[​](https://docs.getdbt.com/docs/deploy/job-commands#job-outcome "Direct link to Job outcome") During a job run, the commands are "chained" together and executed as run steps. If one of the run steps in the chain fails, then the subsequent steps aren't executed, and the job will fail. In the following example image, the first four run steps are successful. However, if the fifth run step (`dbt run --select state:modified+ --full-refresh --fail-fast`) fails, then the next run steps aren't executed, and the entire job fails. The failed job returns a non-zero [exit code](https://docs.getdbt.com/reference/exit-codes) and "Error" job status: [![A failed job run that had an error during a run step](https://docs.getdbt.com/img/docs/dbt-cloud/using-dbt-cloud/skipped-jobs.png?v=2 "A failed job run that had an error during a run step")](https://docs.getdbt.com/docs/deploy/job-commands#) A failed job run that had an error during a run step Job command failures[​](https://docs.getdbt.com/docs/deploy/job-commands#job-command-failures "Direct link to Job command failures") ------------------------------------------------------------------------------------------------------------------------------------- Job command failures can mean different things for different commands. Some common reasons why a job command may fail: * **Failure at`dbt run`** — [`dbt run`](https://docs.getdbt.com/reference/commands/run) executes compiled SQL model files against the current target database. It will fail if there is an error in any of the built models. Tests on upstream resources prevent downstream resources from running and a failed test will skip them. * **Failure at `dbt test`** — [`dbt test`](https://docs.getdbt.com/reference/commands/test) runs tests defined on models, sources, snapshots, and seeds. A test can pass, fail, or warn depending on its [severity](https://docs.getdbt.com/reference/resource-configs/severity) . Unless you set [warnings as errors](https://docs.getdbt.com/reference/global-configs/warnings) , only an error stops the next step. * **Failure at `dbt build`** — [`dbt build`](https://docs.getdbt.com/reference/commands/build) runs models, tests, snapshots, and seeds. This command executes resources in the DAG-specified order. If any upstream resource fails, all downstream resources are skipped, and the command exits with an error code of 1. * **Selector failures** * If a [`select`](https://docs.getdbt.com/reference/node-selection/set-operators) matches multiple nodes and one of the nodes fails, then the job will have an exit code `1` and the subsequent command will fail. If you specified the [`—fail-fast`](https://docs.getdbt.com/reference/global-configs/failing-fast) flag, then the first failure will stop the entire connection for any models that are in progress. * If a selector doesn't match any nodes, it's not considered a failure. Related docs[​](https://docs.getdbt.com/docs/deploy/job-commands#related-docs "Direct link to Related docs") ------------------------------------------------------------------------------------------------------------- * [Job creation best practices](https://discourse.getdbt.com/t/job-creation-best-practices-in-dbt-cloud-feat-my-moms-lasagna/2980) * [dbt Command reference](https://docs.getdbt.com/reference/dbt-commands) * [Job notifications](https://docs.getdbt.com/docs/deploy/job-notifications) * [Source freshness](https://docs.getdbt.com/docs/deploy/source-freshness) * [Build and view your docs](https://docs.getdbt.com/docs/explore/build-and-view-your-docs) Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Job command types](https://docs.getdbt.com/docs/deploy/job-commands#job-command-types) * [Built-in commands](https://docs.getdbt.com/docs/deploy/job-commands#built-in-commands) * [Checkbox commands](https://docs.getdbt.com/docs/deploy/job-commands#checkbox-commands) * [Command list](https://docs.getdbt.com/docs/deploy/job-commands#command-list) * [Job command failures](https://docs.getdbt.com/docs/deploy/job-commands#job-command-failures) * [Related docs](https://docs.getdbt.com/docs/deploy/job-commands#related-docs) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/deploy/job-commands.md) --- # Visualize and orchestrate exposures | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/deploy/orchestrate-exposures#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) The following table summarizes the differences between visualizing and orchestrating downstream exposures: | Info | Set up and visualize downstream exposures | Orchestrate downstream exposures [beta](https://docs.getdbt.com/docs/dbt-versions/product-lifecycles "Go to https://docs.getdbt.com/docs/dbt-versions/product-lifecycles") | | --- | --- | --- | | Purpose | Automatically brings downstream assets into your dbt lineage. | Proactively refreshes the underlying data sources during scheduled dbt jobs. | | Benefits | Provides visibility into data flow and dependencies. | Ensures BI tools always have up-to-date data without manual intervention. | | Location | Exposed in dbt [Catalog](https://docs.getdbt.com/docs/explore/explore-projects) | Exposed in [dbt scheduler](https://docs.getdbt.com/docs/deploy/deployments) | | Supported BI tool | Tableau | Tableau | | Use case | Helps users understand how models are used and reduces incidents. | Optimizes timeliness and reduces costs by running models when needed. | Check out the following sections for more information on visualizing and orchestrating downstream exposures: [![](https://docs.getdbt.com/img/icons/dbt-bit.svg)\ \ #### Set up and visualize downstream exposures\ \ Set up downstream exposures automatically from dashboards to understand how models are used in downstream tools for a richer downstream lineage.](https://docs.getdbt.com/docs/cloud-integrations/downstream-exposures-tableau) [![](https://docs.getdbt.com/img/icons/dbt-bit.svg)\ \ #### Orchestrate downstream exposures\ \ Proactively refreshes the underlying data sources (like Tableau extracts) using the dbt scheduler during scheduled dbt jobs.](https://docs.getdbt.com/docs/cloud-integrations/orchestrate-exposures) Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 --- # Model notifications | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/deploy/model-notifications#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page Set up dbt to notify model owners through email about issues in your deployment environments. Configure dbt to send email notifications to model owners about issues in deployment [environments](https://docs.getdbt.com/docs/dbt-cloud-environments#types-of-environments) as soon as they happen — while the job is still running. Model owners can specify which statuses to receive notifications about: * `Success` and `Fails` for models * `Warning`, `Success`, and `Fails` for tests With model-level notifications, model owners can be the first ones to know about issues before anyone else (like the stakeholders). To be timely and keep the number of notifications to a reasonable amount when multiple models or tests trigger them, dbt observes the following guidelines when notifying the owners: * Send a notification to each unique owner/email during a job run about any models (with status of failure/success) or tests (with status of warning/failure/success). Each owner receives only one notification, the initial one. * No notifications sent about subsequent models or tests while a dbt job is still running. * Each owner/user who subscribes to notifications for one or more statuses (like failure, success, warning) will receive only _one_ email notification at the end of the job run. * The email includes a consolidated list of all models or tests that match the statuses the user subscribed to, instead of sending separate emails for each status. Create configuration YAML files in your project for dbt to send notifications about the status of your models and tests in your deployment environments. Prerequisites[​](https://docs.getdbt.com/docs/deploy/model-notifications#prerequisites "Direct link to Prerequisites") ----------------------------------------------------------------------------------------------------------------------- * Your dbt administrator has [enabled the appropriate account setting](https://docs.getdbt.com/docs/deploy/model-notifications#enable-access-to-model-notifications) for you. * Your deployment environment(s) must be on a [release track](https://docs.getdbt.com/docs/dbt-versions/cloud-release-tracks) instead of a legacy dbt Core version. Configure groups[​](https://docs.getdbt.com/docs/deploy/model-notifications#configure-groups "Direct link to Configure groups") -------------------------------------------------------------------------------------------------------------------------------- Define your [groups](https://docs.getdbt.com/docs/build/groups) in any `.yml` file in your [models directory](https://docs.getdbt.com/reference/project-configs/model-paths) . Each group's owner can now specify one or multiple email addresses to receive model-level notifications. The `email` field supports a single email address as a string or a list of multiple email addresses. The following example shows how to define groups in a `groups.yml` file. models/groups.yml version: 2groups: - name: finance owner: # Email is required to receive model-level notifications, additional properties are also allowed. name: "Finance team" email: finance@dbtlabs.com favorite_food: donuts - name: marketing owner: name: "Marketing team" email: marketing@dbtlabs.com favorite_food: jaffles# Example of multiple emails supported - name: docs owner: name: "Documentation team" email: - docs@dbtlabs.com - community@dbtlabs.com - product@dbtlabs.com favorite_food: pizza tip The `owner` key is flexible and accepts arbitrary inputs in addition to the required `email` field. For example, you could include a custom field like `favorite_food` to add context about the team. Attach groups to models[​](https://docs.getdbt.com/docs/deploy/model-notifications#attach-groups-to-models "Direct link to Attach groups to models") ----------------------------------------------------------------------------------------------------------------------------------------------------- Attach groups to models as you would any other config, in either the `dbt_project.yml` or `whatever.yml` files. For example: models/marts.yml version: 2models: - name: sales description: "Sales data model" config: group: finance - name: campaigns description: "Campaigns data model" config: group: marketing By assigning groups in the `dbt_project.yml` file, you can capture all models in a subdirectory at once. In this example, model notifications related to staging models go to the data engineering group, `marts/sales` models to the finance team, and `marts/campaigns` models to the marketing team. dbt\_project.yml config-version: 2name: "jaffle_shop"[...]models: jaffle_shop: staging: +group: data_engineering marts: sales: +group: finance campaigns: +group: marketing Attaching a group to a model also encompasses its tests, so you will also receive notifications for a model's test failures. Enable access to model notifications[​](https://docs.getdbt.com/docs/deploy/model-notifications#enable-access-to-model-notifications "Direct link to Enable access to model notifications") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Provide dbt account members the ability to configure and receive alerts about issues with models or tests that are encountered during job runs. To use model-level notifications, your dbt account must have access to the feature. Ask your dbt administrator to enable this feature for account members by following these steps: 1. Navigate to **Notification settings** from your profile name in the sidebar (lower left-hand side). 2. From **Email notifications**, enable the setting **Enable group/owner notifications on models** under the **Model notifications** section. Then, specify which statuses to receive notifications about (Success, Warning, and/or Fails). [![Example of the setting Enable group/owner notifications on models](https://docs.getdbt.com/img/docs/dbt-cloud/example-enable-model-notifications.png?v=2 "Example of the setting Enable group/owner notifications on models")](https://docs.getdbt.com/docs/deploy/model-notifications#) Example of the setting Enable group/owner notifications on models 3. Click **Save**. Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Prerequisites](https://docs.getdbt.com/docs/deploy/model-notifications#prerequisites) * [Configure groups](https://docs.getdbt.com/docs/deploy/model-notifications#configure-groups) * [Attach groups to models](https://docs.getdbt.com/docs/deploy/model-notifications#attach-groups-to-models) * [Enable access to model notifications](https://docs.getdbt.com/docs/deploy/model-notifications#enable-access-to-model-notifications) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/deploy/model-notifications.md) --- # Retry your dbt jobs | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/deploy/retry-jobs#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page If your dbt job run completed with a status of **Error**, you can rerun it from start or from the point of failure in dbt. Prerequisites[​](https://docs.getdbt.com/docs/deploy/retry-jobs#prerequisites "Direct link to Prerequisites") -------------------------------------------------------------------------------------------------------------- * You have a [dbt account](https://www.getdbt.com/signup) . * You must be using [dbt version](https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-version-in-cloud) 1.6 or newer. * dbt can successfully parse the project and generate a [manifest](https://docs.getdbt.com/reference/artifacts/manifest-json) * The most recent run of the job hasn't completed successfully. The latest status of the run is **Error**. * The job command that failed in the run must be one that supports the [retry command](https://docs.getdbt.com/reference/commands/retry) . Rerun an errored job[​](https://docs.getdbt.com/docs/deploy/retry-jobs#rerun-an-errored-job "Direct link to Rerun an errored job") ----------------------------------------------------------------------------------------------------------------------------------- 1. Select **Deploy** from the top navigation bar and choose **Run History.** 2. Choose the job run that has errored. 3. In the **Run Summary** tab on the job’s **Run** page, expand the run step that failed. An ❌ denotes the failed step. 4. Examine the error message and determine how to fix it. After you have made your changes, save and commit them to your [Git repo](https://docs.getdbt.com/docs/cloud/git/git-version-control) . 5. Return to your job’s **Run** page. In the upper right corner, click **Rerun** and choose **Rerun from start** or **Rerun from failure**. If you chose to rerun from the failure point, a **Rerun failed steps** modal opens. The modal lists the run steps that will be invoked: the failed step and any skipped steps. To confirm these run steps, click **Rerun from failure**. The job reruns from the failed command in the previously failed run. A banner at the top of the **Run Summary** tab captures this with the message, "This run resumed execution from last failed step". [![Example of the Rerun options in dbt](https://docs.getdbt.com/img/docs/deploy/native-retry.gif?v=2 "Example of the Rerun options in dbt")](https://docs.getdbt.com/docs/deploy/retry-jobs#) Example of the Rerun options in dbt Related content[​](https://docs.getdbt.com/docs/deploy/retry-jobs#related-content "Direct link to Related content") -------------------------------------------------------------------------------------------------------------------- * [Retry a failed run for a job](https://docs.getdbt.com/dbt-cloud/api-v2#/operations/Retry%20Failed%20Job) API endpoint * [Run visibility](https://docs.getdbt.com/docs/deploy/run-visibility) * [Jobs](https://docs.getdbt.com/docs/deploy/jobs) * [Job commands](https://docs.getdbt.com/docs/deploy/job-commands) Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Prerequisites](https://docs.getdbt.com/docs/deploy/retry-jobs#prerequisites) * [Rerun an errored job](https://docs.getdbt.com/docs/deploy/retry-jobs#rerun-an-errored-job) * [Related content](https://docs.getdbt.com/docs/deploy/retry-jobs#related-content) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/deploy/retry-jobs.md) --- # Navigate the dbt Insights interface | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/explore/navigate-dbt-insights#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page Learn how to navigate Insights interface and use the main components. Insights provides an interactive interface for writing, running, and analyzing SQL queries. This section highlights the main components of Insights. Query console[​](https://docs.getdbt.com/docs/explore/navigate-dbt-insights#query-console "Direct link to Query console") -------------------------------------------------------------------------------------------------------------------------- The query console is the main component of Insights. It allows you to write, run, and analyze SQL queries. The Query console supports: * Query console editor, which allows you to write, run, and analyze SQL queries: * It supports syntax highlighting and autocomplete suggestions * Hyperlink from SQL code `ref` to the corresponding Explorer page * [Query console menu](https://docs.getdbt.com/docs/explore/navigate-dbt-insights#query-console-menu) , which contains **Bookmark (icon)**, **Develop**, and **Run** buttons. * [Query output panel](https://docs.getdbt.com/docs/explore/navigate-dbt-insights#query-output-panel) , below the query editor and displays the results of a query: * Has three tabs: **Results**, **Details**, and **Chart**, which allow you to analyze query execution and visualize results. * [Query console sidebar menu](https://docs.getdbt.com/docs/explore/navigate-dbt-insights#query-console-sidebar-menu) , which contains the **Catalog**, **Bookmark**, **Query history**, and **Copilot** icons. [![dbt Insights main interface with blank query editor](https://docs.getdbt.com/img/docs/dbt-insights/insights-main.png?v=2 "dbt Insights main interface with blank query editor")](https://docs.getdbt.com/docs/explore/navigate-dbt-insights#) dbt Insights main interface with blank query editor ### Query console menu[​](https://docs.getdbt.com/docs/explore/navigate-dbt-insights#query-console-menu "Direct link to Query console menu") The Query console menu is located at the top right of the Query editor. It contains the **Bookmark**, **Develop**, and **Run** buttons: * **Bookmark** button — Save your frequently used SQL queries as favorites for easier access. * When you click **Bookmark**, a **Bookmark Query Details** modal (pop up box) will appear where you can add a **Title** and **Description**. * Let [Copilot](https://docs.getdbt.com/docs/cloud/dbt-copilot) do the writing for you — use the AI assistant to automatically generate a helpful description for your bookmark. * Access the newly created bookmark from the **Bookmark** icon in the [Query console sidebar menu](https://docs.getdbt.com/docs/explore/navigate-dbt-insights#query-console-sidebar-menu) . * **Develop**: Open the [Studio IDE](https://docs.getdbt.com/docs/cloud/dbt-cloud-ide/develop-in-the-cloud) or [Canvas](https://docs.getdbt.com/docs/cloud/canvas) to continue editing your SQL query. * **Run** button — Run your SQL query and view the results in the **Results** tab. [![dbt Insights Develop menu.](https://docs.getdbt.com/img/docs/dbt-insights/develop-menu.png?v=2 "dbt Insights Develop menu.")](https://docs.getdbt.com/docs/explore/navigate-dbt-insights#) dbt Insights Develop menu. Query output panel[​](https://docs.getdbt.com/docs/explore/navigate-dbt-insights#query-output-panel "Direct link to Query output panel") ----------------------------------------------------------------------------------------------------------------------------------------- The Query output panel is below the query editor and displays the results of a query. It displays the following tabs to analyze query execution and visualize results: * **Results** tab — Preview your SQL results, with results paginated. * **Details** tab — Generates succinct details of executed SQL query: * Query metadata — Copilot's AI-generated title and description. Along with the supplied SQL and compiled SQL. * Connection details — Relevant data platform connection information. * Query details — Query duration, status, column count, row count. * **Chart** tab — Visualizes query results with built-in charts. * Use the chart icon to select the type of chart you want to visualize your results. Available chart types are **line chart, bar chart, or scatterplot**. * Use the **Chart settings** to customize the chart type and the columns you want to visualize. * Available chart types are **line chart, bar chart, or scatterplot**. * **Download** button — Allows you to export the results to CSV [![dbt Insights Results tab](https://docs.getdbt.com/img/docs/dbt-insights/insights-results.png?v=2 "dbt Insights Results tab")](https://docs.getdbt.com/docs/explore/navigate-dbt-insights#) dbt Insights Results tab [![dbt Insights Details tab](https://docs.getdbt.com/img/docs/dbt-insights/insights-details.png?v=2 "dbt Insights Details tab")](https://docs.getdbt.com/docs/explore/navigate-dbt-insights#) dbt Insights Details tab [![dbt Insights Chart tab](https://docs.getdbt.com/img/docs/dbt-insights/insights-chart.png?v=2 "dbt Insights Chart tab")](https://docs.getdbt.com/docs/explore/navigate-dbt-insights#) dbt Insights Chart tab Query console sidebar menu[​](https://docs.getdbt.com/docs/explore/navigate-dbt-insights#query-console-sidebar-menu "Direct link to Query console sidebar menu") ----------------------------------------------------------------------------------------------------------------------------------------------------------------- The Query console sidebar menu and icons contains the following options: * **Catalog icon** — View your project's models, columns, metrics, and more using the integrated Catalog view. * **Bookmark icon** — Save and access your frequently used queries. * **Query history icon** — View past queries, their statuses (All, Success, Error, or Pending), start time, and duration. Search for past queries and filter by status. You can also re-run a query from the Query history. * **Copilot icon** — Use [Copilot's AI assistant](https://docs.getdbt.com/docs/cloud/dbt-copilot) to modify or generate queries using natural language prompts. [![dbt Insights dbt Catalog icon](https://docs.getdbt.com/img/docs/dbt-insights/insights-explorer.png?v=2 "dbt Insights dbt Catalog icon")](https://docs.getdbt.com/docs/explore/navigate-dbt-insights#) dbt Insights dbt Catalog icon [![dbt Insights Query history icon](https://docs.getdbt.com/img/docs/dbt-insights/insights-query-history.png?v=2 "dbt Insights Query history icon")](https://docs.getdbt.com/docs/explore/navigate-dbt-insights#) dbt Insights Query history icon [![dbt Insights dbt Copilot](https://docs.getdbt.com/img/docs/dbt-insights/insights-copilot.png?v=2 "dbt Insights dbt Copilot")](https://docs.getdbt.com/docs/explore/navigate-dbt-insights#) dbt Insights dbt Copilot [![Manage your query bookmarks](https://docs.getdbt.com/img/docs/dbt-insights/manage-bookmarks.png?v=2 "Manage your query bookmarks")](https://docs.getdbt.com/docs/explore/navigate-dbt-insights#) Manage your query bookmarks Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Query console](https://docs.getdbt.com/docs/explore/navigate-dbt-insights#query-console) * [Query console menu](https://docs.getdbt.com/docs/explore/navigate-dbt-insights#query-console-menu) * [Query output panel](https://docs.getdbt.com/docs/explore/navigate-dbt-insights#query-output-panel) * [Query console sidebar menu](https://docs.getdbt.com/docs/explore/navigate-dbt-insights#query-console-sidebar-menu) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/explore/navigate-dbt-insights.md) --- # Model query history | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/explore/model-query-history#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page Model query history helps data teams track model usage by analyzing query logs. Model query history allows you to: * View the count of consumption queries for a model based on the data warehouse's query logs. * Provides data teams insight, so they can focus their time and infrastructure spend on the worthwhile used data products. * Enable analysts to find the most popular models used by other people. Model query history is powered by a single consumption query of the query log table in your data warehouse aggregated on a daily basis.  What is a consumption query? Consumption query is a metric of queries in your dbt project that has used the model in a given time. It filters down to `select` statements only to gauge model consumption and excludes dbt model build and test executions. So for example, if `model_super_santi` was queried 10 times in the past week, it would count as having 10 consumption queries for that particular time period. Support for Snowflake (Enterprise tier or higher) and BigQuery Model query history for Snowflake users is **only available for Enterprise tier or higher**. The feature also supports BigQuery. Additional platforms coming soon. Prerequisites[​](https://docs.getdbt.com/docs/explore/model-query-history#prerequisites "Direct link to Prerequisites") ------------------------------------------------------------------------------------------------------------------------ To access the features, you should meet the following: 1. You have a dbt account on an [Enterprise-tier plan](https://www.getdbt.com/pricing/) . Single-tenant accounts should contact their account representative for setup. 2. You have set up a [production](https://docs.getdbt.com/docs/deploy/deploy-environments#set-as-production-environment)  deployment environment for each project you want to explore, with at least one successful job run. 3. You have [admin permissions](https://docs.getdbt.com/docs/cloud/manage-access/enterprise-permissions) in dbt to edit project settings or production environment settings. 4. Use Snowflake or BigQuery as your data warehouse and can enable [query history permissions](https://docs.getdbt.com/docs/explore/model-query-history#snowflake-model-query-history) or work with an admin to do so. Support for additional data platforms coming soon. * For Snowflake users: You **must** have a Snowflake Enterprise tier or higher subscription. Enable query history in dbt[​](https://docs.getdbt.com/docs/explore/model-query-history#enable-query-history-in-dbt "Direct link to Enable query history in dbt") ------------------------------------------------------------------------------------------------------------------------------------------------------------------ To enable model query history in dbt, follow these steps: 1. Navigate to **Deploy** and then **Environments**. 2. Select the environment marked **PROD** and click **Settings**. 3. Click **Edit** and scroll to the **Query History** section to enable the query history toggle. When it’s green and to the right, it's enabled. 4. Click the **Test Permissions** button to validate the deployment credentials permissions are sufficient to support query history. 5. dbt automatically enables query history for brand new environments. If query history fails to retrieve data, dbt automatically disables it to prevent unintended warehouse costs. * If the failure is temporary (like a network timeout), dbt may retry. * If the issue is permanent (like a missing permissions), dbt disables query history immediately. To re-enable it, please reach out to [dbt Support](mailto:support@getdbt.com) . [![Enable query history in your environment settings.](https://docs.getdbt.com/img/docs/collaborate/dbt-explorer/enable-query-history.jpg?v=2 "Enable query history in your environment settings.")](https://docs.getdbt.com/docs/explore/model-query-history#) Enable query history in your environment settings. [![Example of permissions verified result after clicking Test Permissions.](https://docs.getdbt.com/img/docs/collaborate/dbt-explorer/enable-query-history-success.jpg?v=2 "Example of permissions verified result after clicking Test Permissions.")](https://docs.getdbt.com/docs/explore/model-query-history#) Example of permissions verified result after clicking Test Permissions. Credential permissions[​](https://docs.getdbt.com/docs/explore/model-query-history#credential-permissions "Direct link to Credential permissions") --------------------------------------------------------------------------------------------------------------------------------------------------- This section explains the permissions and steps you need to enable and view model query history in Catalog. The model query history feature uses the credentials in your production environment to gather metadata from your data warehouse’s query logs. This means you may need elevated permissions with the warehouse. Before making any changes to your data platform permissions, confirm the configured permissions in dbt: 1. Navigate to **Deploy** and then **Environments**. 2. Select the Environment marked **PROD** and click **Settings**. 3. Look at the information under **Deployment credentials**. * Note: Querying query history entails warehouse costs / uses credits. [![Confirm your deployment credentials in your environment settings page.](https://docs.getdbt.com/img/docs/collaborate/dbt-explorer/model-query-credentials.jpg?v=2 "Confirm your deployment credentials in your environment settings page.")](https://docs.getdbt.com/docs/explore/model-query-history#) Confirm your deployment credentials in your environment settings page. 4. Copy or cross reference those credential permissions with the warehouse permissions and grant your user the right permissions. #### Snowflake model query history[​](https://docs.getdbt.com/docs/explore/model-query-history#snowflake-model-query-history "Direct link to Snowflake model query history") Model query history makes use of metadata tables available to [Snowflake Enterprise tier](https://docs.snowflake.com/en/user-guide/intro-editions#enterprise-edition) accounts or higher, `QUERY_HISTORY` and `ACCESS_HISTORY`. The Snowflake user in the production environment must have the `GOVERNANCE_VIEWER` permission to view the data. Before enabling Model query history, your `ACCOUNTADMIN` must run the following grant statement in Snowflake to ensure for access: GRANT DATABASE ROLE SNOWFLAKE.GOVERNANCE_VIEWER TO ROLE ; Without this grant, model query history won't display any data. For more details, view the snowflake docs [here](https://docs.snowflake.com/en/sql-reference/account-usage#enabling-other-roles-to-use-schemas-in-the-snowflake-database) . ##### BigQuery model query history[​](https://docs.getdbt.com/docs/explore/model-query-history#bigquery-model-query-history "Direct link to BigQuery model query history") Model query history uses the metadata from the `INFORMATION_SCHEMA.JOBS` view in BigQuery. To access this, the user configured for your production environment must have the following [IAM roles](https://cloud.google.com/bigquery/docs/access-control) for your BigQuery project: * `roles/bigquery.resourceViewer` * `roles/bigquery.jobs.create` View query history in Explorer[​](https://docs.getdbt.com/docs/explore/model-query-history#view-query-history-in-explorer "Direct link to View query history in Explorer") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- To enhance your discovery, you can view your model query history in various locations within Catalog: * [View from Performance charts](https://docs.getdbt.com/docs/explore/model-query-history#view-from-performance-charts) * [View from Project lineage](https://docs.getdbt.com/docs/explore/model-query-history#view-from-project-lineage) * [View from Model list](https://docs.getdbt.com/docs/explore/model-query-history#view-from-model-list) ### View from Performance charts[​](https://docs.getdbt.com/docs/explore/model-query-history#view-from-performance-charts "Direct link to View from Performance charts") 1. Navigate to Catalog by clicking on the **Explore** link in the navigation. 2. In the main **Overview** page, click on **Performance** under the **Project details** section. Scroll down to view the **Most consumed models**. 3. Use the dropdown menu on the right to select the desired time period, with options available for up to the past 3 months. [![View most consumed models on the 'Performance' page in dbt Catalog.](https://docs.getdbt.com/img/docs/collaborate/dbt-explorer/most-consumed-models.jpg?v=2 "View most consumed models on the 'Performance' page in dbt Catalog.")](https://docs.getdbt.com/docs/explore/model-query-history#) View most consumed models on the 'Performance' page in dbt Catalog. 4. Click on a model for more details and go to the **Performance** tab. 5. On the **Performance** tab, scroll down to the **Model performance** section. 6. Select the **Consumption queries** tab to view the consumption queries over a given time for that model. [![View consumption queries over time for a given model.](https://docs.getdbt.com/img/docs/collaborate/model-consumption-queries.jpg?v=2 "View consumption queries over time for a given model.")](https://docs.getdbt.com/docs/explore/model-query-history#) View consumption queries over time for a given model. ### View from Project lineage[​](https://docs.getdbt.com/docs/explore/model-query-history#view-from-project-lineage "Direct link to View from Project lineage") 1. To view your model in your project lineage, go to the main **Overview page** and click on **Project lineage.** 2. In the lower left of your lineage, click on **Lenses** and select **Consumption queries**. [![View model consumption queries in your lineage using the 'Lenses' feature.](https://docs.getdbt.com/img/docs/collaborate/dbt-explorer/model-consumption-lenses.jpg?v=2 "View model consumption queries in your lineage using the 'Lenses' feature.")](https://docs.getdbt.com/docs/explore/model-query-history#) View model consumption queries in your lineage using the 'Lenses' feature. 3. Your lineage should display a small red box above each model, indicating the consumption query number. The number for each model represents the model consumption over the last 30 days. ### View from Model list[​](https://docs.getdbt.com/docs/explore/model-query-history#view-from-model-list "Direct link to View from Model list") 1. To view a list of models, go to the main **Overview page**. 2. In the left navigation, go to the **Resources** tab and click on **Models** to view the models list. 3. You can view the consumption query count for the models and sort by most or least consumed. The consumption query number for each model represents the consumption over the last 30 days. [![View models consumption in the 'Models' list page under the 'Consumption' column.](https://docs.getdbt.com/img/docs/collaborate/dbt-explorer/model-consumption-list.jpg?v=2 "View models consumption in the 'Models' list page under the 'Consumption' column.")](https://docs.getdbt.com/docs/explore/model-query-history#) View models consumption in the 'Models' list page under the 'Consumption' column. Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Prerequisites](https://docs.getdbt.com/docs/explore/model-query-history#prerequisites) * [Enable query history in dbt](https://docs.getdbt.com/docs/explore/model-query-history#enable-query-history-in-dbt) * [Credential permissions](https://docs.getdbt.com/docs/explore/model-query-history#credential-permissions) * [View query history in Explorer](https://docs.getdbt.com/docs/explore/model-query-history#view-query-history-in-explorer) * [View from Performance charts](https://docs.getdbt.com/docs/explore/model-query-history#view-from-performance-charts) * [View from Project lineage](https://docs.getdbt.com/docs/explore/model-query-history#view-from-project-lineage) * [View from Model list](https://docs.getdbt.com/docs/explore/model-query-history#view-from-model-list) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/explore/model-query-history.md) --- # Merge jobs in dbt | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/deploy/merge-jobs#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page You can set up a merge job to implement a continuous deployment (CD) workflow in dbt. The merge job triggers a dbt job to run when someone merges Git pull requests into production. This workflow creates a seamless development experience where changes made in code will automatically update production data. Also, you can use this workflow for running `dbt compile` to update your environment's manifest so subsequent CI job runs are more performant. By using CD in dbt, you can take advantage of deferral to build only the edited model and any downstream changes. With merge jobs, state will be updated almost instantly, always giving the most up-to-date state information in [Catalog](https://docs.getdbt.com/docs/explore/explore-projects) . Triggering merge jobs in monorepos If you have a monorepo with several dbt projects, merging a single pull request in one of your projects will trigger jobs for all projects connected to the monorepo. To address this, you can use separate target branches per project (for example, `main-project-a`, `main-project-b`) to separate CI triggers. Prerequisites[​](https://docs.getdbt.com/docs/deploy/merge-jobs#prerequisites "Direct link to Prerequisites") -------------------------------------------------------------------------------------------------------------- * You have a dbt account. * You have set up a [connection with your Git provider](https://docs.getdbt.com/docs/cloud/git/git-configuration-in-dbt-cloud) . This integration lets dbt run jobs on your behalf for job triggering. * If you're using a native [GitLab](https://docs.getdbt.com/docs/cloud/git/connect-gitlab) integration, you need a paid or self-hosted account that includes support for GitLab webhooks and [project access tokens](https://docs.gitlab.com/ee/user/project/settings/project_access_tokens.html) . If you're using GitLab Free, merge requests will trigger CI jobs but CI job status updates (success or failure of the job) will not be reported back to GitLab. * For deferral (which is the default), make sure there has been at least one successful job run in the environment you defer to. Set up job trigger on Git merge[​](https://docs.getdbt.com/docs/deploy/merge-jobs#set-up-merge-jobs "Direct link to Set up job trigger on Git merge") ------------------------------------------------------------------------------------------------------------------------------------------------------ 1. On your deployment environment page, click **Create job** > **Merge job**. 2. Options in the **Job settings** section: * **Job name** — Specify the name for the merge job. * **Description** — Provide a description about the job. * **Environment** — By default, it’s set to the environment you created the job from. 3. In the **Git trigger** section, the **Run on merge** option is enabled by default. Every time a PR merges (to a base branch configured in the environment) in your Git repo, this job will get triggered to run. 4. Options in the **Execution settings** section: * **Commands** — By default, it includes the `dbt build --select state:modified+` command. This informs dbt to build only new or changed models and their downstream dependents. Importantly, state comparison can only happen when there is a deferred environment selected to compare state to. Click **Add command** to add more [commands](https://docs.getdbt.com/docs/deploy/job-commands) that you want to be invoked when this job runs. * **Compare changes against** — By default, it's set to compare changes against the environment you created the job from. This option allows dbt to check the state of the code in the PR against the code running in the deferred environment, so as to only check the modified code, instead of building the full table or the entire DAG. To change the default settings, you can select **No deferral**, **This job** for self-deferral, or choose a different environment. 5. (optional) Options in the **Advanced settings** section: * **Environment variables** — Define [environment variables](https://docs.getdbt.com/docs/build/environment-variables) to customize the behavior of your project when this job runs. * **Target name** — Define the [target name](https://docs.getdbt.com/docs/build/custom-target-names) . Similar to environment variables, this option lets you customize the behavior of the project. * **Run timeout** — Cancel this job if the run time exceeds the timeout value. * **dbt version** — By default, it’s set to inherit the [dbt version](https://docs.getdbt.com/docs/dbt-versions/core) from the environment. dbt Labs strongly recommends that you don't change the default setting. This option to change the version at the job level is useful only when you upgrade a project to the next dbt version; otherwise, mismatched versions between the environment and job can lead to confusing behavior. * **Threads** — By default, it’s set to 4 [threads](https://docs.getdbt.com/docs/core/connect-data-platform/connection-profiles#understanding-threads) . Increase the thread count to increase model execution concurrency. [![Example of creating a merge job](https://docs.getdbt.com/img/docs/dbt-cloud/using-dbt-cloud/example-create-merge-job.png?v=2 "Example of creating a merge job")](https://docs.getdbt.com/docs/deploy/merge-jobs#) Example of creating a merge job Verify push events in Git[​](https://docs.getdbt.com/docs/deploy/merge-jobs#verify-push-events-in-git "Direct link to Verify push events in Git") -------------------------------------------------------------------------------------------------------------------------------------------------- Merge jobs require push events so make sure they've been enabled in your Git provider, especially if you have an already-existing Git integration. However, for a new integration setup, you can skip this check since push events are typically enabled by default.  GitHub example The following is a GitHub example of when the push events are already set: [![Example of the Pushes option enabled in the GitHub settings](https://docs.getdbt.com/img/docs/dbt-cloud/using-dbt-cloud/example-github-push-events.png?v=2 "Example of the Pushes option enabled in the GitHub settings")](https://docs.getdbt.com/docs/deploy/merge-jobs#) Example of the Pushes option enabled in the GitHub settings GitLab example The following is a GitLab example of when the push events are already set: [![Example of the Push events option enabled in the GitLab settings](https://docs.getdbt.com/img/docs/dbt-cloud/using-dbt-cloud/example-gitlab-push-events.png?v=2 "Example of the Push events option enabled in the GitLab settings")](https://docs.getdbt.com/docs/deploy/merge-jobs#) Example of the Push events option enabled in the GitLab settings Azure DevOps example The following is an example of creating a new **Code pushed** trigger in Azure DevOps. Create a new service hooks subscription when code pushed events haven't been set: [![Example of creating a new trigger to push events in Azure Devops](https://docs.getdbt.com/img/docs/dbt-cloud/using-dbt-cloud/example-azuredevops-new-event.png?v=2 "Example of creating a new trigger to push events in Azure Devops")](https://docs.getdbt.com/docs/deploy/merge-jobs#) Example of creating a new trigger to push events in Azure Devops Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Prerequisites](https://docs.getdbt.com/docs/deploy/merge-jobs#prerequisites) * [Set up job trigger on Git merge](https://docs.getdbt.com/docs/deploy/merge-jobs#set-up-merge-jobs) * [Verify push events in Git](https://docs.getdbt.com/docs/deploy/merge-jobs#verify-push-events-in-git) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/deploy/merge-jobs.md) --- # New concepts in the dbt Fusion engine | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/fusion/new-concepts#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page The dbt Fusion Engine [fully comprehends your project's SQL](https://docs.getdbt.com/blog/the-levels-of-sql-comprehension) , enabling advanced capabilities like dialect-aware validation and precise column-level lineage. It can do this because its compilation step is more comprehensive than that of the dbt Core engine. When dbt Core referred to _compilation_, it only meant _rendering_ — converting Jinja-templated strings into a SQL query to send to a database. The dbt Fusion engine can also render Jinja, but then it completes a second phase: producing and validating with _static analysis_ a logical plan for every rendered query in the project. This static analysis step is the cornerstone of Fusion's new capabilities. | Step | dbt Core engine | dbt Fusion engine | | --- | --- | --- | | Render Jinja into SQL | ✅ | ✅ | | Produce and statically analyze logical plan | ❌ | ✅ | | Run rendered SQL | ✅ | ✅ | Rendering strategies[​](https://docs.getdbt.com/docs/fusion/new-concepts#rendering-strategies "Direct link to Rendering strategies") ------------------------------------------------------------------------------------------------------------------------------------- [![Each dot represents a step in that model's execution (render, analyze, run). The numbers reflect step order across the DAG. JIT steps are green; AOT steps are purple.](https://docs.getdbt.com/img/fusion/annotated_steps.png?v=2 "Each dot represents a step in that model's execution (render, analyze, run). The numbers reflect step order across the DAG. JIT steps are green; AOT steps are purple.")](https://docs.getdbt.com/docs/fusion/new-concepts#) Each dot represents a step in that model's execution (render, analyze, run). The numbers reflect step order across the DAG. JIT steps are green; AOT steps are purple.  JIT rendering and execution (dbt Core) dbt Core will _always_ use **Just In Time (JIT) rendering**. It renders a model, runs it in the warehouse, then moves on to the next model.  AOT rendering, analysis and execution (dbt Fusion engine) The dbt Fusion Engine will _default to_ **Ahead of Time (AOT) rendering and analysis**. It renders all models in the project, then produces and statically analyzes every model's logical plan, and only then will it start running models in the warehouse. By rendering and analyzing all models ahead of time, and only beginning execution once everything is proven to be valid, the dbt Fusion Engine avoids consuming any warehouse resources unnecessarily. By contrast, SQL errors in models run by dbt Core's engine will only be flagged by the database itself during execution. ### Rendering introspective queries[​](https://docs.getdbt.com/docs/fusion/new-concepts#rendering-introspective-queries "Direct link to Rendering introspective queries") The exception to AOT rendering is an introspective model: a model whose rendered SQL depends on the results of a database query. Models containg macros like `run_query()` or `dbt_utils.get_column_values()` are introspective. Introspection causes issues with ahead-of-time rendering because: * Most introspective queries are run against the results of an earlier model in the DAG, which may not yet exist in the database during AOT rendering. * Even if the model does exist in the database, it might be out of date until after the model has been refreshed. The dbt Fusion Engine switches to **JIT rendering for introspective models**, to ensure it renders them the same way as dbt Core. Note that macros like `adapter.get_columns_in_relation()` and `dbt_utils.star()` _can_ be rendered and analyzed ahead of time, as long as the [`Relations`](https://docs.getdbt.com/reference/dbt-classes#relation) they inspect aren't themselves dynamic. This is because the dbt Fusion Engine populates schemas into memory as part of the compilation process. Principles of static analysis[​](https://docs.getdbt.com/docs/fusion/new-concepts#principles-of-static-analysis "Direct link to Principles of static analysis") ---------------------------------------------------------------------------------------------------------------------------------------------------------------- [Static analysis](https://en.wikipedia.org/wiki/Static_program_analysis) is meant to guarantee that if a model compiles without error in development, it will also run without compilation errors when deployed. Introspective queries can break this promise by making it possible to modify the rendered query after a model is committed to source control. The dbt Fusion Engine is unique in that it can statically analyze not just a single model in isolation, but every query from one end of your DAG to the other. Even your database can only validate the query in front of it! Concepts like [information flow theory](https://roundup.getdbt.com/i/156064124/beyond-cll-information-flow-theory-and-metadata-propagation) — although not incorporated into the dbt platform [yet](https://www.getdbt.com/blog/where-we-re-headed-with-the-dbt-fusion-engine) — rely on stable inputs and the ability to trace columns DAG-wide. ### Static analysis and introspective queries[​](https://docs.getdbt.com/docs/fusion/new-concepts#static-analysis-and-introspective-queries "Direct link to Static analysis and introspective queries") When Fusion encounters an introspective query, that model will switch to just-in-time rendering (as described above). Both the introspective model and all of its descendants will also be opted in to JIT static analysis. We refer to JIT static analysis as "unsafe" because it will still capture most SQL errors and prevent execution of an invalid model, but only after upstream models have already been materialized. This classification is meant to indicate that Fusion can no longer 100% guarantee alignment between what it analyzes and what will be executed. The most common real-world example where unsafe static analysis can cause an issue is a standalone `dbt compile` step (as opposed to the compilation that happens as part of a `dbt run`). During a `dbt run`, JIT rendering ensures the downstream model's code will be up to date with the current warehouse state, but a standalone compile does not refresh the upstream model. In this scenario Fusion will read from the upstream model as it was last run. This is _probably_ fine, but could lead to errors being raised incorrectly (a false positive) or not at all (a false negative).  Rendering and analyzing without execution Note that `model_d` is rendered AOT, since it doesn't use introspection, but it still has to wait for `introspective_model_c` to be analyzed. You will still derive significant benefits from "unsafe" static analysis compared to no static analysis, and we recommend leaving it on unless you notice it causing you problems. Better still, you should consider whether your introspective code could be rewritten in a way that is eligible for AOT rendering and static analysis. Recapping the differences between engines[​](https://docs.getdbt.com/docs/fusion/new-concepts#recapping-the-differences-between-engines "Direct link to Recapping the differences between engines") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- dbt Core: * renders all models just-in-time * never runs static analysis The dbt Fusion engine: * renders all models ahead-of-time, unless they use introspective queries * statically analyzes all models, defaulting to ahead-of-time unless they or their parents were rendered just-in-time, in which case the static analysis step will also happen just-in-time. Configuring `static_analysis`[​](https://docs.getdbt.com/docs/fusion/new-concepts#configuring-static_analysis "Direct link to configuring-static_analysis") ------------------------------------------------------------------------------------------------------------------------------------------------------------ Beyond the default behavior described above, you can always modify the way static analysis is applied for specific models in your project. Remember that **a model is only eligible for static analysis if all of its parents are also eligible.** The `static_analysis` options are: * `on`: Statically analyze SQL. The default for non-introspective models, depends on AOT rendering. * `unsafe`: Statically analyze SQL. The default for introspective models. Always uses JIT rendering. * `off`: Skip SQL analysis on this model and its descendants. When you disable static analysis, features of the VS Code extension which depend on SQL comprehension will be unavailable. The best place to configure `static_analysis` is as a config on an individual model or group of models. As a debugging aid, you can also use the `--static-analysis off` or `--static-analysis unsafe` CLI flags to override all model-level configuration. Refer to [CLI options](https://docs.getdbt.com/reference/global-configs/command-line-options) and [Configurations and properties](https://docs.getdbt.com/reference/configs-and-properties) to learn more about configs. ### Example configurations[​](https://docs.getdbt.com/docs/fusion/new-concepts#example-configurations "Direct link to Example configurations") Disable static analysis for all models in a package: dbt\_project.yml name: jaffle_shopmodels: jaffle_shop: marts: +materialized: table a_package_with_introspective_queries: +static_analysis: off Disable static analysis in YAML: models/my\_udf\_using\_model.yml models: - name: model_with_static_analysis_off config: static_analysis: off Disable static analysis for a model using a custom UDF: models/my\_udf\_using\_model.sql {{ config(static_analysis='off') }}select user_id, my_cool_udf(ip_address) as cleaned_ipfrom {{ ref('my_model') }} ### When should I turn static analysis `off`?[​](https://docs.getdbt.com/docs/fusion/new-concepts#when-should-i-turn-static-analysis-off "Direct link to when-should-i-turn-static-analysis-off") Static analysis may incorrectly fail on valid queries if they contain: * **syntax or native functions** that the dbt Fusion Engine doesn't recognize. Please [open an issue](https://github.com/dbt-labs/dbt-fusion/issues) in addition to disabling static analysis. * **user-defined functions** that the dbt Fusion Engine doesn't recognize. You will need to temporarily disable static analysis. Native support for UDF compilation will arrive in a future version - see [dbt-fusion#69](https://github.com/dbt-labs/dbt-fusion/issues/69) . * **dynamic SQL** such as [Snowflake's PIVOT ANY](https://docs.snowflake.com/en/sql-reference/constructs/pivot#dynamic-pivot-on-all-distinct-column-values-automatically) which cannot be statically analyzed. You can disable static analysis, refactor your pivot to use explicit column names, or create a [dynamic pivot in Jinja](https://github.com/dbt-labs/dbt-utils#pivot-source) . * **highly volatile data feeding an introspective query** during a standalone `dbt compile` invocation. Because the `dbt compile` step does not run models, it uses old data or defers to a different environment when running introspective queries. The more frequently the input data changes, the more likely it is for this divergence to cause a compilation error. Consider whether these standalone `dbt compile` commands are necessary before disabling static analysis. Examples[​](https://docs.getdbt.com/docs/fusion/new-concepts#examples "Direct link to Examples") ------------------------------------------------------------------------------------------------- ### No introspective models[​](https://docs.getdbt.com/docs/fusion/new-concepts#no-introspective-models "Direct link to No introspective models")  AOT rendering, analysis and execution * Fusion renders each model in order. * Then it statically analyzes each model's logical plan in order. * Finally, it runs each model's rendered SQL. Nothing is persisted to the database until Fusion has validated the entire project. ### Introspective model with `unsafe` static analysis[​](https://docs.getdbt.com/docs/fusion/new-concepts#introspective-model-with-unsafe-static-analysis "Direct link to introspective-model-with-unsafe-static-analysis") Imagine we update `model_c` to contain an introspective query (such as `dbt_utils.get_column_values`). We'll say it's querying `model_b`, but the dbt Fusion Engine's response is the same regardless of what the introspection does.  Unsafe static analysis of introspective models * During parsing, Fusion discovers `model_c`'s introspective query. It switches `model_c` to JIT rendering and opts `model_c+` in to JIT static analysis. * `model_a` and `model_b` are still eligible for AOT compilation, so Fusion handles them the same as in the introspection-free example above. `model_d` is still eligible for AOT rendering (but not analysis). * Once `model_b` is run, Fusion renders `model_c`'s SQL (using the just-refreshed data), analyzes it, and runs it. All three steps happen back-to-back. * `model_d`'s AOT-rendered SQL is analyzed and run.  Complex DAG with an introspective branch As you'd expect, a branching DAG will AOT compile as much as possible before moving on to the JIT components, and will work with multiple `--threads` if they're available. Here, `model_c` can start rendering as soon as `model_b` has finished running, while the AOT-compiled `model_x` and `model_y` run separately: More information about Fusion[​](https://docs.getdbt.com/docs/fusion/new-concepts#more-information-about-fusion "Direct link to More information about Fusion") ---------------------------------------------------------------------------------------------------------------------------------------------------------------- Fusion marks a significant update to dbt. While many of the workflows you've grown accustomed to remain unchanged, there are a lot of new ideas, and a lot of old ones going away. The following is a list of the full scope of our current release of the Fusion engine, including implementation, installation, deprecations, and limitations: * [About the dbt Fusion engine](https://docs.getdbt.com/docs/fusion/about-fusion) * [About the dbt extension](https://docs.getdbt.com/docs/about-dbt-extension) * [New concepts in Fusion](https://docs.getdbt.com/docs/fusion/new-concepts) * [Supported features matrix](https://docs.getdbt.com/docs/fusion/supported-features) * [Installing Fusion CLI](https://docs.getdbt.com/docs/fusion/install-fusion) * [Installing VS Code extension](https://docs.getdbt.com/docs/install-dbt-extension) * [Fusion release track](https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-version-in-cloud#dbt-fusion-engine) * [Quickstart for Fusion](https://docs.getdbt.com/guides/fusion?step=1) * [Upgrade guide](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-fusion) * [Fusion licensing](http://www.getdbt.com/licenses-faq) Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Rendering strategies](https://docs.getdbt.com/docs/fusion/new-concepts#rendering-strategies) * [Rendering introspective queries](https://docs.getdbt.com/docs/fusion/new-concepts#rendering-introspective-queries) * [Principles of static analysis](https://docs.getdbt.com/docs/fusion/new-concepts#principles-of-static-analysis) * [Static analysis and introspective queries](https://docs.getdbt.com/docs/fusion/new-concepts#static-analysis-and-introspective-queries) * [Recapping the differences between engines](https://docs.getdbt.com/docs/fusion/new-concepts#recapping-the-differences-between-engines) * [Configuring `static_analysis`](https://docs.getdbt.com/docs/fusion/new-concepts#configuring-static_analysis) * [Example configurations](https://docs.getdbt.com/docs/fusion/new-concepts#example-configurations) * [When should I turn static analysis `off`?](https://docs.getdbt.com/docs/fusion/new-concepts#when-should-i-turn-static-analysis-off) * [Examples](https://docs.getdbt.com/docs/fusion/new-concepts#examples) * [No introspective models](https://docs.getdbt.com/docs/fusion/new-concepts#no-introspective-models) * [Introspective model with `unsafe` static analysis](https://docs.getdbt.com/docs/fusion/new-concepts#introspective-model-with-unsafe-static-analysis) * [More information about Fusion](https://docs.getdbt.com/docs/fusion/new-concepts#more-information-about-fusion) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/fusion/new-concepts.md) --- # Supported features | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/fusion/supported-features#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page Learn about the features supported by the dbt Fusion engine, including requirements and limitations. ### Parity with dbt Core[​](https://docs.getdbt.com/docs/fusion/supported-features#parity-with-dbt-core "Direct link to Parity with dbt Core") Our goal is for the dbt Fusion Engine to support all capabilities of the dbt Core framework, and then some. Fusion already supports many of the capabilities in dbt Core v1.9, and we're working fast to add more. Note that we have removed some deprecated features, and introduced more-rigorous validation of erroneous project code. Refer to the [Upgrade guide](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-fusion) for details. Requirements[​](https://docs.getdbt.com/docs/fusion/supported-features#requirements "Direct link to Requirements") ------------------------------------------------------------------------------------------------------------------- To use Fusion in your dbt project: * You're using a supported adapter and authentication method:  BigQuery * Service Account / User Token * Native OAuth * External OAuth * [Required permissions](https://docs.getdbt.com/docs/core/connect-data-platform/bigquery-setup#required-permissions) Databricks * Service Account / User Token * Native OAuth Redshift * Username / Password Snowflake * Username / Password * Native OAuth * External OAuth * Key pair * MFA * Have only SQL models defined in your project. Python models are not currently supported because Fusion cannot parse these to extract dependencies (refs) on other models. ### Limitations[​](https://docs.getdbt.com/docs/fusion/supported-features#limitations "Direct link to Limitations") If your project is using any of the features listed in the following table, you can use Fusion, but you won't be able to fully migrate all your workloads because you have: * Models that leverage specific materialization features may be unable to run or may be missing some desirable configurations. * Tooling that expects dbt Core's exact log output. Fusion's logging system is currently unstable and incomplete. * Workflows built around complementary features of the dbt platform (like model-level notifications, Advanced CI, and Semantic Layer) that Fusion does not yet support. note We have been moving quickly to implement many of these features during the Beta and Preview periods, ahead of General Availability. Read more about [the path to GA](https://docs.getdbt.com/blog/dbt-fusion-engine-path-to-ga) , and track our progress in the [`dbt-fusion` milestones](https://github.com/dbt-labs/dbt-fusion/milestones) . | Feature | This will affect you if... | GitHub issue | | --- | --- | --- | | [\--store-failures](https://docs.getdbt.com/reference/resource-configs/store_failures) | You use the --store-failures feature of dbt test to materialize the results of test queries in audit tables. | [dbt-fusion#15](https://github.com/dbt-labs/dbt-fusion/issues/15) | | [\--fail-fast](https://docs.getdbt.com/reference/resource-configs/store_failures) | You use the --fail-fast flag to interrupt runs at the first sign of failure. | [dbt-fusion#18](https://github.com/dbt-labs/dbt-fusion/issues/18) | | [microbatch incremental strategy](https://docs.getdbt.com/docs/build/incremental-microbatch) | You are configuring models with materializations other than view, table, or incremental. You cannot yet run those models with Fusion, but you can run models using the standard materializations. | [dbt-fusion#12](https://github.com/dbt-labs/dbt-fusion/issues/12) | | [query-comment](https://docs.getdbt.com/reference/project-configs/query-comment) | You rely on prepended or appended SQL comments with dbt model metadata to analyze queries. | [dbt-fusion#20](https://github.com/dbt-labs/dbt-fusion/issues/20) | | [\--warn-error, --warn-error-options](https://docs.getdbt.com/reference/global-configs/warnings) | You are upgrading all/specific warnings to errors, or silencing specific warnings, by configuring the warning event names. Fusion's logging system is incomplete and unstable, and so specific event names are likely to change. | [dbt-fusion#8](https://github.com/dbt-labs/dbt-fusion/issues/8) | | [Advanced CI ("compare changes")](https://docs.getdbt.com/docs/deploy/advanced-ci) | You use the "compare changes" feature of Advanced CI in the dbt platform. | [dbt-fusion#26](https://github.com/dbt-labs/dbt-fusion/issues/26) | | [Model governance](https://docs.getdbt.com/docs/mesh/govern/about-model-governance)
(polish and feature completeness) | If you have models with a set `deprecation_date`, Fusion does not yet raise warnings about upcoming/past deprecations. Fusion’s logging system is currently incomplete and unstable. | [dbt-fusion#25](https://github.com/dbt-labs/dbt-fusion/issues/25) | | Iceberg support (across adapters) and "catalogs" (new feature in dbt Core v1.10) | You have configured models to be materialized as Iceberg tables, or you are defining `catalogs` in your project to configure the external write location of Iceberg models. Fusion does not yet support these model configurations. | [dbt-fusion#28](https://github.com/dbt-labs/dbt-fusion/issues/28)
, [dbt-fusion#37](https://github.com/dbt-labs/dbt-fusion/issues/37) | | [Model-level notifications](https://docs.getdbt.com/docs/deploy/model-notifications) | You are leveraging the dbt platform’s capabilities for model-level notifications in your workflows. Fusion currently supports job-level notifications. | [dbt-fusion#7](https://github.com/dbt-labs/dbt-fusion/issues/7) | | [retry](https://docs.getdbt.com/reference/commands/retry) | Fusion does not yet support the dbt retry CLI command, or "rerun failed job from point of failure." In deployment environments, using [state-aware orchestration](https://docs.getdbt.com/docs/deploy/state-aware-about)
, you can simply rerun the job and Fusion will skip models that do not have fresh data or have not met their freshness.build\_after threshold since the last build | [dbt-fusion#21](https://github.com/dbt-labs/dbt-fusion/issues/21) | | [`state:modified.` methods](https://docs.getdbt.com/reference/node-selection/methods#state) | You rely on granular "subselectors" because state:modified is insufficiently precise. Fusion’s state detection is smarter out-of-the-box; give it a try! | [dbt-fusion#33](https://github.com/dbt-labs/dbt-fusion/issues/33) | | [dbt-docs documentation site](https://docs.getdbt.com/docs/build/view-documentation#dbt-docs)
and ["docs generate/serve" commands](https://docs.getdbt.com/reference/commands/cmd-docs) | Fusion does not yet support a local experience for generating, hosting, and viewing documentation, as dbt Core does via dbt-docs (static HTML site). We intend to support such an experience by GA. If you need to generate and host local documentation, you should continue generating the catalog by running dbt docs generate with dbt Core. | [dbt-fusion#9](https://github.com/dbt-labs/dbt-fusion/issues/9) | | [Programmatic invocations](https://docs.getdbt.com/reference/programmatic-invocations) | You use dbt Core’s Python API for triggering invocations and registering callbacks on events/logs. Note that Fusion’s logging system is incomplete and unstable. | [dbt-fusion#10](https://github.com/dbt-labs/dbt-fusion/issues/10) | | [Semantic Layer](https://docs.getdbt.com/docs/use-dbt-semantic-layer/dbt-sl)
: development + saved\_query exports | If you actively develop new semantic objects (semantic\_models, metrics, saved\_queries), or change existing objects in your dbt project, you should do this with dbt Core rather than Fusion, because Fusion does not yet produce semantic\_manifest.json (the interface to MetricFlow). If you use the "exports" feature of saved queries, this is not yet supported in Fusion, so you should continue running your jobs on dbt Core. | [dbt-fusion#40](https://github.com/dbt-labs/dbt-fusion/issues/40) | | [Logging system](https://docs.getdbt.com/reference/events-logging) | You have scripts, workflows, or other integrations that rely on specific log messages (structured or plaintext). At present, Fusion’s logging system is incomplete and unstable. It is also not our goal to provide full conformance between dbt Core logging and Fusion logging. | [dbt-fusion#7](https://github.com/dbt-labs/dbt-fusion/issues/7) | | [Linting via SQLFluff](https://docs.getdbt.com/docs/deploy/continuous-integration#to-configure-sqlfluff-linting) | You use SQLFluff for linting in your development or CI workflows. Eventually, we plan to build linting support into Fusion directly, since the engine has SQL comprehension capabilities. In the meantime, you can continue using the dbt Core + SQLFluff integration. dbt Cloud will do exactly this in the Cloud IDE / Studio + CI jobs. | [dbt-fusion#11](https://github.com/dbt-labs/dbt-fusion/issues/11) | | [`{{ graph }}`](https://docs.getdbt.com/reference/dbt-jinja-functions/graph)
- `raw_sql` attribute (e.g. specific models in [dbt\_project\_evaluator](https://hub.getdbt.com/dbt-labs/dbt_project_evaluator/latest/)
) | You access the `raw_sql` / `raw_code` attribute of the `{{ graph }}` context variable, which Fusion stubs with an empty value at runtime. If you access this attribute, your code will not fail, but it will return different results. This is used in three quality checks within the [`dbt_project_evaluator` package](https://hub.getdbt.com/dbt-labs/dbt_project_evaluator/latest/)
. We intend to find a more-performant mechanism for Fusion to provide this information in the future. | TK | More information about Fusion[​](https://docs.getdbt.com/docs/fusion/supported-features#more-information-about-fusion "Direct link to More information about Fusion") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- Fusion marks a significant update to dbt. While many of the workflows you've grown accustomed to remain unchanged, there are a lot of new ideas, and a lot of old ones going away. The following is a list of the full scope of our current release of the Fusion engine, including implementation, installation, deprecations, and limitations: * [About the dbt Fusion engine](https://docs.getdbt.com/docs/fusion/about-fusion) * [About the dbt extension](https://docs.getdbt.com/docs/about-dbt-extension) * [New concepts in Fusion](https://docs.getdbt.com/docs/fusion/new-concepts) * [Supported features matrix](https://docs.getdbt.com/docs/fusion/supported-features) * [Installing Fusion CLI](https://docs.getdbt.com/docs/fusion/install-fusion) * [Installing VS Code extension](https://docs.getdbt.com/docs/install-dbt-extension) * [Fusion release track](https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-version-in-cloud#dbt-fusion-engine) * [Quickstart for Fusion](https://docs.getdbt.com/guides/fusion?step=1) * [Upgrade guide](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-fusion) * [Fusion licensing](http://www.getdbt.com/licenses-faq) ### Package support[​](https://docs.getdbt.com/docs/fusion/supported-features#package-support "Direct link to Package support") The following packages are verified and supported on the dbt Fusion Engine: * [dbt-labs/audit\_helper](https://github.com/dbt-labs/dbt-audit-helper.git) * [dbt-labs/codegen](https://github.com/dbt-labs/dbt-codegen.git) * [dbt-labs/dbt\_project\_evaluator](https://github.com/dbt-labs/dbt-project-evaluator.git) * [dbt-labs/dbt\_utils](https://github.com/dbt-labs/dbt-utils.git) * [fivetran/ad\_reporting](https://github.com/fivetran/dbt_ad_reporting.git) * [fivetran/facebook\_ads](https://github.com/fivetran/dbt_facebook_ads.git) * [fivetran/fivetran\_log](https://github.com/fivetran/dbt_fivetran_log.git) * [fivetran/fivetran\_utils](https://github.com/fivetran/dbt_fivetran_utils.git) * [fivetran/google\_ads](https://github.com/fivetran/dbt_google_ads.git) * [fivetran/hubspot](https://github.com/fivetran/dbt_hubspot.git) * [fivetran/jira](https://github.com/fivetran/dbt_jira.git) * [fivetran/linkedin](https://github.com/fivetran/dbt_linkedin.git) * [fivetran/microsoft\_ads](https://github.com/fivetran/dbt_microsoft_ads.git) * [fivetran/pendo](https://github.com/fivetran/dbt_pendo.git) * [fivetran/qualtrics](https://github.com/fivetran/dbt_qualtrics.git) * [fivetran/salesforce](https://github.com/fivetran/dbt_salesforce.git) * [fivetran/salesforce\_formula\_utils](https://github.com/fivetran/dbt_salesforce_formula_utils.git) * [fivetran/social\_media\_reporting](https://github.com/fivetran/dbt_social_media_reporting.git) * [fivetran/zendesk](https://github.com/fivetran/dbt_zendesk.git) * [GJMcClintock/dbt\_tld](https://github.com/GJMcClintock/dbt_tld.git) * [godatadriven/dbt\_date](https://github.com/godatadriven/dbt-date.git) * [metaplane/dbt\_expectations](https://github.com/metaplane/dbt-expectations.git) * [Montreal-Analytics/snowflake\_utils](https://github.com/Montreal-Analytics/dbt-snowflake-utils.git) Additionally, the Fivetran `source` and `transformation` packages have been combined into a single package. If you manually installed source packages like `fivetran/github_source`, you need to ensure `fivetran/github` is installed and deactivate the transformation models. Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Parity with dbt Core](https://docs.getdbt.com/docs/fusion/supported-features#parity-with-dbt-core) * [Requirements](https://docs.getdbt.com/docs/fusion/supported-features#requirements) * [Limitations](https://docs.getdbt.com/docs/fusion/supported-features#limitations) * [More information about Fusion](https://docs.getdbt.com/docs/fusion/supported-features#more-information-about-fusion) * [Package support](https://docs.getdbt.com/docs/fusion/supported-features#package-support) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/fusion/supported-features.md) --- # About model governance | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/mesh/govern/about-model-governance#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) dbt supports model governance to help you control who can access models, what data they contain, how they change over time, and reference them across projects. dbt supports model governance in dbt Core and the dbt platform, with some differences in the features available across environments/plans. * Use model governance to define model structure and visibility in dbt Core and the dbt platform. * dbt builds on this with features like [cross-project ref](https://docs.getdbt.com/docs/mesh/govern/project-dependencies) that enable collaboration at scale across multiple projects, powered by its metadata service and [Catalog](https://docs.getdbt.com/docs/explore/explore-projects) . Available in dbt Enterprise or Enterprise+ plans. All of the following features are available in dbt Core and the dbt platform, _except_ project dependencies, which is only available to [dbt Enterprise-tier plans](https://www.getdbt.com/pricing) . * [**Model access**](https://docs.getdbt.com/docs/mesh/govern/model-access) — Mark models as "public" or "private" to distinguish between mature data products and implementation details — and to control who can `ref` each. * [**Model contracts**](https://docs.getdbt.com/docs/mesh/govern/model-contracts) —Guarantee the shape of a model (column names, data types, constraints) before it builds, to prevent surprises for downstream data consumers. * [**Model versions**](https://docs.getdbt.com/docs/mesh/govern/model-versions) — When a breaking change is unavoidable, provide a smoother upgrade pathway and deprecation window for downstream data consumers. * [**Model namespaces**](https://docs.getdbt.com/reference/dbt-jinja-functions/ref#ref-project-specific-models) — Organize models into [groups](https://docs.getdbt.com/docs/build/groups) and [packages](https://docs.getdbt.com/docs/build/packages) to delineate ownership boundaries. Models in different packages can share the same name, and the `ref` function can take the project/package namespace as its first argument. * [**Project dependencies**](https://docs.getdbt.com/docs/mesh/govern/project-dependencies) — Resolve references to public models in other projects ("cross-project ref") using an always-on stateful metadata service, instead of importing all models from those projects as packages. Each project serves data products (public model references) while managing its own implementation details, enabling an [enterprise data mesh](https://docs.getdbt.com/best-practices/how-we-mesh/mesh-1-intro) . [Enterprise](https://www.getdbt.com/pricing "Go to https://www.getdbt.com/pricing") [Enterprise +](https://www.getdbt.com/pricing "Go to https://www.getdbt.com/pricing") Considerations Model governance features like model access, contracts, and versions strengthen trust and stability in your dbt project. Because they add structure, it can make it harder to roll changes back later (for example, removing model access) and increases maintenance if adopted too early. Before adding governance features, consider whether your dbt project is ready to benefit from them. Introducing them too soon can make future changes harder if your models are still changing/evolving. Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 --- # Preview new and experimental features in the dbt platform | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/dbt-versions/experimental-features#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page dbt Labs often tests experimental features before deciding to continue on the [Product lifecycle](https://docs.getdbt.com/docs/dbt-versions/product-lifecycles#dbt-cloud) . You can access experimental features to preview beta features that haven’t yet been released to dbt. You can toggle on or off all experimental features in your Profile settings. Experimental features: * May not be feature-complete or fully stable as we’re actively developing them. * Could be discontinued at any time. * May require feedback from you to understand their limitations or impact. Each experimental feature collects feedback directly in dbt, which may impact dbt Labs' decisions to implement. * May have limited technical support and be excluded from our Support SLAs. * May not have public documentation available. To enable or disable experimental features: 1. From dbt, click on your account name in the left side menu and select **Account settings** 2. Go to **Personal profile** under the **Your profile** header. 3. Find Experimental features at the bottom of Your Profile page. 4. Click **Beta** to toggle the features on or off as shown in the following image. ![Experimental features](https://docs.getdbt.com/assets/images/experimental-feats-0e0504161396cca0f88e363ffd275f42.png) Beta terms and conditions[​](https://docs.getdbt.com/docs/dbt-versions/experimental-features#beta-terms-and-conditions "Direct link to Beta terms and conditions") ------------------------------------------------------------------------------------------------------------------------------------------------------------------- By using or enabling features that are not yet in general release ("Beta Features"), you agree to the [Beta Features Terms and Conditions](https://docs.getdbt.com/assets/files/beta-tc-740ff696113c89c38a96bb70b968775e.pdf) . Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Beta terms and conditions](https://docs.getdbt.com/docs/dbt-versions/experimental-features#beta-terms-and-conditions) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/dbt-versions/experimental-features.md) --- # Column-level lineage | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/explore/column-level-lineage#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page Catalog now offers column-level lineage (CLL) for the resources in your dbt project. Analytics engineers can quickly and easily gain insight into the provenance of their data products at a more granular level. For each column in a resource (model, source, or snapshot) in a dbt project, Catalog provides end-to-end lineage for the data in that column given how it's used. CLL is available to all dbt Enterprise plans that can use Catalog. [![Overview of column level lineage](https://docs.getdbt.com/img/docs/collaborate/dbt-explorer/example-overview-cll.png?v=2 "Overview of column level lineage")](https://docs.getdbt.com/docs/explore/column-level-lineage#) Overview of column level lineage On-demand learning If you enjoy video courses, check out our [dbt Catalog on-demand course](https://learn.getdbt.com/courses/dbt-catalog) and learn how to best explore your dbt project(s)! Access the column-level lineage[​](https://docs.getdbt.com/docs/explore/column-level-lineage#access-the-column-level-lineage "Direct link to Access the column-level lineage") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- There is no additional setup required for CLL if your account is on an Enterprise plan that can use Catalog. You can access the CLL by expanding the column card in the **Columns** tab of an Catalog [resource details page](https://docs.getdbt.com/docs/explore/explore-projects#view-resource-details) for a model, source, or snapshot. dbt updates the lineage in Explorer after each run that's executed in the production or staging environment. At least one job in the production or staging environment must run `dbt docs generate`. Refer to [Generating metadata](https://docs.getdbt.com/docs/explore/explore-projects#generate-metadata) for more details. [![Example of the Columns tab and where to expand for the CLL](https://docs.getdbt.com/img/docs/collaborate/dbt-explorer/example-cll.png?v=2 "Example of the Columns tab and where to expand for the CLL")](https://docs.getdbt.com/docs/explore/column-level-lineage#) Example of the Columns tab and where to expand for the CLL Column evolution lens[​](https://docs.getdbt.com/docs/explore/column-level-lineage#column-lens "Direct link to Column evolution lens") --------------------------------------------------------------------------------------------------------------------------------------- You can use the column evolution lineage lens to determine when a column is transformed vs. reused (passthrough or rename). The lens helps you distinguish when and how a column is actually changed as it flows through your dbt lineage, informing debugging workflows in particular. [![Example of the Column evolution lens](https://docs.getdbt.com/img/docs/collaborate/dbt-explorer/example-evolution-lens.png?v=2 "Example of the Column evolution lens")](https://docs.getdbt.com/docs/explore/column-level-lineage#) Example of the Column evolution lens ### Inherited column descriptions[​](https://docs.getdbt.com/docs/explore/column-level-lineage#inherited-column-descriptions "Direct link to Inherited column descriptions") A reused column, labeled as **Passthrough** or **Rename** in the lineage, automatically inherits its description from the source and upstream model columns. The inheritance goes as far back as possible. As long as the column isn't transformed, you don't need to manually define the description; it'll automatically propagate downstream. Passthrough and rename columns are clearly labeled and color-coded in the lineage. In the following `dim_salesforce_accounts` model example (located at the end of the lineage), the description for a column inherited from the `stg_salesforce__accounts` model (located second to the left) indicates its origin. This helps developers quickly identify the original source of the column, making it easier to know where to make documentation changes. [![Example of lineage with propagated and inherited column descriptions.](https://docs.getdbt.com/img/docs/collaborate/dbt-explorer/example-prop-inherit.jpg?v=2 "Example of lineage with propagated and inherited column descriptions.")](https://docs.getdbt.com/docs/explore/column-level-lineage#) Example of lineage with propagated and inherited column descriptions. Column-level lineage use cases[​](https://docs.getdbt.com/docs/explore/column-level-lineage#use-cases "Direct link to Column-level lineage use cases") ------------------------------------------------------------------------------------------------------------------------------------------------------- Learn more about why and how you can use CLL in the following sections. ### Root cause analysis[​](https://docs.getdbt.com/docs/explore/column-level-lineage#root-cause-analysis "Direct link to Root cause analysis") When there is an unexpected breakage in a data pipeline, column-level lineage can be a valuable tool to understand the exact point where the error occurred in the pipeline. For example, a failing data test on a particular column in your dbt model might've stemmed from an untested column upstream. Using CLL can help quickly identify and fix breakages when they happen. ### Impact analysis[​](https://docs.getdbt.com/docs/explore/column-level-lineage#impact-analysis "Direct link to Impact analysis") During development, analytics engineers can use column-level lineage to understand the full scope of the impact of their proposed changes. This knowledge empowers them to create higher-quality pull requests that require fewer edits, as they can anticipate and preempt issues that would've been unchecked without column-level insights. ### Collaboration and efficiency[​](https://docs.getdbt.com/docs/explore/column-level-lineage#collaboration-and-efficiency "Direct link to Collaboration and efficiency") When exploring your data products, navigating column lineage allows analytics engineers and data analysts to more easily navigate and understand the origin and usage of their data, enabling them to make better decisions with higher confidence. Caveats[​](https://docs.getdbt.com/docs/explore/column-level-lineage#caveats "Direct link to Caveats") ------------------------------------------------------------------------------------------------------- Refer to the following CLL caveats or limitations as you navigate Catalog. ### Column usage[​](https://docs.getdbt.com/docs/explore/column-level-lineage#column-usage "Direct link to Column usage") Column-level lineage reflects the lineage from `select` statements in your models' SQL code. It doesn't reflect other usage like joins and filters. ### SQL parsing[​](https://docs.getdbt.com/docs/explore/column-level-lineage#sql-parsing "Direct link to SQL parsing") Column-level lineage relies on SQL parsing. Errors can occur when parsing fails or a column's origin is unknown (like with JSON unpacking, lateral joins, and so on). In these cases, lineage may be incomplete and dbt will provide a warning about it in the column lineage. [![Example of warning in the full lineage graph](https://docs.getdbt.com/img/docs/collaborate/dbt-explorer/example-parsing-error-pill.png?v=2 "Example of warning in the full lineage graph")](https://docs.getdbt.com/docs/explore/column-level-lineage#) Example of warning in the full lineage graph To review the error details: 1. Click the **Expand** icon in the upper right corner to open the column's lineage graph 2. Select the node to open the column’s details panel Possible error cases are: * **Parsing error** — Error occurs when the SQL is ambiguous or too complex for parsing. An example of ambiguous parsing scenarios are _complex_ lateral joins. * **Python error** — Error occurs when a Python model is used within the lineage. Due to the nature of Python models, it's not possible to parse and determine the lineage. * **Unknown error** — Error occurs when the lineage can't be determined for an unknown reason. An example of this would be if a dbt best practice is not being followed, like using hardcoded table names instead of `ref` statements. Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Access the column-level lineage](https://docs.getdbt.com/docs/explore/column-level-lineage#access-the-column-level-lineage) * [Column evolution lens](https://docs.getdbt.com/docs/explore/column-level-lineage#column-lens) * [Inherited column descriptions](https://docs.getdbt.com/docs/explore/column-level-lineage#inherited-column-descriptions) * [Column-level lineage use cases](https://docs.getdbt.com/docs/explore/column-level-lineage#use-cases) * [Root cause analysis](https://docs.getdbt.com/docs/explore/column-level-lineage#root-cause-analysis) * [Impact analysis](https://docs.getdbt.com/docs/explore/column-level-lineage#impact-analysis) * [Collaboration and efficiency](https://docs.getdbt.com/docs/explore/column-level-lineage#collaboration-and-efficiency) * [Caveats](https://docs.getdbt.com/docs/explore/column-level-lineage#caveats) * [Column usage](https://docs.getdbt.com/docs/explore/column-level-lineage#column-usage) * [SQL parsing](https://docs.getdbt.com/docs/explore/column-level-lineage#sql-parsing) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/explore/column-level-lineage.md) --- # Access Catalog from dbt platform features | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/explore/access-from-dbt-cloud#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page Access Catalog from other features and products inside dbt, ensuring you have a seamless experience navigating between resources and lineage in your project. This page explains how to access Catalog from various dbt features, including the Studio IDE and jobs. While the primary way to navigate to Catalog is through the **Explore** link in the navigation, you can also access it from other dbt features. ### Studio IDE[​](https://docs.getdbt.com/docs/explore/access-from-dbt-cloud#studio-ide "Direct link to Studio IDE") You can enhance your project navigation and editing experience by directly accessing resources from the [Studio IDE](https://docs.getdbt.com/docs/cloud/dbt-cloud-ide/develop-in-the-cloud) to Catalog for model, seed, or snapshot files. This workflow offers a seamless transition between the Studio IDE and Catalog, allowing you to quickly navigate between viewing project metadata and making updates to your models or other resources without switching contexts. #### Access Catalog from the IDE[​](https://docs.getdbt.com/docs/explore/access-from-dbt-cloud#access-catalog-from-the-ide "Direct link to Access Catalog from the IDE") * In your model, seed, or snapshot file, click the **View in Catalog** icon to the right of your file breadcrumb (under the file name tab). * This opens the model, seed, or snapshot file in a new tab, allowing you to view resources/lineage directly in Catalog. [![Access dbt Catalog from the IDE by clicking on the 'View in Explorer' icon next to the file breadcrumbs. ](https://docs.getdbt.com/img/docs/collaborate/dbt-explorer/explorer-from-ide.jpg?v=2 "Access dbt Catalog from the IDE by clicking on the 'View in Explorer' icon next to the file breadcrumbs. ")](https://docs.getdbt.com/docs/explore/access-from-dbt-cloud#) Access dbt Catalog from the IDE by clicking on the 'View in Explorer' icon next to the file breadcrumbs. ### Canvas[​](https://docs.getdbt.com/docs/explore/access-from-dbt-cloud#canvas "Direct link to Canvas") Seamlessly access Catalog via Canvas to bring your workflow to life with visual editing. #### Access Catalog from Canvas[​](https://docs.getdbt.com/docs/explore/access-from-dbt-cloud#access-catalog-from-canvas "Direct link to Access Catalog from Canvas") Steps here \[Roxi to check with Greg and team and will add images on response\] ### Lineage tab in jobs[​](https://docs.getdbt.com/docs/explore/access-from-dbt-cloud#lineage-tab-in-jobs "Direct link to Lineage tab in jobs") The **Lineage tab** in dbt jobs displays the lineage associated with the [job run](https://docs.getdbt.com/docs/deploy/jobs) . Access Catalog directly from this tab, allowing you understand dependencies/relationships of resources in your project. #### Access Catalog from the lineage tab[​](https://docs.getdbt.com/docs/explore/access-from-dbt-cloud#access-catalog-from-the-lineage-tab "Direct link to Access Catalog from the lineage tab") * From a job, select the **Lineage tab**. * Double-click the node in the lineage to open a new tab and view its metadata directly in Catalog. [![Access dbt Catalog from the lineage tab by double-clicking on the lineage node.](https://docs.getdbt.com/img/docs/collaborate/dbt-explorer/explorer-from-lineage.gif?v=2 "Access dbt Catalog from the lineage tab by double-clicking on the lineage node.")](https://docs.getdbt.com/docs/explore/access-from-dbt-cloud#) Access dbt Catalog from the lineage tab by double-clicking on the lineage node. ### Model timing tab in jobs [Starter](https://www.getdbt.com/pricing "Go to https://www.getdbt.com/pricing") [Enterprise](https://www.getdbt.com/pricing "Go to https://www.getdbt.com/pricing") [Enterprise +](https://www.getdbt.com/pricing "Go to https://www.getdbt.com/pricing") [​](https://docs.getdbt.com/docs/explore/access-from-dbt-cloud#model-timing-tab-in-jobs- "Direct link to model-timing-tab-in-jobs-") The [model timing tab](https://docs.getdbt.com/docs/deploy/run-visibility#model-timing) in dbt jobs displays the composition, order, and time taken by each model in a job run. Access Catalog directly from the **modeling timing tab**, which helps you investigate resources, diagnose performance bottlenecks, understand dependencies/relationships of slow-running models, and potentially make changes to improve their performance. #### Access Catalog from the model timing tab[​](https://docs.getdbt.com/docs/explore/access-from-dbt-cloud#access-catalog-from-the-model-timing-tab "Direct link to Access Catalog from the model timing tab") * From a job, select the **model timing tab**. * Hover over a resource and click on **View on Catalog** to view the resource metadata directly in Catalog. [![Access dbt Catalog from the model timing tab by hovering over the resource and clicking 'View in Explorer'.](https://docs.getdbt.com/img/docs/collaborate/dbt-explorer/explorer-from-model-timing.jpg?v=2 "Access dbt Catalog from the model timing tab by hovering over the resource and clicking 'View in Explorer'.")](https://docs.getdbt.com/docs/explore/access-from-dbt-cloud#) Access dbt Catalog from the model timing tab by hovering over the resource and clicking 'View in Explorer'. ### dbt Insights [preview](https://docs.getdbt.com/docs/dbt-versions/product-lifecycles "Go to https://docs.getdbt.com/docs/dbt-versions/product-lifecycles") [Enterprise](https://www.getdbt.com/pricing "Go to https://www.getdbt.com/pricing") [Enterprise +](https://www.getdbt.com/pricing "Go to https://www.getdbt.com/pricing") [​](https://docs.getdbt.com/docs/explore/access-from-dbt-cloud#dbt-insights- "Direct link to dbt-insights-") Access Catalog directly from [Insights](https://docs.getdbt.com/docs/explore/access-dbt-insights) to view the project lineage and project resources with access to tables, columns, metrics, dimensions, and more. To access Catalog from Insights, click on the **Catalog** icon in the Query console sidebar menu and search for the resource you're interested in. [![dbt Insights integrated with dbt Catalog](https://docs.getdbt.com/img/docs/dbt-insights/insights-explorer.png?v=2 "dbt Insights integrated with dbt Catalog")](https://docs.getdbt.com/docs/explore/access-from-dbt-cloud#) dbt Insights integrated with dbt Catalog Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Studio IDE](https://docs.getdbt.com/docs/explore/access-from-dbt-cloud#studio-ide) * [Canvas](https://docs.getdbt.com/docs/explore/access-from-dbt-cloud#canvas) * [Lineage tab in jobs](https://docs.getdbt.com/docs/explore/access-from-dbt-cloud#lineage-tab-in-jobs) * [Model timing tab in jobs](https://docs.getdbt.com/docs/explore/access-from-dbt-cloud#model-timing-tab-in-jobs-) * [dbt Insights](https://docs.getdbt.com/docs/explore/access-from-dbt-cloud#dbt-insights-) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/explore/access-from-dbt-cloud.md) --- # Model versions | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/mesh/govern/model-versions#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page Model versions, dbt\_project.yml versions, and .yml versions Take note that [model versions](https://docs.getdbt.com/docs/mesh/govern/model-versions) are different from [dbt\_project.yml versions](https://docs.getdbt.com/reference/project-configs/version#dbt_projectyml-versions) and [.yml property file versions](https://docs.getdbt.com/reference/project-configs/version#yml-property-file-versions) . Model versions is a _feature_ that enables better governance and data model management by allowing you to track changes and updates to models over time. dbt\_project.yml versions refer to the compatibility of the dbt project with a specific version of dbt. Version numbers within .yml property files inform how dbt parses those YAML files. The latter two are completely optional starting from dbt v1.5. Versioning APIs is a hard problem in software engineering. The root of the challenge is that the producers and consumers of an API have competing incentives: * Producers of an API need the ability to modify its logic and structure. There is a real cost to maintaining legacy endpoints forever, but losing the trust of downstream users is far costlier. * Consumers of an API need to trust in its stability: their queries will keep working, and won't break without warning. Although migrating to a newer API version incurs an expense, an unplanned migration is far costlier. When sharing a final dbt model with other teams or systems, that model is operating like an API. When the producer of that model needs to make significant changes, how can they avoid breaking the queries of its users downstream? Model versioning is a tool to tackle this problem, thoughtfully and head-on. The goal is not to make the problem go away entirely, nor to pretend it's easier or simpler than it is. Related documentation[​](https://docs.getdbt.com/docs/mesh/govern/model-versions#related-documentation "Direct link to Related documentation") ----------------------------------------------------------------------------------------------------------------------------------------------- * [`versions`](https://docs.getdbt.com/reference/resource-properties/versions) * [`latest_version`](https://docs.getdbt.com/reference/resource-properties/latest_version) * [`include` and `exclude`](https://docs.getdbt.com/reference/resource-properties/versions#include) * [`ref` with `version` argument](https://docs.getdbt.com/reference/dbt-jinja-functions/ref#versioned-ref) Why version a model?[​](https://docs.getdbt.com/docs/mesh/govern/model-versions#why-version-a-model "Direct link to Why version a model?") ------------------------------------------------------------------------------------------------------------------------------------------- If a model defines a ["contract"](https://docs.getdbt.com/docs/mesh/govern/model-contracts) (a set of guarantees for its structure), it's also possible to change that model's structure in a way that breaks the previous set of guarantees. This could be as obvious as removing or renaming a column, or more subtle, like changing its data type or nullability. One approach is to force every model consumer to immediately handle the breaking change as soon as it's deployed to production. This is actually the appropriate answer at many smaller organizations, or while rapidly iterating on a not-yet-mature set of data models. But it doesn’t scale well beyond that. Instead, for mature models at larger organizations, powering queries inside & outside dbt, the model owner can use **model versions** to: * Test "prerelease" changes (in production, in downstream systems) * Bump the latest version, to be used as the canonical source of truth * Offer a migration window off the "old" version During that migration window, anywhere that model is being used downstream, it can continue to be referenced at a specific version. dbt Core 1.6 introduced first-class support for **deprecating models** by specifying a [`deprecation_date`](https://docs.getdbt.com/reference/resource-properties/deprecation_date) . Taken together, model versions and deprecation offer a pathway for model producers to _sunset_ old models, and consumers the time to _migrate_ across breaking changes. It's a way of managing change across an organization: develop a new version, bump the latest, slate the old version for deprecation, update downstream references, and then remove the old version. There is a real trade-off that exists here—the cost to frequently migrate downstream code, and the cost (and clutter) of materializing multiple versions of a model in the data warehouse. Model versions do not make that problem go away, but by setting a deprecation date, and communicating a clear window for consumers to gracefully migrate off old versions, they put a known boundary on the cost of that migration. When should you version a model?[​](https://docs.getdbt.com/docs/mesh/govern/model-versions#when-should-you-version-a-model "Direct link to When should you version a model?") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Considerations Model governance features like model access, contracts, and versions strengthen trust and stability in your dbt project. Because they add structure, it can make it harder to roll changes back later (for example, removing model access) and increases maintenance if adopted too early. Before adding governance features, consider whether your dbt project is ready to benefit from them. Introducing them too soon can make future changes harder if your models are still changing/evolving. By enforcing a model's contract, dbt can help you catch unintended changes to column names and data types that could cause a big headache for downstream queriers. If you're making these changes intentionally, you should create a new model version. If you're making a non-breaking change, you don't need a new version—such as adding a new column, or fixing a bug in an existing column's calculation. Of course, it's possible to change a model's definition in other ways—recalculating a column in a way that doesn't change its name, data type, or enforceable characteristics—but would substantially change the results seen by downstream queriers. This is always a judgment call. As the maintainer of a widely-used model, you know best what's a bug fix and what's an unexpected behavior change. The process of sunsetting and migrating model versions requires real work, and likely significant coordination across teams. You should opt for non-breaking changes whenever possible. Inevitably, however, these non-breaking additions will leave your most important models with lots of unused or deprecated columns. Rather than constantly adding a new version for each small change, you should opt for a predictable cadence (once or twice a year, communicated well in advance) where you bump the "latest" version of your model, removing columns that are no longer being used. How is this different from "version control"?[​](https://docs.getdbt.com/docs/mesh/govern/model-versions#how-is-this-different-from-version-control "Direct link to How is this different from "version control"?") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- [Version control](https://docs.getdbt.com/docs/cloud/git/git-version-control) allows your team to collaborate simultaneously on a single code repository, manage conflicts between changes, and review changes before deploying into production. In that sense, version control is an essential tool for versioning the deployment of an entire dbt project—always the latest state of the `main` branch. In general, only one version of your project code is deployed into an environment at a time. If something goes wrong, you have the ability to roll back changes by reverting a commit or pull request, or by leveraging data platform capabilities around "time travel." When you make updates to a model's source code — its logical definition, in SQL or Python, or related configuration — dbt can [compare your project to the previous state](https://docs.getdbt.com/reference/node-selection/syntax#about-node-selection) , enabling you to rebuild only models that have changed, and models downstream of a change. In this way, it's possible to develop changes to a model, quickly test in CI, and efficiently deploy into production — all coordinated via your version control system. **Versioned models are different.** Defining model `versions` is appropriate when people, systems, and processes beyond your team's control, inside or outside of dbt, depend on your models. You can neither simply go migrate them all, nor break their queries on a whim. You need to offer a migration path, with clear diffs and deprecation dates. Multiple versions of a model will live in the same code repository at the same time, and be deployed into the same data environment simultaneously. This is similar to how web APIs are versioned: Multiple versions live simultaneously, two or three, and not more). Over time, newer versions come online, and older versions are sunsetted . How is this different from just creating a new model?[​](https://docs.getdbt.com/docs/mesh/govern/model-versions#how-is-this-different-from-just-creating-a-new-model "Direct link to How is this different from just creating a new model?") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Honestly, it's only a little bit different! There isn't much magic here, and that's by design. You've always been able to copy-paste, create a new model file, and name it `dim_customers_v2.sql`. Why should you opt for a "real" versioned model instead? As the **producer** of a versioned model: * You keep track of all live versions in one place, rather than scattering them throughout the codebase * You can reuse the model's configuration, and highlight just the diffs between versions * You can select models to build (or not) based on whether they're a `latest`, `prerelease`, or `old` version * dbt will notify consumers of your versioned model when new versions become available, or when they are slated for deprecation As the **consumer** of a versioned model: * You use a consistent `ref`, with the option of pinning to a specific live version * You will be notified throughout the life cycle of a versioned model All versions of a model preserve the model's original name. They are `ref`'d by that name, rather than the name of the file that they're defined in. By default, the `ref` resolves to the latest version (as declared by that model's maintainer), but you can also `ref` a specific version of the model, with a `version` keyword. Let's say that `dim_customers` has three versions defined: `v2` is the "latest", `v3` is "prerelease," and `v1` is an old version that's still within its deprecation window. Because `v2` is the latest version, it gets some special treatment: it can be defined in a file without a suffix, and `ref('dim_customers')` will resolve to `v2` if a version pin is not specified. The table below breaks down the standard conventions: | v | version | `ref` syntax | File name | Database relation | | --- | --- | --- | --- | --- | | 3 | "prerelease" | `ref('dim_customers', v=3)` | `dim_customers_v3.sql` | `analytics.dim_customers_v3` | | 2 | "latest" | `ref('dim_customers', v=2)` **and** `ref('dim_customers')` | `dim_customers_v2.sql` **or** `dim_customers.sql` | `analytics.dim_customers_v2` **and** `analytics.dim_customers` (recommended) | | 1 | "old" | `ref('dim_customers', v=1)` | `dim_customers_v1.sql` | `analytics.dim_customers_v1` | As you'll see in the implementation section below, a versioned model can reuse the majority of its YAML properties and configuration. Each version needs to only say how it _differs_ from the shared set of attributes. This gives you, as the producer of a versioned model, the opportunity to highlight the differences across versions—which is otherwise difficult to detect in models with dozens or hundreds of columns—and to clearly track, in one place, all versions of the model which are currently live. dbt also supports [`version`\-based selection](https://docs.getdbt.com/reference/node-selection/methods#version) . For example, you could define a [default YAML selector](https://docs.getdbt.com/reference/node-selection/yaml-selectors#default) that avoids running any old model versions in development, even while you continue to run them in production through a sunset and migration period. (You could accomplish something similar by applying `tags` to these models, and cycling through those tags over time.) selectors.yml selectors: - name: exclude_old_versions default: "{{ target.name == 'dev' }}" definition: method: fqn value: "*" exclude: - method: version value: old Because dbt knows that these models are _actually the same model_, it can notify downstream consumers as new versions become available, and as older versions are slated for deprecation. Found an unpinned reference to versioned model 'dim_customers'.Resolving to latest version: my_model.v2A prerelease version 3 is available. It has not yet been marked 'latest' by its maintainer.When that happens, this reference will resolve to my_model.v3 instead. Try out v3: {{ ref('my_dbt_project', 'my_model', v='3') }} Pin to v2: {{ ref('my_dbt_project', 'my_model', v='2') }} How to create a new version of a model[​](https://docs.getdbt.com/docs/mesh/govern/model-versions#how-to-create-a-new-version-of-a-model "Direct link to How to create a new version of a model") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Most often, you'll start with a model that is not yet versioned. Let's go back in time to when `dim_customers` was a simple standalone model, with an enforced contract. For simplicity, let's pretend it has only two columns, `customer_id` and `country_name`, though most mature models will have many more. models/dim\_customers.sql -- lots of sqlfinal as ( select customer_id, country_name from ...)select * from final models/schema.yml models: - name: dim_customers config: materialized: table contract: enforced: true columns: - name: customer_id description: This is the primary key data_type: int - name: country_name description: Where this customer lives data_type: varchar Let's say you need to make a breaking change to the model: Removing the `country_name` column, which is no longer reliable. First, create a new model file (SQL or Python) encompassing those breaking changes. The default convention is naming the new file with a `_v` suffix. Let's make a new file, named `dim_customers_v2.sql`. (We don't need to rename the existing model file just yet, while it's still the "latest" version.) models/dim\_customers\_v2.sql -- lots of sqlfinal as ( select customer_id -- country_name has been removed! from ...)select * from final Now, you could define properties and configuration for `dim_customers_v2` as a new standalone model, with no actual relation to `dim_customers` save a striking resemblance. Instead, we're going to declare that these are versions of the same model, both named `dim_customers`. We can define their properties in common, and then **just** highlight the diffs between them. (Or, you can choose to define each model version with full specifications, and repeat the values they have in common.) * Diffs only (recommended) * Fully specified models/schema.yml models: - name: dim_customers latest_version: 1 config: materialized: table contract: {enforced: true} columns: - name: customer_id description: This is the primary key data_type: int - name: country_name description: Where this customer lives data_type: varchar # Declare the versions, and highlight the diffs versions: - v: 1 # Matches what's above -- nothing more needed - v: 2 # Removed a column -- this is the breaking change! columns: # This means: use the 'columns' list from above, but exclude country_name - include: all exclude: [country_name] models/schema.yml models: - name: dim_customers latest_version: 1 # declare the versions, and fully specify them versions: - v: 2 config: materialized: table contract: {enforced: true} columns: - name: customer_id description: This is the primary key data_type: int # no country_name column - v: 1 config: materialized: table contract: {enforced: true} columns: - name: customer_id description: This is the primary key data_type: int - name: country_name description: Where this customer lives data_type: varchar Note: If none of your model versions specify columns, you don't need to define columns at all and can omit the `columns/include`/`exclude` keys from the versioned model. In this case, dbt will automatically use all top-level columns for all versions. The configuration above says: Instead of two unrelated models, I have two versioned definitions of the same model: `dim_customers_v1` and `dim_customers_v2`. **Where are they defined?** dbt expects each model version to be defined in a file named `_v`. In this case: `dim_customers_v1.sql` and `dim_customers_v2.sql`. It's also possible to define the "latest" version in `dim_customers.sql` (no suffix), without additional configuration. Finally, you can override this convention by setting [`defined_in: any_file_name_you_want`](https://docs.getdbt.com/reference/resource-properties/versions#defined_in) —but we strongly encourage you to follow the convention, unless you have a very good reason. **Where will they be materialized?** Each model version will create a database relation with alias `_v`. In this case: `dim_customers_v1` and `dim_customers_v2`. See [the section below](https://docs.getdbt.com/docs/mesh/govern/model-versions#configuring-database-location-with-alias) for more details on configuring aliases. **Which version is "latest"?** If not specified explicitly, the `latest_version` would be `2`, because it's numerically greatest. In this case, we've explicitly specified that `latest_version: 1`. That means `v2` is a "prerelease," in early development and testing. When we're ready to roll out `v2` to everyone by default, we would bump `latest_version: 2`, or remove `latest_version` from the specification. ### Configuring versioned models[​](https://docs.getdbt.com/docs/mesh/govern/model-versions#configuring-versioned-models "Direct link to Configuring versioned models") You can reconfigure each version independently. For example, you could materialize `v2` as a table and `v1` as a view: models/schema.yml versions: - v: 2 config: materialized: table - v: 1 config: materialized: view Like with all config inheritance, any configs set _within_ the versioned model's definition (`.sql` or `.py` file) will take precedence over the configs set in YAML. ### Configuring database location with `alias`[​](https://docs.getdbt.com/docs/mesh/govern/model-versions#configuring-database-location-with-alias "Direct link to configuring-database-location-with-alias") Following the example, let's say you wanted `dim_customers_v1` to continue populating the database table named `dim_customers`. That's what the table was named previously, and you may have several other dashboards or tools expecting to read its data from `..dim_customers`. You could use the `alias` configuration: models/schema.yml - v: 1 config: alias: dim_customers # keep v1 in its original database location **The pattern we recommend:** Create a view or table clone with the model's canonical name that always points to the latest version. By following this pattern, you can offer the same flexibility as `ref`, even if someone is querying outside of dbt. Want a specific version? Pin to version X by adding the `_vX` suffix. Want the latest version? No suffix, and the view will redirect you. We intend to build this into `dbt-core` as out-of-the-box functionality. (Upvote or comment on [dbt-core#7442](https://github.com/dbt-labs/dbt-core/issues/7442) .) In the meantime, you can implement this pattern yourself with a custom macro and post-hook: macros/create\_latest\_version\_view.sql {% macro create_latest_version_view() %} -- this hook will run only if the model is versioned, and only if it's the latest version -- otherwise, it's a no-op {% if model.get('version') and model.get('version') == model.get('latest_version') %} {% set new_relation = this.incorporate(path={"identifier": model['name']}) %} {% set existing_relation = load_relation(new_relation) %} {% if existing_relation and not existing_relation.is_view %} {{ drop_relation_if_exists(existing_relation) }} {% endif %} {% set create_view_sql -%} -- this syntax may vary by data platform create or replace view {{ new_relation }} as select * from {{ this }} {%- endset %} {% do log("Creating view " ~ new_relation ~ " pointing to " ~ this, info = true) if execute %} {{ return(create_view_sql) }} {% else %} -- no-op select 1 as id {% endif %}{% endmacro %} dbt\_project.yml # dbt_project.ymlmodels: post-hook: - "{{ create_latest_version_view() }}" info If your project has historically implemented [custom aliases](https://docs.getdbt.com/docs/build/custom-aliases) by reimplementing the `generate_alias_name` macro, and you'd like to start using model versions, you should update your custom implementation to account for model versions. Specifically, we'd encourage you to add [a condition like this one](https://github.com/dbt-labs/dbt-core/blob/ada8860e48b32ac712d92e8b0977b2c3c9749981/core/dbt/include/global_project/macros/get_custom_name/get_custom_alias.sql#L26-L30) . Your existing implementation of `generate_alias_name` should not encounter any errors upon first upgrading to v1.5. It's only when you create your first versioned model, that you may see an error like: dbt.exceptions.AmbiguousAliasError: Compilation Error dbt found two resources with the database representation "database.schema.model_name". dbt cannot create two resources with identical database representations. To fix this, change the configuration of one of these resources: - model.project_name.model_name.v1 (models/.../model_name.sql) - model.project_name.model_name.v2 (models/.../model_name_v2.sql) We opted to use `generate_alias_name` for this functionality so that the logic remains accessible to end users, and could be reimplemented with custom logic. ### Run a model with multiple versions[​](https://docs.getdbt.com/docs/mesh/govern/model-versions#run-a-model-with-multiple-versions "Direct link to Run a model with multiple versions") To run a model with multiple versions, you can use the [`--select` flag](https://docs.getdbt.com/reference/node-selection/syntax) . For example: * Run all versions of `dim_customers`: dbt run --select dim_customers # Run all versions of the model * Run only version 2 of `dim_customers`: You can use either of the following commands (both achieve the same result): dbt run --select dim_customers.v2 # Run a specific version of the model dbt run --select dim_customers_v2 # Alternative syntax for the specific version * Run the latest version of `dim_customers` using the `--select` flag shorthand: dbt run -s dim_customers,version:latest # Run the latest version of the model These commands provide flexibility in managing and executing different versions of a dbt model. ### Optimizing model versions[​](https://docs.getdbt.com/docs/mesh/govern/model-versions#optimizing-model-versions "Direct link to Optimizing model versions") How you define each model version is completely up to you. While it's easy to start by copy-pasting from one model's SQL definition into another, you should think about _what actually is changing_ from one version to another. For example, if your new model version is only renaming or removing certain columns, you could define one version as a view on top of the other one: models/dim\_customers\_v2.sql {{ config(materialized = 'view') }}{% set dim_customers_v1 = ref('dim_customers', v=1) %}select{{ dbt_utils.star(from=dim_customers_v1, except=["country_name"]) }}from {{ dim_customers_v1 }} Of course, if one model version makes meaningful and substantive changes to logic in another, it may not be possible to optimize it in this way. At that point, the cost of human intuition and legibility is more important than the cost of recomputing similar transformations. We expect to develop more opinionated recommendations as teams start adopting model versions in practice. One recommended pattern we can envision: Prioritize the definition of the `latest_version`, and define other versions (old and prerelease) based on their diffs from the latest. How? * Define the properties and configuration for the latest version in the top-level model YAML, and the diffs for other versions below (via `include`/`exclude`) * Where possible, define other versions as `select` transformations, which take the latest version as their starting point * When bumping the `latest_version`, migrate the SQL and YAML accordingly. In the example above, the third point might be tricky. It's easier to _exclude_ `country_name`, than it is to add it back in. Instead, we might need to keep around the full original logic for `dim_customers_v1`—but materialize it as a `view`, to minimize the data warehouse cost of building it. If downstream queriers see slightly degraded performance, it's still significantly better than broken queries, and all the more reason to migrate to the new "latest" version. Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Related documentation](https://docs.getdbt.com/docs/mesh/govern/model-versions#related-documentation) * [Why version a model?](https://docs.getdbt.com/docs/mesh/govern/model-versions#why-version-a-model) * [When should you version a model?](https://docs.getdbt.com/docs/mesh/govern/model-versions#when-should-you-version-a-model) * [How is this different from "version control"?](https://docs.getdbt.com/docs/mesh/govern/model-versions#how-is-this-different-from-version-control) * [How is this different from just creating a new model?](https://docs.getdbt.com/docs/mesh/govern/model-versions#how-is-this-different-from-just-creating-a-new-model) * [How to create a new version of a model](https://docs.getdbt.com/docs/mesh/govern/model-versions#how-to-create-a-new-version-of-a-model) * [Configuring versioned models](https://docs.getdbt.com/docs/mesh/govern/model-versions#configuring-versioned-models) * [Configuring database location with `alias`](https://docs.getdbt.com/docs/mesh/govern/model-versions#configuring-database-location-with-alias) * [Run a model with multiple versions](https://docs.getdbt.com/docs/mesh/govern/model-versions#run-a-model-with-multiple-versions) * [Optimizing model versions](https://docs.getdbt.com/docs/mesh/govern/model-versions#optimizing-model-versions) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/mesh/govern/model-versions.md) --- # Upgrading to the dbt Fusion engine (v2.0) | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-fusion#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page important The dbt Fusion Engine is currently available for installation in: * [Local command line interface (CLI) tools](https://docs.getdbt.com/docs/fusion/install-fusion-cli) [preview](https://docs.getdbt.com/docs/dbt-versions/product-lifecycles "Go to https://docs.getdbt.com/docs/dbt-versions/product-lifecycles") * [VS Code and Cursor with the dbt extension](https://docs.getdbt.com/docs/install-dbt-extension) [preview](https://docs.getdbt.com/docs/dbt-versions/product-lifecycles "Go to https://docs.getdbt.com/docs/dbt-versions/product-lifecycles") * [dbt platform environments](https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-version-in-cloud#dbt-fusion-engine) [beta](https://docs.getdbt.com/docs/dbt-versions/product-lifecycles "Go to https://docs.getdbt.com/docs/dbt-versions/product-lifecycles") Join the conversation in our Community Slack channel [`#dbt-fusion-engine`](https://getdbt.slack.com/archives/C088YCAB6GH) . Read the [Fusion Diaries](https://github.com/dbt-labs/dbt-fusion/discussions/categories/announcements) for the latest updates. More information about Fusion[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-fusion#more-information-about-fusion "Direct link to More information about Fusion") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ Fusion marks a significant update to dbt. While many of the workflows you've grown accustomed to remain unchanged, there are a lot of new ideas, and a lot of old ones going away. The following is a list of the full scope of our current release of the Fusion engine, including implementation, installation, deprecations, and limitations: * [About the dbt Fusion engine](https://docs.getdbt.com/docs/fusion/about-fusion) * [About the dbt extension](https://docs.getdbt.com/docs/about-dbt-extension) * [New concepts in Fusion](https://docs.getdbt.com/docs/fusion/new-concepts) * [Supported features matrix](https://docs.getdbt.com/docs/fusion/supported-features) * [Installing Fusion CLI](https://docs.getdbt.com/docs/fusion/install-fusion) * [Installing VS Code extension](https://docs.getdbt.com/docs/install-dbt-extension) * [Fusion release track](https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-version-in-cloud#dbt-fusion-engine) * [Quickstart for Fusion](https://docs.getdbt.com/guides/fusion?step=1) * [Upgrade guide](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-fusion) * [Fusion licensing](http://www.getdbt.com/licenses-faq) What to know before upgrading[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-fusion#what-to-know-before-upgrading "Direct link to What to know before upgrading") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ dbt Core and dbt Fusion share a common language spec—the code in your project. dbt Labs is committed to providing feature parity with dbt Core wherever possible. At the same time, we want to take this opportunity to _strengthen the framework_ by removing deprecated functionality, rationalizing confusing behavior, and providing more rigorous validation on erroneous inputs. This means that there is some work involved in preparing an existing dbt project for readiness on Fusion. That work is documented below — it should be simple, straightforward, and in many cases, auto-fixable with the [`dbt-autofix`](https://github.com/dbt-labs/dbt-autofix) helper. You can find more information about what's changing in the dbt Fusion engine [changelog](https://github.com/dbt-labs/dbt-fusion/blob/main/CHANGELOG.md) . ### Supported adapters[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-fusion#supported-adapters "Direct link to Supported adapters") The following adapters are supported in the dbt Fusion engine:  BigQuery * Service Account / User Token * Native OAuth * External OAuth * [Required permissions](https://docs.getdbt.com/docs/core/connect-data-platform/bigquery-setup#required-permissions) Databricks * Service Account / User Token * Native OAuth Redshift * Username / Password Snowflake * Username / Password * Native OAuth * External OAuth * Key pair * MFA ### A clean slate[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-fusion#a-clean-slate "Direct link to A clean slate") dbt Labs is committed to moving forward with Fusion, and it will not support any deprecated functionality: * All [deprecation warnings](https://docs.getdbt.com/reference/deprecations) must be resolved before upgrading to the new engine. This included historic deprecations and [new ones as of dbt Core v1.10](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.10#deprecation-warnings) . _While Fusion is in beta, it will raise validation warnings, but these warnings will become errors when Fusion goes into Preview._ * All [behavior change flags](https://docs.getdbt.com/reference/global-configs/behavior-changes#behaviors) will be removed (generally enabled). You can no longer opt out of them using `flags:` in your `dbt_project.yml`. ### Ecosystem packages[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-fusion#ecosystem-packages "Direct link to Ecosystem packages") The most popular `dbt-labs` packages (`dbt_utils`, `audit_helper`, `dbt_external_tables`, `dbt_project_evaluator`) are already compatible with Fusion. External packages published by organizations outside of dbt may use outdated code or incompatible features that fail to parse with the new Fusion engine. Now that we've announced Fusion in beta, we're going to work with other package maintainers to get them ready & working on Fusion. If we know that a popular package will require upgrading to a new release for Fusion compatibility, we will document it here. ### Changed functionality[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-fusion#changed-functionality "Direct link to Changed functionality") When developing the Fusion engine, there were opportunities to improve the dbt framework - failing earlier (when possible), fixing bugs, optimizing run order, and deprecating flags that are no longer relevant. The result is a handful of specific and nuanced changes to existing behavior. When upgrading to Fusion, you should expect the following changes in functionality: #### Parse time printing of relations will print out the full qualified name, instead of an empty string[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-fusion#parse-time-printing-of-relations-will-print-out-the-full-qualified-name-instead-of-an-empty-string "Direct link to Parse time printing of relations will print out the full qualified name, instead of an empty string") In dbt Core v1, when printing the result of `get_relation()`, the parse time output for that Jinja would print `None` (the undefined object coerces to the string “None”). In Fusion, to help with intelligent batching of `get_relation()` calls (and significantly speed up `dbt compile`), dbt needs to construct a relation object with the fully qualified name resolved at parse time for the `get_relation()` adapter call. Constructing a relation object with the fully qualified name in Fusion produces different behavior than dbt Core v1 in `print()`, `log()`, or any Jinja macro that outputs to `stdout` or `stderr` at parse time. Example: {% set relation = adapter.get_relation(database=db_name,schema=db_schema,identifier='a')%}{{ print('relation: ' ~ relation) }}{% set relation_via_api = api.Relation.create(database=db_name,schema=db_schema,identifier='a') %}{{ print('relation_via_api: ' ~ relation_via_api) }} The output after `dbt parse` in dbt Core v1: relation: Nonerelation_via_api: my_db.my_schema.my_table The output after `dbt parse` in Fusion: relation: my_db.my_schema.my_tablerelation_via_api: my_db.my_schema.my_table #### Deprecated flags[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-fusion#deprecated-flags "Direct link to Deprecated flags") Some historic flags in dbt Core v1 will no longer do anything in Fusion. If you pass them into a dbt command using Fusion, the command will not error, but the flag will do nothing (and warn accordingly). One exception to this rule: The `--models` / `--model` / `-m` flag was renamed to `--select` / `--s` way back in dbt Core v0.21 (Oct 2021). Silently skipping this flag means ignoring your command's selection criteria, which could mean building your entire DAG when you only meant to select a small subset. For this reason, the `--models` / `--model` / `-m` flag **will raise an error** in Fusion. Please update your job definitions accordingly. | flag name | remediation | | --- | --- | | `dbt seed` [`--show`](https://docs.getdbt.com/reference/commands/seed) | N/A | | [`--print` / `--no-print`](https://docs.getdbt.com/reference/global-configs/print-output) | No action required | | [`--printer-width`](https://docs.getdbt.com/reference/global-configs/print-output#printer-width) | No action required | | [`--source`](https://docs.getdbt.com/reference/commands/deps#non-hub-packages) | No action required | | [`--record-timing-info` / `-r`](https://docs.getdbt.com/reference/global-configs/record-timing-info) | No action required | | [`--cache-selected-only` / `--no-cache-selected-only`](https://docs.getdbt.com/reference/global-configs/cache) | No action required | | [`--clean-project-files-only` / `--no-clean-project-files-only`](https://docs.getdbt.com/reference/commands/clean#--clean-project-files-only) | No action required | | `--single-threaded` / `--no-single-threaded` | No action required | | `dbt source freshness` [`--output` / `-o`](https://docs.getdbt.com/docs/deploy/source-freshness) | | | [`--config-dir`](https://docs.getdbt.com/reference/commands/debug) | No action required | | [`--resource-type` / `--exclude-resource-type`](https://docs.getdbt.com/reference/global-configs/resource-type) | change to `--resource-types` / `--exclude-resource-types` | | `--show-resource-report` / `--no-show-resource-report` | No action required | | [`--log-cache-events` / `--no-log-cache-events`](https://docs.getdbt.com/reference/global-configs/logs#logging-relational-cache-events) | No action required | | `--use-experimental-parser` / `--no-use-experimental-parser` | No action required | | [`--empty-catalog`](https://docs.getdbt.com/reference/commands/cmd-docs#dbt-docs-generate) | | | [`--compile` / `--no-compile`](https://docs.getdbt.com/reference/commands/cmd-docs#dbt-docs-generate) | | | `--inline-direct` | No action required | | `--partial-parse-file-diff` / `--no-partial-parse-file-diff` | No action required | | `--partial-parse-file-path` | No action required | | `--populate-cache` / `--no-populate-cache` | No action required | | `--static-parser` / `--no-static-parser` | No action required | | `--use-fast-test-edges` / `--no-use-fast-test-edges` | No action required | | [`--introspect` / `--no-introspect`](https://docs.getdbt.com/reference/commands/compile#introspective-queries) | No action required | | `--inject-ephemeral-ctes` / `--no-inject-ephemeral-ctes` | | | [`--partial-parse` / `--no-partial-parse`](https://docs.getdbt.com/reference/parsing#partial-parsing) | No action required | #### Conflicting package versions when a local package depends on a hub package which the root package also wants will error[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-fusion#conflicting-package-versions-when-a-local-package-depends-on-a-hub-package-which-the-root-package-also-wants-will-error "Direct link to Conflicting package versions when a local package depends on a hub package which the root package also wants will error") If a local package depends on a hub package that the root package also wants, `dbt deps` doesn't resolve conflicting versions in dbt Core v1; it will install whatever the root project requests. Fusion will present an error: error: dbt8999: Cannot combine non-exact versions: =0.8.3 and =1.1.1 #### Parse will fail on nonexistent macro invocations and adapter methods[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-fusion#parse-will-fail-on-nonexistent-macro-invocations-and-adapter-methods "Direct link to Parse will fail on nonexistent macro invocations and adapter methods") When you call a nonexistent macro in dbt: select id as payment_id, # my_nonexistent_macro is a macro that DOES NOT EXIST {{ my_nonexistent_macro('amount') }} as amount_usd,from app_data.payments Or a nonexistent adapter method: {{ adapter.does_not_exist() }} In dbt Core v1, `dbt parse` passes, but `dbt compile` fails. Fusion will error out during `parse`. #### Parse will fail on missing generic test[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-fusion#parse-will-fail-on-missing-generic-test "Direct link to Parse will fail on missing generic test") When you have an undefined generic test in your project: models: - name: dim_wizards data_tests: - does_not_exist In dbt Core v1, `dbt parse` passes, but `dbt compile` fails. Fusion will error out during `parse`. #### Parse will fail on missing variable[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-fusion#parse-will-fail-on-missing-variable "Direct link to Parse will fail on missing variable") When you have an undefined variable in your project: select {{ var('does_not_exist') }} as my_column In dbt Core v1, `dbt parse` passes, but `dbt compile` fails. Fusion will error out during `parse`. #### End of support for legacy manifest versions[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-fusion#end-of-support-for-legacy-manifest-versions "Direct link to End of support for legacy manifest versions") You can no longer interoperate with pre-1.8 versions of dbt-core if you're a: * Hybrid customer running Fusion and an old (pre-v1.8) version of dbt Core * Customer upgrading from the old (pre-v1.8) version of dbt Core to Fusion Fusion can not interoperate with the old manifest, which powers features like deferral for `state:modified` comparison. #### `dbt clean` will not delete any files in configured resource paths or files outside the project directory[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-fusion#dbt-clean-will-not-delete-any-files-in-configured-resource-paths-or-files-outside-the-project-directory "Direct link to dbt-clean-will-not-delete-any-files-in-configured-resource-paths-or-files-outside-the-project-directory") In dbt Core v1, `dbt clean` deletes: * Any files outside the project directory if `clean-targets` is configured with an absolute path or relative path containing `../`, though there is an opt-in config to disable this (`--clean-project-files-only` / `--no-clean-project-files-only`). * Any files in the `asset-paths` or `doc-paths` (even though other resource paths, like `model-paths` and `seed-paths`, are restricted). In Fusion, `dbt clean` will not delete any files in configured resource paths or files outside the project directory. #### All unit tests are run first in `dbt build`[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-fusion#all-unit-tests-are-run-first-in-dbt-build "Direct link to all-unit-tests-are-run-first-in-dbt-build") In dbt Core v1, the direct parents of the model being unit tested needed to exist in the warehouse to retrieve the needed column name and type information. `dbt build` runs the unit tests (and their dependent models) _in lineage order_. In Fusion, `dbt build` runs _all_ of the unit tests _first_, and then build the rest of the DAG, due to built-in column name and type awareness. #### Configuring `--threads`[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-fusion#configuring---threads "Direct link to configuring---threads") dbt Core runs with `--threads 1` by default. You can increase this number to run more nodes in parallel on the remote data platform, up to the max parallelism enabled by the DAG. In Fusion, if `--threads` is not set, or set to `--threads 0`, dbt will use a per-adapter default value for maximum threads. Some data platforms can handle more concurrent connections than others. If there is a user-configured value for `--threads` (via CLI flag or `profiles.yml`), Fusion will use it. #### Continue to compile unrelated nodes after hitting a compile error[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-fusion#continue-to-compile-unrelated-nodes-after-hitting-a-compile-error "Direct link to Continue to compile unrelated nodes after hitting a compile error") As soon as dbt Core's `compile` encounters an error compiling one of your models, dbt stops and doesn't compile anything else. When Fusion's `compile` encounters an error, it will skip nodes downstream of the one that failed to compile, but it will keep compiling the rest of the DAG (in parallel, up to the number of configured / optimal threads). #### Seeds with extra commas don't result in extra columns[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-fusion#seeds-with-extra-commas-dont-result-in-extra-columns "Direct link to Seeds with extra commas don't result in extra columns") In dbt Core v1, if you have an additional comma on your seed, dbt creates a seed with an additional empty column. For example, the following seed file (with an extra comma): animal, dog, cat, bear, Will produce this table when `dbt seed` is executed: | animal | b | | --- | --- | | dog | | | cat | | | bear | | Fusion will not produce this extra column in the table resulting from `dbt seed`: | animal | | --- | | dog | | cat | | bear | #### Move standalone anchors under `anchors:` key[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-fusion#move-standalone-anchors-under-anchors-key "Direct link to move-standalone-anchors-under-anchors-key") As part of the ongoing process of making the dbt authoring language more precise, unexpected top-level keys in a YAML file will result in errors. A common use case behind these unexpected keys is standalone anchor definitions at the top level of a YAML file. You can use the new top-level `anchors:` key as a container for these reusable configuration blocks. For example, rather than using this configuration: models/\_models.yml # id_column is not a valid name for a top-level key in the dbt authoring spec, and will raise an errorid_column: &id_column_alias name: id description: This is a unique identifier. data_type: int data_tests: - not_null - uniquemodels: - name: my_first_model columns: - *id_column_alias - name: unrelated_column_a description: This column is not repeated in other models. - name: my_second_model columns: - *id_column_alias Move the anchor under the `anchors:` key instead: models/\_models.yml anchors: - &id_column_alias name: id description: This is a unique identifier. data_type: int data_tests: - not_null - uniquemodels: - name: my_first_model columns: - *id_column_alias - name: unrelated_column_a description: This column is not repeated in other models - name: my_second_model columns: - *id_column_alias This move is only necessary for fragments defined outside of the main YAML structure. For more information about this new key, see [anchors](https://docs.getdbt.com/reference/resource-properties/anchors) . #### Algebraic operations in Jinja macros[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-fusion#algebraic-operations-in-jinja-macros "Direct link to Algebraic operations in Jinja macros") In dbt Core, you can set algebraic functions in the return function of a Jinja macro: {% macro my_macro() %}return('xyz') + 'abc'{% endmacro %} This is no longer supported in Fusion and will return an error. This is not a common use case and there is no deprecation warning for this behavior in dbt Core. The supported format is: {% macro my_macro() %}return('xyzabc'){% endmacro %} ### Package support[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-fusion#package-support "Direct link to Package support") The following packages are verified and supported on the dbt Fusion Engine: * [dbt-labs/audit\_helper](https://github.com/dbt-labs/dbt-audit-helper.git) * [dbt-labs/codegen](https://github.com/dbt-labs/dbt-codegen.git) * [dbt-labs/dbt\_project\_evaluator](https://github.com/dbt-labs/dbt-project-evaluator.git) * [dbt-labs/dbt\_utils](https://github.com/dbt-labs/dbt-utils.git) * [fivetran/ad\_reporting](https://github.com/fivetran/dbt_ad_reporting.git) * [fivetran/facebook\_ads](https://github.com/fivetran/dbt_facebook_ads.git) * [fivetran/fivetran\_log](https://github.com/fivetran/dbt_fivetran_log.git) * [fivetran/fivetran\_utils](https://github.com/fivetran/dbt_fivetran_utils.git) * [fivetran/google\_ads](https://github.com/fivetran/dbt_google_ads.git) * [fivetran/hubspot](https://github.com/fivetran/dbt_hubspot.git) * [fivetran/jira](https://github.com/fivetran/dbt_jira.git) * [fivetran/linkedin](https://github.com/fivetran/dbt_linkedin.git) * [fivetran/microsoft\_ads](https://github.com/fivetran/dbt_microsoft_ads.git) * [fivetran/pendo](https://github.com/fivetran/dbt_pendo.git) * [fivetran/qualtrics](https://github.com/fivetran/dbt_qualtrics.git) * [fivetran/salesforce](https://github.com/fivetran/dbt_salesforce.git) * [fivetran/salesforce\_formula\_utils](https://github.com/fivetran/dbt_salesforce_formula_utils.git) * [fivetran/social\_media\_reporting](https://github.com/fivetran/dbt_social_media_reporting.git) * [fivetran/zendesk](https://github.com/fivetran/dbt_zendesk.git) * [GJMcClintock/dbt\_tld](https://github.com/GJMcClintock/dbt_tld.git) * [godatadriven/dbt\_date](https://github.com/godatadriven/dbt-date.git) * [metaplane/dbt\_expectations](https://github.com/metaplane/dbt-expectations.git) * [Montreal-Analytics/snowflake\_utils](https://github.com/Montreal-Analytics/dbt-snowflake-utils.git) Additionally, the Fivetran `source` and `transformation` packages have been combined into a single package. If you manually installed source packages like `fivetran/github_source`, you need to ensure `fivetran/github` is installed and deactivate the transformation models. Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [More information about Fusion](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-fusion#more-information-about-fusion) * [What to know before upgrading](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-fusion#what-to-know-before-upgrading) * [Supported adapters](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-fusion#supported-adapters) * [A clean slate](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-fusion#a-clean-slate) * [Ecosystem packages](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-fusion#ecosystem-packages) * [Changed functionality](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-fusion#changed-functionality) * [Package support](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-fusion#package-support) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/dbt-versions/core-upgrade/04-upgrading-to-fusion.md) --- # Data health signals | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/explore/data-health-signals#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page Data health signals offer a quick, at-a-glance view of data health when browsing your resources in Catalog. They keep you informed on the status of your resource's health using the indicators **Healthy**, **Caution**, **Degraded**, or **Unknown**. Note, we don’t calculate data health for non-dbt resources. * Supported resources are [models](https://docs.getdbt.com/docs/build/models) , [sources](https://docs.getdbt.com/docs/build/sources) , and [exposures](https://docs.getdbt.com/docs/build/exposures) . * For accurate health data, ensure the resource is up-to-date and had a recent job run. * Each data health signal reflects key data health components, such as test success status, missing resource descriptions, missing tests, absence of builds in 30-day windows, [and more](https://docs.getdbt.com/docs/explore/data-health-signals#data-health-signal-criteria) . [![View data health signals for your models.](https://docs.getdbt.com/img/docs/collaborate/dbt-explorer/data-health-signal.jpg?v=2 "View data health signals for your models.")](https://docs.getdbt.com/docs/explore/data-health-signals#) View data health signals for your models. Access data health signals[​](https://docs.getdbt.com/docs/explore/data-health-signals#access-data-health-signals "Direct link to Access data health signals") --------------------------------------------------------------------------------------------------------------------------------------------------------------- Access data health signals in the following places: * In the [search function](https://docs.getdbt.com/docs/explore/explore-projects#search-resources) or under **Models**, **Sources**, or **Exposures** in the **Resource** tab. * For sources, the data health signal also indicates the [source freshness](https://docs.getdbt.com/docs/deploy/source-freshness) status. * In the **Health** column on [each resource's details page](https://docs.getdbt.com/docs/explore/explore-projects#view-resource-details) . Hover over or click the signal to view detailed information. * In the **Health** column of public models tables. * In the [DAG lineage graph](https://docs.getdbt.com/docs/explore/explore-projects#project-lineage) . Click any node to open the node details panel where you can view it and its details. * In [Data health tiles](https://docs.getdbt.com/docs/explore/data-tile) through an embeddable iFrame and visible in your BI dashboard. [![Access data health signals in multiple places in dbt Catalog.](https://docs.getdbt.com/img/docs/collaborate/dbt-explorer/data-health-signal.gif?v=2 "Access data health signals in multiple places in dbt Catalog.")](https://docs.getdbt.com/docs/explore/data-health-signals#) Access data health signals in multiple places in dbt Catalog. Data health signal criteria[​](https://docs.getdbt.com/docs/explore/data-health-signals#data-health-signal-criteria "Direct link to Data health signal criteria") ------------------------------------------------------------------------------------------------------------------------------------------------------------------ Each resource has a health state that is determined by specific set of criteria. Select the following tabs to view the criteria for that resource type. * Models * Sources * Exposures The health state of a model is determined by the following criteria: | **Health state** | **Criteria** | | --- | --- | | ✅ **Healthy** | All of the following must be true:

\- Built successfully in the last run
\- Built in the last 30 days
\- Model has tests configured
\- All tests passed
\- All upstream [sources are fresh](https://docs.getdbt.com/docs/build/sources#source-data-freshness)
or freshness is not applicable (set to `null`)
\- Has a description | | 🟡 **Caution** | One of the following must be true:

\- Not built in the last 30 days
\- Tests are not configured
\- Tests return warnings
\- One or more upstream sources are stale:
    - Has a freshness check configured
    - Freshness check ran in the past 30 days
    - Freshness check returned a warning
\- Missing a description | | 🔴 **Degraded** | One of the following must be true:

\- Model failed to build
\- Model has failing tests
\- One or more upstream sources are stale:
    - Freshness check hasn’t run in the past 30 days
    - Freshness check returned an error | | ⚪ **Unknown** | \- Unable to determine health of resource; no job runs have processed the resource. | The health state of a source is determined by the following criteria: | **Health state** | **Criteria** | | --- | --- | | ✅ Healthy | All of the following must be true:

\- Freshness check configured
\- Freshness check passed
\- Freshness check ran in the past 30 days
\- Has a description | | 🟡 Caution | One of the following must be true:

\- Freshness check returned a warning
\- Freshness check not configured
\- Freshness check not run in the past 30 days
\- Missing a description | | 🔴 Degraded | \- Freshness check returned an error | | ⚪ Unknown | Unable to determine health of resource; no job runs have processed the resource. | The health state of an exposure is determined by the following criteria: | **Health state** | **Criteria** | | --- | --- | | ✅ Healthy | All of the following must be true:

\- Underlying sources are fresh
\- Underlying models built successfully
\- Underlying models’ tests passing | | 🟡 Caution | One of the following must be true:

\- At least one underlying source’s freshness checks returned a warning
\- At least one underlying model was skipped
\- At least one underlying model’s tests returned a warning | | 🔴 Degraded | One of the following must be true:

\- At least one underlying source’s freshness checks returned an error
\- At least one underlying model did not build successfully
\- At least one model’s tests returned an error | Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Access data health signals](https://docs.getdbt.com/docs/explore/data-health-signals#access-data-health-signals) * [Data health signal criteria](https://docs.getdbt.com/docs/explore/data-health-signals#data-health-signal-criteria) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/explore/data-health-signals.md) --- # Explore multiple projects | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/explore/explore-multiple-projects#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page View all the projects and public models in your account (where public models are defined) and gain a better understanding of your cross-project resources and how they're used. On-demand learning If you enjoy video courses, check out our [dbt Catalog on-demand course](https://learn.getdbt.com/courses/dbt-catalog) and learn how to best explore your dbt project(s)! The resource-level lineage graph for a project displays the cross-project relationships in the DAG, with a **PRJ** icon indicating whether or not it's a project resource. That icon is located to the left side of the node name. To view the project-level lineage graph, click the **View lineage** icon in the upper right corner from the main overview page: * This view displays all the projects in your account and their relationships. * Viewing an upstream (parent) project displays the downstream (child) projects that depend on it. * Selecting a model reveals its dependent projects in the lineage. * Click on an upstream (parent) project to view the other projects that reference it in the **Relationships** tab, showing the number of downstream (child) projects that depend on them. * This includes all projects listing the upstream one as a dependency in its `dependencies.yml` file, even without a direct `{{ ref() }}`. * Selecting a project node from a public model opens its detailed lineage graph if you have the [permissions](https://docs.getdbt.com/docs/cloud/manage-access/enterprise-permissions) to do so. Indirect dependencies When viewing a project's lineage, Catalog shows only _directly_ [referenced](https://docs.getdbt.com/docs/mesh/govern/project-dependencies) public models. It doesn't show [indirect dependencies](https://docs.getdbt.com/faqs/Project_ref/indirectly-reference-upstream-model) . If a referenced model in your project depends on another upstream public model, the second-level model won't appear in Catalog, however it will appear in the [Studio IDE](https://docs.getdbt.com/docs/cloud/dbt-cloud-ide/develop-in-the-cloud) lineage view. [![View your cross-project lineage in a parent project and the other projects that reference it by clicking the 'Relationships' tab.](https://docs.getdbt.com/img/docs/collaborate/dbt-explorer/cross-project-lineage-parent.png?v=2 "View your cross-project lineage in a parent project and the other projects that reference it by clicking the 'Relationships' tab.")](https://docs.getdbt.com/docs/explore/explore-multiple-projects#) View your cross-project lineage in a parent project and the other projects that reference it by clicking the 'Relationships' tab. When viewing a downstream (child) project that imports and refs public models from upstream (parent) projects: * Public models will show up in the lineage graph and you can click on them to view the model details. * Clicking on a model opens a side panel containing general information about the model, such as the specific dbt project that produces that model, description, package, and more. * Double-clicking on a model from another project opens the resource-level lineage graph of the parent project, if you have the permissions to do so. [![View a downstream (child) project that imports and refs public models from the upstream (parent) project.](https://docs.getdbt.com/img/docs/collaborate/dbt-explorer/cross-project-child.png?v=2 "View a downstream (child) project that imports and refs public models from the upstream (parent) project.")](https://docs.getdbt.com/docs/explore/explore-multiple-projects#) View a downstream (child) project that imports and refs public models from the upstream (parent) project. Explore the project-level lineage graph[​](https://docs.getdbt.com/docs/explore/explore-multiple-projects#explore-the-project-level-lineage-graph "Direct link to Explore the project-level lineage graph") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ For cross-project collaboration, you can interact with the DAG in all the same ways as described in [Explore your project's lineage](https://docs.getdbt.com/docs/explore/explore-projects#project-lineage) but you can also interact with it at the project level and view the details. If you have permissions for a project in the account, you can view all public models used across the entire account. However, you can only view full public model details and private models if you have permissions for the specific project where those models are defined. To view all the projects in your account (displayed as a lineage graph or list view): * Navigate to the top left section of the **Explore** page, near the navigation bar. * Hover over the project name and select the account name. This takes you to a account-level lineage graph page, where you can view all the projects in the account, including dependencies and relationships between different projects. * Click the **List view** icon in the page's upper right corner to see a list view of all the projects in the account. * The list view page displays a public model list, project list, and a search bar for project searches. * Click the **Lineage view** icon in the page's upper right corner to view the account-level lineage graph. [![View a downstream (child) project, which imports and refs public models from upstream (parent) projects.](https://docs.getdbt.com/img/docs/collaborate/dbt-explorer/account-level-lineage.gif?v=2 "View a downstream (child) project, which imports and refs public models from upstream (parent) projects.")](https://docs.getdbt.com/docs/explore/explore-multiple-projects#) View a downstream (child) project, which imports and refs public models from upstream (parent) projects. From the account-level lineage graph, you can: * Click the **Lineage view** icon (in the graph’s upper right corner) to view the cross-project lineage graph. * Click the **List view** icon (in the graph’s upper right corner) to view the project list. * Select a project from the **Projects** tab to switch to that project’s main **Explore** page. * Select a model from the **Public Models** tab to view the [model’s details page](https://docs.getdbt.com/docs/explore/explore-projects#view-resource-details) . * Perform searches on your projects with the search bar. * Select a project node in the graph (double-clicking) to switch to that particular project’s lineage graph. When you select a project node in the graph, a project details panel opens on the graph’s right-hand side where you can: * View counts of the resources defined in the project. * View a list of its public models, if any. * View a list of other projects that uses the project, if any. * Click **Open Project Lineage** to switch to the project’s lineage graph. * Click the **Share** icon to copy the project panel link to your clipboard so you can share the graph with someone. [![Select a downstream (child) project to open the project details panel for resource counts, public models associated, and more. ](https://docs.getdbt.com/img/docs/collaborate/dbt-explorer/multi-project-overview.gif?v=2 "Select a downstream (child) project to open the project details panel for resource counts, public models associated, and more. ")](https://docs.getdbt.com/docs/explore/explore-multiple-projects#) Select a downstream (child) project to open the project details panel for resource counts, public models associated, and more. Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Explore the project-level lineage graph](https://docs.getdbt.com/docs/explore/explore-multiple-projects#explore-the-project-level-lineage-graph) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/explore/explore-multiple-projects.md) --- # Changelog 2019 and 2020 | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page note This changelog references dbt versions that are no longer supported and have been removed from the docs. For more information about upgrading to a supported version of dbt in your dbt Cloud environment, read [Upgrade dbt version in Cloud](https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-version-in-cloud) . Welcome to the 2019 and 2020 changelog for the dbt application! You can use this changelog to see the highlights of what was new, fixed, and enhanced during this time period. dbt Cloud v1.1.16 (December 23, 2020)[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#dbt-cloud-v1116-december-23-2020 "Direct link to dbt Cloud v1.1.16 (December 23, 2020)") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ This release adds preview support for Databricks Spark in dbt and adds two new permission sets for Enterprise acccounts. #### Enhancements[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#enhancements "Direct link to Enhancements") * Added preview support for Databricks Spark support * Added two new Enterprise permission sets: Account Viewer and Project Creator #### Fixed[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#fixed "Direct link to Fixed") * Improve logging infrastructure for dbt run logs * Fix for SSH tunnel logging errors dbt Cloud v1.1.15 (December 10, 2020)[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#dbt-cloud-v1115-december-10-2020 "Direct link to dbt Cloud v1.1.15 (December 10, 2020)") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ Lots of great stuff to confer about this go-round: things really coalesced this week! Lots of excitement around adding Spark to the connection family, as well as knocking out some longstanding bugs. #### Enhancements[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#enhancements-1 "Direct link to Enhancements") * Add Spark as an option for database setup #### Fixed[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#fixed-1 "Direct link to Fixed") * Fix this one hairy bug where one email could have multiple user accounts * Fix setup-connection react-page routing * Break out group selection logic from license types and group names * Handle JSON errors in v1/v2 body parsing * Handle AuthForbidden and AuthCancelled graciously - ie, not throw 500s * Fix regression with Studio IDE loading spinner dbt Cloud v1.1.14 (November 25, 2020)[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#dbt-cloud-v1114-november-25-2020 "Direct link to dbt Cloud v1.1.14 (November 25, 2020)") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ This release adds a few new pieces of connective tissue, notably OAuth for BigQuery and SparkAdapter work. There are also some quality of life improvements and investments for the future, focused on our beloved Studio IDE users, and some improved piping for observability into log management and API usage. #### Enhancements[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#enhancements-2 "Direct link to Enhancements") * Update IP allowlist * User can OAuth for BigQuery in profile credentials * Adding SparkAdapter backend models, mappers and services * Added BigQuery OAuth integration * Adding db index for owner\_thread\_id #### Fixed[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#fixed-2 "Direct link to Fixed") * Fix post /run error rate * Fix bug where bad argument was passed to dbt runs * Log out unhandled error in environment variable context manager * Remove account settings permissions for user integrations dbt Cloud v1.1.13 (November 12, 2020)[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#dbt-cloud-v1113-november-12-2020 "Direct link to dbt Cloud v1.1.13 (November 12, 2020)") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ This release adds support for triggering runs with overriden attributes via the [triggerRun](https://docs.getdbt.com/dbt-cloud/api-v2) API endpoint. Additionally, a number of bugs have been squashed and performance improvements have been made. #### Enhancements[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#enhancements-3 "Direct link to Enhancements") * Improve error handling for long-running queries in the Studio IDE * Use S3 client caching to improve log download speed for scheduled runs * Support triggering jobs [with overriden attributes from the API](https://docs.getdbt.com/dbt-cloud/api-v2) * Clarify "upgrade" copy on the billing page #### Fixed[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#fixed-3 "Direct link to Fixed") * GitLab groups endpoint now returns all groups and subgroups * Support BigQuery retry configs with value 0 * Prevent web IDE from crashing after running an invalid dbt command * Apply additional log scrubbing to filter short-lived git credentials * Fix older migration to make auth\_url field nullable * Support paths in GitLab instance URL * Fix for auth token request url in GitLab oauth flow dbt Cloud v1.1.12 (October 30, 2020)[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#dbt-cloud-v1112-october-30-2020 "Direct link to dbt Cloud v1.1.12 (October 30, 2020)") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- This release adds dbt v.18.1 and 0.19.0b1 to dbt Cloud. Additionally, a number of bugs have been fixed. #### Enhancements[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#enhancements-4 "Direct link to Enhancements") * Update copy on billing page for picking a plan at the end of a trial * Improved authorization for metadata API * Add dbt 0.19.0b1 * Add dbt 0.18.1 #### Fixed[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#fixed-4 "Direct link to Fixed") * Fixed an issue where groups from other logged-in accounts appeared in the RBAC UI * Fixed requested GitLab scopes and an issue when encrypting deploy tokens for GitLab auth * Fixed an issue where null characters in logs threw errors in scheduled runs dbt Cloud v1.1.11 (October 15, 2020)[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#dbt-cloud-v1111-october-15-2020 "Direct link to dbt Cloud v1.1.11 (October 15, 2020)") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Release v1.1.11 includes some quality-of-life enhancements, copy tweaks, and error resolutions. It also marks the last time we'll have the same digit four times in a row in a release until v2.2.22. #### Enhancements[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#enhancements-5 "Direct link to Enhancements") * Add InterfaceError exception handling for commands * Rename My Account --> Profile * Add project and connection to admin backend #### Fixed[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#fixed-5 "Direct link to Fixed") * Resolve errors from presence of null-characters in logs * Email verifications backend * Undo run.serialize * Fix error while serialized run * Fix logic error in connection setup * Fix a bug with GitLab auth flow for unauthenticated users * Fix bug where Native Okta SSO uses the wrong port dbt Cloud v1.1.10 (October 8, 2020)[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#dbt-cloud-v1110-october-8-2020 "Direct link to dbt Cloud v1.1.10 (October 8, 2020)") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ This release adds support for repositories imported via GitLab (Enterprise) and contains a number of bugfixes and improvements in the Studio IDE. #### Enhancements[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#enhancements-6 "Direct link to Enhancements") * Add Gitlab integration (Enterprise) * Add GitLab repository setup to project setup flow (Enterprise) * Add GitLab automated Deploy Token installation (Enterprise) * Add dbt 0.18.1rc1 #### Fixed[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#fixed-6 "Direct link to Fixed") * Fix bug where Studio IDE gets stuck after changing project repository * Fix race condition where connections can be added to the wrong project * Fix revoking email invites * Fix a bug in slim CI deferring run search where missing previous run caused the scheduler to raise an error * Fix a source of Studio IDE instability * Gracefully clean up Studio IDE backend on shutdown * Always show SSO mappings on Group Details page dbt Cloud v1.1.9 (October 1, 2020)[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#dbt-cloud-v119-october-1-2020 "Direct link to dbt Cloud v1.1.9 (October 1, 2020)") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- This release adds the ability for admins on the Enterprise plan to configure the Role Based Access Control permissions applied to Projects in their account. Additionally, job execution deferral is now available behind a feature flag, and a number of fixes and improvements were released as well. #### Enhancements[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#enhancements-7 "Direct link to Enhancements") * Add dbt version in the navigation sidebar * Add RBAC Group Permission view, create, and modify UIs * Add personal git auth for Studio IDE error handling modals * Add Develop Requests to backend views * Implemented job execution deferral * Add support for dbt v0.18.1b2 #### Fixed[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#fixed-7 "Direct link to Fixed") * Fixed the scenario where interacting with the Refresh Studio IDE button causes an index.lock file to remain in the Studio IDE file system * Validate PR URL for XSS attempts * Address RBAC inconsistencies * Fixed users not being able to update their dbt password in-app * Fix for applying user permissions across multiple accounts after SSO auth * Google API: default to common api endpoint but allow override * Fix for missing email variable in GSuite debug logging * Destroy Studio IDE session when switching projects dbt Cloud v1.1.8 (September 17, 2020)[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#dbt-cloud-v118-september-17-2020 "Direct link to dbt Cloud v1.1.8 (September 17, 2020)") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ This release adds native support for Okta SSO and dbt v0.18.0. It also adds initial support for a GitLab integration and self-service RBAC configuration. #### Enhancements[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#enhancements-8 "Direct link to Enhancements") * Add dbt 0.18.0 * Add native Okta SSO support * Add additional logging for Gsuite and Azure SSO * Add git cloning support via GitLab deploy tokens for scheduled runs (coming soon) * add RBAC Groups Detail Page and Groups List UIs #### Fixed[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#fixed-8 "Direct link to Fixed") * Allow `*_proxy` env vars in scheduled runs dbt Cloud v1.1.7 \[September 3, 2020\][​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#dbt-cloud-v117-september-3-2020 "Direct link to dbt Cloud v1.1.7 [September 3, 2020]") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- This release adds a Release Candidate for [dbt v0.18.0](https://docs.getdbt.com/docs/dbt-versions/core-upgrade) and includes bugfixes and improvements to the Cloud IDE and job scheduler. #### Enhancements[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#enhancements-9 "Direct link to Enhancements") * Improve scheduler backoff behavior * Add dbt 0.18.0rc1 * Add support for non-standard ssh ports in connection tunnels * Add support for closing the Studio IDE filesystem context menu by clicking outside the menu #### Fixed[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#fixed-9 "Direct link to Fixed") * Fix for joining threads in run triggers * Fix thread caching for s3 uploads dbt Cloud v1.1.6 (August 20, 2020)[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#dbt-cloud-v116-august-20-2020 "Direct link to dbt Cloud v1.1.6 (August 20, 2020)") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- This release includes security enhancements and improvements across the entire dbt application. #### Enhancements[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#enhancements-10 "Direct link to Enhancements") * Support for viewing development docs inside of the Studio IDE ([docs](https://docs.getdbt.com/docs/cloud/dbt-cloud-ide/develop-in-the-cloud) * Change CI temporary schema names to be prefixed with `dbt_cloud` instead of `sinter` * Change coloring and iconography to improve accessibility and UX across the application * \[Enterprise\] Support the specification of multiple authorized domains in SSO configuration * \[On-premises\] Upgrade boto3 to support KIAM authentication #### Fixed[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#fixed-10 "Direct link to Fixed") * \[Enterprise\] Fix for missing IdP group membership mappings when users belong to >100 Azure AD groups * Disallow the creation of symlinks in the Studio IDE * Improve reliability of background cleanup processes * Improve performance and reliability of artifact management and PR webhook processing dbt Cloud v1.1.5 (August 4, 2020)[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#dbt-cloud-v115-august-4-2020 "Direct link to dbt Cloud v1.1.5 (August 4, 2020)") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ This release adds a major new feature to the Studio IDE: merge conflict resolution! It also includes changes to the job scheduler that cut the time and resource utilization significantly. #### Enhancements[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#enhancements-11 "Direct link to Enhancements") * Add dbt 0.17.2 * Add dbt 0.18.0 beta 2 * Add merge conflict resolution, a merge commit workflow, and merge abort workflow to the IDE * Deprecate dbt versions prior to 0.13.0 * Refactor to cut job scheduler loop time * Reduce extra database calls to account table in job scheduler loop * \[On-premises\] Allow clients to disable authentication for SMTP * \[On-premises\] Allow disabling of TLS for SMTP * \[On-premises\] Making k8s access mode for Studio IDE pods an environment variable * \[Security\] Force session cookie to be secure * Make api and admin modules flake8 complaint #### Fixed[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#fixed-11 "Direct link to Fixed") * Fix incorrect usage of `region_name` in KMS client * Fix a call to a deprecated Github API * Remove extraneous billing API calls during job scheduler loop * Fix error where refreshing the IDE would leave running dbt processes in a bad state dbt Cloud v1.1.4 (July 21, 2020)[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#dbt-cloud-v114-july-21-2020 "Direct link to dbt Cloud v1.1.4 (July 21, 2020)") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- This release dramatically speeds up the job scheduler. It adds a new stable dbt version (0.17.1) and a new prerelease (0.17.2b1), and it includes a number of bugfixes. #### Enhancements[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#enhancements-12 "Direct link to Enhancements") * Add dbt 0.17.2b1 * Add dbt 0.17.1 and set as default version * Speed up job scheduler by 50% * Added generate docs to rpc service and new view docs route * Queue limiting by account for scheduled jobs #### Fixed[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#fixed-12 "Direct link to Fixed") * Fix enterprise SSO configuration when old Auth0 Azure AD is configured * Do not schedule jobs for deleted job definitions or environments * Fix permissions issues * Fix a bug with metadata set in azure storage provider * Fixed error when switching to developer plan from trial * Fix authentication bug where we setup all accounts with same domain * \[Security\] Add security check to prevent potentially malicious html files in dbt docs dbt Cloud v1.1.3 (July 7, 2020)[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#dbt-cloud-v113-july-7-2020 "Direct link to dbt Cloud v1.1.3 (July 7, 2020)") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ This release contains a number of IDE features and bugfixes, a new release candidate of dbt, and a brand new Enterprise Single-Sign On method: Azure Active Directory! #### Enhancements[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#enhancements-13 "Direct link to Enhancements") * Add dbt 0.17.1rc3 * Snowflake: Add support for `client_session_keep_alive` config * Enterprise: Native Azure Oauth2 for Enterprise accounts * Studio IDE: Add custom command palette for finding files #### Fixed[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#fixed-13 "Direct link to Fixed") * Do not run CI builds for draft PRs in GitHub * Remove race condition when syncing account with stripe billing events * Enterprise: Fixed JIT provisioning bug impacting accounts with shared IdP domains * Studio IDE: Fix a regression with Github git clone method * Studio IDE: Fix a race condition where git clone didn't complete before user entered Studio IDE * Studio IDE: Fix bug with checking out an environment custom branch on Studio IDE refresh * Bigquery: Fix PR schema dropping dbt Cloud v1.1.2 (June 23, 2020)[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#dbt-cloud-v112-june-23-2020 "Direct link to dbt Cloud v1.1.2 (June 23, 2020)") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- This branch includes an important security fix, two new versions of dbt, and some miscellaneous fixes. #### Enhancements[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#enhancements-14 "Direct link to Enhancements") * Add project names to the account settings notifications section * Add dbt 0.17.1 release candidate * Update development dbt version to Marian Anderson * Add remember me to login page and expire user sessions at browser close * Adding Auth Provider and enabling Gsuite SSO for enterprise customers #### Fixed[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#fixed-14 "Direct link to Fixed") * \[Security\] Fix intra-account API key leakage * Support queries containing unicode characters in the Studio IDE dbt Cloud v1.1.1 (June 9, 2020)[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#dbt-cloud-v111-june-9-2020 "Direct link to dbt Cloud v1.1.1 (June 9, 2020)") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ This release includes dbt 0.17.0 and a number of IDE quality of life improvements. #### Enhancements[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#enhancements-15 "Direct link to Enhancements") * Added dbt 0.17.0 * Added the ability to create a new folder in the IDE * Added gitignore status to file system and display dbt artifacts, including directories dbt\_modules, logs and target * (Cloud only) Added rollbar and update some various error handling clean up * (On-premises only) Admin site: allow Repository's Pull Request Template field to be blank * (On-premises only) Added AWS KMS support #### Fixed[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#fixed-15 "Direct link to Fixed") * Expires old pending password reset codes when a new password reset is requested dbt Cloud v1.1.0 (June 2, 2020)[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#dbt-cloud-v110-june-2-2020 "Direct link to dbt Cloud v1.1.0 (June 2, 2020)") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ This release adds some new admin backend functionality, as well as automatic seat usage reporting. ### On-Premises Only[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#on-premises-only "Direct link to On-Premises Only") #### Added[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#added "Direct link to Added") * Added automatic reporting of seat usage. #### Changed[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#changed "Direct link to Changed") * Admins can now edit remote URLs for repository in the admin backend. * Admins can now edit credentials in the admin backend. * * * dbt Cloud v1.0.12 (May 27, 2020)[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#dbt-cloud-v1012-may-27-2020 "Direct link to dbt Cloud v1.0.12 (May 27, 2020)") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- This release contains a few bugfixes for the Studio IDE and email notifications, as well as the latest release candidate of 0.17.0. ### All versions[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#all-versions "Direct link to All versions") #### Added[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#added-1 "Direct link to Added") * Use the correct starter project tag, based on dbt version, when initializing a new project in the IDE * Added branch filtering to IDE git checkout UI. * Added dbt 0.17.0-rc3. #### Fixed[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#fixed-16 "Direct link to Fixed") * Fixed source freshness report for dbt version v0.17.0 * Fixed issue with checking-out git branches * Fixed issue of logs being omitted on long running queries in the Studio IDE * Fixed slack notifications failing to send if email notifications fail ### On-Premises Only[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#on-premises-only-1 "Direct link to On-Premises Only") #### Added[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#added-2 "Direct link to Added") * Added an Admin page for deleting credentials. * * * dbt Cloud v1.0.11 (May 19, 2020)[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#dbt-cloud-v1011-may-19-2020 "Direct link to dbt Cloud v1.0.11 (May 19, 2020)") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- This version adds some new permission sets, and a new release candidate of dbt. ### All versions[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#all-versions-1 "Direct link to All versions") #### Added[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#added-3 "Direct link to Added") * Added permission sets for Job Viewer, Job Admin and Analyst. * Added dbt 0.17.0-rc1 * * * dbt Cloud v1.0.10 (May 11, 2020)[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#dbt-cloud-v1010-may-11-2020 "Direct link to dbt Cloud v1.0.10 (May 11, 2020)") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### All versions[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#all-versions-2 "Direct link to All versions") #### Added[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#added-4 "Direct link to Added") * Added dbt 0.17.0-b1. * PR Url is now self serve configurable. * Added more granular permissions around creating and deleting permissions. (Account Admin can create new projects by default while both Account Admin and Project Admin can delete the projects they have permissions for by default) * Added an error message to display to users that do not have permissions set up for any projects on an account. #### Fixed[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#fixed-17 "Direct link to Fixed") * Removed .sql from CSV download filename * Fixed breaking JobDefinition API with new param custom\_branch\_only * Fixed Studio IDE query table column heading casing * * * dbt Cloud v1.0.9 (May 5, 2020)[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#dbt-cloud-v109-may-5-2020 "Direct link to dbt Cloud v1.0.9 (May 5, 2020)") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- This release includes bugfixes around how permissions are applied to runs and run steps, fixes a bug where the scheduler would hang up, and improves performance of the Studio IDE. ### All versions[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#all-versions-3 "Direct link to All versions") #### Fixed[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#fixed-18 "Direct link to Fixed") * Fixed permission checks around Runs and Run Steps, this should only affect Enterprise accounts with per-project permissions. * Fixed receiving arbitrary remote\_url when creating a git url repository. * Fixed issue when handling non-resource specific errors from RPC server in Studio IDE. * Fixed a bug where the scheduler would stop if the database went away. * Fixed IDE query results table not supporting horizontal scrolling. #### Changed[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#changed-1 "Direct link to Changed") * Improve Studio IDE query results performance. * Allow configuration on jobs to only run builds when environment target branch is env's custom branch. * Allow configuration of GitHub installation IDs in the admin backend. ### On-Premises Only[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#on-premises-only-2 "Direct link to On-Premises Only") #### Fixed[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#fixed-19 "Direct link to Fixed") * Fixed logic error for installations with user/password auth enabled in an on-premises context * * * dbt Cloud v1.0.8 (April 28, 2020)[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#dbt-cloud-v108-april-28-2020 "Direct link to dbt Cloud v1.0.8 (April 28, 2020)") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ This release adds a new version of dbt (0.16.1), fixes a number of IDE bugs, and fixes some dbt Cloud on-premises bugs. ### All versions[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#all-versions-4 "Direct link to All versions") #### Added[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#added-5 "Direct link to Added") * Add dbt 0.16.1 #### Fixed[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#fixed-20 "Direct link to Fixed") * Fixed Studio IDE filesystem loading to check for directories to ensure that load and write methods are only performed on files. * Fixed a bug with generating private keys for connection SSH tunnels. * Fixed issue preventing temporary PR schemas from being dropped when PR is closed. * Fix issues with Studio IDE tabs not updating query compile and run results. * Fix issues with query runtime timer in Studio IDE for compile and run query functions. * Fixed what settings are displayed on the account settings page to align with the user's permissions. * Fixed bug with checking user's permissions in frontend when user belonged to more than one project. * Fixed bug with access control around environments and file system/git interactions that occurred when using Studio IDE. * Fixed a bug with Environments too generously matching repository. #### Changed[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#changed-2 "Direct link to Changed") * Make the configured base branch in the Studio IDE read-only. * Support configuring groups using an account ID in the admin backend. * Use gunicorn webserver in Studio IDE. * Allow any repository with a Github installation ID to use build-on-PR. * Member and Owner Groups are now editable from admin UI. ### On-Premises Only[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#on-premises-only-3 "Direct link to On-Premises Only") #### Fixed[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#fixed-21 "Direct link to Fixed") * Fixed an issue where account license counts were not set correctly from onprem license file. * Fixed an issue where docs would sometimes fail to load due to a server error. * * * dbt Cloud v1.0.7 (April 13, 2020)[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#dbt-cloud-v107-april-13-2020 "Direct link to dbt Cloud v1.0.7 (April 13, 2020)") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ This release rolls out a major change to how permissions are applied in dbt's API. It also adds some minor bugfixes, and some tooling for improved future QA. ### All versions[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#all-versions-5 "Direct link to All versions") #### Added[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#added-6 "Direct link to Added") * Added support to permission connections on a per project basis. * Added support to permission credentials on a per project basis. * Added support to permission repositories on a per project basis. * Smoke tests for account signup, user login and basic project setup * Add dbt 0.16.1rc1 * Non-enterprise users can now add new accounts from the Accounts dropdown. #### Fixed[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#fixed-22 "Direct link to Fixed") * Fix missing migration for credentials. * Fixed issue with testing connections with a non-default target name specified in the credentials. * Fix issue where Bigquery connections could be created with invalid values for `location`. * * * dbt Cloud v1.0.6 (March 30, 2020)[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#dbt-cloud-v106-march-30-2020 "Direct link to dbt Cloud v1.0.6 (March 30, 2020)") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ This release adds UIs to select group permissions in the project settings UI. It also contains bugfixes for the Studio IDE, PR build schema dropping, and adds support for dissociating Github and Slack integrations via the Admin backend. ### All versions[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#all-versions-6 "Direct link to All versions") #### Added[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#added-7 "Direct link to Added") * (Enterprise only) Added ability to create group permissions for specific projects in the project settings UI. #### Fixed[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#fixed-23 "Direct link to Fixed") * Fix empty state for selecting github repositories * Fixed an issue with the IDE failing to report an invalid project subdirectory for a dbt project * Fix blank loading screen displayed when switching accounts while on account/profile settings page * Fix issue preventing schemas from dropping during PR builds * Fix issue where whitespace in user's name breaks default schema name * Added webhook processing for when a user disassociates github access to their account. * Added slack disassociation capability on user integrations page and on backend admin panel (for notifications). #### Changed[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#changed-3 "Direct link to Changed") * Declare application store using configureStore from redux-toolkit * * * dbt Cloud v1.0.5 (March 23, 2020)[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#dbt-cloud-v105-march-23-2020 "Direct link to dbt Cloud v1.0.5 (March 23, 2020)") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ ### All versions[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#all-versions-7 "Direct link to All versions") #### Added[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#added-8 "Direct link to Added") * Add support for authenticating Development and Deployment Snowflake credentials using keypair auth * Add support for checking out tags, render git output in "clone" run step * Add dbt 0.15.3 * Add dbt 0.16.0 #### Fixed[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#fixed-24 "Direct link to Fixed") * Git provider urls now built with correct github account and repository directories. * Invalid DateTime Start time in Studio IDE Results Panel KPIs. * Fix a race condition causing the Invite User UI to not work properly. * Incorrect model build times in Studio IDE. #### Changed[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#changed-4 "Direct link to Changed") * Git: ignore `logs/` and `target/` directories in the IDE. * * * 1.0.4 (March 16, 2020)[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#104-march-16-2020 "Direct link to 1.0.4 (March 16, 2020)") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- This release adds two new versions of dbt, adds Snowflake SSO support for Enterprise accounts, and fixes a number of bugs. ### All versions[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#all-versions-8 "Direct link to All versions") #### Added[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#added-9 "Direct link to Added") * Added dbt 0.15.3rc1 * Added dbt 0.16.0rc2 * Add support for cloning private deps in the IDE when using deploy key auth. * Log user that kicked off manual runs. * Enterprise support for authenticating user Snowflake connections using Snowflake single sign-on #### Fixed[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#fixed-25 "Direct link to Fixed") * Fixed issue loading accounts for a user if they lack permissions for any subset of accounts they have a user license for. * Fixed issue with showing blank page for user who is not associated with any accounts. * Fixed issue where runs would continue to kick off on a deleted project. * Fixed issue where accounts connected to GitHub integrations with SAML protection could not import repositories * Improved error messages shown to the user if repos are unauthorized in a GitHub integration when importing a repo * Fix colors of buttons in generated emails ### On-Premises[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#on-premises "Direct link to On-Premises") #### Added[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#added-10 "Direct link to Added") * Added Admin backend UIs for managing user permissions. * * * 1.0.3 (March 1, 2020)[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#103-march-1-2020 "Direct link to 1.0.3 (March 1, 2020)") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ This release contains the building blocks for RBAC, and a number of bugfixes and upgrades. ### All versions[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#all-versions-9 "Direct link to All versions") #### Added[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#added-11 "Direct link to Added") * Add support for a read replica for reading runs from the API. * Added groups, group permissions, and user groups. * Add email address to email verification screen. * Add Enterprise Permissions. * Allow account-level access to resources for groups with a permission statement of "all resources" for api backwards compatibility. * Add dbt 0.16.0b3 #### Fixed[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#fixed-26 "Direct link to Fixed") * Fix issue with loading projects after switching accounts. * Fix broken links to connections from deployment environment settings. * Fix a bug with inviting readonly users. * Fix a bug where permissions were removed from Enterprise users upon login. #### Changed[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#changed-5 "Direct link to Changed") * Update Django version: 2.2.10 * Update Django admin panel version * Update Social Auth version and the related Django component * Update jobs from using account-based resource permissions to project-based resource permissions * Update modal that shows when trials are expired; fix copy for past-due accounts in modal * Replace formatted string logging with structured logging * Move connection and repository settings from account settings to project settings * Update project setup flow to be used for creating projects * Update develop requests to have a foreign key on projects ### On-Premises[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#on-premises-1 "Direct link to On-Premises") #### Added[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#added-12 "Direct link to Added") * Accounts created from admin backend will come with a default set of groups #### Changed[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#changed-6 "Direct link to Changed") * Rename "Fishtown Analytics User" to "Superuser" * * * dbt Cloud v1.0.2 (February 20, 2020)[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#dbt-cloud-v102-february-20-2020 "Direct link to dbt Cloud v1.0.2 (February 20, 2020)") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- This release contains a number of package upgrades, and a number of bugfixes. ### All versions[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#all-versions-10 "Direct link to All versions") #### Added[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#added-13 "Direct link to Added") * Add request context data to logs * Comprehensive logging for git subprocesses #### Fixed[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#fixed-27 "Direct link to Fixed") * Fix an issue where the "Cancel Run" button does not work * Fix warnings regarding mutable resource model defaults for jobs and job notifications * Fix bug where users can create multiple connection user credentials through the project setup workflow * Update auth for requests against Github's api from using query parameters to using an Authorization header * Remove unused threads input from deployment environments * Fix issue that prevented user from viewing documentation and data sources * Fix issue rendering code editor panel in the IDE when using Safari * Fix issue with log levels that caused dbt logs to be too chatty #### Changed[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#changed-7 "Direct link to Changed") * Update Django version: 2.2.10 * Update Django admin panel version * Update Social Auth version and the related Django component * Update jobs from using account-based resource permissions to project-based resource permissions * Update modal that shows when trials are expired; fix copy for past-due accounts in modal * Replace formatted string logging with structured logging * Move connection and repository settings from account settings to project settings * Update project setup flow to be used for creating projects #### Removed[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#removed "Direct link to Removed") None. * * * dbt Cloud v1.0.1 (February 4, 2020)[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#dbt-cloud-v101-february-4-2020 "Direct link to dbt Cloud v1.0.1 (February 4, 2020)") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ This release makes the IDE generally available, and adds two new versions of dbt (0.15.1, 0.15.2). For on-premises customers, there is a new set of configurations in the configuration console: SMTP: You can now configure dbt to send email notifications through your own SMTP server. RSA Encryption: You can now provide your own RSA keypair for dbt to use for encryption. These fields need to be specified for your instance of dbt to function properly. ### All versions[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#all-versions-11 "Direct link to All versions") #### Added[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#added-14 "Direct link to Added") * New Team List page * New Team User Detail page * New Invite User page * New dashboard for Read Only users * New dbt version: 0.15.1 * New dbt version: 0.15.2 * Ability to rename files in Studio IDE * New backend service for project-based resource permissions #### Fixed[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#fixed-28 "Direct link to Fixed") * Fix an issue where the user has to repeat steps in the onboarding flow * Fix issue where user can get stuck in the onboarding flow * Fix bug where email notifications could be sent to deleted users * Fix UI bug not allowing user to check "Build on pull request?" when creating a job * Fix UI bug in header of the Edit User page * Fix issue that did not take into account pending invites and license seats when re-sending a user invite. * Fix an issue when processing Github webhooks with unconfigured environments * Fix console warning presented when updating React state from unmounted component * Fix issue where closed tabs would continue to be shown, though the content was removed correctly * Fix issue that prevented opening an adjacent tab when a tab was closed * Fix issue creating BigQuery connections causing the account connections list to not load correctly. * Fix for locked accounts that have downgraded to the developer plan at trial end * Fix for not properly showing server error messages on the user invite page #### Changed[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#changed-8 "Direct link to Changed") * Deployed a number of Studio IDE visual improvements * Batch logs up every 5 seconds instead of every second to improve database performance * Make `retries` profile configuration for BigQuery connections optional * Support `retries` profile configuration for BigQuery connections (new in dbt v0.15.1) * Replace Gravatar images with generic person icons in the top navbar * Remove deprecated account subscription models * Remove external JS dependencies #### Removed[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#removed-1 "Direct link to Removed") * Remove the "read only" role (this is now a "read only" license type) * Remove the "standard" license type * Remove "beta" tag from Studio IDE * Remove unused frontend code (team page/create repository page and related services) ### Self-Service[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#self-service "Direct link to Self-Service") #### Fixed[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#fixed-29 "Direct link to Fixed") * Fix for locked accounts that have downgraded to the developer plan at trial end #### Added[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#added-15 "Direct link to Added") * New Plans page * Add a 14 day free trial * Add the ability to provision a new repository via dbt * New Invite Team step for project setup process for trial accounts #### Changed[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#changed-9 "Direct link to Changed") * The "Basic" and "Pro" plans are no longer available. The new "Developer" and "Team" plans are available. * Prorations are now charged immediately, instead of applied to the next billing cycle. * It is no longer possible to downgrade to a plan that does not support the current number of allocated seats. * A "Team" plan that has been cancelled will be locked (closed) at the end of the subscription's period ### On-Premises[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#on-premises-2 "Direct link to On-Premises") #### Added[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#added-16 "Direct link to Added") * Support custom SMTP settings * Support Azure Blob Storage for run logs + artifacts * Optionally disable anonymous usage tracking * * * dbt Cloud v0.5.0 (December 19, 2019)[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#dbt-cloud-v050-december-19-2019 "Direct link to dbt Cloud v0.5.0 (December 19, 2019)") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- This release preps dbt for the general Studio IDE release in January. Beta Studio IDE functionality can be turned on by checking "Develop file system" in the Accounts page in the dbt backend. ### All versions[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#all-versions-12 "Direct link to All versions") #### Added[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#added-17 "Direct link to Added") * New dbt version: 0.14.2 * New dbt version: 0.14.3 * New dbt version: 0.14.4 * New dbt version: 0.15.0 * New API endpoint: v3/projects * New API endpoint: v3/credentials * New API endpoint: v3/environments * New API endpoint: v3/events * Studio IDE: Add git workflow UI * Studio IDE: Add filesystem management * Studio IDE: Hup the server when files change * Studio IDE: Display server status and task history * Added development and deployment environments and credentials * Support `--warn-error` flag in dbt runs #### Fixed[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#fixed-30 "Direct link to Fixed") * Fixed an issue where the run scheduler would hang up when deleting PR schemas * Fixed an issue where the webhook processor would mark a webhook as processed without queuing a run * Fix a bug where SSH tunnels were not created for the Develop Studio IDE * Fix Develop Studio IDE scrolling in Firefox * Fix a bug where requests were timed out too aggressively * Require company name at signup * Fix security issue where IP blacklist could be bypassed using shorthand * Do a better job of handling git errors * Allow users to delete projects #### Changed[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#changed-10 "Direct link to Changed") * Move account picker to sidebar * Increase require.js timeout from 7s to 30s * Migrate environments to projects * Move some UIs into Account Settings * Make cron scheduling available on the free tier * Apply new styles to Studio IDE * Speed up develop Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [dbt Cloud v1.1.16 (December 23, 2020)](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#dbt-cloud-v1116-december-23-2020) * [dbt Cloud v1.1.15 (December 10, 2020)](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#dbt-cloud-v1115-december-10-2020) * [dbt Cloud v1.1.14 (November 25, 2020)](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#dbt-cloud-v1114-november-25-2020) * [dbt Cloud v1.1.13 (November 12, 2020)](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#dbt-cloud-v1113-november-12-2020) * [dbt Cloud v1.1.12 (October 30, 2020)](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#dbt-cloud-v1112-october-30-2020) * [dbt Cloud v1.1.11 (October 15, 2020)](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#dbt-cloud-v1111-october-15-2020) * [dbt Cloud v1.1.10 (October 8, 2020)](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#dbt-cloud-v1110-october-8-2020) * [dbt Cloud v1.1.9 (October 1, 2020)](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#dbt-cloud-v119-october-1-2020) * [dbt Cloud v1.1.8 (September 17, 2020)](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#dbt-cloud-v118-september-17-2020) * [dbt Cloud v1.1.7 \[September 3, 2020\]](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#dbt-cloud-v117-september-3-2020) * [dbt Cloud v1.1.6 (August 20, 2020)](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#dbt-cloud-v116-august-20-2020) * [dbt Cloud v1.1.5 (August 4, 2020)](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#dbt-cloud-v115-august-4-2020) * [dbt Cloud v1.1.4 (July 21, 2020)](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#dbt-cloud-v114-july-21-2020) * [dbt Cloud v1.1.3 (July 7, 2020)](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#dbt-cloud-v113-july-7-2020) * [dbt Cloud v1.1.2 (June 23, 2020)](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#dbt-cloud-v112-june-23-2020) * [dbt Cloud v1.1.1 (June 9, 2020)](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#dbt-cloud-v111-june-9-2020) * [dbt Cloud v1.1.0 (June 2, 2020)](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#dbt-cloud-v110-june-2-2020) * [On-Premises Only](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#on-premises-only) * [dbt Cloud v1.0.12 (May 27, 2020)](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#dbt-cloud-v1012-may-27-2020) * [All versions](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#all-versions) * [On-Premises Only](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#on-premises-only-1) * [dbt Cloud v1.0.11 (May 19, 2020)](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#dbt-cloud-v1011-may-19-2020) * [All versions](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#all-versions-1) * [dbt Cloud v1.0.10 (May 11, 2020)](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#dbt-cloud-v1010-may-11-2020) * [All versions](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#all-versions-2) * [dbt Cloud v1.0.9 (May 5, 2020)](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#dbt-cloud-v109-may-5-2020) * [All versions](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#all-versions-3) * [On-Premises Only](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#on-premises-only-2) * [dbt Cloud v1.0.8 (April 28, 2020)](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#dbt-cloud-v108-april-28-2020) * [All versions](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#all-versions-4) * [On-Premises Only](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#on-premises-only-3) * [dbt Cloud v1.0.7 (April 13, 2020)](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#dbt-cloud-v107-april-13-2020) * [All versions](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#all-versions-5) * [dbt Cloud v1.0.6 (March 30, 2020)](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#dbt-cloud-v106-march-30-2020) * [All versions](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#all-versions-6) * [dbt Cloud v1.0.5 (March 23, 2020)](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#dbt-cloud-v105-march-23-2020) * [All versions](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#all-versions-7) * [1.0.4 (March 16, 2020)](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#104-march-16-2020) * [All versions](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#all-versions-8) * [On-Premises](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#on-premises) * [1.0.3 (March 1, 2020)](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#103-march-1-2020) * [All versions](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#all-versions-9) * [On-Premises](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#on-premises-1) * [dbt Cloud v1.0.2 (February 20, 2020)](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#dbt-cloud-v102-february-20-2020) * [All versions](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#all-versions-10) * [dbt Cloud v1.0.1 (February 4, 2020)](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#dbt-cloud-v101-february-4-2020) * [All versions](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#all-versions-11) * [Self-Service](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#self-service) * [On-Premises](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#on-premises-2) * [dbt Cloud v0.5.0 (December 19, 2019)](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#dbt-cloud-v050-december-19-2019) * [All versions](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2019-2020#all-versions-12) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/dbt-versions/release-notes/99-dbt-cloud-changelog-2019-2020.md) --- # Changelog 2021 | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page note This changelog references dbt versions that are no longer supported and have been removed from the docs. For more information about upgrading to a supported version of dbt in your dbt environment, read [Upgrade dbt version in Cloud](https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-version-in-cloud) . Welcome to the 2021 changelog for the dbt application! You can use this changelog to see highlights of what was new, fixed, and enhanced. dbt Cloud v1.1.41 (December 8, 2021)[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#dbt-cloud-v1141-december-8-2021 "Direct link to dbt Cloud v1.1.41 (December 8, 2021)") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- It's one of the best weeks of the year - it's [Coalesce](https://coalesce.getdbt.com/) ! We'll have some exciting product announcements to share! Did somebody say [metrics](https://coalesce.getdbt.com/talks/keynote-metric-system/) and [dbt Core v1.0](https://coalesce.getdbt.com/talks/dbt-v10-reveal/) ?! #### New products and features[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#new-products-and-features "Direct link to New products and features") * dbt v1.0 is now available in dbt... nbd. #### Performance improvements and enhancements[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#performance-improvements-and-enhancements "Direct link to Performance improvements and enhancements") * Now whenever you log back into dbt, you'll return to the account and project that you most recently were working in! dbt Cloud v1.1.39 (November 10, 2021)[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#dbt-cloud-v1139-november-10-2021 "Direct link to dbt Cloud v1.1.39 (November 10, 2021)") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- We shipped environment variables in dbt. Environment variables create a way to separate code from configuration - allowing you to set config based on context and keep secrets like git tokens securely stored. #### New products and features[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#new-products-and-features-1 "Direct link to New products and features") * You can now add environment variables to your dbt project. Why does this matter? Environment variables are a fundamental building block of a dbt project, which until now, we only enabled in dbt Core. They power many use cases such as cloning private packages, limiting the amount of data that is processed in development environments, changing your data sources depending on the environment, and more. Read about environment variables in our [blog post](https://blog.getdbt.com/introducing-environment-variables-in-dbt-cloud/) or [docs](https://docs.getdbt.com/docs/build/environment-variables) . dbt Cloud v1.1.38 (October 27, 2021)[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#dbt-cloud-v1138-october-27-2021 "Direct link to dbt Cloud v1.1.38 (October 27, 2021)") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Have you used the [Metadata API](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-api) yet? The Metadata API is available to customers on the Team and Enterprise plans, and with it, you can learn tons about your dbt project, if it's running dbt v0.19.0 or later. You can now query information about _any_ run, not just the last run of a job. Mo' data, mo' fun! dbt Cloud v1.1.37 (October 13, 2021)[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#dbt-cloud-v1137-october-13-2021 "Direct link to dbt Cloud v1.1.37 (October 13, 2021)") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- dbt v0.21 is now available in dbt Cloud. The big change with this release is it introduces the `dbt build` command. `dbt build` logically does everything you'd want to do in your DAG. It runs your models, tests your tests, snapshots your snapshots, and seeds your seeds. It does this, resource by resource, from left to right across your DAG. dbt build is an opinionated task. It’s the culmination of all we’ve built- running models with resilient materializations, prioritizing data quality with tests, updating fixtures with seeds, capturing slowly changing dimensions with snapshot. Give it a try! #### New products and features[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#new-products-and-features-2 "Direct link to New products and features") * We have a new beta feature, which we're calling Model Bottlenecks. It allows you to visually see how long it takes to build models in each run, so you can see clearly which models are taking the longest. If you're interested in learning more, check out #beta-feedback-model-bottlenecks in the dbt community Slack, and we can add you to the beta. dbt Cloud v1.1.36 (September 29, 2021)[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#dbt-cloud-v1136-september-29-2021 "Direct link to dbt Cloud v1.1.36 (September 29, 2021)") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Check out the release candidate for `dbt v0.21.0`! Also tab switching in the dbt Cloud IDE now keeps track of your scroll position - at last! #### Bug fixes[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#bug-fixes "Direct link to Bug fixes") * Some Redshift customers were experiencing timeouts on runs. We've since fixed this bug by keeping the session alive longer. #### Performance improvements and enhancements[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#performance-improvements-and-enhancements-1 "Direct link to Performance improvements and enhancements") * You won't lose track of the code snippets you were looking at when you switch back and forth between tabs in the dbt Cloud IDE, as we now keep track of your scroll position. dbt Cloud v1.1.35 (September 15, 2021)[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#dbt-cloud-v1135-september-15-2021 "Direct link to dbt Cloud v1.1.35 (September 15, 2021)") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Have you ever been working in the Studio IDE, taken a several hour break from developing, and when you returned to your work, the Studio IDE started behaving in unexpected ways? Your develop session became inactive, without any notification. Well, that silent failure won’t happen anymore! dbt now will let you know when you have to refresh your Studio IDE so you can continue to pick up work where you last left off. #### New products and features[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#new-products-and-features-3 "Direct link to New products and features") * dbt v0.20.2 is released in dbt. #### Performance improvements and enhancements[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#performance-improvements-and-enhancements-2 "Direct link to Performance improvements and enhancements") * Set default threads to 4 for new jobs and in development creds. #### Bug fixes[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#bug-fixes-1 "Direct link to Bug fixes") * The user is now prompted to refresh the page when in a disconnected Studio IDE state. * dbt tasks that fail or error are now correctly ordered in the run drawer history. dbt Cloud v1.1.34 (September 1, 2021)[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#dbt-cloud-v1134-september-1-2021 "Direct link to dbt Cloud v1.1.34 (September 1, 2021)") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- We just launched our beta for supporting environment variables in dbt. Environment variables are exciting because they allow you to clone private packages. If you’re interested in joining the beta, check out the #beta-feedback-for-env-vars channel in dbt Slack for more information. #### Performance improvements and enhancements[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#performance-improvements-and-enhancements-3 "Direct link to Performance improvements and enhancements") Our Studio IDE SQL drawer got a fresh new look, and it now has improved accessibility. dbt Cloud v1.1.33 (August 18, 2021)[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#dbt-cloud-v1133-august-18-2021 "Direct link to dbt Cloud v1.1.33 (August 18, 2021)") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- We added a DAG in the Studio IDE, so that you can see your model dependencies as you develop! If you haven’t seen the DAG visualization yet, take a moment to spin up the Studio IDE, navigate to the Lineage tab, and click-click-click around in there — it is legitimately a brand new modality for developing dbt projects, and it’s something worth being excited about! #### New products and features[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#new-products-and-features-4 "Direct link to New products and features") * [Dashboard Status Tiles](https://docs.getdbt.com/docs/explore/data-tile) can now be embedded on dashboards (or anywhere you can embed an iFrame) to give immediate insight into data freshness and quality. This helps dbt project maintainers build trust internally about the data that end users are seeing. * We shipped DAG in the Studio IDE to GA! * Support for `dbt v0.20.1` in Cloud. #### Bug fixes[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#bug-fixes-2 "Direct link to Bug fixes") * Databricks users will now be able to see and update the token/schema for deployment environments. * Some Github users were experiencing a broken profile image in dbt. This should be fixed if users disconnect and reconnect their Github accounts. dbt Cloud v1.1.32 (August 4, 2021)[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#dbt-cloud-v1132-august-4-2021 "Direct link to dbt Cloud v1.1.32 (August 4, 2021)") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The Metadata API is now in GA! When dbt invokes certain commands like run, test, seed, etc, dbt generates metadata in the form of [artifacts](https://docs.getdbt.com/reference/artifacts/dbt-artifacts) . These artifacts give you tons of information about project set up, run times, test details, compiled SQL, and so much more. Now dbt serves a GraphQL API which supports arbitrary queries over these artifacts, so you can retrieve the metadata you want almost instantaneously. #### New products and features[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#new-products-and-features-5 "Direct link to New products and features") * The Metadata API is the start of our metadata product suite. Learn more about how to use the Metadata API [here](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-api) . * dbt Enterprise customers using GitHub now get better fine-grained access control in their dbt projects. dbt will enforce git permissions for every developer to ensure that read / write policies in GitHub carry through to the IDE. dbt Cloud v1.1.31 (July 21, 2021)[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#dbt-cloud-v1131-july-21-2021 "Direct link to dbt Cloud v1.1.31 (July 21, 2021)") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- We’ve improved the tabbing experience in the Studio IDE. Tabs now work much more intuitively, and you don’t have to worry about losing your work anymore! #### New products and features[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#new-products-and-features-6 "Direct link to New products and features") * We are working to release a DAG directly in the IDE, so that when you’re developing, you have a clear idea of where the model you’re working on sits in the dependency graph. If you’re interested in testing out the feature early, head over to the `#beta-feedback-for-ide-dag` channel in the dbt Slack, and we’ll get the new product feature-flagged on your account! * Added dbt 0.20.0 to Cloud #### Bug fixes[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#bug-fixes-3 "Direct link to Bug fixes") * Users will now be able to initialize any project that doesn't contain a `dbt_project.yml` file, regardless of whether or not there are pre-existing files and/or commits to that repo. #### Performance improvements and enhancements[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#performance-improvements-and-enhancements-4 "Direct link to Performance improvements and enhancements") * We've been working on some nice improvements to tabs in our Studio IDE. We’ve fixed deficiencies with tabs that caused users to lose work if they didn’t hit save regularly enough. Additionally, opening, closing, and the order of the tabs work much more smoothly. * You may have noticed that there is now a source freshness checkbox in your execution settings when you configure a job on dbt Cloud. Selecting this checkbox will run `dbt source freshness` as the first step in your job, but it will not break subsequent steps if it fails. Updated source freshness documentation available [here](https://docs.getdbt.com/docs/deploy/source-freshness) . * Added a new endpoint to allow API key rotation via `POST https://cloud.getdbt.com/api/v2/users/{user-id}/apikey` dbt Cloud v1.1.30 (July 7, 2021)[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#dbt-cloud-v1130-july-7-2021 "Direct link to dbt Cloud v1.1.30 (July 7, 2021)") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- We shipped a resizable folder pane in the Studio IDE, and we're hearing great things! "My quality of life has greatly increased with this little update!" Hope this helps everyone else enjoy the Studio IDE a little more too. #### New products and features[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#new-products-and-features-7 "Direct link to New products and features") * Resizable folder pane in the Studio IDE: Have you ever developed in the Studio IDE and not been able to see the full name of your model because you couldn’t adjust the width of the file pane? Yeah, us too. Now you’ll be able to adjust your project’s file tree width to be as wide or as narrow as you’d like. It’s these small things that make developing in the Studio IDE so much easier. #### Bug fixes[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#bug-fixes-4 "Direct link to Bug fixes") * Made some changes to GitLab webhooks so that the status of the dbt run gets properly updated in GitLab. * Resolved an issue where users saw a blank screen rather than the SSO reauthentication page. #### Performance improvements and enhancements[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#performance-improvements-and-enhancements-5 "Direct link to Performance improvements and enhancements") * Refreshed the design of the repository import page. dbt Cloud v1.1.29 (June 23, 2021)[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#dbt-cloud-v1129-june-23-2021 "Direct link to dbt Cloud v1.1.29 (June 23, 2021)") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- We're heads down working on a handful of new features that we're going to share at the end of this month. The finish line is in sight. In the meantime, check out our latest release candidates for dbt Core. The biggest changes are better tests, providing consistency, configurability, and persistence. Additionally, we've refactored partial parsing and introduced an experimental parser; both are set to off by default. #### New products and features[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#new-products-and-features-8 "Direct link to New products and features") * Add support for latest Core release candidates to dbt: v0.19.2-rc2 and v0.20.0-rc1 #### Bug fixes[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#bug-fixes-5 "Direct link to Bug fixes") * Add a safeguard for the SSO reauth page to avoid 401 interceptors #### Performance improvements and enhancements[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#performance-improvements-and-enhancements-6 "Direct link to Performance improvements and enhancements") * Ensure navigation bar is in dark mode when Studio IDE is set to dark mode dbt Cloud v1.1.28 (June 9, 2021)[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#dbt-cloud-v1128-june-9-2021 "Direct link to dbt Cloud v1.1.28 (June 9, 2021)") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- We shipped a far better experience for GitLab users. Be sure to check out new CI features that are now available for customers using GitLab. Additionally, all developers should test out Slim CI which will speed up their model builds. #### New products and features[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#new-products-and-features-9 "Direct link to New products and features") * `Slim CI`: We’ve made Slim CI available for all our cloud customers! With Slim CI, you don't have to rebuild and test all your models; you can instruct dbt Cloud to run jobs on only modified or new resources. If you are a GitHub or GitLab user, try creating a new job that runs on pull requests and you can signal to dbt to run only on these modified resources by including the `state:modified+` argument. Read more about Slim CI [here](https://docs.getdbt.com/docs/deploy/continuous-integration) . * Native GitLab authentication for dbt Developer and Team Tiers: We’ve shipped native GitLab auth into GA. You can now import new GitLab repos with a couple clicks, trigger CI builds when Merge Requests are opened in GitLab, and carry GitLab permissions through to Studio IDE's git actions. Read how to set up native GitLab auth [here](https://docs.getdbt.com/docs/cloud/git/connect-gitlab) . #### Bug fixes[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#bug-fixes-6 "Direct link to Bug fixes") * Allow users to select artifacts from a job that runs source freshness on jobs with the source freshness execution settings set to `ON`. * Resolve `RUN ONLY ON CUSTOM BRANCH?` button to toggle on and off properly. * Retain information in a `Statement` tab when the page is refreshed. * Unsaved changes in the Studio IDE are now saved when committing work. * Drop temporary schemas in the data warehouse for closed or merged GitLab merge requests. #### Performance improvements and enhancements[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#performance-improvements-and-enhancements-7 "Direct link to Performance improvements and enhancements") * Behind the scenes, we’ve been moving off of Angular and onto React. We’ve started the process of migrating the central pieces of our UI over - the first of which is the main navigation. We think this will have a big impact on our ability to reduce UI bugs and improve user experience. * Added support for dbt 0.19.2rc2 + 0.20.0rc1 in dbt. dbt Cloud v1.1.27 (May 26, 2021)[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#dbt-cloud-v1127-may-26-2021 "Direct link to dbt Cloud v1.1.27 (May 26, 2021)") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- A lot of improvements coming for GitLab webhooks and native auth. We also fixed a number of bugs in the Studio IDE. Our goal is for you to never see an infinite spinner again! #### Enhancements[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#enhancements "Direct link to Enhancements") * Add dbt v0.19.2rc1 and v0.20.0b1 * Add an open/closable overlay for the DAG * Disable department dropdown * Add DAG flags, button, and tab context * Add run source freshness option to jobs * Implement conditional redirecting after GitLab app integration * Add Develop Pod Support for Rook and Ceph file storage * Show all common actions for valid top level commands #### Fixed[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#fixed "Direct link to Fixed") * Fix link to documentation * Disable the "Restart Studio IDE" Button while the Studio IDE is loading * Continue canceling runs when we run into deleted accounts * Fix SSO re-auth page * Fix blank verify email page * Resolve git refresh regression * Fix missing "Run on Merge" button in Job creation/edit form- * Warn users they have unsaved changes * Updates test command suggestions and regex for common action suggestions * Updates order of stylesheet import to fix missing border bug * Fix GitLab PR link for Run Page * Fix infinite spinner for missing environment or development credentials * Fix infinite spinner when user is missing dev credentials * Do not try to push if awaiting a merge * Fix deleting schemas * Fix favicon reference dbt Cloud v1.1.26 (May 12, 2021)[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#dbt-cloud-v1126-may-12-2021 "Direct link to dbt Cloud v1.1.26 (May 12, 2021)") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- If you haven't seen it yet, spin up the Studio IDE: the command bar now has recent actions (you can up-arrow like on the command line) as well as some hardcoded suggestions that will auto-populate your active model, if there is one. Check it out! Other fixes and adjustments as well, as we all get ready for Staging this Thursday - exciting week for the Product org over at ol' Fishtown! #### Enhancements[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#enhancements-1 "Direct link to Enhancements") * Made dbt default version on env 0.19.1 * Rolled out new command line experience to all customers * Post webhook triggered run status back to gitlab * Temporary tabs can also populate the model from manifest * Check command line content is minimally valid * Allow user to restart server when develop pod crashes * Prevent overflow of menu items #### Fixed[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#fixed-1 "Direct link to Fixed") * Handle validation error for improper remote URLs in the Scheduler * Refactor exception logging out of GitRepo and into exception handlers * Required tags returning null from core no longer causing infinite spinner * Removed deleted repos while fetching repository for sending commit statuses * Refactor git provider service * Resolve files with special characters becoming forever dirty * Disable input when RPC command running & add button when command bar is empty * Updating button for the Cancel/Enter button on commandline * Fix connection setup to always use the project referenced in the route * Fix "View data sources" URL in environment page * Add support for clicking on previously run commands and updating the text inside of the commandline * Fix sources URL in environments page * Fix metadata token not allowed API response dbt Cloud v1.1.25 (April 28, 2021)[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#dbt-cloud-v1125-april-28-2021 "Direct link to dbt Cloud v1.1.25 (April 28, 2021)") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Exciting things coming down the pipe - ongoing enhancements to the command bar experience in the Studio IDE, doing some work to ensure that more git providers are presented with a first class experience in Cloud, as well as assorted bug fixes - "I must have bug fixes, always and always" - that was Monet I think #### Enhancements[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#enhancements-2 "Direct link to Enhancements") * Made a grip of visual updates to the new command bar work * Moved to using the active model name instead of a placeholder in command bar work * Added user ability to delete connections, remove association from a given project. * Added verification of dbt version for command bar beta feature flag #### Fixed[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#fixed-2 "Direct link to Fixed") * Removed testing prop that keeps drawer open * Added double encoding to handle Snowflake roles with spaces * Fixed account switching in user notifications * Handled invalid Azure SSO group responses * Fixed error which only showed common actions when run drawer was closed * Allowed unencrypted adapter fields to be edited * Fixed bugs with file and folder renaming, alongside associated tab state dbt Cloud v1.1.24 (April 14, 2021)[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#dbt-cloud-v1124-april-14-2021 "Direct link to dbt Cloud v1.1.24 (April 14, 2021)") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Phew! As our company grows, so too does our changelog! Look at all these! The big chunks you'll see here are related to some ongoing in-Studio IDE work, focused on the command bar experience, as well as some partner & connection work (see the Gits, Databricks, and so forth), and of course ongoing longer-term bets around metadata! #### Enhancements[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#enhancements-3 "Direct link to Enhancements") * Added onFocus and onBlur properties to populate and remove "dbt" in command bar * Enabled executing command on enter if user's cursor is in the command bar * Added Metadata API access button to account settings * Added feature flag for displaying only recent actions * Added dbt 0.19.1 * Added regex validation to Databrick's hostname web-form field * Updated Connection Edit to allow adapter editing * Enabled self-service Github and GitLab integration disconnection * Added link to docs for license map & handle duplicate error gracefully * Moved deferred job execution to execution settings. * Recorded user command history * Enabled new file creation flow #### Fixed[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#fixed-3 "Direct link to Fixed") * Added styling class to popup to ensure text is readable * Fixed sourcemaps syntax for dev commands * Added timeout and retry to dbt deps * Updated databricks schema field type and add error handling to ConnectionSetup * Fixed Bigquery private keys & convert text to textarea * Fixed last used datetime in the service token UI * Added missing token URI to Bigquery connection edit * Prevent multiple develop sessions for one user * Fixed SchemaForm validating non-displayed fields * Fixed required fields for Bigquery connection JSON uploads * Fixed self selection as deferred job * Always create a Monaco model on tab open if no matching model exists * Fixed tab dirty indicator on open tab * Fixed password reset flow * Fixed docs and sources links in dashboard page for read only users * Fixed truncating first\_name to 30 characters dbt Cloud v1.1.23 (March 31, 2021)[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#dbt-cloud-v1123-march-31-2021 "Direct link to dbt Cloud v1.1.23 (March 31, 2021)") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Some backend work, some frontend work, some bug fixes: a nice mix for this release. A few user facing changes you may have noticed already are the persistence of dark/light mode settings across refresh (no more blinding Studio IDE!), branches in the Studio IDE being categorized by Active vs. Removed from Remote, and a tidier new file creation flow, with the file tree expanding to show the new file and opening a new tab to populate the said file! #### Enhancements[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#enhancements-4 "Direct link to Enhancements") * Splitting Local-only and Remote branches into different sections of the dropdown selector * Update Profile Integrations to include SSO info * Upgrade to Tailwind 2.0 and FUI 0.0.5 * Allow users to create metadata tokens from the UI * Support manually-managed group memberships * SSO: resolve bug w/ first & last names acting up * Integrate Delighted for NPS surveys * Add dbt 0.19.1rc1 to Cloud * Add an account-level setting to require users to re-authenticate via SSO * Read-only metadata ServiceToken for Cloud * Persist Studio IDE light mode / dark mode across refresh * Categorize & order git branches * Improve new file creation flow #### Fixed[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#fixed-4 "Direct link to Fixed") * Check for an empty repository before checking matching remote * Increase wait if run was finished recently * Support default branches through git when a custom branch is not specified * Don't download logs for skipped steps * API Gateway is no longer flooded with errors due to Studio IDE blindly polling dead Develop pod * Fix user license creation via admin interface * Adjusted addition of global .gitignore dbt Cloud v1.1.22 (March 17, 2021)[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#dbt-cloud-v1122-march-17-2021 "Direct link to dbt Cloud v1.1.22 (March 17, 2021)") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Rolling out a few long-term bets to ensure that our beloved dbt does not fall over for want of memory, as well as a grip of bug fixes and error messaging improvements (error messages should be helpful, not scolding or baffling, after all!) #### Enhancements[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#enhancements-5 "Direct link to Enhancements") * Release Scribe to 100% of multi-tenant accounts * Update language for SQL drawer empty state * Reduce Scribe memory usage #### Fixed[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#fixed-5 "Direct link to Fixed") * Fix NoSuchKey error * Guarantee unique notification settings per account, user, and type * Fix for account notification settings * Don't show deleted projects on notifications page * Fix unicode error while decoding last\_chunk * Show more relevant errors to customers * Groups are now editable by non-sudo requests * Normalize domain names across inputs/outputs * Redirect auth failed errors back to appropriate page with error description dbt Cloud v1.1.21 (March 3, 2021)[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#dbt-cloud-v1121-march-3-2021 "Direct link to dbt Cloud v1.1.21 (March 3, 2021)") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- This changelog wraps up work on what we've been calling the SQL Drawer in the Studio IDE - some design nudges, some interface adjustments, overall a cleaner and snappier experience. If you haven't dipped into the Studio IDE in a while it's worth taking a look! Some back-end work as well, making SSO and role based admin easier and more broadly available for Enterprise level folks, along with your usual assortment of bug squashes and iterations. #### Enhancements[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#enhancements-6 "Direct link to Enhancements") * Styling and copy adjustments in the Cloud Studio IDE * Open self-service role based access control to all Enterprise customers * Update AuthProvider UI to enable SAML and Okta * Add a SAML auth redirect URL #### Fixed[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#fixed-6 "Direct link to Fixed") * Add param to admin project mapper to included soft deleted projects * Fix delaying logs when we are waiting for a model to finish executing * Saving GSuite auth provider form triggers an authorize * Scribe populates truncated debug logs when runs are executing * Delay attempts for non-200 status codes * Add logic to support select fields in adapter UI * Undo clobbering groups dbt Cloud v1.1.20 (February 17, 2021)[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#dbt-cloud-v1120-february-17-2021 "Direct link to dbt Cloud v1.1.20 (February 17, 2021)") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Continued stability and quality of life improvements for folks with multiple accounts and projects - no longer will you have to remember the chronological order of birth of your accounts and projects, as they'll be ordered by the much easier to parse (for human brains anyway) alphabetical order. We're also shipping some experience improvements in the SQL Drawer at the bottom half of the Studio IDE. #### Enhancements[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#enhancements-7 "Direct link to Enhancements") * Deleted Info and Logs Studio IDE Tabs, logs will now be displayed in Results Tab * Removed service token feature flag * List Jobs dropdown in alphabetical order * List Account and Project dropdowns in alphabetica order * Pre-join Job Definition results to speed up scheduler * Combine scheduler queries to speedup runtime by about 30% #### Fixed[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#fixed-7 "Direct link to Fixed") * Fix issue with source freshness for 0.19.0 dbt Cloud v1.1.19 (February 3, 2021)[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#dbt-cloud-v1119-february-3-2021 "Direct link to dbt Cloud v1.1.19 (February 3, 2021)") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The latest release of dbt (Oh Nineteen Oh) is now available for your enjoyment on dbt! We're also releasing some service token pieces here, though they're not quite ready for wide release yet. Moving forward, Oh Nineteen Oh will probably end up being the minimum version required to run the Metadata API & Metadata Toolkit, so, this is a big release! #### Enhancements[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#enhancements-8 "Direct link to Enhancements") * Added dbt 0.19.0 😻 * Allowed account-wide service tokens to create connections * Added integration for service token UI and API * Authorized requests that supply a service token #### Fixed[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#fixed-8 "Direct link to Fixed") * Added logic to show the entered service token name prior to the request completing * Fixed endlessly running rpc queries with non-working cancel button on Studio IDE refresh dbt Cloud v1.1.18 (January 20, 2021)[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#dbt-cloud-v1118-january-20-2021 "Direct link to dbt Cloud v1.1.18 (January 20, 2021)") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Most notable things here are around foundational work toward future feature releases, as well as strong assurances of future stability for dbt, and ensuring future sales tax compliance (which we understand turns out to be quite important!) - turns out to be a quite future-looking release! #### Enhancements[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#enhancements-9 "Direct link to Enhancements") * Add service tokens UI (stubbed) behind a feature flag * Fixing and Upgrading social-auth * Add dbt Spark 0.19.0rc1 * Adds the reconciliation of persisted file content and tab state when navigating into the Studio IDE * Adds the reconciliation of persisted file content and tab state between Studio IDE sessions * Read logs from scribe and stop logging to db * Upgrade social auth 3.3.3 * Add warning logs for social auth failures * Add dbt 0.19.0rc1 #### Fixed[​](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#fixed-9 "Direct link to Fixed") * Prevent social-auth from updating first or last name * Page through Stripe results when listing subscriptions * Prevent enqueueing runs in deleted projects * Fix Studio IDE git actions causing open tab contents to be lost on Studio IDE re-entry * Add DBT\_CLOUD\_CONTEXT environment variable * Add logic to hide IP whitelist message for on-prem customers * fix 0.19.0rc1 run image dependencies Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [dbt Cloud v1.1.41 (December 8, 2021)](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#dbt-cloud-v1141-december-8-2021) * [dbt Cloud v1.1.39 (November 10, 2021)](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#dbt-cloud-v1139-november-10-2021) * [dbt Cloud v1.1.38 (October 27, 2021)](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#dbt-cloud-v1138-october-27-2021) * [dbt Cloud v1.1.37 (October 13, 2021)](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#dbt-cloud-v1137-october-13-2021) * [dbt Cloud v1.1.36 (September 29, 2021)](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#dbt-cloud-v1136-september-29-2021) * [dbt Cloud v1.1.35 (September 15, 2021)](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#dbt-cloud-v1135-september-15-2021) * [dbt Cloud v1.1.34 (September 1, 2021)](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#dbt-cloud-v1134-september-1-2021) * [dbt Cloud v1.1.33 (August 18, 2021)](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#dbt-cloud-v1133-august-18-2021) * [dbt Cloud v1.1.32 (August 4, 2021)](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#dbt-cloud-v1132-august-4-2021) * [dbt Cloud v1.1.31 (July 21, 2021)](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#dbt-cloud-v1131-july-21-2021) * [dbt Cloud v1.1.30 (July 7, 2021)](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#dbt-cloud-v1130-july-7-2021) * [dbt Cloud v1.1.29 (June 23, 2021)](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#dbt-cloud-v1129-june-23-2021) * [dbt Cloud v1.1.28 (June 9, 2021)](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#dbt-cloud-v1128-june-9-2021) * [dbt Cloud v1.1.27 (May 26, 2021)](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#dbt-cloud-v1127-may-26-2021) * [dbt Cloud v1.1.26 (May 12, 2021)](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#dbt-cloud-v1126-may-12-2021) * [dbt Cloud v1.1.25 (April 28, 2021)](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#dbt-cloud-v1125-april-28-2021) * [dbt Cloud v1.1.24 (April 14, 2021)](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#dbt-cloud-v1124-april-14-2021) * [dbt Cloud v1.1.23 (March 31, 2021)](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#dbt-cloud-v1123-march-31-2021) * [dbt Cloud v1.1.22 (March 17, 2021)](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#dbt-cloud-v1122-march-17-2021) * [dbt Cloud v1.1.21 (March 3, 2021)](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#dbt-cloud-v1121-march-3-2021) * [dbt Cloud v1.1.20 (February 17, 2021)](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#dbt-cloud-v1120-february-17-2021) * [dbt Cloud v1.1.19 (February 3, 2021)](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#dbt-cloud-v1119-february-3-2021) * [dbt Cloud v1.1.18 (January 20, 2021)](https://docs.getdbt.com/docs/dbt-versions/release-notes/dbt-cloud-changelog-2021#dbt-cloud-v1118-january-20-2021) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/dbt-versions/release-notes/98-dbt-cloud-changelog-2021.md) --- # Hybrid setup | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/deploy/hybrid-setup#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page Set up Hybrid projects to upload dbt Core artifacts into dbt for better collaboration and visibility. Available in public preview Hybrid projects is available in public preview to [dbt Enterprise accounts](https://www.getdbt.com/pricing) . Set up Hybrid projects[​](https://docs.getdbt.com/docs/deploy/hybrid-setup#set-up-hybrid-projects "Direct link to Set up Hybrid projects") ------------------------------------------------------------------------------------------------------------------------------------------- In a hybrid project, you use dbt Core locally and can upload artifacts of that dbt Core project to dbt for central visibility, cross-project referencing, and easier collaboration. This setup requires connecting your dbt Core project to a dbt project and configuring a few environment variables and access settings. Follow these steps to set up a dbt Hybrid project and upload dbt Core artifacts into dbt: * [Make dbt Core models public](https://docs.getdbt.com/docs/deploy/hybrid-setup#make-dbt-core-models-public) (optional) * [Create hybrid project](https://docs.getdbt.com/docs/deploy/hybrid-setup#create-hybrid-project) * [Generate service token and artifact upload values](https://docs.getdbt.com/docs/deploy/hybrid-setup#generate-service-token-and-artifact-upload-values) * [Configure dbt Core project and upload artifacts](https://docs.getdbt.com/docs/deploy/hybrid-setup#configure-dbt-core-project-and-upload-artifacts) * [Review artifacts in dbt](https://docs.getdbt.com/docs/deploy/hybrid-setup#review-artifacts-in-dbt-cloud) Make sure to enable the hybrid projects toggle in dbt’s **Account settings** page. ### Make dbt Core models public (optional)[​](https://docs.getdbt.com/docs/deploy/hybrid-setup#make-dbt-core-models-public "Direct link to Make dbt Core models public (optional)") This step is optional and and only needed if you want to share your dbt Core models with other dbt projects using the [cross-project referencing](https://docs.getdbt.com/docs/mesh/govern/project-dependencies#how-to-write-cross-project-ref) feature. Before connecting your dbt Core project to a dbt project, make sure models that you want to share have `access: public` in their model configuration. This setting makes those models visible to other dbt projects for better collaboration, such as [cross-project referencing](https://docs.getdbt.com/docs/mesh/govern/project-dependencies#how-to-write-cross-project-ref) . 1. The easiest way to set this would be in your `dbt_project.yml` file, however you can also set this in the following places: * `dbt_project.yml` (project-level) * `properties.yml` (for individual models) * A model's `.sql` file using a `config` block Here's an example using a `dbt_project.yml` file where the marts directory is set as public so they can be consumed by downstream tools: dbt\_project.yml models: define_public_models: # This is my project name, remember it must be specified marts: +access: public 2. After defining `access: public`, rerun a dbt execution in the dbt Core command line interface (CLI) (like `dbt run`) to apply the change. 3. For more details on how to set this up, see [access modifier](https://docs.getdbt.com/docs/mesh/govern/model-access#access-modifiers) and [`access` config](https://docs.getdbt.com/reference/resource-configs/access) . ### Create hybrid project[​](https://docs.getdbt.com/docs/deploy/hybrid-setup#create-hybrid-project "Direct link to Create hybrid project") Create a hybrid project in dbt to allow you to upload your dbt Core artifacts to dbt. A [dbt account admin](https://docs.getdbt.com/docs/cloud/manage-access/enterprise-permissions#permission-sets) should perform the following steps and share the artifacts information with a dbt Core user: 1. To create a new project in dbt, navigate to **Account home**. 2. Click on **+New project**. 3. Fill out the **Project name**. Name the project something that allows you to recognize it's a dbt Core project. * You don't need to set up a [data warehouse](https://docs.getdbt.com/docs/supported-data-platforms) or [Git connection](https://docs.getdbt.com/docs/cloud/git/git-configuration-in-dbt-cloud) , however to upgrade the hybrid project to a full dbt project, you'd need to set up data warehouse and Git connection. 4. Select the **Advanced settings** toggle and then select the **Hybrid development** checkbox. Click **Continue**. * The hybrid project will have a visible **Hybrid** indicator in the project list to help you identify it. [![Hybrid project new project](https://docs.getdbt.com/img/docs/deploy/hp-new-project.jpg?v=2 "Hybrid project new project")](https://docs.getdbt.com/docs/deploy/hybrid-setup#) Hybrid project new project 5. After creating a project, create a corresponding [production environment](https://docs.getdbt.com/docs/deploy/deploy-environments#create-a-deployment-environment) and click **Save**. Note that you can leave the **Connection** field blank. 6. (Optional) To update an existing dbt project to a hybrid project, navigate to **Account settings** and then select the **Project**. Click **Edit** and then check the **Hybrid development** checkbox. [![Hybrid project for an existing project](https://docs.getdbt.com/img/docs/deploy/hp-existing-project.jpg?v=2 "Hybrid project for an existing project")](https://docs.getdbt.com/docs/deploy/hybrid-setup#) Hybrid project for an existing project ### Generate service token and artifact upload values[​](https://docs.getdbt.com/docs/deploy/hybrid-setup#generate-service-token-and-artifact-upload-values "Direct link to Generate service token and artifact upload values") A dbt admin should perform these steps to generate a [service token](https://docs.getdbt.com/docs/dbt-cloud-apis/service-tokens#enterprise-plans-using-service-account-tokens) (with both **Job Runner** _and_ **Job Viewer** permissions) and copy the values needed to configure a dbt Core project so it's ready to upload generated artifacts to dbt. The dbt admin should share the values with a dbt Core user. 1. Go to the Hybrid project environment you created in the previous step by navigating to **Deploy** > **Environments** and selecting the environment. 2. Select the **Artifact upload** button and copy the following values, which the dbt Core user will need to reference in their dbt Core's `dbt_project.yml` configuration: * **[Tenant URL](https://docs.getdbt.com/docs/cloud/about-cloud/access-regions-ip-addresses) ** * **Account ID** * **Environment ID** * **Create a service token** * dbt creates a service token with both **Job Runner** _and_ **Job Viewer** permissions. * Note if you don't see the **Create service token** button, it's likely you don't have the necessary permissions to create a service token. Contact your dbt admin to either get the necessary permissions or create the service token for you. [![Generate hybrid project service token](https://docs.getdbt.com/img/docs/deploy/hp-artifact-upload.png?v=2 "Generate hybrid project service token")](https://docs.getdbt.com/docs/deploy/hybrid-setup#) Generate hybrid project service token 3. Make sure to copy and save the values as they're needed to configure your dbt Core project in the next step. Once the service token is created, you can't access it again. ### Configure dbt Core project and upload artifacts[​](https://docs.getdbt.com/docs/deploy/hybrid-setup#configure-dbt-core-project-and-upload-artifacts "Direct link to Configure dbt Core project and upload artifacts") Once you have the values from the previous step, you can prepare your dbt Core project for artifact upload by following these steps: 1. Check your dbt version by running `dbt --version` and you should see the following: Core: - installed: 1.10.0-b1 - latest: 1.9.3 - Ahead of latest version! 2. If you don't have the latest version (1.10 or later), [upgrade](https://docs.getdbt.com/docs/core/pip-install#change-dbt-core-versions) your dbt Core project by running `python -m pip install --upgrade dbt-core`. 3. Set the following environment variables in your dbt Core project by running the following commands in the CLI. Replace the `your_account_id`, `your_environment_id`, and `your_token` with the actual values in the [previous step](https://docs.getdbt.com/docs/deploy/hybrid-setup#generate-service-token-and-artifact-upload-values) . export DBT_CLOUD_ACCOUNT_ID=your_account_idexport DBT_CLOUD_ENVIRONMENT_ID=your_environment_idexport DBT_CLOUD_TOKEN=your_tokenexport DBT_UPLOAD_TO_ARTIFACTS_INGEST_API=True * Set the environment variables in whatever way you use them in your project. * To unset an environment variable, run `unset environment_variable_name`, replacing `environment_variable_name` with the actual name of the environment variable. 4. In your local dbt Core project, add the following items you copied in the [previous section](https://docs.getdbt.com/docs/deploy/hybrid-setup#enable-artifact-upload) to the dbt Core's `dbt_project.yml` file: * `tenant_hostname` name: "jaffle_shop"version: "3.0.0"require-dbt-version: ">=1.5.0"....rest of dbt_project.yml configuration...dbt-cloud: tenant_hostname: cloud.getdbt.com # Replace with your Tenant URL 5. Once you set the environment variables using the `export` command in the same dbt Core CLI session, you can execute a `dbt run` in the CLI. dbt run To override the environment variables set, execute a `dbt run` with the environment variable prefix. For example, to use a different account ID and environment ID: DBT_CLOUD_ACCOUNT_ID=1 DBT_CLOUD_ENVIRONMENT_ID=123 dbt run 6. After the run completes, you should see a `Artifacts uploaded successfully to artifact ingestion API: command run completed successfully` message and a run in dbt under your production environment. ### Review artifacts in the dbt platform[​](https://docs.getdbt.com/docs/deploy/hybrid-setup#review-artifacts-in-the-dbt-platform "Direct link to Review artifacts in the dbt platform") Now that you've uploaded dbt Core artifacts into the dbt platform and executed a `dbt run`, you can view the artifacts job run: 1. Navigate to **Deploy** 2. Click on **Jobs** and then the **Runs** tab. 3. You should see a job run with the status **Success** with a ` Artifact ingestion` indicator. 4. Click on the job run to review the logs to confirm a successfully artifacts upload message. If there are any errors, resolve them by checking out the debug logs. [![Hybrid project job run with artifact ingestion](https://docs.getdbt.com/img/docs/deploy/hp-artifact-job.jpg?v=2 "Hybrid project job run with artifact ingestion")](https://docs.getdbt.com/docs/deploy/hybrid-setup#) Hybrid project job run with artifact ingestion Benefits of using Hybrid projects[​](https://docs.getdbt.com/docs/deploy/hybrid-setup#benefits-of-using-hybrid-projects "Direct link to Benefits of using Hybrid projects") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Now that you've integrated dbt Core artifacts with your dbt project, you can now: * Collaborate with dbt users by enabling them to visualize and perform [cross-project references](https://docs.getdbt.com/docs/mesh/govern/project-dependencies#how-to-write-cross-project-ref) to dbt models that live in Core projects. * (Coming soon) New users interested in the [Canvas](https://docs.getdbt.com/docs/cloud/canvas) can build off of dbt models already created by a central data team in dbt Core rather than having to start from scratch. * dbt Core users can navigate to [Catalog](https://docs.getdbt.com/docs/explore/explore-projects) and view their models and assets. To view Catalog, you must have a [read-only seat](https://docs.getdbt.com/docs/cloud/manage-access/seats-and-users) . Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Set up Hybrid projects](https://docs.getdbt.com/docs/deploy/hybrid-setup#set-up-hybrid-projects) * [Make dbt Core models public (optional)](https://docs.getdbt.com/docs/deploy/hybrid-setup#make-dbt-core-models-public) * [Create hybrid project](https://docs.getdbt.com/docs/deploy/hybrid-setup#create-hybrid-project) * [Generate service token and artifact upload values](https://docs.getdbt.com/docs/deploy/hybrid-setup#generate-service-token-and-artifact-upload-values) * [Configure dbt Core project and upload artifacts](https://docs.getdbt.com/docs/deploy/hybrid-setup#configure-dbt-core-project-and-upload-artifacts) * [Review artifacts in the dbt platform](https://docs.getdbt.com/docs/deploy/hybrid-setup#review-artifacts-in-the-dbt-platform) * [Benefits of using Hybrid projects](https://docs.getdbt.com/docs/deploy/hybrid-setup#benefits-of-using-hybrid-projects) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/deploy/hybrid-setup.md) --- # Seeds object schema | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-seeds#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page The seeds object allows you to query information about all seeds in a given job. ### Arguments[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-seeds#arguments "Direct link to Arguments") When querying for `seeds`, the following arguments are available. Fetching data... ================ Below we show some illustrative example queries and outline the schema of the seeds object. ### Example query[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-seeds#example-query "Direct link to Example query") The example query below pulls relevant information about all seeds in a given job. For instance, you can view load times. { job(id: 123) { seeds { uniqueId name executionTime status } }} ### Fields[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-seeds#fields "Direct link to Fields") When querying for `seeds`, the following fields are available: Fetching data... ================ Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Arguments](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-seeds#arguments) * [Example query](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-seeds#example-query) * [Fields](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-seeds#fields) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/dbt-cloud-apis/schema-discovery-job-seeds.mdx) --- # Tests object schema | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-tests#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page The tests object allows you to query information about all tests in a given job. ### Arguments[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-tests#arguments "Direct link to Arguments") When querying for `tests`, the following arguments are available. Fetching data... ================ Below we show some illustrative example queries and outline the schema (all possible fields you can query) of the tests object. ### Example query[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-tests#example-query "Direct link to Example query") The example query below finds all tests in this job and includes information about those tests. { job(id: 123) { tests { runId accountId projectId uniqueId name columnName state } }} ### Fields[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-tests#fields "Direct link to Fields") When querying for `tests`, the following fields are available: Fetching data... ================ Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Arguments](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-tests#arguments) * [Example query](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-tests#example-query) * [Fields](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-tests#fields) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/dbt-cloud-apis/schema-discovery-job-tests.mdx) --- # dbt platform compatible track - changelog | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/dbt-versions/compatible-track-changelog#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page Select the "Compatible" and "Extended" release tracks if you need a less-frequent release cadence, the ability to test new dbt releases before they go live in production, and/or ongoing compatibility with the latest open source releases of dbt Core. Each monthly "Compatible" release includes functionality matching up-to-date open source versions of dbt Core and adapters at the time of release. For more information, see [release tracks](https://docs.getdbt.com/docs/dbt-versions/cloud-release-tracks) . September 2025[​](https://docs.getdbt.com/docs/dbt-versions/compatible-track-changelog#september-2025 "Direct link to September 2025") --------------------------------------------------------------------------------------------------------------------------------------- Release Date: September 10, 2025 This compatible release includes functionality from the following versions of dbt Core OSS: dbt-core==1.10.11# shared interfacesdbt-adapters==1.16.6dbt-common==1.29.0dbt-semantic-interfaces==0.9.0# adaptersdbt-athena==1.9.5dbt-bigquery==1.10.2dbt-databricks==1.10.12dbt-extractor==0.6.0dbt-fabric==1.9.4dbt-postgres==1.9.1dbt-protos==1.0.348dbt-redshift==1.9.5dbt-sl-sdk[sync]==0.13.0dbt-snowflake==1.10.2dbt-spark==1.9.3dbt-synapse==1.8.4dbt-teradata==1.10.0dbt-trino==1.9.3 Changelogs: * [dbt-core 1.10.11](https://github.com/dbt-labs/dbt-core/blob/1.10.latest/CHANGELOG.md#dbt-core-11011---september-04-2025) * [dbt-adapters 1.16.6](https://github.com/dbt-labs/dbt-adapters/blob/main/dbt-adapters/CHANGELOG.md#dbt-adapters-1166---september-03-2025) * [dbt-common 1.29.0](https://github.com/dbt-labs/dbt-common/blob/main/CHANGELOG.md#dbt-common-1290---september-04-2025) * [dbt-athena 1.9.4](https://github.com/dbt-labs/dbt-adapters/blob/main/dbt-athena/CHANGELOG.md#dbt-athena-194---april-28-2025) * [dbt-bigquery 1.10.2](https://github.com/dbt-labs/dbt-adapters/blob/main/dbt-bigquery/CHANGELOG.md#dbt-bigquery-1101---july-29-2025) * [dbt-databricks 1.10.12](https://github.com/databricks/dbt-databricks/blob/main/CHANGELOG.md#dbt-databricks-11012-september-8-2025) * [dbt-fabric 1.9.4](https://github.com/microsoft/dbt-fabric/releases/tag/v1.9.4) * [dbt-postgres 1.9.1](https://github.com/dbt-labs/dbt-adapters/blob/main/dbt-postgres/CHANGELOG.md#changelog) * [dbt-redshift 1.9.5](https://github.com/dbt-labs/dbt-adapters/blob/main/dbt-redshift/CHANGELOG.md#dbt-redshift-195---may-13-2025) * [dbt-snowflake 1.10.2](http://github.com/dbt-labs/dbt-adapters/blob/main/dbt-snowflake/CHANGELOG.md) * [dbt-spark 1.9.3](https://github.com/dbt-labs/dbt-adapters/blob/main/dbt-spark/CHANGELOG.md#dbt-spark-193---july-16-2025) * [dbt-synapse 1.8.4](https://github.com/microsoft/dbt-synapse/blob/v1.8.latest/CHANGELOG.md) * [dbt-teradata 1.10.0](https://github.com/Teradata/dbt-teradata/releases/tag/v1.10.0) * [dbt-trino 1.9.3](https://github.com/starburstdata/dbt-trino/blob/master/CHANGELOG.md#dbt-trino-193---july-22-2025) August 2025[​](https://docs.getdbt.com/docs/dbt-versions/compatible-track-changelog#august-2025 "Direct link to August 2025") ------------------------------------------------------------------------------------------------------------------------------ Release date: August 12, 2025 ### Notable dbt Core OSS changes[​](https://docs.getdbt.com/docs/dbt-versions/compatible-track-changelog#notable-dbt-core-oss-changes "Direct link to Notable dbt Core OSS changes") This compatible upgrade brings in a minor update to `dbt-core`, from `dbt-core==1.9.8` to `dbt-core==1.10.8`. Some noteworthy changes from this minor version include: * Introduction of several new [deprecations](https://docs.getdbt.com/reference/deprecations) that warn about project incompatibilities between dbt Core and Fusion engines. * Support for defining `meta` and `tags` within `config` of columns and exposures, as well as defining `freshness` within `config` of sources. These changes lead to manifest.json minor schema evolutions which may cause an intermittent increase in false positives during `state:modified` comparisons. ### dbt cloud-based platform[​](https://docs.getdbt.com/docs/dbt-versions/compatible-track-changelog#dbt-cloud-based-platform "Direct link to dbt cloud-based platform") ### Fixes[​](https://docs.getdbt.com/docs/dbt-versions/compatible-track-changelog#fixes "Direct link to Fixes") * Update generate publications script to add project and env id in generated publication file * Use JSON stream for publication artifact generation script * Get environment variables correctly from environment for publication artifacts * Adding `--resource-type` and `--exclude-resource-type` flags to Semantic Layer commands * Azure DevOps Private Packages are now properly matched with Private Package Definition in packages.yml ### Under the Hood[​](https://docs.getdbt.com/docs/dbt-versions/compatible-track-changelog#under-the-hood "Direct link to Under the Hood") * Prepare support for Private Package's URLs with multiple levels * Disable telemetry client logger * Update semantic layer SDK to 0.11 This release includes functionality from the following versions of dbt Core OSS: dbt-core==1.10.8# shared interfacesdbt-adapters==1.16.3dbt-common==1.27.1dbt-semantic-interfaces==0.9.0dbt-extractor==0.6.0dbt-protos==1.0.348# dbt-adaptersdbt-athena==1.9.4dbt-bigquery==1.10.1dbt-databricks==1.10.10dbt-fabric==1.9.4dbt-postgres==1.9.0dbt-redshift==1.9.5dbt-snowflake==1.10.0dbt-spark==1.9.3dbt-synapse==1.8.2dbt-teradata==1.9.3dbt-trino==1.9.3 Changelogs: * [dbt-core 1.10.8](https://github.com/dbt-labs/dbt-core/blob/1.10.latest/CHANGELOG.md#dbt-core-1108---august-12-2025) * [dbt-adapters 1.16.3](https://github.com/dbt-labs/dbt-adapters/blob/main/dbt-adapters/CHANGELOG.md#dbt-adapters-1163---july-21-2025) * [dbt-common 1.25.0](https://github.com/dbt-labs/dbt-common/blob/main/CHANGELOG.md#dbt-common-1271---july-21-2025) * [dbt-athena 1.9.4](https://github.com/dbt-labs/dbt-adapters/blob/main/dbt-athena/CHANGELOG.md#dbt-athena-194---april-28-2025) * [dbt-bigquery 1.10.1](https://github.com/dbt-labs/dbt-adapters/blob/main/dbt-bigquery/CHANGELOG.md#dbt-bigquery-1101---july-29-2025) * [dbt-databricks 1.9.7](https://github.com/databricks/dbt-databricks/blob/main/CHANGELOG.md#dbt-databricks-1109-august-7-2025) * [dbt-fabric 1.9.4](https://github.com/microsoft/dbt-fabric/releases/tag/v1.9.4) * [dbt-postgres 1.9.0](https://github.com/dbt-labs/dbt-postgres/blob/main/CHANGELOG.md#dbt-postgres-190---december-09-2024) * [dbt-redshift 1.9.5](https://github.com/dbt-labs/dbt-adapters/blob/main/dbt-redshift/CHANGELOG.md#dbt-redshift-195---may-13-2025) * [dbt-snowflake 1.10.0](https://github.com/dbt-labs/dbt-adapters/blob/main/dbt-snowflake/CHANGELOG.md#dbt-snowflake-1100-rc3---june-24-2025) * [dbt-spark 1.9.3](https://github.com/dbt-labs/dbt-adapters/blob/main/dbt-spark/CHANGELOG.md#dbt-spark-193---july-16-2025) * [dbt-synapse 1.8.2](https://github.com/microsoft/dbt-synapse/blob/v1.8.latest/CHANGELOG.md) * [dbt-teradata 1.9.3](https://github.com/Teradata/dbt-teradata/releases/tag/v1.9.3) * [dbt-trino 1.9.3](https://github.com/starburstdata/dbt-trino/blob/master/CHANGELOG.md#dbt-trino-193---july-22-2025) July 2025[​](https://docs.getdbt.com/docs/dbt-versions/compatible-track-changelog#july-2025 "Direct link to July 2025") ------------------------------------------------------------------------------------------------------------------------ The compatible release slated for July 2025 will be skipped in order to further stabilize the minor upgrade of `dbt-core==1.10.0` ([released June 16, 2025](https://pypi.org/project/dbt-core/1.10.0/) ) across the dbt platform. Compatible releases will resume in August 2025. June 2025[​](https://docs.getdbt.com/docs/dbt-versions/compatible-track-changelog#june-2025 "Direct link to June 2025") ------------------------------------------------------------------------------------------------------------------------ Release date: June 12, 2025 This release includes functionality from the following versions of dbt Core OSS: dbt-core==1.9.8# shared interfacesdbt-adapters==1.15.3dbt-common==1.25.0dbt-semantic-interfaces==0.7.4# adaptersdbt-athena==1.9.4dbt-bigquery==1.9.1dbt-databricks==1.9.7dbt-extractor==0.6.0dbt-fabric==1.9.4dbt-postgres==1.9.0dbt-protos==1.0.317dbt-redshift==1.9.5dbt-sl-sdk-internal[sync]==0.7.0dbt-sl-sdk[sync]==0.7.0dbt-snowflake==1.9.4dbt-spark==1.9.2dbt-synapse==1.8.2dbt-teradata==1.9.2dbt-trino==1.9.2 Changelogs: * [dbt-core 1.9.8](https://github.com/dbt-labs/dbt-core/blob/1.9.latest/CHANGELOG.md#dbt-core-198---june-10-2025) * [dbt-adapters 1.15.3](https://github.com/dbt-labs/dbt-adapters/blob/main/dbt-adapters/CHANGELOG.md#dbt-adapters-1153---may-20-2025) * [dbt-common 1.25.0](https://github.com/dbt-labs/dbt-common/blob/main/CHANGELOG.md#dbt-common-1250---may-20-2025) * [dbt-athena 1.9.4](https://github.com/dbt-labs/dbt-adapters/blob/main/dbt-athena/CHANGELOG.md#dbt-athena-194---april-28-2025) * [dbt-bigquery 1.9.1](https://github.com/dbt-labs/dbt-bigquery/blob/1.9.latest/CHANGELOG.md#dbt-bigquery-191---january-10-2025) * [dbt-databricks 1.9.7](https://github.com/databricks/dbt-databricks/blob/main/CHANGELOG.md#dbt-databricks-197-feb-25-2025) * [dbt-fabric 1.9.4](https://github.com/microsoft/dbt-fabric/releases/tag/v1.9.4) * [dbt-postgres 1.9.0](https://github.com/dbt-labs/dbt-postgres/blob/main/CHANGELOG.md#dbt-postgres-190---december-09-2024) * [dbt-redshift 1.9.5](https://github.com/dbt-labs/dbt-adapters/blob/main/dbt-redshift/CHANGELOG.md#dbt-redshift-195---may-13-2025) * [dbt-snowflake 1.9.4](https://github.com/dbt-labs/dbt-adapters/blob/main/dbt-snowflake/CHANGELOG.md#dbt-snowflake-194---may-02-2025) * [dbt-spark 1.9.2](https://github.com/dbt-labs/dbt-adapters/blob/main/dbt-spark/CHANGELOG.md#dbt-spark-192---march-07-2025) * [dbt-synapse 1.8.2](https://github.com/microsoft/dbt-synapse/blob/v1.8.latest/CHANGELOG.md) * [dbt-teradata 1.9.2](https://github.com/Teradata/dbt-teradata/releases/tag/v1.9.2) * [dbt-trino 1.9.1](https://github.com/starburstdata/dbt-trino/blob/master/CHANGELOG.md#dbt-trino-192---june-03-2025) May 2025[​](https://docs.getdbt.com/docs/dbt-versions/compatible-track-changelog#may-2025 "Direct link to May 2025") --------------------------------------------------------------------------------------------------------------------- Release date: May 19, 2025 ### dbt cloud-based platform[​](https://docs.getdbt.com/docs/dbt-versions/compatible-track-changelog#dbt-cloud-based-platform-1 "Direct link to dbt cloud-based platform") These changes reflect capabilities that are only available in the dbt platform. ### Fixes[​](https://docs.getdbt.com/docs/dbt-versions/compatible-track-changelog#fixes-1 "Direct link to Fixes") * Get environment variables correctly from the environment for publication artifacts ### Under the hood[​](https://docs.getdbt.com/docs/dbt-versions/compatible-track-changelog#under-the-hood-1 "Direct link to Under the hood") * Create JSON schemas for PublicationArtifact and ResolvedProjectsArtifact This release includes functionality from the following versions of dbt Core OSS: dbt-core==1.9.4# shared interfacesdbt-adapters==1.14.8dbt-common==1.24.0dbt-semantic-interfaces==0.7.4# adaptersdbt-athena==1.9.4dbt-bigquery==1.9.1dbt-databricks==1.9.7dbt-fabric==1.9.4dbt-postgres==1.9.0dbt-redshift==1.9.5dbt-snowflake==1.9.4dbt-spark==1.9.2dbt-synapse==1.8.2dbt-teradata==1.9.2dbt-trino==1.9.1 Changelogs: * [dbt-core 1.9.4](https://github.com/dbt-labs/dbt-core/blob/1.9.latest/CHANGELOG.md#dbt-core-194---april-02-2025) * [dbt-adapters 1.14.8](https://github.com/dbt-labs/dbt-adapters/blob/main/dbt-adapters/CHANGELOG.md#dbt-adapters-1148---april-25-2025) * [dbt-common 1.24.0](https://github.com/dbt-labs/dbt-common/blob/main/CHANGELOG.md#dbt-common-1240---may-09-2025) * [dbt-athena 1.9.4](https://github.com/dbt-labs/dbt-adapters/blob/main/dbt-athena/CHANGELOG.md#dbt-athena-194---april-28-2025) * [dbt-bigquery 1.9.1](https://github.com/dbt-labs/dbt-bigquery/blob/1.9.latest/CHANGELOG.md#dbt-bigquery-191---january-10-2025) * [dbt-databricks 1.9.7](https://github.com/databricks/dbt-databricks/blob/main/CHANGELOG.md#dbt-databricks-197-feb-25-2025) * [dbt-fabric 1.9.4](https://github.com/microsoft/dbt-fabric/releases/tag/v1.9.4) * [dbt-postgres 1.9.0](https://github.com/dbt-labs/dbt-postgres/blob/main/CHANGELOG.md#dbt-postgres-190---december-09-2024) * [dbt-redshift 1.9.5](https://github.com/dbt-labs/dbt-adapters/blob/main/dbt-redshift/CHANGELOG.md#dbt-redshift-195---may-13-2025) * [dbt-snowflake 1.9.4](https://github.com/dbt-labs/dbt-adapters/blob/main/dbt-snowflake/CHANGELOG.md#dbt-snowflake-194---may-02-2025) * [dbt-spark 1.9.2](https://github.com/dbt-labs/dbt-adapters/blob/main/dbt-spark/CHANGELOG.md#dbt-spark-192---march-07-2025) * [dbt-synapse 1.8.2](https://github.com/microsoft/dbt-synapse/blob/v1.8.latest/CHANGELOG.md) * [dbt-teradata 1.9.2](https://github.com/Teradata/dbt-teradata/releases/tag/v1.9.2) * [dbt-trino 1.9.1](https://github.com/starburstdata/dbt-trino/blob/master/CHANGELOG.md#dbt-trino-191---march-26-2025) April 2025[​](https://docs.getdbt.com/docs/dbt-versions/compatible-track-changelog#april-2025 "Direct link to April 2025") --------------------------------------------------------------------------------------------------------------------------- Release date: April 9, 2025 ### dbt Cloud[​](https://docs.getdbt.com/docs/dbt-versions/compatible-track-changelog#dbt-cloud "Direct link to dbt Cloud") These changes reflect capabilities that are only available in dbt Cloud. ### Under the Hood[​](https://docs.getdbt.com/docs/dbt-versions/compatible-track-changelog#under-the-hood-2 "Direct link to Under the Hood") * Add secondary profiles to profile.py This release includes functionality from the following versions of dbt Core OSS: dbt-core==1.9.4# shared interfacesdbt-adapters==1.14.5dbt-common==1.17.0dbt-semantic-interfaces==0.7.4# adaptersdbt-athena==1.9.3dbt-bigquery==1.9.1dbt-databricks==1.9.7dbt-fabric==1.9.4dbt-postgres==1.9.0dbt-redshift==1.9.3dbt-snowflake==1.9.2dbt-spark==1.9.2dbt-synapse==1.8.2dbt-teradata==1.9.2dbt-trino==1.9.1 Changelogs: * [dbt-core 1.9.4](https://github.com/dbt-labs/dbt-core/blob/1.9.latest/CHANGELOG.md#dbt-core-194---april-02-2025) * [dbt-adapters 1.14.5](https://github.com/dbt-labs/dbt-adapters/blob/main/dbt-adapters/CHANGELOG.md#dbt-adapters-1145---april-07-2025) * [dbt-common 1.17.0](https://github.com/dbt-labs/dbt-common/blob/main/CHANGELOG.md#dbt-common-1170---march-31-2025) * [dbt-athena 1.9.3](https://github.com/dbt-labs/dbt-adapters/blob/main/dbt-athena/CHANGELOG.md#dbt-athena-193---april-07-2025) * [dbt-bigquery 1.9.1](https://github.com/dbt-labs/dbt-bigquery/blob/1.9.latest/CHANGELOG.md#dbt-bigquery-191---january-10-2025) * [dbt-databricks 1.9.7](https://github.com/databricks/dbt-databricks/blob/main/CHANGELOG.md#dbt-databricks-197-feb-25-2025) * [dbt-fabric 1.9.4](https://github.com/microsoft/dbt-fabric/releases/tag/v1.9.4) * [dbt-postgres 1.9.0](https://github.com/dbt-labs/dbt-postgres/blob/main/CHANGELOG.md#dbt-postgres-190---december-09-2024) * [dbt-redshift 1.9.3](https://github.com/dbt-labs/dbt-adapters/blob/main/dbt-redshift/CHANGELOG.md#dbt-redshift-193---april-01-2025) * [dbt-snowflake 1.9.2](https://github.com/dbt-labs/dbt-adapters/blob/main/dbt-snowflake/CHANGELOG.md#dbt-snowflake-192---march-07-2025) * [dbt-spark 1.9.2](https://github.com/dbt-labs/dbt-adapters/blob/main/dbt-spark/CHANGELOG.md#dbt-spark-192---march-07-2025) * [dbt-synapse 1.8.2](https://github.com/microsoft/dbt-synapse/blob/v1.8.latest/CHANGELOG.md) * [dbt-teradata 1.9.2](https://github.com/Teradata/dbt-teradata/releases/tag/v1.9.2) * [dbt-trino 1.9.1](https://github.com/starburstdata/dbt-trino/blob/master/CHANGELOG.md#dbt-trino-191---march-26-2025) March 2025[​](https://docs.getdbt.com/docs/dbt-versions/compatible-track-changelog#march-2025 "Direct link to March 2025") --------------------------------------------------------------------------------------------------------------------------- Release date: March 11, 2025 This release includes functionality from the following versions of dbt Core OSS: dbt-core==1.9.3# shared interfacesdbt-adapters==1.14.1dbt-common==1.15.0dbt-semantic-interfaces==0.7.4# adaptersdbt-athena==1.9.2dbt-bigquery==1.9.1dbt-databricks==1.9.7dbt-fabric==1.9.2dbt-postgres==1.9.0dbt-redshift==1.9.1dbt-snowflake==1.9.2dbt-spark==1.9.2dbt-synapse==1.8.2dbt-teradata==1.9.1dbt-trino==1.9.0 Changelogs: * [dbt Core 1.9.3](https://github.com/dbt-labs/dbt-core/blob/1.9.latest/CHANGELOG.md#dbt-core-193---march-07-2025) * [dbt-adapters 1.14.1](https://github.com/dbt-labs/dbt-adapters/blob/main/dbt-adapters/CHANGELOG.md#dbt-adapters-1141---march-04-2025) * [dbt-common 1.15.0](https://github.com/dbt-labs/dbt-common/blob/main/CHANGELOG.md#dbt-common-1150---february-14-2025) * [dbt-bigquery 1.9.1](https://github.com/dbt-labs/dbt-bigquery/blob/1.9.latest/CHANGELOG.md#dbt-bigquery-191---january-10-2025) * [dbt-databricks 1.9.7](https://github.com/databricks/dbt-databricks/blob/main/CHANGELOG.md#dbt-databricks-197-feb-25-2025) * [dbt-fabric 1.9.2](https://github.com/microsoft/dbt-fabric/releases/tag/v1.9.2) * [dbt-postgres 1.9.0](https://github.com/dbt-labs/dbt-postgres/blob/main/CHANGELOG.md#dbt-postgres-190---december-09-2024) * [dbt-redshift 1.9.1](https://github.com/dbt-labs/dbt-adapters/blob/main/dbt-redshift/CHANGELOG.md#dbt-redshift-191---march-07-2025) * [dbt-snowflake 1.9.2](https://github.com/dbt-labs/dbt-adapters/blob/main/dbt-snowflake/CHANGELOG.md#dbt-snowflake-192---march-07-2025) * [dbt-spark 1.9.2](https://github.com/dbt-labs/dbt-adapters/blob/main/dbt-spark/CHANGELOG.md#dbt-spark-192---march-07-2025) * [dbt-synapse 1.8.2](https://github.com/microsoft/dbt-synapse/blob/v1.8.latest/CHANGELOG.md) * [dbt-teradata 1.9.1](https://github.com/Teradata/dbt-teradata/releases/tag/v1.9.1) * [dbt-trino 1.9.0](https://github.com/starburstdata/dbt-trino/blob/master/CHANGELOG.md#dbt-trino-190---december-20-2024) February 2025[​](https://docs.getdbt.com/docs/dbt-versions/compatible-track-changelog#february-2025 "Direct link to February 2025") ------------------------------------------------------------------------------------------------------------------------------------ Release date: February 12, 2025 ### dbt Cloud[​](https://docs.getdbt.com/docs/dbt-versions/compatible-track-changelog#dbt-cloud-1 "Direct link to dbt Cloud") These changes reflect capabilities that are only available in dbt. ### Features[​](https://docs.getdbt.com/docs/dbt-versions/compatible-track-changelog#features "Direct link to Features") * Add [`event_time`](https://docs.getdbt.com/reference/resource-configs/event-time) to cross-project ref artifact. * Include debug exception message in ObservabilityMetric. ### Fixes[​](https://docs.getdbt.com/docs/dbt-versions/compatible-track-changelog#fixes-2 "Direct link to Fixes") * Adding support for deferral against the new time spine definition. * Fix error messages for SL query. * Semantic Layer commands now respect `--favor-state` when running with `--defer`. This release includes functionality from the following versions of dbt Core OSS: dbt-core==1.9.2# shared interfacesdbt-adapters==1.14.0dbt-common==1.14.0dbt-semantic-interfaces==0.7.4# adaptersdbt-athena==1.9.1dbt-bigquery==1.9.1dbt-databricks==1.9.4dbt-fabric==1.9.0dbt-postgres==1.9.0dbt-redshift==1.9.0dbt-snowflake==1.9.1dbt-spark==1.9.1dbt-synapse==1.8.2dbt-teradata==1.9.1dbt-trino==1.9.0 Changelogs: * [dbt Core 1.9.2](https://github.com/dbt-labs/dbt-core/blob/1.9.latest/CHANGELOG.md#dbt-core-192---january-29-2025) * [dbt-adapters 1.14.0](https://github.com/dbt-labs/dbt-adapters/blob/main/dbt-adapters/CHANGELOG.md#dbt-adapters-1140---february-07-2025) * [dbt-common 1.14.0](https://github.com/dbt-labs/dbt-common/blob/main/CHANGELOG.md) * [dbt-bigquery 1.9.1](https://github.com/dbt-labs/dbt-bigquery/blob/1.9.latest/CHANGELOG.md#dbt-bigquery-191---january-10-2025) * [dbt-databricks 1.9.4](https://github.com/databricks/dbt-databricks/blob/main/CHANGELOG.md#dbt-databricks-194-jan-30-2024) * [dbt-fabric 1.9.0](https://github.com/microsoft/dbt-fabric/releases/tag/v1.9.0) * [dbt-postgres 1.9.0](https://github.com/dbt-labs/dbt-postgres/blob/main/CHANGELOG.md#dbt-postgres-190---december-09-2024) * [dbt-redshift 1.9.0](https://github.com/dbt-labs/dbt-redshift/blob/1.9.latest/CHANGELOG.md#dbt-redshift-190---december-09-2024) * [dbt-snowflake 1.9.1](https://github.com/dbt-labs/dbt-snowflake/blob/1.9.latest/CHANGELOG.md#dbt-snowflake-191---february-07-2025) * [dbt-spark 1.9.1](https://github.com/dbt-labs/dbt-spark/blob/1.9.latest/CHANGELOG.md#dbt-spark-191---february-07-2025) * [dbt-synapse 1.8.2](https://github.com/microsoft/dbt-synapse/blob/v1.8.latest/CHANGELOG.md) * [dbt-teradata 1.9.1](https://github.com/Teradata/dbt-teradata/releases/tag/v1.9.1) * [dbt-trino 1.9.0](https://github.com/starburstdata/dbt-trino/blob/master/CHANGELOG.md#dbt-trino-190---december-20-2024) January 2025[​](https://docs.getdbt.com/docs/dbt-versions/compatible-track-changelog#january-2025 "Direct link to January 2025") --------------------------------------------------------------------------------------------------------------------------------- Release date: January 14, 2025 ### dbt Cloud[​](https://docs.getdbt.com/docs/dbt-versions/compatible-track-changelog#dbt-cloud-2 "Direct link to dbt Cloud") These changes reflect capabilities that are only available in dbt. ### Features[​](https://docs.getdbt.com/docs/dbt-versions/compatible-track-changelog#features-1 "Direct link to Features") * Filter out external exposures in dbt compare. ### Fixes[​](https://docs.getdbt.com/docs/dbt-versions/compatible-track-changelog#fixes-3 "Direct link to Fixes") * Use `meta.dbt_cloud_id` to `build unique_id` for manually defined exposure for merging against a duplicated exposure. This release includes functionality from the following versions of dbt Core OSS: dbt-core==1.9.1# shared interfacesdbt-adapters==1.13.1dbt-common==1.14.0dbt-semantic-interfaces==0.7.4# adaptersdbt-athena==1.9.0dbt-bigquery==1.9.1dbt-databricks==1.9.1dbt-fabric==1.9.0dbt-postgres==1.9.0dbt-redshift==1.9.0dbt-snowflake==1.9.0dbt-spark==1.9.0dbt-synapse==1.8.2dbt-teradata==1.9.0dbt-trino==1.9.0 Changelogs: * [dbt Core 1.9.1](https://github.com/dbt-labs/dbt-core/blob/1.9.latest/CHANGELOG.md#dbt-core-191---december-16-2024) * [dbt-adapters 1.13.1](https://github.com/dbt-labs/dbt-adapters/blob/main/dbt-adapters/CHANGELOG.md#dbt-adapters-1131---january-10-2025) * [dbt-common 1.14.0](https://github.com/dbt-labs/dbt-common/blob/main/CHANGELOG.md) * [dbt-bigquery 1.9.1](https://github.com/dbt-labs/dbt-bigquery/blob/1.9.latest/CHANGELOG.md#dbt-bigquery-191---january-10-2025) * [dbt-databricks 1.9.1](https://github.com/databricks/dbt-databricks/blob/main/CHANGELOG.md#dbt-databricks-191-december-16-2024) * [dbt-fabric 1.9.0](https://github.com/microsoft/dbt-fabric/releases/tag/v1.9.0) * [dbt-postgres 1.9.0](https://github.com/dbt-labs/dbt-postgres/blob/main/CHANGELOG.md#dbt-postgres-190---december-09-2024) * [dbt-redshift 1.9.0](https://github.com/dbt-labs/dbt-redshift/blob/1.9.latest/CHANGELOG.md#dbt-redshift-190---december-09-2024) * [dbt-snowflake 1.9.0](https://github.com/dbt-labs/dbt-snowflake/blob/1.9.latest/CHANGELOG.md#dbt-snowflake-190---december-09-2024) * [dbt-spark 1.9.0](https://github.com/dbt-labs/dbt-spark/blob/1.9.latest/CHANGELOG.md#dbt-spark-190---december-10-2024) * [dbt-synapse 1.8.2](https://github.com/microsoft/dbt-synapse/blob/v1.8.latest/CHANGELOG.md) * [dbt-teradata 1.9.0](https://github.com/Teradata/dbt-teradata/releases/tag/v1.9.0) * [dbt-trino 1.9.0](https://github.com/starburstdata/dbt-trino/blob/master/CHANGELOG.md#dbt-trino-190---december-20-2024) December 2024[​](https://docs.getdbt.com/docs/dbt-versions/compatible-track-changelog#december-2024 "Direct link to December 2024") ------------------------------------------------------------------------------------------------------------------------------------ Release date: December 12, 2024 This release includes functionality from the following versions of dbt Core OSS: dbt-core==1.9.0# shared interfacesdbt-adapters==1.10.4dbt-common==1.14.0dbt-semantic-interfaces==0.7.4# adaptersdbt-athena==1.9.0dbt-bigquery==1.9.0dbt-databricks==1.9.0dbt-fabric==1.8.8dbt-postgres==1.9.0dbt-redshift==1.9.0dbt-snowflake==1.9.0dbt-spark==1.9.0dbt-synapse==1.8.2dbt-teradata==1.8.2dbt-trino==1.8.5 Changelogs: * [dbt Core 1.9.0](https://github.com/dbt-labs/dbt-core/blob/1.9.latest/CHANGELOG.md#dbt-core-190---december-09-2024) * [dbt-adapters 1.10.4](https://github.com/dbt-labs/dbt-adapters/blob/main/dbt-adapters/CHANGELOG.md#dbt-adapters-1104---november-11-2024) * [dbt-common 1.14.0](https://github.com/dbt-labs/dbt-common/blob/main/CHANGELOG.md) * [dbt-bigquery 1.9.0](https://github.com/dbt-labs/dbt-bigquery/blob/1.9.latest/CHANGELOG.md#dbt-bigquery-190---december-09-2024) * [dbt-databricks 1.9.0](https://github.com/databricks/dbt-databricks/blob/main/CHANGELOG.md#dbt-databricks-190-december-9-2024) * [dbt-fabric 1.8.8](https://github.com/microsoft/dbt-fabric/blob/v1.8.latest/CHANGELOG.md) * [dbt-postgres 1.9.0](https://github.com/dbt-labs/dbt-postgres/blob/main/CHANGELOG.md#dbt-postgres-190---december-09-2024) * [dbt-redshift 1.9.0](https://github.com/dbt-labs/dbt-redshift/blob/1.9.latest/CHANGELOG.md#dbt-redshift-190---december-09-2024) * [dbt-snowflake 1.9.0](https://github.com/dbt-labs/dbt-snowflake/blob/1.9.latest/CHANGELOG.md#dbt-snowflake-190---december-09-2024) * [dbt-spark 1.9.0](https://github.com/dbt-labs/dbt-spark/blob/1.9.latest/CHANGELOG.md#dbt-spark-190---december-10-2024) * [dbt-synapse 1.8.2](https://github.com/microsoft/dbt-synapse/blob/v1.8.latest/CHANGELOG.md) * [dbt-teradata 1.8.2](https://github.com/Teradata/dbt-teradata/releases/tag/v1.8.2) * [dbt-trino 1.8.5](https://github.com/starburstdata/dbt-trino/blob/master/CHANGELOG.md#dbt-trino-185---december-11-2024) Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [September 2025](https://docs.getdbt.com/docs/dbt-versions/compatible-track-changelog#september-2025) * [August 2025](https://docs.getdbt.com/docs/dbt-versions/compatible-track-changelog#august-2025) * [Notable dbt Core OSS changes](https://docs.getdbt.com/docs/dbt-versions/compatible-track-changelog#notable-dbt-core-oss-changes) * [dbt cloud-based platform](https://docs.getdbt.com/docs/dbt-versions/compatible-track-changelog#dbt-cloud-based-platform) * [Fixes](https://docs.getdbt.com/docs/dbt-versions/compatible-track-changelog#fixes) * [Under the Hood](https://docs.getdbt.com/docs/dbt-versions/compatible-track-changelog#under-the-hood) * [July 2025](https://docs.getdbt.com/docs/dbt-versions/compatible-track-changelog#july-2025) * [June 2025](https://docs.getdbt.com/docs/dbt-versions/compatible-track-changelog#june-2025) * [May 2025](https://docs.getdbt.com/docs/dbt-versions/compatible-track-changelog#may-2025) * [dbt cloud-based platform](https://docs.getdbt.com/docs/dbt-versions/compatible-track-changelog#dbt-cloud-based-platform-1) * [Fixes](https://docs.getdbt.com/docs/dbt-versions/compatible-track-changelog#fixes-1) * [Under the hood](https://docs.getdbt.com/docs/dbt-versions/compatible-track-changelog#under-the-hood-1) * [April 2025](https://docs.getdbt.com/docs/dbt-versions/compatible-track-changelog#april-2025) * [dbt Cloud](https://docs.getdbt.com/docs/dbt-versions/compatible-track-changelog#dbt-cloud) * [Under the Hood](https://docs.getdbt.com/docs/dbt-versions/compatible-track-changelog#under-the-hood-2) * [March 2025](https://docs.getdbt.com/docs/dbt-versions/compatible-track-changelog#march-2025) * [February 2025](https://docs.getdbt.com/docs/dbt-versions/compatible-track-changelog#february-2025) * [dbt Cloud](https://docs.getdbt.com/docs/dbt-versions/compatible-track-changelog#dbt-cloud-1) * [Features](https://docs.getdbt.com/docs/dbt-versions/compatible-track-changelog#features) * [Fixes](https://docs.getdbt.com/docs/dbt-versions/compatible-track-changelog#fixes-2) * [January 2025](https://docs.getdbt.com/docs/dbt-versions/compatible-track-changelog#january-2025) * [dbt Cloud](https://docs.getdbt.com/docs/dbt-versions/compatible-track-changelog#dbt-cloud-2) * [Features](https://docs.getdbt.com/docs/dbt-versions/compatible-track-changelog#features-1) * [Fixes](https://docs.getdbt.com/docs/dbt-versions/compatible-track-changelog#fixes-3) * [December 2024](https://docs.getdbt.com/docs/dbt-versions/compatible-track-changelog#december-2024) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/dbt-versions/compatible-track-changelog.md) --- # Upgrading to v1.5 | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.5#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page dbt Core v1.5 is a feature release, with two significant additions: 1. [**Model governance**](https://docs.getdbt.com/docs/mesh/govern/about-model-governance) — access, contracts, versions — the first phase of [multi-project deployments](https://github.com/dbt-labs/dbt-core/discussions/6725) 2. A Python entry point for [**programmatic invocations**](https://docs.getdbt.com/reference/programmatic-invocations) , at parity with the CLI Resources[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.5#resources "Direct link to Resources") --------------------------------------------------------------------------------------------------------------------------------------------- * [Changelog](https://github.com/dbt-labs/dbt-core/blob/1.5.latest/CHANGELOG.md) * [dbt Core CLI Installation guide](https://docs.getdbt.com/docs/core/installation-overview) * [Cloud upgrade guide](https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-version-in-cloud) * [Release schedule](https://github.com/dbt-labs/dbt-core/issues/6715) What to know before upgrading[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.5#what-to-know-before-upgrading "Direct link to What to know before upgrading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- dbt Labs is committed to providing backward compatibility for all versions 1.x, with the exception of any changes explicitly mentioned below. If you encounter an error upon upgrading, please let us know by [opening an issue](https://github.com/dbt-labs/dbt-core/issues/new) . ### Behavior changes[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.5#behavior-changes "Direct link to Behavior changes") Why changes to previous behavior? This release includes significant new features, and rework to `dbt-core`'s CLI and initialization flow. As part of refactoring its internals from [`argparse`](https://docs.python.org/3/library/argparse.html) to [`click`](https://click.palletsprojects.com/) , we made a handful of changes to runtime configuration. The net result of these changes is more consistent and practical configuration options, and a more legible codebase. **_Wherever possible, we will provide backward compatibility and deprecation warnings for at least one minor version before actually removing the old functionality._** In those cases, we still reserve the right to fully remove backwards compatibility for deprecated functionality in a future v1.x minor version of `dbt-core`. Setting `log-path` and `target-path` in `dbt_project.yml` has been deprecated for consistency with other invocation-specific runtime configs ([dbt-core#6882](https://github.com/dbt-labs/dbt-core/issues/6882) ). We recommend setting via env var or CLI flag instead. The `dbt list` command will now include `INFO` level logs by default. Previously, the `list` command (and _only_ the `list` command) had `WARN`\-level stdout logging, to support piping its results to [`jq`](https://jqlang.github.io/jq/manual/) , a file, or another process. To achieve that goal, you can use either of the following parameters: * `dbt list --log-level warn` (recommended; equivalent to previous default) * `dbt --quiet list` (suppresses all logging less than ERROR level, except for "printed" messages and `list` output) The following env vars have been renamed, for consistency with the convention followed by all other parameters: * `DBT_DEFER_TO_STATE` → `DBT_DEFER` * `DBT_FAVOR_STATE_MODE` → `DBT_FAVOR_STATE` * `DBT_NO_PRINT` → `DBT_PRINT` * `DBT_ARTIFACT_STATE_PATH` → `DBT_STATE` As described in [dbt-core#7169](https://github.com/dbt-labs/dbt-core/pull/7169) , command-line parameters that could be silent before will no longer be silent. See [dbt-labs/dbt-core#7158](https://github.com/dbt-labs/dbt-core/issues/7158) and [dbt-labs/dbt-core#6800](https://github.com/dbt-labs/dbt-core/issues/6800) for more examples of the behavior we are fixing. An empty `tests:` key in a yaml file will now raise a validation error, instead of being silently skipped. You can resolve this by removing the empty `tests:` key, or by setting it to an empty list explicitly: # ❌ this will raise an errormodels: - name: my_model tests: config: ...# ✅ this is finemodels: - name: my_model tests: [] # todo! add tests later config: ... Some options that could previously be specified _after_ a subcommand can now only be specified _before_. This includes the inverse of the option, `--write-json` and `--no-write-json`, for example. The list of affected options are: List of affected options --cache-selected-only | --no-cache-selected-only--debug, -d | --no-debug--deprecated-print | --deprecated-no-print--enable-legacy-logger | --no-enable-legacy-logger--fail-fast, -x | --no-fail-fast--log-cache-events | --no-log-cache-events--log-format--log-format-file--log-level--log-level-file--log-path--macro-debugging | --no-macro-debugging--partial-parse | --no-partial-parse--partial-parse-file-path--populate-cache | --no-populate-cache--print | --no-print--printer-width--quiet, -q | --no-quiet--record-timing-info, -r--send-anonymous-usage-stats | --no-send-anonymous-usage-stats--single-threaded | --no-single-threaded--static-parser | --no-static-parser--use-colors | --no-use-colors--use-colors-file | --no-use-colors-file--use-experimental-parser | --no-use-experimental-parser--version, -V, -v--version-check | --no-version-check--warn-error--warn-error-options--write-json | --no-write-json Additionally, some options that could be previously specified _before_ a subcommand can now only be specified _after_. Any option _not_ in the above list must appear _after_ the subcommand from v1.5 and later. For example, `--profiles-dir`. The built-in [collect\_freshness](https://github.com/dbt-labs/dbt-core/blob/1.5.latest/core/dbt/include/global_project/macros/adapters/freshness.sql) macro now returns the entire `response` object, instead of just the `table` result. If you're using a custom override for `collect_freshness`, make sure you're also returning the `response` object; otherwise, some of your dbt commands will never finish. For example: {{ return(load_result('collect_freshness')) }} Finally: The [built-in `generate_alias_name` macro](https://github.com/dbt-labs/dbt-core/blob/1.5.latest/core/dbt/include/global_project/macros/get_custom_name/get_custom_alias.sql) now includes logic to handle versioned models. If your project has reimplemented the `generate_alias_name` macro with custom logic, and you want to start using [model versions](https://docs.getdbt.com/docs/mesh/govern/model-versions) , you will need to update the logic in your macro. Note that, while this is **not** a prerequisite for upgrading to v1.5—only for using the new feature—we recommend that you do this during your upgrade, whether you're planning to use model versions tomorrow or far in the future. Likewise, if your project has reimplemented the `ref` macro with custom logic, you will need to update the logic in your macro as described [here](https://docs.getdbt.com/reference/dbt-jinja-functions/builtins) . ### For consumers of dbt artifacts (metadata)[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.5#for-consumers-of-dbt-artifacts-metadata "Direct link to For consumers of dbt artifacts (metadata)") The [manifest](https://docs.getdbt.com/reference/artifacts/manifest-json) schema version will be updated to `v9`. Specific changes: * Addition of `groups` as a top-level key * Addition of `access`, `constraints`, `version`, `latest_version` as a top-level node attributes for models * Addition of `constraints` as a column-level attribute * Addition of `group` and `contract` as node configs * To support model versions, the type of `refs` has changed from `List[List[str]]` to `List[RefArgs]`, with nested keys `name: str`, `package: Optional[str] = None`, and `version: Union[str, float, NoneType] = None)`. ### For maintainers of adapter plugins[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.5#for-maintainers-of-adapter-plugins "Direct link to For maintainers of adapter plugins") For more detailed information and to ask questions, please read and comment on the GH discussion: [dbt-labs/dbt-core#7213](https://github.com/dbt-labs/dbt-core/discussions/7213) . New and changed documentation[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.5#new-and-changed-documentation "Direct link to New and changed documentation") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### Model governance[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.5#model-governance "Direct link to Model governance") The first phase of supporting dbt deployments at scale, across multiple projects with clearly defined ownership and interface boundaries. [Read about model governance](https://docs.getdbt.com/docs/mesh/govern/about-model-governance) , all of which is new in v1.5. ### Revamped CLI[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.5#revamped-cli "Direct link to Revamped CLI") Compile and preview dbt models and `--inline` dbt-SQL queries on the CLI using: * [`dbt compile`](https://docs.getdbt.com/reference/commands/compile) * [`dbt show`](https://docs.getdbt.com/reference/commands/show) (new!) [Node selection methods](https://docs.getdbt.com/reference/node-selection/methods) can use Unix-style wildcards to glob nodes matching a pattern: dbt ls --select "tag:team_*" And (!): a first-ever entry point for [programmatic invocations](https://docs.getdbt.com/reference/programmatic-invocations) , at parity with CLI commands. Run `dbt --help` to see new & improved help documentation :) ### Quick hits[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.5#quick-hits "Direct link to Quick hits") * The [`version: 2` top-level key](https://docs.getdbt.com/reference/project-configs/version) is now **optional** in all YAML files. Also, the [`config-version: 2`](https://docs.getdbt.com/reference/project-configs/config-version) and `version:` top-level keys are now optional in `dbt_project.yml` files. * [Events and logging](https://docs.getdbt.com/reference/events-logging) : Added `node_relation` (`database`, `schema`, `identifier`) to the `node_info` dictionary, available on node-specific events * Support setting `--project-dir` via environment variable: [`DBT_PROJECT_DIR`](https://docs.getdbt.com/reference/dbt_project.yml) * More granular configurations for logging (to set [log format](https://docs.getdbt.com/reference/global-configs/logs#log-formatting) , [log levels](https://docs.getdbt.com/reference/global-configs/logs#log-level) , and [colorization](https://docs.getdbt.com/reference/global-configs/logs#color) ) and [cache population](https://docs.getdbt.com/reference/global-configs/cache#cache-population) * [dbt overwrites the `manifest.json` file](https://docs.getdbt.com/reference/node-selection/state-comparison-caveats#overwrites-the-manifestjson) during parsing, which means when you reference `--state` from the `target/ directory`, you may encounter a warning indicating that the saved manifest wasn't found. Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Resources](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.5#resources) * [What to know before upgrading](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.5#what-to-know-before-upgrading) * [Behavior changes](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.5#behavior-changes) * [For consumers of dbt artifacts (metadata)](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.5#for-consumers-of-dbt-artifacts-metadata) * [For maintainers of adapter plugins](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.5#for-maintainers-of-adapter-plugins) * [New and changed documentation](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.5#new-and-changed-documentation) * [Model governance](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.5#model-governance) * [Revamped CLI](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.5#revamped-cli) * [Quick hits](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.5#quick-hits) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/dbt-versions/core-upgrade/11-Older%20versions/10-upgrading-to-v1.5.md) --- # Global navigation | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/explore/global-navigation#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page Learn how to enable and use global navigation in Catalog to search, explore, and analyze data assets across all your dbt projects and connected metadata sources. Discover cross-project lineage, data discovery, and unified analytics governance. For enterprise plans, Catalog introduces the ability to widen your search by including dbt resources (models, seeds, snapshots, sources, exposures, and more) across your entire account, and the option to discover external metadata. For Starter plans (single project), you’ll still benefit from the new navigation and search experience within your project. Prerequisites[​](https://docs.getdbt.com/docs/explore/global-navigation#prerequisites "Direct link to Prerequisites") ---------------------------------------------------------------------------------------------------------------------- To enable global navigation: * Have a [developer license with Owner](https://docs.getdbt.com/docs/cloud/manage-access/about-user-access#role-based-access-control) permissions. * Navigate to your [account settings](https://docs.getdbt.com/docs/cloud/account-settings) in your dbt account and check the box to **Enable dbt Catalog’s (formerly dbt Explorer) New Navigation**. About Global navigation[​](https://docs.getdbt.com/docs/explore/global-navigation#about-global-navigation "Direct link to About Global navigation") ---------------------------------------------------------------------------------------------------------------------------------------------------- Global navigation in Catalog lets you search, explore, and analyze data assets across all your dbt projects and connected metadata sources—giving you a unified, account-wide view of your analytics ecosystem. With global navigation, you can: * Search data assets — expand your search by including dbt resources (models, seeds, snapshots, sources, exposures, and more) across your entire account. This broadens the results returned and gives you greater insight into all the assets across your dbt projects. * External metadata ingestion — connect directly to your data warehouse, giving you visibility into tables, views, and other resources that aren't defined in dbt with Catalog. * Explore lineage — explore an interactive map of data relationships across all your dbt projects. It lets you: * View upstream/downstream dependencies for models, sources, and more. * Drill into project and column-level lineage, including multi-project (Mesh) links. * Filter with "lineage lenses" by resource type, materialization, layer, or run status. * Troubleshoot data issues by tracing root causes and downstream impacts. * Optimize pipelines by spotting slow, failing, or unused parts of your DAG. * See recommendations — global navigation offers a project-wide snapshot of dbt health, highlighting actionable tips to enhance your analytics engineering. These insights are automatically generated using dbt metadata and best practices from the project evaluator ruleset. * View model query history — see how often each dbt model is queried in your warehouse, helping you: * Track real usage via successful `SELECT`s (excluding builds/tests) * Identify most/least used models for optimization or deprecation * Guide investment and maintenance with data-driven insights * Track downstream exposures — monitor how your dbt models and sources are used by BI tools, apps, ML models, and reports across all connected projects Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Prerequisites](https://docs.getdbt.com/docs/explore/global-navigation#prerequisites) * [About Global navigation](https://docs.getdbt.com/docs/explore/global-navigation#about-global-navigation) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/explore/explore-global-nav.md) --- # Model performance | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/explore/model-performance#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page Catalog provides metadata on dbt runs for in-depth model performance and quality analysis. This feature assists in reducing infrastructure costs and saving time for data teams by highlighting where to fine-tune projects and deployments — such as model refactoring or job configuration adjustments. [![Overview of Performance page navigation.](https://docs.getdbt.com/img/docs/collaborate/dbt-explorer/explorer-model-performance.gif?v=2 "Overview of Performance page navigation.")](https://docs.getdbt.com/docs/explore/model-performance#) Overview of Performance page navigation. On-demand learning If you enjoy video courses, check out our [dbt Catalog on-demand course](https://learn.getdbt.com/courses/dbt-catalog) and learn how to best explore your dbt project(s)! The Performance overview page[​](https://docs.getdbt.com/docs/explore/model-performance#the-performance-overview-page "Direct link to The Performance overview page") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- You can pinpoint areas for performance enhancement by using the Performance overview page. This page presents a comprehensive analysis across all project models and displays the longest-running models, those most frequently executed, and the ones with the highest failure rates during runs/tests. Data can be segmented by environment and job type which can offer insights into: * Most executed models (total count). * Models with the longest execution time (average duration). * Models with the most failures, detailing run failures (percentage and count) and test failures (percentage and count). Each data point links to individual models in Catalog. [![Example of Performance overview page](https://docs.getdbt.com/img/docs/collaborate/dbt-explorer/example-performance-overview-page.png?v=2 "Example of Performance overview page")](https://docs.getdbt.com/docs/explore/model-performance#) Example of Performance overview page You can view historical metadata for up to the past three months. Select the time horizon using the filter, which defaults to a two-week lookback. [![Example of dropdown](https://docs.getdbt.com/img/docs/collaborate/dbt-explorer/ex-2-week-default.png?v=2 "Example of dropdown")](https://docs.getdbt.com/docs/explore/model-performance#) Example of dropdown The Model performance tab[​](https://docs.getdbt.com/docs/explore/model-performance#the-model-performance-tab "Direct link to The Model performance tab") ---------------------------------------------------------------------------------------------------------------------------------------------------------- You can view trends in execution times, counts, and failures by using the Model performance tab for historical performance analysis. Daily execution data includes: * Average model execution time. * Model execution counts, including failures/errors (total sum). Clicking on a data point reveals a table listing all job runs for that day, with each row providing a direct link to the details of a specific run. [![Example of the Model performance tab](https://docs.getdbt.com/img/docs/collaborate/dbt-explorer/example-model-performance-tab.png?v=2 "Example of the Model performance tab")](https://docs.getdbt.com/docs/explore/model-performance#) Example of the Model performance tab Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [The Performance overview page](https://docs.getdbt.com/docs/explore/model-performance#the-performance-overview-page) * [The Model performance tab](https://docs.getdbt.com/docs/explore/model-performance#the-model-performance-tab) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/explore/model-performance.md) --- # Setting up state-aware orchestration | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/deploy/state-aware-setup#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page Set up state-aware orchestration to automatically determine which models to build by detecting changes in code or data and only building the changed models each time a job is run. important The dbt Fusion Engine is currently available for installation in: * [Local command line interface (CLI) tools](https://docs.getdbt.com/docs/fusion/install-fusion-cli) [preview](https://docs.getdbt.com/docs/dbt-versions/product-lifecycles "Go to https://docs.getdbt.com/docs/dbt-versions/product-lifecycles") * [VS Code and Cursor with the dbt extension](https://docs.getdbt.com/docs/install-dbt-extension) [preview](https://docs.getdbt.com/docs/dbt-versions/product-lifecycles "Go to https://docs.getdbt.com/docs/dbt-versions/product-lifecycles") * [dbt platform environments](https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-version-in-cloud#dbt-fusion-engine) [beta](https://docs.getdbt.com/docs/dbt-versions/product-lifecycles "Go to https://docs.getdbt.com/docs/dbt-versions/product-lifecycles") Join the conversation in our Community Slack channel [`#dbt-fusion-engine`](https://getdbt.slack.com/archives/C088YCAB6GH) . Read the [Fusion Diaries](https://github.com/dbt-labs/dbt-fusion/discussions/categories/announcements) for the latest updates. Prerequisites[​](https://docs.getdbt.com/docs/deploy/state-aware-setup#prerequisites "Direct link to Prerequisites") --------------------------------------------------------------------------------------------------------------------- To use state-aware orchestration, make sure you meet these prerequisites: * You must have a dbt [Enterprise and Enterprise+ accounts](https://www.getdbt.com/signup/) and a [Developer seat license](https://docs.getdbt.com/docs/cloud/manage-access/seats-and-users) . * You have updated the environment that will run state-aware orchestration to the dbt Fusion engine. For more information, refer to [Upgrading to dbt Fusion engine](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-fusion) . * You must have a dbt project connected to a [data platform](https://docs.getdbt.com/docs/cloud/connect-data-platform/about-connections) . * You must have [access permission](https://docs.getdbt.com/docs/cloud/manage-access/about-user-access) to view, create, modify, or run jobs. * You must set up a [deployment environment](https://docs.getdbt.com/docs/deploy/deploy-environments) . * (Optional) To customize behavior, you have configured your model or source data with [advanced configurations](https://docs.getdbt.com/docs/deploy/state-aware-setup#advanced-configurations) . info State-aware orchestration is available for SQL models only. Python models are not supported. Default settings[​](https://docs.getdbt.com/docs/deploy/state-aware-setup#default-settings "Direct link to Default settings") ------------------------------------------------------------------------------------------------------------------------------ By default, for an Enterprise-tier account upgraded to the dbt Fusion engine, any newly created job will automatically be state-aware. Out of the box, without custom configurations, when you run a job, the job will only build models when either the code has changed, or there’s any new data in a source. Create a job[​](https://docs.getdbt.com/docs/deploy/state-aware-setup#create-a-job "Direct link to Create a job") ------------------------------------------------------------------------------------------------------------------ New jobs are state aware by default. If you have existing jobs, you need to unselect **Force node selection** in your job settings to make them state aware. To create a state-aware job: 1. From your deployment environment page, click **Create job** and select **Deploy job**. 2. Options in the **Job settings** section: * **Job name**: Specify the name, for example, `Daily build`. * (Optional) **Description**: Provide a description of what the job does (for example, what the job consumes and what the job produces). * **Environment**: By default, it’s set to the deployment environment you created the state-aware job from. 3. Options in the **Execution settings** and **Triggers** sections: **Note:** New jobs are state aware by default. For existing jobs, you need to uncheck **Force-node selection** under "execution settings" in the Job settings page. [![Example of Triggers on the Deploy Job page](https://docs.getdbt.com/img/docs/dbt-cloud/using-dbt-cloud/example-triggers-section.png?v=2 "Example of Triggers on the Deploy Job page")](https://docs.getdbt.com/docs/deploy/state-aware-setup#) Example of Triggers on the Deploy Job page * **Execution settings** section: * **Commands**: By default, it includes the `dbt build` command. Click **Add command** to add more [commands](https://docs.getdbt.com/docs/deploy/job-commands) that you want to be invoked when the job runs. * **Generate docs on run**: Enable this option if you want to [generate project docs](https://docs.getdbt.com/docs/build/documentation) when this deploy job runs. * **Force node selection**: Enable this option only if you want to rebuild nodes every with every job run and to ignore data freshness. Disable (uncheck the box) to allow state-aware orchestration. * **Triggers** section: * **Run on schedule**: Run the deploy job on a set schedule. * **Timing**: Specify whether to [schedule](https://docs.getdbt.com/docs/deploy/state-aware-setup#schedule-days) the deploy job using **Intervals** that run the job every specified number of hours, **Specific hours** that run the job at specific times of day, or **Cron schedule** that run the job specified using [cron syntax](https://docs.getdbt.com/docs/deploy/state-aware-setup#cron-schedule) . * **Days of the week**: By default, it’s set to every day when **Intervals** or **Specific hours** is chosen for **Timing**. * **Run when another job finishes**: Run the deploy job when another _upstream_ deploy [job completes](https://docs.getdbt.com/docs/deploy/state-aware-setup#trigger-on-job-completion) . * **Project**: Specify the parent project that has that upstream deploy job. * **Job**: Specify the upstream deploy job. * **Completes on**: Select the job run status(es) that will [enqueue](https://docs.getdbt.com/docs/deploy/job-scheduler#scheduler-queue) the deploy job. 6. (Optional) Options in the **Advanced settings** section: * **Environment variables**: Define [environment variables](https://docs.getdbt.com/docs/build/environment-variables) to customize the behavior of your project when the deploy job runs. * **Target name**: Define the [target name](https://docs.getdbt.com/docs/build/custom-target-names) to customize the behavior of your project when the deploy job runs. Environment variables and target names are often used interchangeably. * **Run timeout**: Cancel the deploy job if the run time exceeds the timeout value. * **Compare changes against**: By default, it’s set to **No deferral**. Select either **Environment** or **This Job** to let dbt know what it should compare the changes against. You can see which models dbt builds in the run summary logs. Models that weren't rebuilt during the run will show **reusing** in the logs alongside the reason that dbt was able to skip building the model (and saving you unnecessary compute!) [![Example logs for state-aware orchestration](https://docs.getdbt.com/img/docs/dbt-cloud/using-dbt-cloud/SAO_logs_view.png?v=2 "Example logs for state-aware orchestration")](https://docs.getdbt.com/docs/deploy/state-aware-setup#) Example logs for state-aware orchestration Delete a job[​](https://docs.getdbt.com/docs/deploy/state-aware-setup#delete-a-job "Direct link to Delete a job") ------------------------------------------------------------------------------------------------------------------ To delete a job or multiple jobs in dbt: 1. Click **Deploy** on the navigation header. 2. Click **Jobs** and select the job you want to delete. 3. Click **Settings** on the top right of the page and then click **Edit**. 4. Scroll to the bottom of the page and click **Delete** to delete the job. [![Delete a job](https://docs.getdbt.com/img/docs/dbt-cloud/cloud-configuring-dbt-cloud/delete-job.png?v=2 "Delete a job")](https://docs.getdbt.com/docs/deploy/state-aware-setup#) Delete a job 5. Confirm your action in the pop-up by clicking **Confirm delete** in the bottom right to delete the job immediately. This action cannot be undone. However, you can create a new job with the same information if the deletion was made in error. 6. Refresh the page, and the deleted job should now be gone. If you want to delete multiple jobs, you'll need to perform these steps for each job. If you're having any issues, feel free to [contact us](mailto:support@getdbt.com) for additional help. Advanced configurations[​](https://docs.getdbt.com/docs/deploy/state-aware-setup#advanced-configurations "Direct link to Advanced configurations") --------------------------------------------------------------------------------------------------------------------------------------------------- By default, we use the warehouse metadata to check if sources (or upstream models in the case of Mesh) are fresh. For more advanced use cases, dbt provides other options that enable you to specify what gets run by state-aware orchestration. You can customize with: * `loaded_at_field`: Specify a specific column to use from the data. * `loaded_at_query`: Define a custom freshness condition in SQL to account for partial loading or streaming data. note You can either define `loaded_at_field` or `loaded_at_query` but not both. You can also customize with: * `updates_on`: Change the default from any to all so it doesn’t build unless all upstreams have fresh data reducing compute even more. * `Build_after`: Don’t build a model more often than every x period to reduce build frequency when you need data less often than sources refresh. To learn more about model freshness and build after, refer to [model `freshness` config](https://docs.getdbt.com/reference/resource-configs/freshness) . To learn more about source and upstream model freshness configs, refer to [resource `freshness` config](https://docs.getdbt.com/reference/resource-properties/freshness) Customizing behavior[​](https://docs.getdbt.com/docs/deploy/state-aware-setup#customizing-behavior "Direct link to Customizing behavior") ------------------------------------------------------------------------------------------------------------------------------------------ You can optionally configure state-aware orchestration when you want to fine-tune orchestration behavior for these reasons: * **Defining source freshness:** By default, dbt uses metadata from the data warehouse. You can instead: * Specify a custom column and dbt will go to that column in the table instead * Specify a custom SQL statement to define what freshness means Not all source freshness is equal — especially with partial ingestion pipelines. You may want to delay a model build until your sources have received a larger volume of data or until a specific time window has passed. You can define what "fresh" means on a source-by-source basis using a custom freshness query. This lets you: * Add a time difference to account for late-arriving data * Delay freshness detection until a threshold is reached (for example, number of records or hours of data) * **Reducing model build frequency** Some models don’t need to be rebuilt every time their source data is updated. To control this: * Set a refresh interval on models, folders, or the project to define how often they should be rebuilt at most * This helps avoid overbuilding and reduces costs by only running what's really needed * **Changing the default from `any` to `all`** Based on what a model depends on upstream, you may want to wait until all upstream models have been refreshed rather than going as soon as there is any new data. * Change what orchestration waits on from any to all for models, folders, or the project to wait until all upstream models have new data * This helps avoid overbuilding and reduces costs by building models once everything has been refreshed To configure and customize behavior, you can do so in the following places using the `build_after` config: * `dbt_project.yml` at the project level in YAML * `model/properties.yml` at the model level in YAML * `model/model.sql` at the model level in SQL These configurations are powerful because you can define a sensible default at the project level or for specific model folders, and override it for individual models or model groups that require more frequent updates. Example[​](https://docs.getdbt.com/docs/deploy/state-aware-setup#example "Direct link to Example") --------------------------------------------------------------------------------------------------- Let's use an example to illustrate how to customize our project so a model and its parent model are rebuilt only if they haven't been refreshed in the past 4 hours — even if a job runs more frequently than that. A Jaffle shop has recently expanded globally and wanted to make savings. To reduce spend, they found out about dbt's state-aware orchestration and want to rebuild models only when needed. Maggie — the analytics engineer — wants to configure her dbt `jaffle_shop` project to only rebuild certain models if they haven't been refreshed in the last 4 hours, even if a job runs more often than that. To do this, she uses the model `freshness` config. This config helps state-aware orchestration decide _when_ a model should be rebuilt. Note that for every `freshness` config, you're required to either set values for both `count` and `period`, or set `freshness: null`. This requirement applies to all `freshness` types: `freshness.warn_after`, `freshness.error_after`, and `freshness.build_after`. Refer to the following samples for using the `freshness` config in the model file, in the project file, and in the `config` block of the `model.sql` file: * Model YAML * Project file * Config block models/model.yml models: - name: dim_wizards config: freshness: build_after: count: 4 # how long to wait before rebuilding period: hour # unit of time updates_on: all # only rebuild if all upstream dependencies have new data - name: dim_worlds config: freshness: build_after: count: 4 period: hour updates_on: all dbt\_project.yml models: : +freshness: build_after: count: 4 period: hour updates_on: all models/.sql {{ config( freshness={ "build_after": { "count": 4, "period": "hour", "updates_on": "all" } } )}} With this config, dbt: * Checks if there's new data in the upstream sources * Checks when `dim_wizards` and `dim_worlds` were last built If any new data is available _and_ at least 4 hours have passed, dbt rebuilds the models. ### Differences between `all` and `any`[​](https://docs.getdbt.com/docs/deploy/state-aware-setup#differences-between-all-and-any "Direct link to differences-between-all-and-any") * Since Maggie configured `updates_on: all`, this means _both_ models must have new upstream data to trigger a rebuild. If only one model has fresh data and the other doesn't, nothing is built -- which will massively reduce unnecessary compute costs and save time. * If Maggie wanted these models to rebuild more often (for example, if _any_ upstream source has new data), she would then use `updates_on: any` instead: models/model.yml freshness: build_after: count: 1 period: hour updates_on: any This way, if either `dim_wizards` or `dim_worlds` has fresh upstream data and enough time passed, dbt rebuilds the models. This method helps when the need for fresher data outweighs the costs. Related docs[​](https://docs.getdbt.com/docs/deploy/state-aware-setup#related-docs "Direct link to Related docs") ------------------------------------------------------------------------------------------------------------------ * [State-aware orchestration configuration](https://docs.getdbt.com/docs/deploy/state-aware-about) * [Artifacts](https://docs.getdbt.com/docs/deploy/artifacts) * [Continuous integration (CI) jobs](https://docs.getdbt.com/docs/deploy/ci-jobs) * [`freshness`](https://docs.getdbt.com/reference/resource-configs/freshness) Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Prerequisites](https://docs.getdbt.com/docs/deploy/state-aware-setup#prerequisites) * [Default settings](https://docs.getdbt.com/docs/deploy/state-aware-setup#default-settings) * [Create a job](https://docs.getdbt.com/docs/deploy/state-aware-setup#create-a-job) * [Delete a job](https://docs.getdbt.com/docs/deploy/state-aware-setup#delete-a-job) * [Advanced configurations](https://docs.getdbt.com/docs/deploy/state-aware-setup#advanced-configurations) * [Customizing behavior](https://docs.getdbt.com/docs/deploy/state-aware-setup#customizing-behavior) * [Example](https://docs.getdbt.com/docs/deploy/state-aware-setup#example) * [Differences between `all` and `any`](https://docs.getdbt.com/docs/deploy/state-aware-setup#differences-between-all-and-any) * [Related docs](https://docs.getdbt.com/docs/deploy/state-aware-setup#related-docs) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/deploy/state-aware-setup.md) --- # Upgrading to v1.9 | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.9#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page Resources[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.9#resources "Direct link to Resources") ---------------------------------------------------------------------------------------------------------------------------- * [dbt Core 1.9 changelog](https://github.com/dbt-labs/dbt-core/blob/1.9.latest/CHANGELOG.md) * [dbt Core CLI Installation guide](https://docs.getdbt.com/docs/core/installation-overview) * [Cloud upgrade guide](https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-version-in-cloud#release-tracks) What to know before upgrading[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.9#what-to-know-before-upgrading "Direct link to What to know before upgrading") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- dbt Labs is committed to providing backward compatibility for all versions 1.x. Any behavior changes will be accompanied by a [behavior change flag](https://docs.getdbt.com/reference/global-configs/behavior-changes#behavior-change-flags) to provide a migration window for existing projects. If you encounter an error upon upgrading, please let us know by [opening an issue](https://github.com/dbt-labs/dbt-core/issues/new) . Starting in 2024, dbt provides the functionality from new versions of dbt Core via [release tracks](https://docs.getdbt.com/docs/dbt-versions/cloud-release-tracks) with automatic upgrades. If you have selected the "Latest" release track in dbt, you already have access to all the features, fixes, and other functionality that is included in dbt Core v1.9! If you have selected the "Compatible" release track, you will have access in the next monthly "Compatible" release after the dbt Core v1.9 final release. For users of dbt Core, since v1.8, we recommend explicitly installing both `dbt-core` and `dbt-`. This may become required for a future version of dbt. For example: python3 -m pip install dbt-core dbt-snowflake New and changed features and functionality[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.9#new-and-changed-features-and-functionality "Direct link to New and changed features and functionality") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Features and functionality new in dbt v1.9. ### Microbatch `incremental_strategy`[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.9#microbatch-incremental_strategy "Direct link to microbatch-incremental_strategy") info If you use a custom microbatch macro, set the [`require_batched_execution_for_custom_microbatch_strategy`](https://docs.getdbt.com/reference/global-configs/behavior-changes#custom-microbatch-strategy) behavior flag in your `dbt_project.yml` to enable batched execution. If you don't have a custom microbatch macro, you don't need to set this flag as dbt will handle microbatching automatically for any model using the microbatch strategy. Incremental models are, and have always been, a _performance optimization_ — for datasets that are too large to be dropped and recreated from scratch every time you do a `dbt run`. Learn more about [incremental models](https://docs.getdbt.com/docs/build/incremental-models-overview) . Historically, managing incremental models involved several manual steps and responsibilities, including: * Add a snippet of dbt code (in an `is_incremental()` block) that uses the already-existing table (`this`) as a rough bookmark, so that only new data gets processed. * Pick one of the strategies for smushing old and new data together (`append`, `delete+insert`, or `merge`). * If anything goes wrong, or your schema changes, you can always "full-refresh", by running the same simple query that rebuilds the whole table from scratch. While this works for many use-cases, there’s a clear limitation with this approach: _Some datasets are just too big to fit into one query._ Starting in Core 1.9, you can use the new [microbatch strategy](https://docs.getdbt.com/docs/build/incremental-microbatch#what-is-microbatch-in-dbt) to optimize your largest datasets -- **process your event data in discrete periods with their own SQL queries, rather than all at once.** The benefits include: * Simplified query design: Write your model query for a single batch of data. dbt will use your `event_time`, `lookback`, and `batch_size` configurations to automatically generate the necessary filters for you, making the process more streamlined and reducing the need for you to manage these details. * Independent batch processing: dbt automatically breaks down the data to load into smaller batches based on the specified `batch_size` and processes each batch independently, improving efficiency and reducing the risk of query timeouts. If some of your batches fail, you can use `dbt retry` to load only the failed batches. * Targeted reprocessing: To load a _specific_ batch or batches, you can use the CLI arguments `--event-time-start` and `--event-time-end`. * [Automatic parallel batch execution](https://docs.getdbt.com/docs/build/parallel-batch-execution) : Process multiple batches at the same time, instead of one after the other (sequentially) for faster processing of your microbatch models. dbt intelligently auto-detects if your batches can run in parallel, while also allowing you to manually override parallel execution with the [`concurrent_batches` config](https://docs.getdbt.com/reference/resource-properties/concurrent_batches) . Currently microbatch is supported on these adapters with more to come: * postgres * redshift * snowflake * bigquery * spark * databricks ### Snapshots improvements[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.9#snapshots-improvements "Direct link to Snapshots improvements") Beginning in dbt Core 1.9, we've streamlined snapshot configuration and added a handful of new configurations to make dbt **snapshots easier to configure, run, and customize.** These improvements include: * New snapshot specification: Snapshots can now be configured in a YAML file, which provides a cleaner and more consistent set up. * New `snapshot_meta_column_names` config: Allows you to customize the names of meta fields (for example, `dbt_valid_from`, `dbt_valid_to`, etc.) that dbt automatically adds to snapshots. This increases flexibility to tailor metadata to your needs. * `target_schema` is now optional for snapshots: When omitted, snapshots will use the schema defined for the current environment. * Standard `schema` and `database` configs supported: Snapshots will now be consistent with other dbt resource types. You can specify where environment-aware snapshots should be stored. * Warning for incorrect `updated_at` data type: To ensure data integrity, you'll see a warning if the `updated_at` field specified in the snapshot configuration is not the proper data type or timestamp. * Set a custom current indicator for the value of `dbt_valid_to`: Use the [`dbt_valid_to_current` config](https://docs.getdbt.com/reference/resource-configs/dbt_valid_to_current) to set a custom indicator for the value of `dbt_valid_to` in current snapshot records (like a future date). By default, this value is `NULL`. When configured, dbt will use the specified value instead of `NULL` for `dbt_valid_to` for current records in the snapshot table. * Use the [`hard_deletes`](https://docs.getdbt.com/reference/resource-configs/hard-deletes) configuration to get more control on how to handle deleted rows from the source. Supported methods are `ignore` (default), `invalidate` (replaces legacy `invalidate_hard_deletes=true`), and `new_record`. Setting `hard_deletes='new_record'` allows you to track hard deletes by adding a new record when row becomes "deleted" in source. Read more about [Snapshots meta fields](https://docs.getdbt.com/docs/build/snapshots#snapshot-meta-fields) . To learn how to safely migrate existing snapshots, refer to [Snapshot configuration migration](https://docs.getdbt.com/reference/snapshot-configs#snapshot-configuration-migration) for more information. ### Some `properties` moved to `configs`[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.9#some-properties-moved-to-configs "Direct link to some-properties-moved-to-configs") The following `properties` were moved to `configs` in [Core v1.10](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.10) and backported to Core v1.9: * [`freshness`](https://docs.getdbt.com/reference/resource-properties/freshness) for sources * [`meta`](https://docs.getdbt.com/reference/resource-configs/meta) under `columns` * [`tags`](https://docs.getdbt.com/reference/resource-configs/tags) under `columns` ### `state:modified` improvements[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.9#statemodified-improvements "Direct link to statemodified-improvements") We’ve made improvements to `state:modified` behaviors to help reduce the risk of false positives and negatives. Read more about [the `state:modified` behavior flag](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.9#managing-changes-to-legacy-behaviors) that unlocks this improvement: * Added environment-aware enhancements for environments where the logic purposefully differs (for example, materializing as a table in `prod` but a `view` in dev). ### Managing changes to legacy behaviors[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.9#managing-changes-to-legacy-behaviors "Direct link to Managing changes to legacy behaviors") dbt Core v1.9 has a handful of new flags for [managing changes to legacy behaviors](https://docs.getdbt.com/reference/global-configs/behavior-changes) . You may opt into recently introduced changes (disabled by default), or opt out of mature changes (enabled by default), by setting `True` / `False` values, respectively, for `flags` in `dbt_project.yml`. You can read more about each of these behavior changes in the following links: * (Introduced, disabled by default) [`state_modified_compare_more_unrendered_values`](https://docs.getdbt.com/reference/global-configs/behavior-changes#behavior-change-flags) . Set to `True` to start persisting `unrendered_database` and `unrendered_schema` configs during source parsing, and do comparison on unrendered values during `state:modified` checks to reduce false positives due to environment-aware logic when selecting `state:modified`. * (Introduced, disabled by default) [`skip_nodes_if_on_run_start_fails` project config flag](https://docs.getdbt.com/reference/global-configs/behavior-changes#behavior-change-flags) . If the flag is set and **any** `on-run-start` hook fails, mark all selected nodes as skipped. * `on-run-start/end` hooks are **always** run, regardless of whether they passed or failed last time. * (Introduced, disabled by default) [\[Redshift\] `restrict_direct_pg_catalog_access`](https://docs.getdbt.com/reference/global-configs/behavior-changes#redshift-restrict_direct_pg_catalog_access) . If the flag is set the adapter will use the Redshift API (through the Python client) if available, or query Redshift's `information_schema` tables instead of using `pg_` tables. * (Introduced, disabled by default) [`require_nested_cumulative_type_params`](https://docs.getdbt.com/reference/global-configs/behavior-changes#cumulative-metrics) . If the flag is set to `True`, users will receive an error instead of a warning if they're not properly formatting cumulative metrics using the new [`cumulative_type_params`](https://docs.getdbt.com/docs/build/cumulative#parameters) nesting. * (Introduced, disabled by default) [`require_batched_execution_for_custom_microbatch_strategy`](https://docs.getdbt.com/reference/global-configs/behavior-changes#custom-microbatch-strategy) . Set to `True` if you use a custom microbatch macro to enable batched execution. If you don't have a custom microbatch macro, you don't need to set this flag as dbt will handle microbatching automatically for any model using the microbatch strategy. Adapter specific features and functionalities[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.9#adapter-specific-features-and-functionalities "Direct link to Adapter specific features and functionalities") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### Redshift[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.9#redshift "Direct link to Redshift") * Support IAM Role auth ### Snowflake[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.9#snowflake "Direct link to Snowflake") * Iceberg Table Format — Support will be available on three out-of-the-box materializations: table, incremental, dynamic tables. * Breaking change — When upgrading from dbt 1.8 to 1.9 `{{ target.account }}` replaces underscores with dashes. For example, if the `target.account` is set to `sample_company`, then the compiled code now generates `sample-company`. [Refer to the `dbt-snowflake` issue](https://github.com/dbt-labs/dbt-snowflake/issues/1286) for more information. ### Bigquery[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.9#bigquery "Direct link to Bigquery") * Can cancel running queries on keyboard interrupt * Auto-drop intermediate tables created by incremental models to save resources ### Spark[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.9#spark "Direct link to Spark") * Support overriding the ODBC driver connection string which now enables you to provide custom connections Quick hits[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.9#quick-hits "Direct link to Quick hits") ------------------------------------------------------------------------------------------------------------------------------- We also made some quality-of-life improvements in Core 1.9, enabling you to: * Maintain data quality now that dbt returns an error (versioned models) or warning (unversioned models) when someone [removes a contracted model by deleting, renaming, or disabling](https://docs.getdbt.com/docs/mesh/govern/model-contracts#how-are-breaking-changes-handled) it. * Document [data tests](https://docs.getdbt.com/reference/resource-properties/description) . * Use `ref` and `source` in [foreign key constraints](https://docs.getdbt.com/reference/resource-properties/constraints) . * Use `dbt test` with the `--resource-type` / `--exclude-resource-type` flag, making it possible to include or exclude data tests (`test`) or unit tests (`unit_test`). * The [`enabled`](https://docs.getdbt.com/reference/resource-configs/enabled) config is now available for unit tests. Defaults to `true` if not defined. Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Resources](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.9#resources) * [What to know before upgrading](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.9#what-to-know-before-upgrading) * [New and changed features and functionality](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.9#new-and-changed-features-and-functionality) * [Microbatch `incremental_strategy`](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.9#microbatch-incremental_strategy) * [Snapshots improvements](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.9#snapshots-improvements) * [Some `properties` moved to `configs`](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.9#some-properties-moved-to-configs) * [`state:modified` improvements](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.9#statemodified-improvements) * [Managing changes to legacy behaviors](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.9#managing-changes-to-legacy-behaviors) * [Adapter specific features and functionalities](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.9#adapter-specific-features-and-functionalities) * [Redshift](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.9#redshift) * [Snowflake](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.9#snowflake) * [Bigquery](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.9#bigquery) * [Spark](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.9#spark) * [Quick hits](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.9#quick-hits) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/dbt-versions/core-upgrade/06-upgrading-to-v1.9.md) --- # Install the dbt VS Code extension | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/fusion/install-dbt-extension#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page The dbt extension for VS Code and Cursor streamlines dbt development workflows. The dbt extension is powered by the dbt Fusion Engine. Prerequisites[​](https://docs.getdbt.com/docs/fusion/install-dbt-extension#prerequisites "Direct link to Prerequisites") ------------------------------------------------------------------------------------------------------------------------- To use the extension, you must meet the following prerequisites: * The dbt extension requires installation of the dbt Fusion Engine. Fusion installation is part of the extension installation process, but you can also [manually install](https://docs.getdbt.com/docs/fusion/install-fusion) separate from this workflow, either before or after the extension is installed. * You are using the [VS Code](https://code.visualstudio.com/) or [Cursor](https://www.cursor.com/en) code editor. * You are not using (or have disabled) third-party dbt extensions. * You are using a macOS or Linux-based computer. Installation instructions[​](https://docs.getdbt.com/docs/fusion/install-dbt-extension#installation-instructions "Direct link to Installation instructions") ------------------------------------------------------------------------------------------------------------------------------------------------------------- note This is the only official dbt Labs VS Code extension. Please disable or uninstall any third-party dbt extensions before installing to avoid issues. Read the [Fusion Diaries](https://github.com/dbt-labs/dbt-fusion/discussions/categories/announcements) for the latest updates. In VS Code: 1. Navigate to the **Extensions** tab of your editor and search for `dbt`. Locate the extension from the publisher `dbtLabsInc` or `dbt Labs Inc`. Click **Install**. [![Search for the extension](https://docs.getdbt.com/img/docs/extension/extension-marketplace.png?v=2 "Search for the extension")](https://docs.getdbt.com/docs/fusion/install-dbt-extension#) Search for the extension 2. Open a dbt project in your VS Code environment if you haven't already. Make sure it is added to your current workspace. If you see a **dbt Extension** label in your editor's status bar, then the extension has installed successfully. You can hover over this **dbt Extension** label to see diagnostic information about the extension. [![If you see the 'dbt Extension` label, the extension is activated](https://docs.getdbt.com/img/docs/extension/dbt-extension-statusbar.png?v=2 "If you see the 'dbt Extension` label, the extension is activated")](https://docs.getdbt.com/docs/fusion/install-dbt-extension#) If you see the 'dbt Extension\` label, the extension is activated 3. Once the dbt extension is activated, it will automatically begin downloading the correct dbt Language Server for your operating system. [![The dbt Language Server will be installed automatically](https://docs.getdbt.com/img/docs/extension/extension-lsp-download.png?v=2 "The dbt Language Server will be installed automatically")](https://docs.getdbt.com/docs/fusion/install-dbt-extension#) The dbt Language Server will be installed automatically 4. If the dbt Fusion engine is not already installed on your machine, the extension will prompt you to download and install it. Follow the steps shown in the notification to complete the installation. [![Follow the prompt to install the dbt Fusion engine](https://docs.getdbt.com/img/docs/extension/install-dbt-fusion-engine.png?v=2 "Follow the prompt to install the dbt Fusion engine")](https://docs.getdbt.com/docs/fusion/install-dbt-extension#) Follow the prompt to install the dbt Fusion engine 5. Run the VS Code extension [upgrade tool](https://docs.getdbt.com/docs/fusion/install-dbt-extension#upgrade-to-fusion) to ensure your dbt project is Fusion ready and help you fix any errors and deprecations. 6. You're all set up! See [about the dbt extension](https://docs.getdbt.com/docs/about-dbt-extension) for more information on how to use the dbt extension. [![Showing lineage and compiled code in the extension](https://docs.getdbt.com/img/docs/extension/kitchen-sink.png?v=2 "Showing lineage and compiled code in the extension")](https://docs.getdbt.com/docs/fusion/install-dbt-extension#) Showing lineage and compiled code in the extension Upgrade to Fusion[​](https://docs.getdbt.com/docs/fusion/install-dbt-extension#upgrade-to-fusion "Direct link to Upgrade to Fusion") ------------------------------------------------------------------------------------------------------------------------------------- note If you are already running the dbt Fusion Engine, you must be on version `2.0.0-beta.66` or higher to use the upgrade tool. The dbt extension provides a built-in upgrade tool to walk you through the process of configuring Fusion and updating your dbt project to support all of its features and fix any deprecated code. To start the process: 1. From the VS Code left-side menu, click the **dbt logo**. 2. In the resulting pane, open the **Get started** section and click the **Get started** button. [![The dbt extension help pane and upgrade assistant.](https://docs.getdbt.com/img/docs/extension/fusion-onboarding-experience.png?v=2 "The dbt extension help pane and upgrade assistant.")](https://docs.getdbt.com/docs/fusion/install-dbt-extension#) The dbt extension help pane and upgrade assistant. You can also manually start this process by opening a CLI window and running: dbt init --fusion-upgrade This will start the upgrade tool and guide you through the Fusion upgrade with a series of prompts: * **Do you have an existing dbt platform account?**: If you answer `Y`, you will be given instructions for downloading your dbt platform profile to register the extension. An `N` answer will skip to the next step. * **Ready to run a dbtf init?** (If there is no `profiles.yml` file present): You will go through the dbt configuration processes, including connecting to your data warehouse. * **Ready to run a dbtf debug?** (If there is an existing `profiles.yml` file): Validates that your project is configured correctly and can connect to your data warehouse. * **Ready to run a dbtf parse?**: Your dbt project will be parsed to check for compatibility with Fusion. * If any issues are encountered during the parsing, you'll be given the option to run the [dbt-autofix](https://github.com/dbt-labs/dbt-autofix?tab=readme-ov-file#installation) tool to resolve the errors. If you opt to not run the tool during the upgrade processes, you can always run it later or manually fix any errors. However, the upgrade tool cannot continue until the errors are resolved. * **Ready to run a ‘dbtf compile -static-analysis off’?** (Only runs once the parse passes): Compiles your project without any static analysis, mimicking dbt Core. This compile only renders Jinja into SQL, so Fusion's advanced SQL comprehension is temporarily disabled. * **Ready to run a ‘dbtf compile’?**: Compiles your project with full Fusion static analysis. It checks that your SQL code is valid in the context of your warehouse's tables and columns. [![The message received when you have completed upgrading your project to the dbt Fusion engine.](https://docs.getdbt.com/img/docs/extension/fusion-onboarding-complete.png?v=2 "The message received when you have completed upgrading your project to the dbt Fusion engine.")](https://docs.getdbt.com/docs/fusion/install-dbt-extension#) The message received when you have completed upgrading your project to the dbt Fusion engine. Once the upgrade is completed, you're ready to dive into all the features that the dbt Fusion Engine has to offer! Register the extension[​](https://docs.getdbt.com/docs/fusion/install-dbt-extension#register-the-extension "Direct link to Register the extension") ---------------------------------------------------------------------------------------------------------------------------------------------------- Users must complete registration within 14 days of installing the dbt extension. There are two ways to register: * Users without an existing dbt account can register quickly and easily through an online registration form. For the initial installation, you only need to provide your name and email address to complete the registration. Subsequent installations will require you to complete the entire [dbt account registration process](https://docs.getdbt.com/docs/fusion/install-dbt-extension#accessing-your-dbt-account) to use the extension. * Users with an existing dbt account can connect their account using a `dbt_cloud.yml` credentials file. The VS Code extension is free for organizations for up to 15 users. ### New user registration[​](https://docs.getdbt.com/docs/fusion/install-dbt-extension#new-user-registration "Direct link to New user registration") If you do not already have a dbt account, you'll need to get registered. This only takes a minute! 1. Click the registration prompt in your editor. [![The extension registration prompt in VS Code.](https://docs.getdbt.com/img/docs/extension/registration-prompt.png?v=2 "The extension registration prompt in VS Code.")](https://docs.getdbt.com/docs/fusion/install-dbt-extension#) The extension registration prompt in VS Code. 2. Accept any prompts to open the link in your browser. 3. Fill out the registration form, then click **Continue**. [![The extension registration page in the browser.](https://docs.getdbt.com/img/docs/extension/registration-screen.png?v=2 "The extension registration page in the browser.")](https://docs.getdbt.com/docs/fusion/install-dbt-extension#) The extension registration page in the browser. 4. You will receive an email with a verification link. Once you click it, your registration is complete! ### Accessing your dbt account[​](https://docs.getdbt.com/docs/fusion/install-dbt-extension#accessing-your-dbt-account "Direct link to Accessing your dbt account") Registering to use the dbt extension makes it easy to create a full dbt account. You can follow these steps to finish setting up your account (_Note: This is not required to use the dbt extension_). 1. Navigate to [us1.dbt.com](https://us1.dbt.com/) and click **Forgot password?**. 2. Enter the email address you used for your dbt extension registration and click **Continue**. 3. Check your email for a verification link and follow the password reset instructions to set a password for your account. Now that you have activated your dbt developer account, you can access features of the dbt platform. You can also re-download your registration key using the steps outlined in [Register with an existing dbt account](https://docs.getdbt.com/docs/fusion/install-dbt-extension#register-with-an-existing-dbt-account) if you need to set up the dbt extension on a new machine. ### Register with an existing dbt account[​](https://docs.getdbt.com/docs/fusion/install-dbt-extension#register-with-an-existing-dbt-account "Direct link to Register with an existing dbt account") If you already have a dbt account, you do not need to re-register to use the dbt extension. The dbt extension can authenticate with the dbt platform using a `dbt_cloud.yml` file. If this file is present in your `~/.dbt/` folder, then the registration flow will automatically attempt to use this file during registration. If you do not have a `~/.dbt/dbt_cloud.yml` file downloaded, refer to the following instructions:  For dbt accounts with Fusion enabled 1. Log in to your dbt account. 2. Click your account name at the bottom of the left-side menu and click **Account settings**. 3. Under the **Your profile** section, click **VS Code Extension**. 4. In the **Set up your credentials** section, click **Download credentials**. This downloads the `dbt_cloud.yml` file. [![Download the dbt_cloud.yml file to complete registration.](https://docs.getdbt.com/img/docs/extension/download-registration-2.png?v=2 "Download the dbt_cloud.yml file to complete registration.")](https://docs.getdbt.com/docs/fusion/install-dbt-extension#) Download the dbt\_cloud.yml file to complete registration. 5. Move the downloaded `dbt_cloud.yml` file to your `~/.dbt/` directory. 6. To update your registration in VS Code, open the command palette (`ctrl+shift+P` (Linux) or `cmd+shift+p` (macOS)), then select `dbt: Register dbt extension` to complete the registration. For dbt accounts without Fusion enabled 1. Log in to your dbt account. 2. Click your account name at the bottom of the left-side menu and click **Account settings**. 3. Under the **Your profile** section, click **CLI**. 4. In the **Configure Cloud authentication** section, click **Download CLI configuration file**. This downloads the `dbt_cloud.yml` file. [![Download the dbt_cloud.yml file to complete registration.](https://docs.getdbt.com/img/docs/extension/download-registration.png?v=2 "Download the dbt_cloud.yml file to complete registration.")](https://docs.getdbt.com/docs/fusion/install-dbt-extension#) Download the dbt\_cloud.yml file to complete registration. 5. Move the downloaded `dbt_cloud.yml` file to your `~/.dbt/` directory. 6. To update your registration in VS Code, open the command palette (`ctrl+shift+P` (Linux) or `cmd+shift+p` (macOS)), then select `dbt: Register dbt extension` to complete the registration. Troubleshooting[​](https://docs.getdbt.com/docs/fusion/install-dbt-extension#troubleshooting "Direct link to Troubleshooting") ------------------------------------------------------------------------------------------------------------------------------- #### dbt platform configurations[​](https://docs.getdbt.com/docs/fusion/install-dbt-extension#dbt-platform-configurations "Direct link to dbt platform configurations") If you're a cloud-based dbt platform user who has the `dbt-cloud:` config in the `dbt_project.yml` file and are also using [dbt Mesh](https://docs.getdbt.com/docs/mesh/about-mesh) , you must have the project ID configured: dbt-cloud: project-id: 12345 # Required If you don’t configure this correctly, cross-platform references will not resolve properly, and you will encounter errors executing dbt commands. #### General troubleshooting tips[​](https://docs.getdbt.com/docs/fusion/install-dbt-extension#general-troubleshooting-tips "Direct link to General troubleshooting tips") If the dbt extension has activated successfully, you will see the `dbt Extension` label in the status bar at the bottom left of your editor. You can view diagnostic information about the dbt extension by clicking the **dbt Extension** button. If the dbt extension label is not present, then it is likely that the dbt extension was not installed successfully. If this happens, try uninstalling the extension, restarting your editor, and then reinstalling the extension. Note: It is possible to "hide" status bar items in VS Code. Double-check if the **dbt Extension** status bar label is hidden by right-clicking on the status bar in your editor. If you see **dbt Extension** in the right-click menu, then the extension has installed successfully. #### Missing dbt LSP features[​](https://docs.getdbt.com/docs/fusion/install-dbt-extension#missing-dbt-lsp-features "Direct link to Missing dbt LSP features") If you are not seeing dbt LSP features in your editor, first consult the general troubleshooting steps above. If you have confirmed that the dbt extension is installed correctly, but you still do not see dbt Language Server features (for example, autocomplete, go-to-definition, hover text): * Check the version of your dbt extension on the extensions page in your editor. Ensure that you are using the latest available version of the dbt extension. * Try reinstalling the dbt Language Server by pressing `cmd+shift+P` (macOS) or `ctrl+shift+P` (Linux) and selecting the `dbt: Reinstall dbt LSP` command. #### Unsupported dbt version[​](https://docs.getdbt.com/docs/fusion/install-dbt-extension#unsupported-dbt-version "Direct link to Unsupported dbt version") If you see an error message indicating that your version of dbt is unsupported, then there is likely a problem with your environment. * Check the **dbt Path** setting in your VS Code settings. If this path is set, ensure that it is pointing to a valid dbt Fusion Engine executable. * If necessary, you can also install the dbt Fusion Engine directly using these instructions: [Install the Fusion CLI](https://docs.getdbt.com/docs/fusion/install-fusion) . More information about Fusion[​](https://docs.getdbt.com/docs/fusion/install-dbt-extension#more-information-about-fusion "Direct link to More information about Fusion") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Fusion marks a significant update to dbt. While many of the workflows you've grown accustomed to remain unchanged, there are a lot of new ideas, and a lot of old ones going away. The following is a list of the full scope of our current release of the Fusion engine, including implementation, installation, deprecations, and limitations: * [About the dbt Fusion engine](https://docs.getdbt.com/docs/fusion/about-fusion) * [About the dbt extension](https://docs.getdbt.com/docs/about-dbt-extension) * [New concepts in Fusion](https://docs.getdbt.com/docs/fusion/new-concepts) * [Supported features matrix](https://docs.getdbt.com/docs/fusion/supported-features) * [Installing Fusion CLI](https://docs.getdbt.com/docs/fusion/install-fusion) * [Installing VS Code extension](https://docs.getdbt.com/docs/install-dbt-extension) * [Fusion release track](https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-version-in-cloud#dbt-fusion-engine) * [Quickstart for Fusion](https://docs.getdbt.com/guides/fusion?step=1) * [Upgrade guide](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-fusion) * [Fusion licensing](http://www.getdbt.com/licenses-faq) Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Prerequisites](https://docs.getdbt.com/docs/fusion/install-dbt-extension#prerequisites) * [Installation instructions](https://docs.getdbt.com/docs/fusion/install-dbt-extension#installation-instructions) * [Upgrade to Fusion](https://docs.getdbt.com/docs/fusion/install-dbt-extension#upgrade-to-fusion) * [Register the extension](https://docs.getdbt.com/docs/fusion/install-dbt-extension#register-the-extension) * [New user registration](https://docs.getdbt.com/docs/fusion/install-dbt-extension#new-user-registration) * [Accessing your dbt account](https://docs.getdbt.com/docs/fusion/install-dbt-extension#accessing-your-dbt-account) * [Register with an existing dbt account](https://docs.getdbt.com/docs/fusion/install-dbt-extension#register-with-an-existing-dbt-account) * [Troubleshooting](https://docs.getdbt.com/docs/fusion/install-dbt-extension#troubleshooting) * [More information about Fusion](https://docs.getdbt.com/docs/fusion/install-dbt-extension#more-information-about-fusion) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/fusion/install-dbt-extension.md) --- # Upgrading to v1.1 | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.1#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page ### Resources[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.1#resources "Direct link to Resources") * [Changelog](https://github.com/dbt-labs/dbt-core/blob/1.1.latest/CHANGELOG.md) * [dbt Core CLI Installation guide](https://docs.getdbt.com/docs/core/installation-overview) * [Cloud upgrade guide](https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-version-in-cloud) What to know before upgrading[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.1#what-to-know-before-upgrading "Direct link to What to know before upgrading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- There are no breaking changes for code in dbt projects and packages. We are committed to providing backwards compatibility for all versions 1.x. If you encounter an error upon upgrading, please let us know by [opening an issue](https://github.com/dbt-labs/dbt-core/issues/new) . ### For maintainers of adapter plugins[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.1#for-maintainers-of-adapter-plugins "Direct link to For maintainers of adapter plugins") We have reworked the testing suite for adapter plugin functionality. For details on the new testing suite, refer to the "Test your adapter" step in the [Build, test, document, and promote adapters](https://docs.getdbt.com/guides/adapter-creation) guide. The abstract methods `get_response` and `execute` now only return `connection.AdapterReponse` in type hints. Previously, they could return a string. We encourage you to update your methods to return an object of class `AdapterResponse`, or implement a subclass specific to your adapter. This also gives you the opportunity to add fields specific to your adapter's query execution, such as `rows_affected` or `bytes_processed`. ### For consumers of dbt artifacts (metadata)[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.1#for-consumers-of-dbt-artifacts-metadata "Direct link to For consumers of dbt artifacts (metadata)") The manifest schema version will be updated to v5. The only change is to the default value of `config` for parsed nodes. For users of [state-based functionality](https://docs.getdbt.com/reference/node-selection/syntax#about-node-selection) , such as the `state:modified` selector, recall that: > The `--state` artifacts must be of schema versions that are compatible with the currently running dbt version. If you have two jobs, whereby one job compares or defers to artifacts produced by the other, you'll need to upgrade both at the same time. If there's a mismatch, dbt will alert you with this error message: Expected a schema version of "https://schemas.getdbt.com/dbt/manifest/v5.json" in /manifest.json, but found "https://schemas.getdbt.com/dbt/manifest/v4.json". Are you running with a different version of dbt? New and changed documentation[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.1#new-and-changed-documentation "Direct link to New and changed documentation") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- [**Incremental models**](https://docs.getdbt.com/docs/build/incremental-models) can now accept a list of multiple columns as their `unique_key`, for models that need a combination of columns to uniquely identify each row. This is supported by the most common data warehouses, for incremental strategies that make use of the `unique_key` config (`merge` and `delete+insert`). [**Generic tests**](https://docs.getdbt.com/reference/resource-properties/data-tests) can define custom names. This is useful to "prettify" the synthetic name that dbt applies automatically. It's needed to disambiguate the case when the same generic test is defined multiple times with different configurations. [**Sources**](https://docs.getdbt.com/reference/source-properties) can define configuration inline with other `.yml` properties, just like other resource types. The only supported config is `enabled`; you can use this to dynamically enable/disable sources based on environment or package variables. ### Advanced and experimental functionality[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.1#advanced-and-experimental-functionality "Direct link to Advanced and experimental functionality") **Fresh Rebuilds.** There's a new _experimental_ selection method in town: [`source_status:fresher`](https://docs.getdbt.com/reference/node-selection/methods#source_status) . Much like the `state:` and `result` methods, the goal is to use dbt metadata to run your DAG more efficiently. If dbt has access to previous and current results of `dbt source freshness` (the `sources.json` artifact), dbt can compare them to determine which sources have loaded new data, and select only resources downstream of "fresher" sources. Read more in [Understanding State](https://docs.getdbt.com/reference/node-selection/syntax#about-node-selection) and [CI/CD in dbt](https://docs.getdbt.com/docs/deploy/continuous-integration) . [**dbt-Jinja functions**](https://docs.getdbt.com/reference/dbt-jinja-functions) have a new landing page, and two new members: * [`print`](https://docs.getdbt.com/reference/dbt-jinja-functions/print) exposes the Python `print()` function. It can be used as an alternative to `log()`, and together with the `QUIET` config, for advanced macro-driven workflows. * [`selected_resources`](https://docs.getdbt.com/reference/dbt-jinja-functions/selected_resources) exposes, at runtime, the list of DAG nodes selected by the current task. [**Global configs**](https://docs.getdbt.com/reference/global-configs/about-global-configs) include some new additions: * `QUIET` and `NO_PRINT`, to control which log messages dbt prints to terminal output. For use in advanced macro-driven workflows, such as [codegen](https://hub.getdbt.com/dbt-labs/codegen/latest/) . * `CACHE_SELECTED_ONLY` is an _experimental_ config that can significantly speed up dbt's start-of-run preparations, in cases where you're running only a few models from a large project that manages many schemas. ### For users of specific adapters[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.1#for-users-of-specific-adapters "Direct link to For users of specific adapters") **dbt-bigquery** added Support for finer-grained configuration of query timeout and retry when defining your [connection profile](https://docs.getdbt.com/docs/core/connect-data-platform/bigquery-setup) . **dbt-spark** added support for a [`session` connection method](https://docs.getdbt.com/docs/core/connect-data-platform/spark-setup#session) , for use with a pySpark session, to support rapid iteration when developing advanced or experimental functionality. This connection method is not recommended for new users, and it is not supported in dbt. ### Dependencies[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.1#dependencies "Direct link to Dependencies") [Python compatibility](https://docs.getdbt.com/faqs/Core/install-python-compatibility) : dbt Core officially supports Python 3.10 Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Resources](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.1#resources) * [What to know before upgrading](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.1#what-to-know-before-upgrading) * [For maintainers of adapter plugins](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.1#for-maintainers-of-adapter-plugins) * [For consumers of dbt artifacts (metadata)](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.1#for-consumers-of-dbt-artifacts-metadata) * [New and changed documentation](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.1#new-and-changed-documentation) * [Advanced and experimental functionality](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.1#advanced-and-experimental-functionality) * [For users of specific adapters](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.1#for-users-of-specific-adapters) * [Dependencies](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.1#dependencies) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/dbt-versions/core-upgrade/11-Older%20versions/15-upgrading-to-v1.1.md) --- # Exposure object schema | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-exposure#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page The exposure object allows you to query information about a particular exposure. To learn more, refer to [Add Exposures to your DAG](https://docs.getdbt.com/docs/build/exposures) . ### Arguments[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-exposure#arguments "Direct link to Arguments") When querying for an `exposure`, the following arguments are available. Fetching data... ================ Below we show some illustrative example queries and outline the schema of the exposure object. ### Example query[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-exposure#example-query "Direct link to Example query") The example below queries information about an exposure including the owner's name and email, the URL, and information about parent sources and parent models. { job(id: 123) { exposure(name: "my_awesome_exposure") { runId projectId name uniqueId resourceType ownerName url ownerEmail parentsSources { uniqueId sourceName name state maxLoadedAt criteria { warnAfter { period count } errorAfter { period count } } maxLoadedAtTimeAgoInS } parentsModels { uniqueId } } }} ### Fields[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-exposure#fields "Direct link to Fields") When querying for an `exposure`, the following fields are available: Fetching data... ================ Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Arguments](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-exposure#arguments) * [Example query](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-exposure#example-query) * [Fields](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-exposure#fields) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/dbt-cloud-apis/schema-discovery-job-exposure.mdx) --- # Project recommendations | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/explore/project-recommendations#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page Catalog provides recommendations about your project from the `dbt_project_evaluator` [package](https://hub.getdbt.com/dbt-labs/dbt_project_evaluator/latest/) using metadata from the [Discovery API](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-api) . * Catalog also offers a global view, showing all the recommendations across the project for easy sorting and summarizing. * These recommendations provide insight into how you can create a better-documented, better-tested, and better-built dbt project, creating more trust and less confusion. * For a seamless and consistent experience, recommendations use `dbt_project_evaluator`'s pre-defined settings and don't import customizations applied to your package or project. On-demand learning If you enjoy video courses, check out our [dbt Catalog on-demand course](https://learn.getdbt.com/courses/dbt-catalog) and learn how to best explore your dbt project(s)! Recommendations page[​](https://docs.getdbt.com/docs/explore/project-recommendations#recommendations-page "Direct link to Recommendations page") ------------------------------------------------------------------------------------------------------------------------------------------------- The Recommendations overview page includes two top-level metrics measuring the test and documentation coverage of the models in your project. * **Model test coverage** — The percent of models in your project (models not from a package or imported via Mesh) with at least one dbt test configured on them. * **Model documentation coverage** — The percent of models in your project (models not from a package or imported via Mesh) with a description. [![Example of the Recommendations overview page with project metrics and the recommendations for all resources in the project](https://docs.getdbt.com/img/docs/collaborate/dbt-explorer/example-recommendations-overview.png?v=2 "Example of the Recommendations overview page with project metrics and the recommendations for all resources in the project")](https://docs.getdbt.com/docs/explore/project-recommendations#) Example of the Recommendations overview page with project metrics and the recommendations for all resources in the project List of rules[​](https://docs.getdbt.com/docs/explore/project-recommendations#list-of-rules "Direct link to List of rules") ---------------------------------------------------------------------------------------------------------------------------- The following table lists the rules currently defined in the `dbt_project_evaluator` [package](https://hub.getdbt.com/dbt-labs/dbt_project_evaluator/latest/) . | Category | Name | Description | Package Docs Link | | --- | --- | --- | --- | | Modeling | Direct Join to Source | Model that joins both a model and source, indicating a missing staging model | [GitHub](https://dbt-labs.github.io/dbt-project-evaluator/0.8/rules/modeling/#direct-join-to-source) | | Modeling | Duplicate Sources | More than one source node corresponds to the same data warehouse relation | [GitHub](https://dbt-labs.github.io/dbt-project-evaluator/0.8/rules/modeling/#duplicate-sources) | | Modeling | Multiple Sources Joined | Models with more than one source parent, indicating lack of staging models | [GitHub](https://dbt-labs.github.io/dbt-project-evaluator/0.8/rules/modeling/#multiple-sources-joined) | | Modeling | Root Model | Models with no parents, indicating potential hardcoded references and need for sources | [GitHub](https://dbt-labs.github.io/dbt-project-evaluator/0.8/rules/modeling/#root-models) | | Modeling | Source Fanout | Sources with more than one model child, indicating a need for staging models | [GitHub](https://dbt-labs.github.io/dbt-project-evaluator/0.8/rules/modeling/#source-fanout) | | Modeling | Unused Source | Sources that are not referenced by any resource | [GitHub](https://dbt-labs.github.io/dbt-project-evaluator/0.8/rules/modeling/#unused-sources) | | Performance | Exposure Dependent on View | Exposures with at least one model parent materialized as a view, indicating potential query performance issues | [GitHub](https://dbt-labs.github.io/dbt-project-evaluator/0.8/rules/performance/#exposure-parents-materializations) | | Testing | Missing Primary Key Test | Models with insufficient testing on the grain of the model. | [GitHub](https://dbt-labs.github.io/dbt-project-evaluator/0.8/rules/testing/#missing-primary-key-tests) | | Documentation | Undocumented Models | Models without a model-level description | [GitHub](https://dbt-labs.github.io/dbt-project-evaluator/0.8/rules/documentation/#undocumented-models) | | Documentation | Undocumented Source | Sources (collections of source tables) without descriptions | [GitHub](https://dbt-labs.github.io/dbt-project-evaluator/0.8/rules/documentation/#undocumented-sources) | | Documentation | Undocumented Source Tables | Source tables without descriptions | [GitHub](https://dbt-labs.github.io/dbt-project-evaluator/0.8/rules/documentation/#undocumented-source-tables) | | Governance | Public Model Missing Contract | Models with public access that do not have a model contract to ensure the data types | [GitHub](https://dbt-labs.github.io/dbt-project-evaluator/0.8/rules/governance/#public-models-without-contracts) | The Recommendations tab[​](https://docs.getdbt.com/docs/explore/project-recommendations#the-recommendations-tab "Direct link to The Recommendations tab") ---------------------------------------------------------------------------------------------------------------------------------------------------------- Models, sources, and exposures each also have a **Recommendations** tab on their resource details page, with the specific recommendations that correspond to that resource: [![Example of the Recommendations tab ](https://docs.getdbt.com/img/docs/collaborate/dbt-explorer/example-recommendations-tab.png?v=2 "Example of the Recommendations tab ")](https://docs.getdbt.com/docs/explore/project-recommendations#) Example of the Recommendations tab Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Recommendations page](https://docs.getdbt.com/docs/explore/project-recommendations#recommendations-page) * [List of rules](https://docs.getdbt.com/docs/explore/project-recommendations#list-of-rules) * [The Recommendations tab](https://docs.getdbt.com/docs/explore/project-recommendations#the-recommendations-tab) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/explore/project-recommendations.md) --- # dbt Catalog FAQs | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/explore/dbt-explorer-faqs#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page [Catalog](https://docs.getdbt.com/docs/explore/explore-projects) is dbt’s new knowledge base and lineage visualization experience. It offers an interactive and high-level view of your company’s entire data estate, where you can dive deep into the context you need to understand and improve lineage so your teams can trust the data they’re using to make decisions. Overview[​](https://docs.getdbt.com/docs/explore/dbt-explorer-faqs#overview "Direct link to Overview") -------------------------------------------------------------------------------------------------------  How does dbt Catalog help with data quality? Catalog makes it easy and intuitive to understand your entire lineage — from data source to the reporting layer — so you can troubleshoot, improve, and optimize your pipelines. With built-in features like project recommendations and model performance analysis, you can be sure you have appropriate test and documentation coverage across your estate and quickly spot and remediate slow-running models. With column-level lineage, you can quickly identify the potential downstream impacts of table changes or work backwards to quickly understand the root cause of an incident. Catalog gives teams the insights they need to improve data quality proactively, ensuring pipelines stay performant and data trust remains solid. How is dbt Catalog priced? Catalog is generally available to all regions and deployment types on all dbt [Enterprise-tier and Starter plans](https://www.getdbt.com/) . Certain features within Catalog, such as project recommendations, multi-project lineage, column-level lineage, and more are only available on the Enterprise and Enterprise+ plans. Catalog can be accessed by users with developer and read-only seats. What happened to dbt Docs? Catalog is the default documentation experience for dbt customers. dbt Docs is still available but doesn't offer the same speed, metadata, or visibility as Catalog and will become a legacy feature. How dbt Catalog works[​](https://docs.getdbt.com/docs/explore/dbt-explorer-faqs#how-dbt-catalog-works "Direct link to How dbt Catalog works") ----------------------------------------------------------------------------------------------------------------------------------------------  Can I use dbt Catalog on-premises or with my self-hosted dbt Core deployment? No. Catalog and all of its features are only available as a dbt user experience. Catalog reflects the metadata from your dbt project(s) and their runs. How does dbt Catalog support dbt environments? Catalog supports a production or staging [deployment environment](https://docs.getdbt.com/docs/deploy/deploy-environments) for each project you want to explore. It defaults to the latest production or staging state of a project. Users can only assign one production and one staging environment per dbt project. Support for development (Cloud CLI and Studio IDE) environments is coming soon. How do I get started in Catalog? How does it update? Simply select **Explore** from the dbt top navigation bar. Catalog automatically updates after each dbt run in the given project’s environment (production, by default). The dbt commands you run within the environment will generate and update the metadata in Catalog, so make sure to run the correct combination of commands within the jobs of the environment; for more details, refer to [Generate metadata](https://docs.getdbt.com/docs/explore/explore-projects#generate-metadata) . Is it possible to export dbt lineage to an external system or catalog? Yes. The lineage that powers Catalog is also available through the Discovery API. How does dbt Catalog integrate with third-party tools to show end-to-end lineage? Catalog reflects all the lineage defined within the dbt project. Our vision for Catalog is to incorporate additional metadata from external tools like data loaders (sources) and BI/analytics tools (exposures) integrated with dbt, all seamlessly incorporated into the lineage of the dbt project. Why did previously visible data in dbt Catalog disappear? Catalog automatically deletes stale metadata after 3 months if no jobs were run to refresh it. To avoid this, make sure you schedule jobs to run more frequently than 3 months with the necessary commands. Key features[​](https://docs.getdbt.com/docs/explore/dbt-explorer-faqs#key-features "Direct link to Key features") -------------------------------------------------------------------------------------------------------------------  Does dbt Catalog support multi-project discovery (dbt Mesh)? Yes. Refer to [Explore multiple projects](https://docs.getdbt.com/docs/explore/explore-multiple-projects) to learn more. What kind of search capabilities does dbt Catalog support? Resource search capabilities include using keywords, partial strings (fuzzy search), and set operators like `OR`. Meanwhile, lineage search supports using dbt selectors. For details, refer to [Keyword search](https://docs.getdbt.com/docs/explore/explore-projects#search-resources) . Can I view model execution information for a job that is currently being run? dbt updates the performance charts and metrics after a job run. Can I analyze the number of successful model runs within a month? A chart of models built by month is available in thedbt dashboard. Can model or column descriptions be edited within dbt? Yes. Today, you can edit descriptions in the Studio IDE or Cloud CLI by changing the YAML files within the dbt project. In the future, Catalog will support more ways of editing descriptions. Where do recommendations come from? Can they be customized? Recommendations largely mirror the best practice rules from the `dbt_project_evaluator` package. At this time, recommendations can’t be customized. In the future, Catalog will likely support recommendation customization capabilities (for example, in project code). Column-level lineage[​](https://docs.getdbt.com/docs/explore/dbt-explorer-faqs#column-level-lineage "Direct link to Column-level lineage") -------------------------------------------------------------------------------------------------------------------------------------------  What are the best use cases for column-level lineage in dbt Catalog? Column-level lineage in Catalog can be used to improve many data development workflows, including: * **Audit** — Visualize how data moves through and is used in your dbt project * **Root cause** — Improve time to detect and resolve data quality issues, tracking back to the source * **Impact analysis** — Trace transformations and usage to avoid introducing issues for consumers * **Efficiency** — Prune unnecessary columns to reduce costs and data team overhead Does the column-level lineage remain functional even if column names vary between models? Yes. Column-level lineage can handle name changes across instances of the column in the dbt project. Can multiple projects leverage the same column definition? No. Cross-project column lineage is supported in the sense of viewing how a public model is used across projects, but not on a column-level. Can column descriptions be propagated down in downstream lineage automatically? Yes, a reused column, labeled as passthrough or rename, inherits its description from source and upstream model columns. In other words, source and upstream model columns propagate their descriptions downstream whenever they are not transformed, meaning you don’t need to manually define the description. Refer to [Inherited column descriptions](https://docs.getdbt.com/docs/explore/column-level-lineage#inherited-column-descriptions) for more info. Is column-level lineage also available in the development tab? Not currently, but we plan to incorporate column-level awareness across features in dbt in the future. Availability, access, and permissions[​](https://docs.getdbt.com/docs/explore/dbt-explorer-faqs#availability-access-and-permissions "Direct link to Availability, access, and permissions") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------  How can non-developers interact with dbt Catalog? Read-only users can consume metadata in Catalog. More bespoke experiences and exploration avenues for analysts and less-technical contributors will be provided in the future. Does dbt Catalog require a specific dbt plan? Catalog is available on dbt Starter and all Enterprise plans. Certain features within Catalog, like project recommendations, multi-project lineage, column-level lineage, and more are only available on the Enterprise and Enterprise+ plans. Will dbt Core users be able to leverage any of these new dbt Catalog features? No. Catalog is a dbt\-only product experience. Is it possible to access dbt Catalog using a read-only license? Yes, users with read-only access can use the Catalog. Specific feature availability within Catalog will depend on your dbt plan. Is there an easy way to share useful dbt Catalog content with people outside of dbt? The ability to embed and share views is being evaluated as a potential future capability.  Is dbt Catalog accessible from other areas inside dbt? Yes, you can [access Catalog from various dbt features](https://docs.getdbt.com/docs/explore/access-from-dbt-cloud) , ensuring you have a seamless experience navigating between resources and lineage in your project. While the primary way to access Catalog is through the **Explore** link in the navigation, you can also access it from the [Studio IDE](https://docs.getdbt.com/docs/explore/access-from-dbt-cloud#dbt-cloud-ide) , [the lineage tab in jobs](https://docs.getdbt.com/docs/explore/access-from-dbt-cloud#lineage-tab-in-jobs) , and the [model timing tab in jobs](https://docs.getdbt.com/docs/explore/access-from-dbt-cloud#model-timing-tab-in-jobs) . Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Overview](https://docs.getdbt.com/docs/explore/dbt-explorer-faqs#overview) * [How dbt Catalog works](https://docs.getdbt.com/docs/explore/dbt-explorer-faqs#how-dbt-catalog-works) * [Key features](https://docs.getdbt.com/docs/explore/dbt-explorer-faqs#key-features) * [Column-level lineage](https://docs.getdbt.com/docs/explore/dbt-explorer-faqs#column-level-lineage) * [Availability, access, and permissions](https://docs.getdbt.com/docs/explore/dbt-explorer-faqs#availability-access-and-permissions) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/explore/dbt-explorer-faqs.md) --- # Upgrading to v1.7 | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.7#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page Resources[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.7#resources "Direct link to Resources") ---------------------------------------------------------------------------------------------------------------------------- * [Changelog](https://github.com/dbt-labs/dbt-core/blob/1.7.latest/CHANGELOG.md) * [dbt Core CLI Installation guide](https://docs.getdbt.com/docs/core/installation-overview) * [Cloud upgrade guide](https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-version-in-cloud) * [Release schedule](https://github.com/dbt-labs/dbt-core/issues/8260) What to know before upgrading[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.7#what-to-know-before-upgrading "Direct link to What to know before upgrading") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- dbt Labs is committed to providing backward compatibility for all versions 1.x, with the exception of any changes explicitly mentioned below. If you encounter an error upon upgrading, please let us know by [opening an issue](https://github.com/dbt-labs/dbt-core/issues/new) . ### Behavior changes[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.7#behavior-changes "Direct link to Behavior changes") dbt Core v1.7 expands the amount of sources you can configure freshness for. Previously, freshness was limited to sources with a `loaded_at_field`; now, freshness can be generated from warehouse metadata tables when available. As part of this change, the `loaded_at_field` is no longer required to generate source freshness. If a source has a `freshness:` block, dbt will attempt to calculate freshness for that source: * If a `loaded_at_field` is provided, dbt will calculate freshness via a select query (previous behavior). * If a `loaded_at_field` is _not_ provided, dbt will calculate freshness via warehouse metadata tables when possible (new behavior). This is a relatively small behavior change, but worth calling out in case you notice that dbt is calculating freshness for _more_ sources than before. To exclude a source from freshness calculations, you have two options: 1. Don't add a `freshness:` block. 2. Explicitly set `freshness: null` Beginning with v1.7, running [`dbt deps`](https://docs.getdbt.com/reference/commands/deps) creates or updates the `package-lock.yml` file in the _project\_root_ where `packages.yml` is recorded. The `package-lock.yml` file contains a record of all packages installed and, if subsequent `dbt deps` runs contain no updated packages in `dependencies.yml` or `packages.yml`, dbt-core installs from `package-lock.yml`. To retain the behavior prior to v1.7, there are two main options: 1. Use `dbt deps --upgrade` everywhere `dbt deps` was used previously. 2. Add `package-lock.yml` to your `.gitignore` file. New and changed features and functionality[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.7#new-and-changed-features-and-functionality "Direct link to New and changed features and functionality") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- * [`dbt docs generate`](https://docs.getdbt.com/reference/commands/cmd-docs) now supports `--select` to generate [catalog metadata](https://docs.getdbt.com/reference/artifacts/catalog-json) for a subset of your project. * [Source freshness](https://docs.getdbt.com/docs/deploy/source-freshness) can now be generated from warehouse metadata tables. ### MetricFlow enhancements[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.7#metricflow-enhancements "Direct link to MetricFlow enhancements") * Automatically create metrics on measures with [`create_metric: true`](https://docs.getdbt.com/docs/build/semantic-models) . * Optional [`label`](https://docs.getdbt.com/docs/build/semantic-models) in semantic\_models, measures, dimensions and entities. * New configurations for semantic models - [enable/disable](https://docs.getdbt.com/reference/resource-configs/enabled) , [group](https://docs.getdbt.com/reference/resource-configs/group) , and [meta](https://docs.getdbt.com/reference/resource-configs/meta) . * Support `fill_nulls_with` and `join_to_timespine` for metric nodes. * `saved_queries` extends governance beyond the semantic objects to their consumption. ### For consumers of dbt artifacts (metadata)[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.7#for-consumers-of-dbt-artifacts-metadata "Direct link to For consumers of dbt artifacts (metadata)") * The [manifest](https://docs.getdbt.com/reference/artifacts/manifest-json) schema version has been updated to v11. * The [run\_results](https://docs.getdbt.com/reference/artifacts/run-results-json) schema version has been updated to v5. * There are a few specific changes to the [catalog.json](https://docs.getdbt.com/reference/artifacts/catalog-json) : * Added [node attributes](https://docs.getdbt.com/reference/artifacts/run-results-json) related to compilation (`compiled`, `compiled_code`, `relation_name`) to the `catalog.json`. * The nodes dictionary in the `catalog.json` can now be "partial" if `dbt docs generate` is run with a selector. ### Model governance[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.7#model-governance "Direct link to Model governance") dbt Core v1.5 introduced model governance which we're continuing to refine. v1.7 includes these additional features and functionality: * **[Breaking change detection](https://docs.getdbt.com/reference/resource-properties/versions#detecting-breaking-changes) for models with contracts enforced:** When dbt detects a breaking change to a model with an enforced contract during state comparison, it will now raise an error for versioned models and a warning for models that are not versioned. * **[Set `access` as a config](https://docs.getdbt.com/reference/resource-configs/access) :** You can now set a model's `access` within config blocks in the model's file or in the `dbt_project.yml` for an entire subfolder at once. * **[Type aliasing for model contracts](https://docs.getdbt.com/reference/resource-configs/contract) :** dbt will use each adapter's built-in type aliasing for user-provided data types—meaning you can now write `string` always, and dbt will translate to `text` on Postgres/Redshift. This is "on" by default, but you can opt-out. * **[Raise warning for numeric types](https://docs.getdbt.com/reference/resource-configs/contract) :** Because of issues when putting `numeric` in model contracts without considering that default values such as `numeric(38,0)` might round decimals accordingly. dbt will now warn you if it finds a numeric type without specified precision/scale. ### dbt clean[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.7#dbt-clean "Direct link to dbt clean") [dbt clean](https://docs.getdbt.com/reference/commands/clean) only cleans paths within the current working directory. The `--no-clean-project-files-only` flag will delete all paths specified in the `clean-targets` section of `dbt_project.yml`, even if they're outside the dbt project. Supported flags: * `--clean-project-files-only` (default) * `--no-clean-project-files-only` ### Additional attributes in run\_results.json[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.7#additional-attributes-in-run_resultsjson "Direct link to Additional attributes in run_results.json") The run\_results.json now includes three attributes related to the `applied` state that complement `unique_id`: * `compiled`: Boolean entry of the node compilation status (`False` after parsing, but `True` after compiling). * `compiled_code`: Rendered string of the code that was compiled (empty after parsing, but full string after compiling). * `relation_name`: The fully-qualified name of the object that was (or will be) created/updated within the database. ### Deprecated functionality[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.7#deprecated-functionality "Direct link to Deprecated functionality") The ability for installed packages to override built-in materializations without explicit opt-in from the user is being deprecated. * Overriding a built-in materialization from an installed package raises a deprecation warning. * Using a custom materialization from an installed package does not raise a deprecation warning. * Using a built-in materialization package override from the root project via a wrapping materialization is still supported. For example: {% materialization view, default %}{{ return(my_cool_package.materialization_view_default()) }}{% endmaterialization %} ### Quick hits[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.7#quick-hits "Direct link to Quick hits") With these quick hits, you can now: * Configure a [`delimiter`](https://docs.getdbt.com/reference/resource-configs/delimiter) for a seed file. * Use packages with the same git repo and unique subdirectory. * Access the `date_spine` macro directly from dbt-core (moved over from dbt-utils). * Syntax for `DBT_ENV_SECRET_` has changed to `DBT_ENV_SECRET` and no longer requires the closing underscore. Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Resources](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.7#resources) * [What to know before upgrading](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.7#what-to-know-before-upgrading) * [Behavior changes](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.7#behavior-changes) * [New and changed features and functionality](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.7#new-and-changed-features-and-functionality) * [MetricFlow enhancements](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.7#metricflow-enhancements) * [For consumers of dbt artifacts (metadata)](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.7#for-consumers-of-dbt-artifacts-metadata) * [Model governance](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.7#model-governance) * [dbt clean](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.7#dbt-clean) * [Additional attributes in run\_results.json](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.7#additional-attributes-in-run_resultsjson) * [Deprecated functionality](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.7#deprecated-functionality) * [Quick hits](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.7#quick-hits) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/dbt-versions/core-upgrade/08-upgrading-to-v1.7.md) --- # Upgrading to v1.10 | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.10#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page Resources[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.10#resources "Direct link to Resources") ----------------------------------------------------------------------------------------------------------------------------- * dbt Core [v1.10 changelog](https://github.com/dbt-labs/dbt-core/blob/1.10.latest/CHANGELOG.md) * [dbt Core CLI Installation guide](https://docs.getdbt.com/docs/core/installation-overview) * [Cloud upgrade guide](https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-version-in-cloud#release-tracks) What to know before upgrading[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.10#what-to-know-before-upgrading "Direct link to What to know before upgrading") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- dbt Labs is committed to providing backward compatibility for all versions 1.x. Any behavior changes will be accompanied by a [behavior change flag](https://docs.getdbt.com/reference/global-configs/behavior-changes#behavior-change-flags) to provide a migration window for existing projects. If you encounter an error upon upgrading, please let us know by [opening an issue](https://github.com/dbt-labs/dbt-core/issues/new) . Starting in 2024, dbt provides the functionality from new versions of dbt Core via [release tracks](https://docs.getdbt.com/docs/dbt-versions/cloud-release-tracks) with automatic upgrades. If you have selected the "Latest" release track in dbt, you already have access to all the features, fixes, and other functionality that is included in dbt Core v1.10! If you have selected the "Compatible" release track, you will have access in the next monthly "Compatible" release after the dbt Core v1.10 final release. For users of dbt Core, since v1.8, we recommend explicitly installing both `dbt-core` and `dbt-`. This may become required for a future version of dbt. For example: python3 -m pip install dbt-core dbt-snowflake New and changed features and functionality[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.10#new-and-changed-features-and-functionality "Direct link to New and changed features and functionality") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- New features and functionality available in dbt Core v1.10 ### The `--sample` flag[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.10#the---sample-flag "Direct link to the---sample-flag") Large data sets can slow down dbt build times, making it harder for developers to test new code efficiently. The [`--sample` flag](https://docs.getdbt.com/docs/build/sample-flag) , available for the `run` and `build` commands, helps reduce build times and warehouse costs by running dbt in sample mode. It generates filtered refs and sources using time-based sampling, allowing developers to validate outputs without building entire models. ### Move standalone anchors under `anchors:` key[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.10#move-standalone-anchors-under-anchors-key "Direct link to move-standalone-anchors-under-anchors-key") As part of the ongoing process of making the dbt authoring language more precise, dbt Core v1.10 raises a warning when it sees an unexpected top-level key in a YAML file. A common use case behind these unexpected keys is standalone anchor definitions at the top level of a YAML file. You can use the new top-level `anchors:` key as a container for these reusable configuration blocks. For example, rather than using this configuration: models/\_models.yml id_column: &id_column_alias name: id description: This is a unique identifier. data_type: int data_tests: - not_null - uniquemodels: - name: my_first_model columns: - *id_column_alias - name: unrelated_column_a description: This column is not repeated in other models. - name: my_second_model columns: - *id_column_alias Move the anchor under the `anchors:` key instead: models/\_models.yml anchors: - &id_column_alias name: id description: This is a unique identifier. data_type: int data_tests: - not_null - uniquemodels: - name: my_first_model columns: - *id_column_alias - name: unrelated_column_a description: This column is not repeated in other models - name: my_second_model columns: - *id_column_alias This move is only necessary for fragments defined outside of the main YAML structure. For more information about this new key, see [anchors](https://docs.getdbt.com/reference/resource-properties/anchors) . ### Parsing `catalogs.yml`[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.10#parsing-catalogsyml "Direct link to parsing-catalogsyml") dbt Core can now parse the `catalogs.yml` file. This is an important milestone in the journey to supporting external catalogs for Iceberg tables, as it enables write integrations. You'll be able to provide a config specifying a catalog integration for your producer model: For example: catalogs: - name: catalog_dave # materializing the data to an external location, and metadata to that data catalog write_integrations: - name: databricks_glue_write_integration external_volume: databricks_external_volume_prod table_format: iceberg catalog_type: unity The implementation for the model would look like this: models/schemas.yml models: - name: my_second_public_model config: catalog_name: catalog_dave Check out our [docs on external catalog support](https://docs.getdbt.com/docs/mesh/iceberg/about-catalogs) today! We'll have more information about this in the coming weeks, but this is an exciting step in journey to cross-platform support. ### Integrating dbt Core artifacts with dbt projects[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.10#integrating-dbt-core-artifacts-with-dbt-projects "Direct link to Integrating dbt Core artifacts with dbt projects") With [hybrid projects](https://docs.getdbt.com/docs/deploy/hybrid-projects) , dbt Core users working in the command line interface (CLI) can execute runs that seamlessly upload [artifacts](https://docs.getdbt.com/reference/artifacts/dbt-artifacts) into dbt. This enhances hybrid dbt Core/dbt deployments by: * Fostering collaboration between dbt + dbt Core users by enabling them to visualize and perform [cross-project references](https://docs.getdbt.com/docs/mesh/govern/project-dependencies#how-to-write-cross-project-ref) to models defined in dbt Core projects. This feature unifies dbt + dbt Core workflows for a more connected dbt experience. * Giving dbt and dbt Core users insights into their models and assets in [Catalog](https://docs.getdbt.com/docs/explore/explore-projects) . To view Catalog, you must have have a [developer or read-only license](https://docs.getdbt.com/docs/cloud/manage-access/seats-and-users) . * (Coming soon) Enabling users working in the [Canvas](https://docs.getdbt.com/docs/cloud/canvas) to build off of models already created by a central data team in dbt Core rather than having to start from scratch. Hybrid projects are available as a private beta to [dbt Enterprise accounts](https://www.getdbt.com/pricing) . Contact your account representative to register your interest in the beta. ### Managing changes to legacy behaviors[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.10#managing-changes-to-legacy-behaviors "Direct link to Managing changes to legacy behaviors") dbt Core v1.10 introduces new flags for [managing changes to legacy behaviors](https://docs.getdbt.com/reference/global-configs/behavior-changes) . You may opt into recently introduced changes (disabled by default), or opt out of mature changes (enabled by default), by setting `True` / `False` values, respectively, for `flags` in `dbt_project.yml`. You can read more about each of these behavior changes in the following links: * (Introduced, disabled by default) [`validate_macro_args`](https://docs.getdbt.com/reference/global-configs/behavior-changes#macro-argument-validation) . If the flag is set to `True`, dbt will raise a warning if the argument `type` names you've added in your macro YAMLs don't match the argument names in your macro or if the argument types aren't valid according to the [supported types](https://docs.getdbt.com/reference/resource-properties/arguments#supported-types) . ### Deprecation warnings[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.10#deprecation-warnings "Direct link to Deprecation warnings") Starting in `v1.10`, you will receive deprecation warnings for dbt code that will become invalid in the future, including: * Custom inputs (for example, unrecognized resource properties, configurations, and top-level keys) * Duplicate YAML keys in the same file * Unexpected Jinja blocks (for example, `{% endmacro %}` tags without a corresponding `{% macro %}` tag) * Some `properties` are moving to `configs` * And more dbt will start raising these warnings in version `1.10`, but making these changes will not be a prerequisite for using it. We at dbt Labs understand that it will take existing users time to migrate their projects, and it is not our goal to disrupt anyone with this update. The goal is to enable you to work with more safety, feedback, and confidence going forward. What does this mean for you? 1. If your project (or dbt package) encounters a new deprecation warning in `v1.10`, plan to update your invalid code soon. Although it’s just a warning for now, in a future version, dbt will enforce stricter validation of the inputs in your project. Check out the [`dbt-autofix` tool](https://github.com/dbt-labs/dbt-autofix) to autofix many of these! 2. In the future, the [`meta` config](https://docs.getdbt.com/reference/resource-configs/meta) will be the only place to put custom user-defined attributes. Everything else will be strongly typed and strictly validated. If you have an extra attribute you want to include in your project, or a model config you want to access in a custom materialization, you must nest it under `meta` moving forward. 3. If you are using the [`—-warn-error` flag](https://docs.getdbt.com/reference/global-configs/warnings) (or `--warn-error-options '{"error": "all"}'`) to promote all warnings to errors, this will include new deprecation warnings coming to dbt Core. If you don’t want these to be promoted to errors, the `--warn-error-options` flag gives you more granular control over exactly which types of warnings are treated as errors. You can set `"warn": ["Deprecations"]` (new as of `v1.10`) to continue treating the deprecation warnings as warnings. 4. The `--models` / `--model` / `-m` flag was renamed to `--select` / `--s` way back in dbt Core v0.21 (Oct 2021). Silently skipping this flag means ignoring your command's selection criteria, which could mean building your entire DAG when you only meant to select a small subset. For this reason, the `--models` / `--model` / `-m` flag **will raise a warning** in dbt Core v1.10, and an error in Fusion. Please update your job definitions accordingly. #### Custom inputs[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.10#custom-inputs "Direct link to Custom inputs") Historically, dbt has allowed you to configure inputs largely unconstrained. A common example of this is setting custom YAML properties: models: - name: my_model description: A model in my project. dbt_is_awesome: true # a custom property dbt detects the unrecognized custom property (`dbt_is_awesome`) and silently continues. Without a set of strictly defined inputs, it becomes challenging to validate your project's configuration. This creates unintended issues such as: * Silently ignoring misspelled properties and configurations (for example, `desciption:` instead of `description:`). * Unintended collisions with user code when dbt introduces a new “reserved” property or configuration. If you have an unrecognized custom property, you will receive a warning, and in a future version, dbt will cease to support custom properties. Moving forward, these should be nested under the [`meta` config](https://docs.getdbt.com/reference/resource-configs/meta) , which will be the only place to put custom user-defined attributes: models: - name: my_model description: A model in my project. config: meta: dbt_is_awesome: true #### Custom keys not nested under meta[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.10#custom-keys-not-nested-under-meta "Direct link to Custom keys not nested under meta") Previously, when you could define any additional fields directly under `config`, it could lead to collisions between pre-existing user-defined configurations and official configurations of the dbt framework. In the future, the `meta` config will be the sole location for custom user-defined attributes. Everything else will be strongly typed and strictly validated. If you have an extra attribute you want to include in your project, or a model config you want to access in a custom materialization, you must nest it under `meta` moving forward: models: - name: my_model config: meta: custom_config_key: value columns: - name: my_column config: meta: some_key: some_value #### Duplicate keys in the same yaml file[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.10#duplicate-keys-in-the-same-yaml-file "Direct link to Duplicate keys in the same yaml file") If two identical keys exist in the same YAML file, you will get a warning, and in a future version, dbt will stop supporting duplicate keys. Previously, if identical keys existed in the same YAML file, dbt silently overwrite, using the last configuration listed in the file. profiles.yml my_profile: target: my_target outputs:...my_profile: # dbt would use only this profile key target: my_other_target outputs:... Moving forward, you should delete unused keys or move them to a separate YAML file. #### Unexpected Jinja blocks[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.10#unexpected-jinja-blocks "Direct link to Unexpected Jinja blocks") If you have an orphaned Jinja block, you will receive a warning, and in a future version, dbt will stop supporting unexpected Jinja blocks. Previously, these orphaned Jinja blocks were silently ignored. macros/my\_macro.sql {% endmacro %} # orphaned endmacro jinja block{% macro hello() %}hello!{% endmacro %} Moving forward, you should delete these orphaned Jinja blocks. #### Properties moving to configs[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.10#properties-moving-to-configs "Direct link to Properties moving to configs") Some historical properties are moving entirely to configs. This will include: `freshness`, `meta`, `tags`, `docs`, `group`, and `access` If you previously set one of the impacted properties, such as `freshness`: sources: - name: ecom schema: raw description: E-commerce data for the Jaffle Shop freshness: warn_after: count: 24 period: hour You should now set it under `config`: sources: - name: ecom schema: raw description: E-commerce data for the Jaffle Shop config: freshness: warn_after: count: 24 period: hour #### Custom output path for source freshness[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.10#custom-output-path-for-source-freshness "Direct link to Custom output path for source freshness") The ability to override the default path for `sources.json` via the `--output` or `-o` flags has been deprecated. You can still set the path for all artifacts in the step with `--target-path`, but will receive a warning if trying to set the path for just source freshness. #### Warn error options[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.10#warn-error-options "Direct link to Warn error options") The `warn_error_option` options for `include` and `exclude` have been deprecated and replaced with `error` and `warn`, respectively. ...flags: warn_error_options: error: # Previously called "include" warn: # Previously called "exclude" silence: # To silence or ignore warnings - NoNodesForSelectionCriteria Quick hits[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.10#quick-hits "Direct link to Quick hits") -------------------------------------------------------------------------------------------------------------------------------- * Provide the [`loaded_at_query`](https://docs.getdbt.com/reference/resource-properties/freshness#loaded_at_query) property for source freshness to specify custom SQL to generate the `maxLoadedAt` time stamp on the source (versus the [built-in query](https://github.com/dbt-labs/dbt-adapters/blob/6c41bedf27063eda64375845db6ce5f7535ef6aa/dbt/include/global_project/macros/adapters/freshness.sql#L4-L16) , which uses the `loaded_at_field`). You cannot define `loaded_at_query` if the `loaded_at_field` config is also provided. * Provide validation for macro arguments using the [`validate_macro_args`](https://docs.getdbt.com/reference/global-configs/behavior-changes#macro-argument-validation) flag, which is disabled by default. When enabled, this flag checks that documented macro argument names match those in the macro definition and validates their types against a supported format. Previously, dbt did not enforce standard argument types, treating the type field as documentation-only. If no arguments are documented, dbt infers them from the macro and includes them in the manifest.json file. Learn more about [supported types](https://docs.getdbt.com/reference/resource-properties/arguments#supported-types) . Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Resources](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.10#resources) * [What to know before upgrading](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.10#what-to-know-before-upgrading) * [New and changed features and functionality](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.10#new-and-changed-features-and-functionality) * [The `--sample` flag](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.10#the---sample-flag) * [Move standalone anchors under `anchors:` key](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.10#move-standalone-anchors-under-anchors-key) * [Parsing `catalogs.yml`](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.10#parsing-catalogsyml) * [Integrating dbt Core artifacts with dbt projects](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.10#integrating-dbt-core-artifacts-with-dbt-projects) * [Managing changes to legacy behaviors](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.10#managing-changes-to-legacy-behaviors) * [Deprecation warnings](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.10#deprecation-warnings) * [Quick hits](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.10#quick-hits) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/dbt-versions/core-upgrade/05-upgrading-to-v1.10.md) --- # Upgrading to v1.0 | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.0#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page ### Resources[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.0#resources "Direct link to Resources") * [Discourse](https://discourse.getdbt.com/t/3180) * [Changelog](https://github.com/dbt-labs/dbt-core/blob/1.0.latest/CHANGELOG.md) * [dbt Core CLI Installation guide](https://docs.getdbt.com/docs/core/installation-overview) * [Cloud upgrade guide](https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-version-in-cloud) What to know before upgrading[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.0#what-to-know-before-upgrading "Direct link to What to know before upgrading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- dbt Core major version 1.0 includes a number of breaking changes! Wherever possible, we have offered backwards compatibility for old behavior, and (where necessary) made migration simple. ### Renamed fields in `dbt_project.yml`[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.0#renamed-fields-in-dbt_projectyml "Direct link to renamed-fields-in-dbt_projectyml") **These affect everyone:** * [model-paths](https://docs.getdbt.com/reference/project-configs/model-paths) have replaced `source-paths` in `dbt-project.yml`. * [seed-paths](https://docs.getdbt.com/reference/project-configs/seed-paths) have replaced `data-paths` in `dbt-project.yml` with a default value of `seeds`. * The [packages-install-path](https://docs.getdbt.com/reference/project-configs/packages-install-path) was updated from `modules-path`. Additionally the default value is now `dbt_packages` instead of `dbt_modules`. You may need to update this value in [`clean-targets`](https://docs.getdbt.com/reference/project-configs/clean-targets) . * Default for `quote_columns` is now `True` for all adapters other than Snowflake. **These probably don't:** * The default value of [test-paths](https://docs.getdbt.com/reference/project-configs/test-paths) has been updated to be the plural `tests`. * The default value of [analysis-paths](https://docs.getdbt.com/reference/project-configs/analysis-paths) has been updated to be the plural `analyses`. ### Tests[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.0#tests "Direct link to Tests") The two **test types** are now "singular" and "generic" (instead of "data" and "schema", respectively). The `test_type:` selection method accepts `test_type:singular` and `test_type:generic`. (It will also accept `test_type:schema` and `test_type:data` for backwards compatibility.) **Not backwards compatible:** The `--data` and `--schema` flags to dbt test are no longer supported, and tests no longer have the tags `'data'` and `'schema'` automatically applied. Updated docs: [data tests](https://docs.getdbt.com/docs/build/data-tests) , [test selection](https://docs.getdbt.com/reference/node-selection/test-selection-examples) , [selection methods](https://docs.getdbt.com/reference/node-selection/methods) . The `greedy` flag/property has been renamed to **`indirect_selection`**, which is now eager by default. **Note:** This reverts test selection to its pre-v0.20 behavior by default. `dbt test -s my_model` _will_ select multi-parent tests, such as `relationships`, that depend on unselected resources. To achieve the behavior change in v0.20 + v0.21, set `--indirect-selection=cautious` on the CLI or `indirect_selection: cautious` in YAML selectors. Updated docs: [test selection examples](https://docs.getdbt.com/reference/node-selection/test-selection-examples) , [yaml selectors](https://docs.getdbt.com/reference/node-selection/yaml-selectors) . ### Global macros[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.0#global-macros "Direct link to Global macros") Global project macros have been reorganized, and some old unused macros have been removed: `column_list`, `column_list_for_create_table`, `incremental_upsert`. This is unlikely to affect your project. ### Installation[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.0#installation "Direct link to Installation") * [Installation docs](https://docs.getdbt.com/docs/supported-data-platforms) reflects adapter-specific installations * `python -m pip install dbt` is no longer supported, and will raise an explicit error. Install the specific adapter plugin you need as `python -m pip install dbt-`. * `brew install dbt` is no longer supported. Install the specific adapter plugin you need (among Postgres, Redshift, Snowflake, or BigQuery) as `brew install dbt-`. * Removed official support for python 3.6, which is reaching end of life on December 23, 2021 ### For users of adapter plugins[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.0#for-users-of-adapter-plugins "Direct link to For users of adapter plugins") * **BigQuery:** Support for ingestion-time-partitioned tables has been officially deprecated in favor of modern approaches. Use `partition_by` and incremental modeling strategies instead. For more information, refer to [Incremental models](https://docs.getdbt.com/docs/build/incremental-models) . ### For maintainers of plugins + other integrations[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.0#for-maintainers-of-plugins--other-integrations "Direct link to For maintainers of plugins + other integrations") We've introduced a new [**structured event interface**](https://docs.getdbt.com/reference/events-logging) , and we've transitioned all dbt logging to use this new system. **This includes a breaking change for adapter plugins**, requiring a very simple migration. For more details, see the [`events` module README](https://github.com/dbt-labs/dbt-core/blob/HEAD/core/dbt/events/README.md#adapter-maintainers) . If you maintain a different kind of plugin that _needs_ legacy logging, for the time being, you can re-enable it with an env var (`DBT_ENABLE_LEGACY_LOGGER=True`); be advised that we will remove this capability in a future version of dbt Core. The [**dbt RPC Server**](https://docs.getdbt.com/reference/commands/rpc) has been split out from `dbt-core` and is now packaged separately. Its functionality will be fully deprecated by the end of 2022, in favor of a new dbt Server. Instead of `dbt rpc`, use `dbt-rpc serve`. **Artifacts:** New schemas (manifest v4, run results v4, sources v3). Notable changes: add `metrics` nodes; schema test + data test nodes are renamed to generic test + singular test nodes; freshness threshold default values look slightly different. ### Deprecations from long ago[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.0#deprecations-from-long-ago "Direct link to Deprecations from long ago") Several under-the-hood changes from past minor versions, tagged with deprecation warnings, have now been fully deprecated. * The `packages` argument of [dispatch](https://docs.getdbt.com/reference/dbt-jinja-functions/dispatch) has been deprecated and will raise an exception when used. * The "adapter\_macro" macro has been deprecated. Instead, use the [dispatch](https://docs.getdbt.com/reference/dbt-jinja-functions/dispatch) method to find a macro and call the result. * The `release` arg has been removed from the `execute_macro` method. New features and changed documentation[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.0#new-features-and-changed-documentation "Direct link to New features and changed documentation") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ * Add [metrics](https://docs.getdbt.com/docs/build/build-metrics-intro) , a new node type * [Generic tests](https://docs.getdbt.com/best-practices/writing-custom-generic-tests) can be defined in `tests/generic` (new), in addition to `macros/` (as before) * [Parsing](https://docs.getdbt.com/reference/parsing) : partial parsing and static parsing have been turned on by default. * [Global configs](https://docs.getdbt.com/reference/global-configs/about-global-configs) have been standardized. Related updates to [global CLI flags](https://docs.getdbt.com/reference/global-configs/about-global-configs) and [`profiles.yml`](https://docs.getdbt.com/docs/core/connect-data-platform/profiles.yml) . * [The `init` command](https://docs.getdbt.com/reference/commands/init) has a whole new look and feel. It's no longer just for first-time users. * Add `result:` subselectors for smarter reruns when dbt models have errors and tests fail. See examples: [Pro-tips for Workflows](https://docs.getdbt.com/best-practices/best-practice-workflows#pro-tips-for-workflows) * Secret-prefixed [env vars](https://docs.getdbt.com/reference/dbt-jinja-functions/env_var) are now allowed only in `profiles.yml` + `packages.yml` Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Resources](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.0#resources) * [What to know before upgrading](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.0#what-to-know-before-upgrading) * [Renamed fields in `dbt_project.yml`](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.0#renamed-fields-in-dbt_projectyml) * [Tests](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.0#tests) * [Global macros](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.0#global-macros) * [Installation](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.0#installation) * [For users of adapter plugins](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.0#for-users-of-adapter-plugins) * [For maintainers of plugins + other integrations](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.0#for-maintainers-of-plugins--other-integrations) * [Deprecations from long ago](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.0#deprecations-from-long-ago) * [New features and changed documentation](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.0#new-features-and-changed-documentation) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/dbt-versions/core-upgrade/11-Older%20versions/16-upgrading-to-v1.0.md) --- # Test object schema | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-test#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page The test object allows you to query information about a particular test. ### Arguments[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-test#arguments "Direct link to Arguments") When querying for a `test`, the following arguments are available. Fetching data... ================ Below we show some illustrative example queries and outline the schema (all possible fields you can query) of the test object. ### Example query[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-test#example-query "Direct link to Example query") The example query below outputs information about a test including the state of the test result. In order of severity, the result can be one of these: "error", "fail", "warn", or "pass". { job(id: 123) { test(uniqueId: "test.internal_analytics.not_null_metrics_id") { runId accountId projectId uniqueId name columnName state } }} ### Fields[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-test#fields "Direct link to Fields") When querying for a `test`, the following fields are available: Fetching data... ================ Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Arguments](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-test#arguments) * [Example query](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-test#example-query) * [Fields](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-test#fields) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/dbt-cloud-apis/schema-discovery-job-test.mdx) --- # Snapshots object schema | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-snapshots#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page The snapshots object allows you to query information about all snapshots in a given job. ### Arguments[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-snapshots#arguments "Direct link to Arguments") When querying for `snapshots`, the following arguments are available. Fetching data... ================ Below we show some illustrative example queries and outline the schema of the snapshots object. ### Example query[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-snapshots#example-query "Direct link to Example query") The database, schema, and identifier arguments are optional. This means that with this endpoint you can: * Find a specific snapshot by providing `..` * Find all of the snapshots in a database and/or schema by providing `` and/or `` #### Find snapshots information for a job[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-snapshots#find-snapshots-information-for-a-job "Direct link to Find snapshots information for a job") The example query returns information about all snapshots in this job. { job(id: 123) { snapshots { uniqueId name executionTime environmentId executeStartedAt executeCompletedAt } }} ### Fields[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-snapshots#fields "Direct link to Fields") When querying for `snapshots`, the following fields are available: Fetching data... ================ Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Arguments](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-snapshots#arguments) * [Example query](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-snapshots#example-query) * [Fields](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-snapshots#fields) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/dbt-cloud-apis/schema-discovery-job-snapshots.mdx) --- # 2022 dbt Cloud release notes | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page Archived release notes for dbt from 2022 December 2022[​](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#december-2022 "Direct link to December 2022") ---------------------------------------------------------------------------------------------------------------------------- ### Threads default value changed to 4[​](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#threads-default-value-changed-to-4 "Direct link to Threads default value changed to 4") Threads help parallelize node execution in the dbt directed acyclic graph [(DAG)](https://docs.getdbt.com/terms/dag) . Previously, the thread value defaulted to 1, which can increase the runtime of your project. To help reduce the runtime of your project, the default value for threads in user profiles is now set to 4 threads. You can supply a custom thread count if you'd prefer more or less parallelization. For more information, read [Understanding threads](https://docs.getdbt.com/docs/running-a-dbt-project/using-threads) . ### Creating a new job no longer triggers a run by default[​](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#creating-a-new-job-no-longer-triggers-a-run-by-default "Direct link to Creating a new job no longer triggers a run by default") To help save compute time, new jobs will no longer be triggered to run by default. When you create a new job in dbt, you can trigger the job to run by selecting **Run on schedule** and completing the desired schedule and timing information. For more information, refer to [Deploy jobs](https://docs.getdbt.com/docs/deploy/deploy-jobs) . [![Default for newly created jobs](https://docs.getdbt.com/img/docs/release-notes/new-jobs-default-as-off.png?v=2 "Default for newly created jobs")](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#) Default for newly created jobs ### Private packages must be cloned using access tokens provided by environment variables[​](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#private-packages-must-be-cloned-using-access-tokens-provided-by-environment-variables "Direct link to Private packages must be cloned using access tokens provided by environment variables") The supported method for cloning private GitHub packages is the [git token method](https://docs.getdbt.com/docs/build/packages#git-token-method) , where an appropriate access token is passed into the package repository URL with an environment variable. A small number of people have been able to clone private packages using dbt's native GitHub application without explicitly providing an access token. This functionality is being deprecated as it’s limited in flexibility. If you have been using a package hosted in a private repository on GitHub, you must start passing an access token into the URL. An example of passing an access token: packages.yml packages:- git: "https://{{env_var('DBT_ENV_SECRET_GIT_CREDENTIAL')}}@github.com/dbt-labs/awesome_repo.git" November 2022[​](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#november-2022 "Direct link to November 2022") ---------------------------------------------------------------------------------------------------------------------------- ### The dbt Cloud + Databricks experience is getting even better[​](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#the-dbt-cloud--databricks-experience-is-getting-even-better "Direct link to The dbt Cloud + Databricks experience is getting even better") dbt is the easiest and most reliable way to develop and deploy a dbt project. It helps remove complexity while also giving you more features and better performance. A simpler Databricks connection experience with support for Databricks’ Unity Catalog and better modeling defaults is now available for your use. For all the Databricks customers already using dbt with the dbt-spark adapter, you can now [migrate](https://docs.getdbt.com/guides/migrate-from-spark-to-databricks) your connection to the [dbt-databricks adapter](https://docs.getdbt.com/docs/core/connect-data-platform/databricks-setup) to get the benefits. [Databricks](https://www.databricks.com/blog/2022/11/17/introducing-native-high-performance-integration-dbt-cloud.html) is committed to maintaining and improving the adapter, so this integrated experience will continue to provide the best of dbt and Databricks. Check out our [live blog post](https://www.getdbt.com/blog/dbt-cloud-databricks-experience/)  to learn more. ### Extra features in new and refreshed IDE[​](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#extra-features-in-new-and-refreshed-ide "Direct link to Extra features in new and refreshed IDE") The refreshed version of the Studio IDE has launched four brand-new additional features, making it easier and faster for you to develop in the Studio IDE. The new features are: * **Formatting** — Format your dbt SQL files to a single code style with a click of a button. This uses the tool [sqlfmt](https://github.com/tconbeer/sqlfmt) . * **Git diff view** — Highlights the changes in a file before opening a pull request. * **dbt autocomplete** — There are four new types of autocomplete features to help you develop faster: * Use `ref` to autocomplete your model names * Use `source` to autocomplete your source name + table name * Use `macro` to autocomplete your arguments * Use `env var` to autocomplete env var * **Dark mode** — Use dark mode in the Studio IDE for low-light environments. Read more about all the [Cloud Studio IDE features](https://docs.getdbt.com/docs/cloud/dbt-cloud-ide/develop-in-the-cloud#cloud-ide-features) . ### Classic IDE deprecation notice[​](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#classic-ide-deprecation-notice "Direct link to Classic IDE deprecation notice") In December 2022, dbt Labs will deprecate the classic Studio IDE. The [new and refreshed Studio IDE](https://docs.getdbt.com/docs/cloud/dbt-cloud-ide/develop-in-the-cloud) will be available for _all_ dbt users. You will no longer be able to access the classic Studio IDE and dbt Labs might introduce changes that break the classic Studio IDE. With deprecation, dbt Labs will only support the refreshed version of the Studio IDE. Virtual Private Cloud (VPC) customers with questions about when this change will affect your account can contact your account team or support contact for assistance. October 2022[​](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#october-2022 "Direct link to October 2022") ------------------------------------------------------------------------------------------------------------------------- ### Announcing dbt Cloud’s native integration with Azure DevOps[​](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#announcing-dbt-clouds-native-integration-with-azure-devops "Direct link to Announcing dbt Cloud’s native integration with Azure DevOps") dbt now offers a native integration with Azure DevOps for dbt customers on the enterprise plan. We built this integration to remove friction, increase security, and unlock net new product experiences for our customers. [Setting up the Azure DevOps integration](https://docs.getdbt.com/docs/cloud/git/connect-azure-devops)  in dbt provides: * easy dbt project set up, * an improved security posture, * repo permissions enforcement in Studio IDE, and * dbt Slim CI. Check out our [live blog post](https://www.getdbt.com/blog/dbt-cloud-integration-azure-devops/)  to learn more! ### Introducing a snappier, improved, and powerful Cloud IDE[​](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#introducing-a-snappier-improved-and-powerful-cloud-ide "Direct link to Introducing a snappier, improved, and powerful Cloud IDE") The new version of the Cloud Studio IDE makes it easy for you to build data models without thinking much about environment setup and configuration. The new Cloud Studio IDE includes performance upgrades, ergonomics improvements, and some delightful enhancements! Some of the improvements include: * Improved Cloud Studio IDE startup time (starting the Studio IDE), interaction time (saving and committing), and reliability. * Better organization and navigation with features like drag and drop of files, breadcrumb, build button drop-down, and more. * You can use new features like auto-format your file, auto-complete model names, and git diff view to see your changes before making a pull request. Read more about the new [Cloud Studio IDE features](https://docs.getdbt.com/docs/cloud/dbt-cloud-ide/develop-in-the-cloud#cloud-ide-features) and check out [New and improved Cloud Studio IDE](https://www.getdbt.com/blog/new-improved-cloud-ide/) blog for more info! September 2022[​](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#september-2022 "Direct link to September 2022") ------------------------------------------------------------------------------------------------------------------------------- ### List Steps API endpoint deprecation warning[​](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#list-steps-api-endpoint-deprecation-warning "Direct link to List Steps API endpoint deprecation warning") On October 14th, 2022 dbt Labs is deprecating the List Steps API endpoint. From October 14th, any GET requests to this endpoint will fail. Please prepare to stop using the List Steps endpoint as soon as possible. dbt Labs will continue to maintain the [Retrieve Run](https://docs.getdbt.com/dbt-cloud/api-v2#/operations/Retrieve%20Run) endpoint, which is a viable alternative depending on the use case. You can fetch run steps for an individual run with a GET request to the following URL, replacing `YOUR_ACCESS_URL` with the [appropriate Access URL](https://docs.getdbt.com/docs/cloud/about-cloud/access-regions-ip-addresses) for your region and plan: `https://YOUR_ACCESS_URL/api/v2/accounts/{accountId}/runs/{runId}/?include_related=["run_steps"]` ### Query the previous three months of data using the metadata API[​](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#query-the-previous-three-months-of-data-using-the-metadata-api "Direct link to Query the previous three months of data using the metadata API") In order to make the metadata API more scalable and improve its latency, we’ve implemented data retention limits. The metadata API can now query data from the previous three months. For example, if today was March 1, you could query data back to January 1st. For more information, see [Metadata API](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-api) August 2022[​](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#august-2022 "Direct link to August 2022") ---------------------------------------------------------------------------------------------------------------------- ### Support for cross-database sources on Redshift RA3 instances[​](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#support-for-cross-database-sources-on-redshift-ra3-instances "Direct link to Support for cross-database sources on Redshift RA3 instances") Cross-database queries for RA3 instances are now supported by dbt projects using a Redshift connection. With cross-database queries, you can seamlessly query data from any database in the cluster, regardless of which database you are connected to with dbt. The [connection configuration](https://docs.getdbt.com/docs/core/connect-data-platform/redshift-setup) `ra3_node` has been defaulted to `true`. This allows users to: * benefit from the full RA3 nodes’ capabilities, * generate appropriate dbt documentation. July 2022[​](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#july-2022 "Direct link to July 2022") ---------------------------------------------------------------------------------------------------------------- ### Large DAG feature[​](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#large-dag-feature "Direct link to Large DAG feature") You can now select **Render Lineage** to visualize large DAGs. Large DAGs can take a long time (10 or more seconds, if not minutes) to render and can cause browsers to crash. The new button prevents large DAGs from rendering automatically. Instead, you can select **Render Lineage** to load the visualization. This should affect about 15% of the DAGs. [![Render Lineage](https://docs.getdbt.com/img/docs/dbt-cloud/dag%20v1.1.56%20release.png?v=2 "Render Lineage")](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#) Render Lineage May 2022[​](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#may-2022 "Direct link to May 2022") ------------------------------------------------------------------------------------------------------------- ### Refresh expired access tokens in the IDE when using GitLab[​](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#refresh-expired-access-tokens-in-the-ide-when-using-gitlab "Direct link to Refresh expired access tokens in the IDE when using GitLab") On May 22, GitLab changed how they treat [OAuth access tokens that don't expire](https://docs.gitlab.com/ee/update/deprecations.html#oauth-tokens-without-expiration) . We updated our Studio IDE logic to handle OAuth token expiration more gracefully. Now, the first time your token expires after 2 hours of consecutive Studio IDE usage, you will have to re-authenticate in GitLab to refresh your expired OAuth access token. We will handle subsequent refreshes for you if you provide the authorization when you re-authenticate. This additional security layer in the Studio IDE is available only to the dbt enterprise plan. April 2022[​](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#april-2022 "Direct link to April 2022") ------------------------------------------------------------------------------------------------------------------- ### Audit log[​](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#audit-log "Direct link to Audit log") To review actions performed by people in your organization, dbt provides logs of audited user and system events. The dbt audit log lists events triggered in your organization within the last 90 days. The audit log includes details such as who performed the action, what the action was, and when it was performed. For more details, review [the audit log for dbt Enterprise](https://docs.getdbt.com/docs/cloud/manage-access/audit-log) documentation. ### Credentials no longer accidentally wiped when editing an environment[​](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#credentials-no-longer-accidentally-wiped-when-editing-an-environment "Direct link to Credentials no longer accidentally wiped when editing an environment") We resolved a bug where when updating unencrypted fields (e.g. threads, schema name) in an environment setting would cause secret fields (e.g. password, keypair, credential details) to be deleted from that environment. Now users can freely update environment settings without fear of unintentionally wiping credentials. ### Email verification[​](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#email-verification "Direct link to Email verification") To enhance the security of user creation, dbt users created using SAML Just-in-Time (JIT) will now confirm identity via email to activate their account. Using email to confirm identity ensures the user still has access to the same email address they use to login via SAML. ### Scheduler performance improvements[​](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#scheduler-performance-improvements "Direct link to Scheduler performance improvements") We rolled out our new distributed scheduler, which has much faster prep times, especially at the top of the hour. We share more about our work and improvements in our [product news blog post](https://www.getdbt.com/blog/a-good-problem-to-have/) . March 2022[​](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#march-2022 "Direct link to March 2022") ------------------------------------------------------------------------------------------------------------------- ### Spotty internet issues no longer cause a session time out message[​](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#spotty-internet-issues-no-longer-cause-a-session-time-out-message "Direct link to Spotty internet issues no longer cause a session time out message") We fixed an issue where a spotty internet connection could cause the “Studio IDE session timed out” message to appear unexpectedly. People using a VPN were most likely to see this issue. We updated the health check logic so it now excludes client-side connectivity issues from the Studio IDE session check. If you lose your internet connection, we no longer update the health-check state. Now, losing internet connectivity will no longer cause this unexpected message. [![Fix Session Timeout](https://docs.getdbt.com/img/docs/dbt-cloud/Fix%20Session%20Timeout.png?v=2 "Fix Session Timeout")](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#) Fix Session Timeout ### Dividing queue time into waiting and prep time[​](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#dividing-queue-time-into-waiting-and-prep-time "Direct link to Dividing queue time into waiting and prep time") dbt now shows "waiting time" and "prep time" for a run, which used to be expressed in aggregate as "queue time". Waiting time captures the time dbt waits to run your job if there isn't an available run slot or if a previous run of the same job is still running. Prep time represents the time it takes dbt to ready your job to run in your cloud data warehouse. [![New prep time and waiting time](https://docs.getdbt.com/img/docs/dbt-cloud/v1.1.46releasenotes_img1.png?v=2 "New prep time and waiting time")](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#) New prep time and waiting time February 2022[​](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#february-2022 "Direct link to February 2022") ---------------------------------------------------------------------------------------------------------------------------- ### DAG updates and performance improvements[​](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#dag-updates-and-performance-improvements "Direct link to DAG updates and performance improvements") Love the DAG in the Studio IDE as much as we do? Now when you click on a node in the DAG, the model or config file will open as a new tab in the Studio IDE, so you can directly view or edit the code. We'll continue to ship better developer ergonomic functionality throughout the year. #### Performance improvements and enhancements[​](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#performance-improvements-and-enhancements "Direct link to Performance improvements and enhancements") * Updated recommended dbt commands in the Studio IDE to include dbt Core v1.0 commands, such as "build" and the "--select" argument. ### Service tokens and bug fixes[​](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#service-tokens-and-bug-fixes "Direct link to Service tokens and bug fixes") Service tokens can now be assigned granular permissions to enforce least privilege access. If you're on Enterprise, you can assign any enterprise permission set to newly issued service tokens. If you're on Teams, you can assign the Job Admin permission set to newly issued service tokens. We highly recommend you re-issue service tokens with these new permissions to increase your security posture! See docs [here](https://docs.getdbt.com/docs/dbt-cloud-apis/service-tokens#permissions-for-service-account-tokens) . #### New products and features[​](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#new-products-and-features "Direct link to New products and features") * We are joining the [GitHub secret scanning partner program](https://docs.github.com/en/developers/overview/secret-scanning-partner-program) to better secure your token against accidental public exposure and potential fraudulent usage. #### Bug fixes[​](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#bug-fixes "Direct link to Bug fixes") * Credentials are no longer accidentally deleted when a user updates an environment setting. January 2022[​](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#january-2022 "Direct link to January 2022") ------------------------------------------------------------------------------------------------------------------------- ### Autocomplete snippets for SQL and YAML files in IDE[​](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#autocomplete-snippets-for-sql-and-yaml-files-in-ide "Direct link to Autocomplete snippets for SQL and YAML files in IDE") Some noteworthy improvements include autocomplete snippets for SQL and YAML files in the IDE, which are available for use now! We also added a [new metric layer page](https://docs.getdbt.com/docs/use-dbt-semantic-layer/dbt-sl) to docs.getdbt.com to help you begin thinking about the metrics layer in dbt Cloud. #### Performance improvements and enhancements[​](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#performance-improvements-and-enhancements-1 "Direct link to Performance improvements and enhancements") * Branch names now default to "main" instead of "master" in new managed and unmanaged Git repositories. * Update IDE autocomplete snippets. ### Model timing for Multi-tenant Team and Enterprise accounts[​](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#model-timing-for-multi-tenant-team-and-enterprise-accounts "Direct link to Model timing for Multi-tenant Team and Enterprise accounts") We started the new year with a gift! Multi-tenant Team and Enterprise accounts can now use the new [Model timing](https://docs.getdbt.com/docs/deploy/deploy-jobs#model-timing) tab in dbt. You can use this tab to further explore long-running models to see if they need refactoring or rescheduling. #### Performance improvements and enhancements[​](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#performance-improvements-and-enhancements-2 "Direct link to Performance improvements and enhancements") * We added client-side naming validation for file or folder creation. Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [December 2022](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#december-2022) * [Threads default value changed to 4](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#threads-default-value-changed-to-4) * [Creating a new job no longer triggers a run by default](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#creating-a-new-job-no-longer-triggers-a-run-by-default) * [Private packages must be cloned using access tokens provided by environment variables](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#private-packages-must-be-cloned-using-access-tokens-provided-by-environment-variables) * [November 2022](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#november-2022) * [The dbt Cloud + Databricks experience is getting even better](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#the-dbt-cloud--databricks-experience-is-getting-even-better) * [Extra features in new and refreshed IDE](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#extra-features-in-new-and-refreshed-ide) * [Classic IDE deprecation notice](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#classic-ide-deprecation-notice) * [October 2022](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#october-2022) * [Announcing dbt Cloud’s native integration with Azure DevOps](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#announcing-dbt-clouds-native-integration-with-azure-devops) * [Introducing a snappier, improved, and powerful Cloud IDE](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#introducing-a-snappier-improved-and-powerful-cloud-ide) * [September 2022](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#september-2022) * [List Steps API endpoint deprecation warning](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#list-steps-api-endpoint-deprecation-warning) * [Query the previous three months of data using the metadata API](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#query-the-previous-three-months-of-data-using-the-metadata-api) * [August 2022](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#august-2022) * [Support for cross-database sources on Redshift RA3 instances](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#support-for-cross-database-sources-on-redshift-ra3-instances) * [July 2022](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#july-2022) * [Large DAG feature](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#large-dag-feature) * [May 2022](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#may-2022) * [Refresh expired access tokens in the IDE when using GitLab](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#refresh-expired-access-tokens-in-the-ide-when-using-gitlab) * [April 2022](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#april-2022) * [Audit log](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#audit-log) * [Credentials no longer accidentally wiped when editing an environment](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#credentials-no-longer-accidentally-wiped-when-editing-an-environment) * [Email verification](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#email-verification) * [Scheduler performance improvements](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#scheduler-performance-improvements) * [March 2022](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#march-2022) * [Spotty internet issues no longer cause a session time out message](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#spotty-internet-issues-no-longer-cause-a-session-time-out-message) * [Dividing queue time into waiting and prep time](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#dividing-queue-time-into-waiting-and-prep-time) * [February 2022](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#february-2022) * [DAG updates and performance improvements](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#dag-updates-and-performance-improvements) * [Service tokens and bug fixes](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#service-tokens-and-bug-fixes) * [January 2022](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#january-2022) * [Autocomplete snippets for SQL and YAML files in IDE](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#autocomplete-snippets-for-sql-and-yaml-files-in-ide) * [Model timing for Multi-tenant Team and Enterprise accounts](https://docs.getdbt.com/docs/dbt-versions/2022-release-notes#model-timing-for-multi-tenant-team-and-enterprise-accounts) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/dbt-versions/2022-release-notes.md) --- # Install Fusion from the CLI | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/fusion/install-fusion-cli#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page Fusion can be installed via the command line from our official CDN: * **macOS/Linux:** Using `curl` macOS & Linux installation[​](https://docs.getdbt.com/docs/fusion/install-fusion-cli#macos--linux-installation "Direct link to macOS & Linux installation") ------------------------------------------------------------------------------------------------------------------------------------------------------------ Run the following command in the terminal: curl -fsSL https://public.cdn.getdbt.com/fs/install/install.sh | sh -s -- --update To use `dbtf` immediately after installation, reload your shell so that the new `$PATH` is recognized: exec $SHELL Or, close and reopen your Terminal window. This will load the updated environment settings into the new session. ### Windows installation (PowerShell)[​](https://docs.getdbt.com/docs/fusion/install-fusion-cli#windows-installation-powershell "Direct link to Windows installation (PowerShell)") Run the following command in PowerShell: irm https://public.cdn.getdbt.com/fs/install/install.ps1 | iex To use `dbtf` immediately after installation, reload your shell so that the new `Path` is recognized: Start-Process powershell Or, close and reopen PowerShell. This will load the updated environment settings into the new session. Verify the installation[​](https://docs.getdbt.com/docs/fusion/install-fusion-cli#verify-the-installation "Direct link to Verify the installation") ---------------------------------------------------------------------------------------------------------------------------------------------------- After installation, open a new command-line window and verify that Fusion is installed correctly by checking the version. You can run these commands using `dbt`, or use `dbtf` as an unambiguous alias for Fusion, if you have another dbt CLI installed on your machine. dbtf --version * **macOS** & **Linux**: $HOME/.local/bin/dbt * **Windows:** `C:\Users\\.local\bin\dbt.exe` This location is automatically added to your path to easily execute the `dbtf` command, but it requires reloading your shell. Update Fusion[​](https://docs.getdbt.com/docs/fusion/install-fusion-cli#update-fusion "Direct link to Update Fusion") ---------------------------------------------------------------------------------------------------------------------- The following command will update to the latest version of Fusion and adapter code: dbtf system update Uninstall Fusion[​](https://docs.getdbt.com/docs/fusion/install-fusion-cli#uninstall-fusion "Direct link to Uninstall Fusion") ------------------------------------------------------------------------------------------------------------------------------- This command will uninstall the Fusion binary from your system, but aliases will remain wherever they are installed (for example `~/.zshrc`): dbtf system uninstall Adapter installation[​](https://docs.getdbt.com/docs/fusion/install-fusion-cli#adapter-installation "Direct link to Adapter installation") ------------------------------------------------------------------------------------------------------------------------------------------- The Fusion install automatically includes adapters outlined in the [Fusion requirements](https://docs.getdbt.com/docs/fusion/supported-features#requirements) . Other adapters will be available at a later date. Troubleshooting[​](https://docs.getdbt.com/docs/fusion/install-fusion-cli#troubleshooting "Direct link to Troubleshooting") ---------------------------------------------------------------------------------------------------------------------------- Common issues and resolutions: * **dbt command not found:** Ensure installation location is correctly added to your `$PATH`. * **Version conflicts:** Verify no existing dbt Core or dbt CLI versions are installed (or active) that could conflict with Fusion. * **Installation permissions:** Confirm your user has appropriate permissions to install software locally. Frequently asked questions[​](https://docs.getdbt.com/docs/fusion/install-fusion-cli#frequently-asked-questions "Direct link to Frequently asked questions") ------------------------------------------------------------------------------------------------------------------------------------------------------------- * Can I revert to my previous dbt installation? Yes. If you want to test Fusion without affecting your existing workflows, consider isolating or managing your installation via separate environments or virtual machines. More information about Fusion[​](https://docs.getdbt.com/docs/fusion/install-fusion-cli#more-information-about-fusion "Direct link to More information about Fusion") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- Fusion marks a significant update to dbt. While many of the workflows you've grown accustomed to remain unchanged, there are a lot of new ideas, and a lot of old ones going away. The following is a list of the full scope of our current release of the Fusion engine, including implementation, installation, deprecations, and limitations: * [About the dbt Fusion engine](https://docs.getdbt.com/docs/fusion/about-fusion) * [About the dbt extension](https://docs.getdbt.com/docs/about-dbt-extension) * [New concepts in Fusion](https://docs.getdbt.com/docs/fusion/new-concepts) * [Supported features matrix](https://docs.getdbt.com/docs/fusion/supported-features) * [Installing Fusion CLI](https://docs.getdbt.com/docs/fusion/install-fusion) * [Installing VS Code extension](https://docs.getdbt.com/docs/install-dbt-extension) * [Fusion release track](https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-version-in-cloud#dbt-fusion-engine) * [Quickstart for Fusion](https://docs.getdbt.com/guides/fusion?step=1) * [Upgrade guide](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-fusion) * [Fusion licensing](http://www.getdbt.com/licenses-faq) Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [macOS & Linux installation](https://docs.getdbt.com/docs/fusion/install-fusion-cli#macos--linux-installation) * [Windows installation (PowerShell)](https://docs.getdbt.com/docs/fusion/install-fusion-cli#windows-installation-powershell) * [Verify the installation](https://docs.getdbt.com/docs/fusion/install-fusion-cli#verify-the-installation) * [Update Fusion](https://docs.getdbt.com/docs/fusion/install-fusion-cli#update-fusion) * [Uninstall Fusion](https://docs.getdbt.com/docs/fusion/install-fusion-cli#uninstall-fusion) * [Adapter installation](https://docs.getdbt.com/docs/fusion/install-fusion-cli#adapter-installation) * [Troubleshooting](https://docs.getdbt.com/docs/fusion/install-fusion-cli#troubleshooting) * [Frequently asked questions](https://docs.getdbt.com/docs/fusion/install-fusion-cli#frequently-asked-questions) * [More information about Fusion](https://docs.getdbt.com/docs/fusion/install-fusion-cli#more-information-about-fusion) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/fusion/install-fusion-cli.md) --- # Seed object schema | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-seed#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page The seed object allows you to query information about a particular seed in a given job. ### Arguments[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-seed#arguments "Direct link to Arguments") When querying for a `seed`, the following arguments are available. Fetching data... ================ Below we show some illustrative example queries and outline the schema of the seed object. ### Example query[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-seed#example-query "Direct link to Example query") The example query below pulls relevant information about a given seed. For instance, you can view the load time. { job(id: 123) { seed(uniqueId: "seed.jaffle_shop.raw_customers") { database schema uniqueId name status error } }} ### Fields[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-seed#fields "Direct link to Fields") When querying for a `seed`, the following fields are available: Fetching data... ================ Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Arguments](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-seed#arguments) * [Example query](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-seed#example-query) * [Fields](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-seed#fields) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/dbt-cloud-apis/schema-discovery-job-seed.mdx) --- # Upgrading to v1.8 | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.8#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page Resources[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.8#resources "Direct link to Resources") ---------------------------------------------------------------------------------------------------------------------------- * [Changelog](https://github.com/dbt-labs/dbt-core/blob/1.8.latest/CHANGELOG.md) * [dbt Core CLI Installation guide](https://docs.getdbt.com/docs/core/installation-overview) * [Cloud upgrade guide](https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-version-in-cloud) What to know before upgrading[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.8#what-to-know-before-upgrading "Direct link to What to know before upgrading") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- dbt Labs is committed to providing backward compatibility for all versions 1.x, except for any changes explicitly mentioned on this page. If you encounter an error upon upgrading, please let us know by [opening an issue](https://github.com/dbt-labs/dbt-core/issues/new) . Release tracks[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.8#release-tracks "Direct link to Release tracks") ------------------------------------------------------------------------------------------------------------------------------------------- Starting in 2024, dbt provides the functionality from new versions of dbt Core via [release tracks](https://docs.getdbt.com/docs/dbt-versions/cloud-release-tracks) with automatic upgrades. Select a release track in your development, staging, and production [environments](https://docs.getdbt.com/docs/deploy/deploy-environments) to access everything in dbt Core v1.8+ and more. To upgrade an environment in the [dbt Admin API](https://docs.getdbt.com/docs/dbt-cloud-apis/admin-cloud-api) or [Terraform](https://registry.terraform.io/providers/dbt-labs/dbtcloud/latest) , set `dbt_version` to the string `latest`. New and changed features and functionality[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.8#new-and-changed-features-and-functionality "Direct link to New and changed features and functionality") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Features and functionality new in dbt v1.8. ### New dbt Core adapter installation procedure[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.8#new-dbt-core-adapter-installation-procedure "Direct link to New dbt Core adapter installation procedure") Before dbt Core v1.8, whenever you would `pip install` a data warehouse adapter for dbt, `pip` would automatically install `dbt-core` alongside it. The dbt adapter directly depended on components of `dbt-core`, and `dbt-core` depended on the adapter for execution. This bidirectional dependency made it difficult to develop adapters independent of `dbt-core`. Beginning in v1.8, [`dbt-core` and adapters are decoupled](https://github.com/dbt-labs/dbt-adapters/discussions/87) . Going forward, your installations should explicitly include _both_ `dbt-core` _and_ the desired adapter. The new `pip` installation command should look like this: pip install dbt-core dbt-ADAPTER_NAME For example, you would use the following command if you use Snowflake: pip install dbt-core dbt-snowflake For the time being, we have maintained install-time dependencies to avoid breaking existing scripts in surprising ways; `pip install dbt-snowflake` will continue to install the latest versions of both `dbt-core` and `dbt-snowflake`. Given that we may remove this implicit dependency in future versions, we strongly encourage you to update install scripts **now**. ### Unit Tests[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.8#unit-tests "Direct link to Unit Tests") Historically, dbt's test coverage was confined to [“data” tests](https://docs.getdbt.com/docs/build/data-tests) , assessing the quality of input data or resulting datasets' structure. In v1.8, we're introducing native support for [unit testing](https://docs.getdbt.com/docs/build/unit-tests) . Unit tests validate your SQL modeling logic on a small set of static inputs **before** you materialize your full model in production. They support a test-driven development approach, improving both the efficiency of developers and the reliability of code. Starting from v1.8, when you execute the `dbt test` command, it will run both unit and data tests. Use the [`test_type`](https://docs.getdbt.com/reference/node-selection/methods#test_type) method to run only unit or data tests: dbt test --select "test_type:unit" # run all unit testsdbt test --select "test_type:data" # run all data tests Unit tests are defined in YML files in your `models/` directory and are currently only supported on SQL models. To distinguish between the two, the `tests:` config has been renamed to `data_tests:`. Both are currently supported for backward compatibility. #### New `data_tests:` syntax[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.8#new-data_tests-syntax "Direct link to new-data_tests-syntax") The `tests:` syntax is changing to reflect the addition of unit tests. Start migrating your [data test](https://docs.getdbt.com/docs/build/data-tests#new-data_tests-syntax) YML to use `data_tests:` after you upgrade to v1.8 to prevent issues in the future. models: - name: orders columns: - name: order_id data_tests: - unique - not_null #### The `--empty` flag[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.8#the---empty-flag "Direct link to the---empty-flag") The [`run`](https://docs.getdbt.com/reference/commands/run#the-%60--empty%60-flag) and [`build`](https://docs.getdbt.com/reference/commands/build#the---empty-flag) commands now support the `--empty` flag for building schema-only dry runs. The `--empty` flag limits the refs and sources to zero rows. dbt will still execute the model SQL against the target data warehouse but will avoid expensive reads of input data. This validates dependencies and ensures your models will build properly. ### Deprecated functionality[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.8#deprecated-functionality "Direct link to Deprecated functionality") The ability for installed packages to override built-in materializations without explicit opt-in from the user is being deprecated. * Overriding a built-in materialization from an installed package raises a deprecation warning. * Using a custom materialization from an installed package does not raise a deprecation warning. * Using a built-in materialization package override from the root project via a wrapping materialization is still supported. For example: {% materialization view, default %}{{ return(my_cool_package.materialization_view_default()) }}{% endmaterialization %} ### Managing changes to legacy behaviors[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.8#managing-changes-to-legacy-behaviors "Direct link to Managing changes to legacy behaviors") dbt Core v1.8 has introduced flags for [managing changes to legacy behaviors](https://docs.getdbt.com/reference/global-configs/behavior-changes) . You may opt into recently introduced changes (disabled by default), or opt out of mature changes (enabled by default), by setting `True` / `False` values, respectively, for `flags` in `dbt_project.yml`. You can read more about each of these behavior changes in the following links: * (Mature, enabled by default) [Require explicit package overrides for builtin materializations](https://docs.getdbt.com/reference/global-configs/behavior-changes#require_explicit_package_overrides_for_builtin_materializations) * (Introduced, disabled by default) [Require resource names without spaces](https://docs.getdbt.com/reference/global-configs/behavior-changes#require_resource_names_without_spaces) * (Introduced, disabled by default) [Run project hooks (`on-run-*`) in the `dbt source freshness` command](https://docs.getdbt.com/reference/global-configs/behavior-changes#source_freshness_run_project_hooks) Quick hits[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.8#quick-hits "Direct link to Quick hits") ------------------------------------------------------------------------------------------------------------------------------- * Custom defaults of [global config flags](https://docs.getdbt.com/reference/global-configs/about-global-configs) should be set in the `flags` dictionary in [`dbt_project.yml`](https://docs.getdbt.com/reference/dbt_project.yml) , instead of in [`profiles.yml`](https://docs.getdbt.com/docs/core/connect-data-platform/profiles.yml) . Support for `profiles.yml` has been deprecated. * New CLI flag [`--resource-type`/`--exclude-resource-type`](https://docs.getdbt.com/reference/global-configs/resource-type) for including/excluding resources from dbt `build`, `run`, and `clone`. * To improve performance, dbt now issues a single (batch) query when calculating `source freshness` through metadata, instead of executing a query per source. * Syntax for `DBT_ENV_SECRET_` has changed to `DBT_ENV_SECRET` and no longer requires the closing underscore. Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Resources](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.8#resources) * [What to know before upgrading](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.8#what-to-know-before-upgrading) * [Release tracks](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.8#release-tracks) * [New and changed features and functionality](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.8#new-and-changed-features-and-functionality) * [New dbt Core adapter installation procedure](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.8#new-dbt-core-adapter-installation-procedure) * [Unit Tests](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.8#unit-tests) * [Deprecated functionality](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.8#deprecated-functionality) * [Managing changes to legacy behaviors](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.8#managing-changes-to-legacy-behaviors) * [Quick hits](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.8#quick-hits) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/dbt-versions/core-upgrade/07-upgrading-to-v1.8.md) --- # Upgrading to v1.2 | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.2#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page ### Resources[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.2#resources "Direct link to Resources") * [Changelog](https://github.com/dbt-labs/dbt-core/blob/1.2.latest/CHANGELOG.md) * [dbt Core CLI Installation guide](https://docs.getdbt.com/docs/core/installation-overview) * [Cloud upgrade guide](https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-version-in-cloud) What to know before upgrading[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.2#what-to-know-before-upgrading "Direct link to What to know before upgrading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- There are no breaking changes for code in dbt projects and packages. We are committed to providing backwards compatibility for all versions 1.x. If you encounter an error upon upgrading, please let us know by [opening an issue](https://github.com/dbt-labs/dbt-core/issues/new) . ### For consumers of dbt artifacts (metadata)[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.2#for-consumers-of-dbt-artifacts-metadata "Direct link to For consumers of dbt artifacts (metadata)") The manifest schema version has been updated to `v6`. The relevant changes are: * Change to `config` default, which includes a new `grants` property with default value `{}` * Addition of a `metrics` property, to any node which could reference metrics using the `metric()` function For users of [state-based selection](https://docs.getdbt.com/reference/node-selection/syntax#about-node-selection) : This release also includes new logic declaring forwards compatibility for older manifest versions. While running dbt Core v1.2, it should be possible to use `state:modified --state ...` selection against a manifest produced by dbt Core v1.0 or v1.1. For maintainers of adapter plugins[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.2#for-maintainers-of-adapter-plugins "Direct link to For maintainers of adapter plugins") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ See GitHub discussion [dbt-labs/dbt-core#5468](https://github.com/dbt-labs/dbt-core/discussions/5468) for detailed information New and changed functionality[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.2#new-and-changed-functionality "Direct link to New and changed functionality") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- * **[Grants](https://docs.getdbt.com/reference/resource-configs/grants) ** are natively supported in `dbt-core` for the first time. That support extends to all standard materializations, and the most popular adapters. If you already use hooks to apply simple grants, we encourage you to use built-in `grants` to configure your models, seeds, and snapshots instead. This will enable you to [DRY](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself) up your duplicated or boilerplate code. * **[Metrics](https://docs.getdbt.com/docs/build/build-metrics-intro) ** now support an `expression` type (metrics-on-metrics), as well as a `metric()` function to use when referencing metrics from within models, macros, or `expression`\-type metrics. For more information on how to use expression metrics, check out the [**`dbt_metrics` package**](https://github.com/dbt-labs/dbt_metrics) * **[dbt-Jinja functions](https://docs.getdbt.com/reference/dbt-jinja-functions) ** now include the [`itertools` Python module](https://docs.getdbt.com/reference/dbt-jinja-functions/modules#itertools) , as well as the [set](https://docs.getdbt.com/reference/dbt-jinja-functions/set) and [zip](https://docs.getdbt.com/reference/dbt-jinja-functions/zip) functions. * **[Node selection](https://docs.getdbt.com/reference/node-selection/syntax) ** includes a [file selection method](https://docs.getdbt.com/reference/node-selection/methods#file) (`-s model.sql`), and [yaml selector](https://docs.getdbt.com/reference/node-selection/yaml-selectors) inheritance. * **[Global configs](https://docs.getdbt.com/reference/global-configs/about-global-configs) ** now include CLI flag and environment variable settings for [`target-path`](https://docs.getdbt.com/reference/global-configs/json-artifacts) and [`log-path`](https://docs.getdbt.com/reference/global-configs/logs) , which can be used to override the values set in `dbt_project.yml` ### Specific adapters[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.2#specific-adapters "Direct link to Specific adapters") * [Postgres](https://docs.getdbt.com/docs/core/connect-data-platform/postgres-setup) and [Redshift](https://docs.getdbt.com/docs/core/connect-data-platform/redshift-setup) profiles support a `retries` config, if dbt encounters an operational error or timeout when opening a connection. The default is 1 retry. Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Resources](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.2#resources) * [What to know before upgrading](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.2#what-to-know-before-upgrading) * [For consumers of dbt artifacts (metadata)](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.2#for-consumers-of-dbt-artifacts-metadata) * [For maintainers of adapter plugins](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.2#for-maintainers-of-adapter-plugins) * [New and changed functionality](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.2#new-and-changed-functionality) * [Specific adapters](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.2#specific-adapters) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/dbt-versions/core-upgrade/11-Older%20versions/14-upgrading-to-v1.2.md) --- # Sources object schema | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-sources#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page The sources object allows you to query information about all sources in a given job. ### Arguments[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-sources#arguments "Direct link to Arguments") When querying for `sources`, the following arguments are available. Fetching data... ================ Below we show some illustrative example queries and outline the schema of the sources object. ### Example queries[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-sources#example-queries "Direct link to Example queries") The database, schema, and identifier arguments are optional. This means that with this endpoint you can: * Find a specific source by providing `..` * Find all of the sources in a database and/or schema by providing `` and/or `` #### Finding sources by their database, schema, and identifier[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-sources#finding-sources-by-their-database-schema-and-identifier "Direct link to Finding sources by their database, schema, and identifier") The example query below finds a source by its unique database, schema, and identifier. { job(id: 123) { sources( database: "analytics" schema: "analytics" identifier: "dim_customers" ) { uniqueId } }} #### Finding sources by their schema[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-sources#finding-sources-by-their-schema "Direct link to Finding sources by their schema") The example query below finds all sources in this schema and their respective states (pass, error, fail). { job(id: 123) { sources(schema: "analytics") { uniqueId state } }} ### Fields[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-sources#fields "Direct link to Fields") The sources object can access the _same fields_ as the [source node](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-source) . The difference is that the sources object can output a list so instead of querying for fields for one specific source, you can query for those parameters for all sources within a jobID, database, and so on. When querying for `sources`, the following fields are available: Fetching data... ================ Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Arguments](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-sources#arguments) * [Example queries](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-sources#example-queries) * [Fields](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-sources#fields) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/dbt-cloud-apis/schema-discovery-job-sources.mdx) --- # Apache Iceberg Support | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/mesh/iceberg/apache-iceberg-support#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) Apache Iceberg is an open standard table format that brings greater portability and interoperability to the data ecosystem. By standardizing how data is stored and accessed, Iceberg enables teams to work across different engines and platforms with confidence. It has many components to it but the main ones that dbt interacts with are: * **Iceberg Table Format** - an open-source table format. Tables materialized in iceberg table format are stored on a user’s infrastructure, such as a S3 Bucket. * **Iceberg Data Catalog** - an open-source metadata management system that tracks the schema, partition, and versions of Iceberg tables. * **Iceberg REST Protocol** (also referred to as Iceberg REST API) is how engines can support and speak to other Iceberg-compatible catalogs. dbt abstracts the complexity of table formats so teams can focus on delivering reliable, well-modeled data. Our initial integration with Iceberg supports table materializations and catalog integrations, allowing users to define and manage Iceberg tables directly in their dbt projects. To learn more, click on one of the following tiles [![](https://docs.getdbt.com/img/icons/dbt-icon.svg)\ \ #### Using dbt + Iceberg Catalog overview\ \ dbt support for Apache Iceberg](https://docs.getdbt.com/docs/mesh/iceberg/about-catalogs) [![](https://docs.getdbt.com/img/icons/snowflake.svg)\ \ #### Snowflake\ \ Snowflake Iceberg Configurations](https://docs.getdbt.com/docs/mesh/iceberg/snowflake-iceberg-support) [![](https://docs.getdbt.com/img/icons/bigquery.svg)\ \ #### BigQuery\ \ BigQuery Iceberg Configurations](https://docs.getdbt.com/docs/mesh/iceberg/bigquery-iceberg-support) Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 --- # Trusted adapters | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/trusted-adapters#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) Trusted adapters take part in the Trusted Adapter Program, including a commitment to meet the program's requirements. They are maintained by dbt Labs, partners, and community members. Trusted adapters in dbt undergo an additional rigorous process that covers development, documentation, user experience, and maintenance requirements. We strongly recommend using them in production environments. For further details, refer to [What it means to be trusted](https://docs.getdbt.com/guides/adapter-creation?step=8#what-it-means-to-be-trusted) . Free and open-source tools for the data professional are increasingly abundant. This is by-and-large a _good thing_, however it requires due diligence that wasn't required in a paid-license, closed-source software world. As a user, there are important questions to answer before taking a dependency on an open-source project. The trusted adapter designation is meant to streamline this process for end users. ### Trusted adapter specifications[​](https://docs.getdbt.com/docs/trusted-adapters#trusted-adapter-specifications "Direct link to Trusted adapter specifications") Refer to the [Build, test, document, and promote adapters](https://docs.getdbt.com/guides/adapter-creation) guide for more information, particularly if you are an adapter maintainer considering having your adapter be added to the trusted list. ### Trusted adapters[​](https://docs.getdbt.com/docs/trusted-adapters#trusted-adapters "Direct link to Trusted adapters") ![](https://docs.getdbt.com/img/icons/alloydb.svg) #### AlloyDB * [Set up in the dbt platform](https://docs.getdbt.com/docs/cloud/connect-data-platform/connect-redshift-postgresql-alloydb) * [Install with dbt Core](https://docs.getdbt.com/docs/core/connect-data-platform/alloydb-setup) [![](https://badge.fury.io/py/dbt-postgres.svg/)](https://badge.fury.io/py/dbt-postgres) dbt platformdbt Core ![](https://docs.getdbt.com/img/icons/apache-spark.svg) #### Apache Spark * [Set up in the dbt platform](https://docs.getdbt.com/docs/cloud/connect-data-platform/connect-apache-spark) * [Install with dbt Core](https://docs.getdbt.com/docs/core/connect-data-platform/spark-setup) [![](https://badge.fury.io/py/dbt-spark.svg/)](https://badge.fury.io/py/dbt-spark) dbt platformdbt Core ![](https://docs.getdbt.com/img/icons/athena.svg) #### Athena * [Set up in dbt](https://docs.getdbt.com/docs/cloud/connect-data-platform/connect-amazon-athena) * [Install with dbt Core](https://docs.getdbt.com/docs/core/connect-data-platform/athena-setup) [![](https://badge.fury.io/py/dbt-athena.svg/)](https://badge.fury.io/py/dbt-athena) dbt platformdbt Core ![](https://docs.getdbt.com/img/icons/azure-synapse-analytics.svg) #### Azure Synapse * [Set up in the dbt platform](https://docs.getdbt.com/docs/cloud/connect-data-platform/connect-azure-synapse-analytics) * [Install with dbt Core](https://docs.getdbt.com/docs/core/connect-data-platform/azuresynapse-setup) [![](https://badge.fury.io/py/dbt-synapse.svg/)](https://badge.fury.io/py/dbt-synapse) dbt platformdbt Core ![](https://docs.getdbt.com/img/icons/bigquery.svg) #### BigQuery * [Set up in the dbt platform](https://docs.getdbt.com/docs/cloud/connect-data-platform/connect-bigquery) * [Install with dbt Core](https://docs.getdbt.com/docs/core/connect-data-platform/bigquery-setup) [![](https://badge.fury.io/py/dbt-bigquery.svg/)](https://badge.fury.io/py/dbt-bigquery) dbt platformdbt Core ![](https://docs.getdbt.com/img/icons/clickhouse.svg) #### ClickHouse * [Install with dbt Core](https://docs.getdbt.com/docs/core/connect-data-platform/clickhouse-setup) [![](https://badge.fury.io/py/dbt-clickhouse.svg/)](https://badge.fury.io/py/dbt-clickhouse) dbt Core ![](https://docs.getdbt.com/img/icons/databricks.svg) #### Databricks * [Set up in the dbt platform](https://docs.getdbt.com/docs/cloud/connect-data-platform/connect-databricks) * [Install with dbt Core](https://docs.getdbt.com/docs/core/connect-data-platform/databricks-setup) [![](https://badge.fury.io/py/dbt-databricks.svg/)](https://badge.fury.io/py/dbt-databricks) dbt platformdbt Core ![](https://docs.getdbt.com/img/icons/dremio.svg) #### Dremio * [Install with dbt Core](https://docs.getdbt.com/docs/core/connect-data-platform/dremio-setup) [![](https://badge.fury.io/py/dbt-dremio.svg/)](https://badge.fury.io/py/dbt-dremio) dbt Core ![](https://docs.getdbt.com/img/icons/glue.svg) #### Glue * [Install with dbt Core](https://docs.getdbt.com/docs/core/connect-data-platform/glue-setup) [![](https://badge.fury.io/py/dbt-glue.svg/)](https://badge.fury.io/py/dbt-glue) dbt Core ![](https://docs.getdbt.com/img/icons/dbt-ibm-netezza.svg) #### IBM Netezza * [Install with dbt Core](https://docs.getdbt.com/docs/core/connect-data-platform/ibmnetezza-setup) [![](https://badge.fury.io/py/dbt-ibm-netezza.svg/)](https://badge.fury.io/py/dbt-ibm-netezza) dbt Core ![](https://docs.getdbt.com/img/icons/lakebase.svg) #### Databricks Lakebase * [Install with dbt Core](https://docs.getdbt.com/docs/core/connect-data-platform/lakebase-setup) [![](https://badge.fury.io/py/dbt-postgres.svg/)](https://badge.fury.io/py/dbt-postgres) dbt platformdbt Core ![](https://docs.getdbt.com/img/icons/materialize.svg) #### Materialize * [Install with dbt Core](https://docs.getdbt.com/docs/core/connect-data-platform/materialize-setup) [![](https://badge.fury.io/py/dbt-materialize.svg/)](https://badge.fury.io/py/dbt-materialize) dbt Core ![](https://docs.getdbt.com/img/icons/fabric_warehouse.svg) #### Microsoft Fabric Warehouse * [Set up in the dbt platform](https://docs.getdbt.com/docs/cloud/connect-data-platform/connect-microsoft-fabric) * [Install with dbt Core](https://docs.getdbt.com/docs/core/connect-data-platform/fabric-setup) [![](https://badge.fury.io/py/dbt-fabric.svg/)](https://badge.fury.io/py/dbt-fabric) dbt platformdbt Core ![](https://docs.getdbt.com/img/icons/fabric_lakehouse.svg) #### Microsoft Fabric Lakehouse * [Install with dbt Core](https://docs.getdbt.com/docs/core/connect-data-platform/fabricspark-setup) [![](https://badge.fury.io/py/dbt-fabricspark.svg/)](https://badge.fury.io/py/dbt-fabricspark) dbt Core ![](https://docs.getdbt.com/img/icons/oracle.svg) #### Oracle Autonomous Database * [Install with dbt Core](https://docs.getdbt.com/docs/core/connect-data-platform/oracle-setup) [![](https://badge.fury.io/py/dbt-oracle.svg/)](https://badge.fury.io/py/dbt-oracle) dbt Core ![](https://docs.getdbt.com/img/icons/postgres.svg) #### Postgres * [Set up in the dbt platform](https://docs.getdbt.com/docs/cloud/connect-data-platform/connect-redshift-postgresql-alloydb) * [Install with dbt Core](https://docs.getdbt.com/docs/core/connect-data-platform/postgres-setup) [![](https://badge.fury.io/py/dbt-postgres.svg/)](https://badge.fury.io/py/dbt-postgres) dbt platformdbt Core ![](https://docs.getdbt.com/img/icons/redshift.svg) #### Redshift * [Set up in the dbt platform](https://docs.getdbt.com/docs/cloud/connect-data-platform/connect-redshift-postgresql-alloydb) * [Install with dbt Core](https://docs.getdbt.com/docs/core/connect-data-platform/redshift-setup) [![](https://badge.fury.io/py/dbt-redshift.svg/)](https://badge.fury.io/py/dbt-redshift) dbt platformdbt Core ![](https://docs.getdbt.com/img/icons/snowflake.svg) #### Snowflake * [Set up in the dbt platform](https://docs.getdbt.com/docs/cloud/connect-data-platform/connect-snowflake) * [Install with dbt Core](https://docs.getdbt.com/docs/core/connect-data-platform/snowflake-setup) [![](https://badge.fury.io/py/dbt-snowflake.svg/)](https://badge.fury.io/py/dbt-snowflake) dbt platformdbt Core ![](https://docs.getdbt.com/img/icons/starburst.svg) #### Starburst/Trino * [Set up in the dbt platform](https://docs.getdbt.com/docs/cloud/connect-data-platform/connect-starburst-trino) * [Install with dbt Core](https://docs.getdbt.com/docs/core/connect-data-platform/trino-setup) [![](https://badge.fury.io/py/dbt-trino.svg/)](https://badge.fury.io/py/dbt-trino) dbt platformdbt Core ![](https://docs.getdbt.com/img/icons/teradata.svg) #### Teradata * [Set up in the dbt platform](https://docs.getdbt.com/docs/cloud/connect-data-platform/connect-teradata) * [Install with dbt Core](https://docs.getdbt.com/docs/core/connect-data-platform/teradata-setup) [![](https://badge.fury.io/py/dbt-teradata.svg/)](https://badge.fury.io/py/dbt-teradata) dbt platformdbt Core Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 --- # Model object schema | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-model#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page The model object allows you to query information about a particular model in a given job. ### Arguments[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-model#arguments "Direct link to Arguments") When querying for a `model`, the following arguments are available. Fetching data... ================ Below we show some illustrative example queries and outline the schema (all possible fields you can query) of the model object. ### Example query for finding parent models and sources[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-model#example-query-for-finding-parent-models-and-sources "Direct link to Example query for finding parent models and sources") The example query below uses the `parentsModels` and `parentsSources` fields to fetch information about a model’s parent models and parent sources. The jobID and uniqueID fields are placeholders that you will need to replace with your own values. { job(id: 123) { model(uniqueId: "model.jaffle_shop.dim_user") { parentsModels { runId uniqueId executionTime } parentsSources { runId uniqueId state } } }} ### Example query for model timing[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-model#example-query-for-model-timing "Direct link to Example query for model timing") The example query below could be useful if you want to understand information around execution timing on a given model (start, end, completion). { job(id: 123) { model(uniqueId: "model.jaffle_shop.dim_user") { runId projectId name uniqueId resourceType executeStartedAt executeCompletedAt executionTime } }} ### Example query for column-level information[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-model#example-query-for-column-level-information "Direct link to Example query for column-level information") You can use the following example query to understand more about the columns of a given model. This query will only work if the job has generated documentation; that is, it will work with the command `dbt docs generate`. { job(id: 123) { model(uniqueId: "model.jaffle_shop.dim_user") { columns { name index type comment description tags meta } } }} ### Fields[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-model#fields "Direct link to Fields") When querying for a `model`, the following fields are available: Fetching data... ================ Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Arguments](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-model#arguments) * [Example query for finding parent models and sources](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-model#example-query-for-finding-parent-models-and-sources) * [Example query for model timing](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-model#example-query-for-model-timing) * [Example query for column-level information](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-model#example-query-for-column-level-information) * [Fields](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-model#fields) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/dbt-cloud-apis/schema-discovery-job-model.mdx) --- # Upgrading to v1.4 | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.4#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page ### Resources[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.4#resources "Direct link to Resources") * [Changelog](https://github.com/dbt-labs/dbt-core/blob/1.4.latest/CHANGELOG.md) * [dbt Core CLI Installation guide](https://docs.getdbt.com/docs/core/installation-overview) * [Cloud upgrade guide](https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-version-in-cloud) **Final release:** January 25, 2023 dbt Core v1.4 is a "behind-the-scenes" release. We've been hard at work rebuilding `dbt-core` internals on top of more-solid foundations, to enable an exciting year of new feature development. Check out the [v1.5 milestone](https://github.com/dbt-labs/dbt-core/milestone/82) in GitHub for a preview of what's planned for April. What to know before upgrading[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.4#what-to-know-before-upgrading "Direct link to What to know before upgrading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- dbt Labs is committed to providing backward compatibility for all versions 1.x. If you encounter an error upon upgrading, please let us know by [opening an issue](https://github.com/dbt-labs/dbt-core/issues/new) . ### For consumers of dbt artifacts (metadata)[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.4#for-consumers-of-dbt-artifacts-metadata "Direct link to For consumers of dbt artifacts (metadata)") The manifest schema version has updated to `v8`. These changes are relevant for people who parse or analyze the contents of the `manifest.json` file, or who have custom code accessing the [`model`](https://docs.getdbt.com/reference/dbt-jinja-functions/model) or [`graph`](https://docs.getdbt.com/reference/dbt-jinja-functions/graph) variables, e.g. `{{ model.root_path }}`. Relevant changes: * The `root_path` attribute has been removed for non-seed nodes to reduce duplicative information. * Unused attributes have been removed from seed nodes (including `depends_on.nodes`), and from `macros` (including `tags`). * The `unique_id` of docs blocks now start with `doc` for consistency with other resource types. ### For maintainers of adapter plugins[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.4#for-maintainers-of-adapter-plugins "Direct link to For maintainers of adapter plugins") > **TL;DR** Not much heavy lifting for this minor version. We anticipate more work for `1.5.0`. We plan to release betas early & often, and provide guidance on upgrading. The high-level changes are: * Add support for Python 3.11 * Rename/replace deprecated exception functions * Add support for Incremental Predicates (if applicable) * Make use of new adapter-zone tests For more detailed information and to ask any questions, please visit [dbt Core/discussions/6624](https://github.com/dbt-labs/dbt-core/discussions/6624) . New and changed documentation[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.4#new-and-changed-documentation "Direct link to New and changed documentation") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- * [**Events and structured logging**](https://docs.getdbt.com/reference/events-logging) : dbt's event system got a makeover. Expect more consistency in the availability and structure of information, backed by type-safe event schemas. * [**Python support**](https://docs.getdbt.com/faqs/Core/install-python-compatibility) : Python 3.11 was released in October 2022. It is officially supported in dbt-core v1.4, although full support depends also on the adapter plugin for your data platform. According to the Python maintainers, "Python 3.11 is between 10-60% faster than Python 3.10." We encourage you to try [`dbt parse`](https://docs.getdbt.com/reference/commands/parse) with dbt Core v1.4 + Python 3.11, and compare the timing with dbt Core v1.3 + Python 3.10. Let us know what you find! * [**Metrics**](https://docs.getdbt.com/docs/build/build-metrics-intro) : `time_grain` is optional, to provide better ergonomics around metrics that aren't time-bound. * **dbt-Jinja context:** The [local\_md5](https://docs.getdbt.com/reference/dbt-jinja-functions/local_md5) context method will calculate an [MD5 hash](https://en.wikipedia.org/wiki/MD5) for use _within_ dbt. (Not to be confused with SQL md5!) * [**Exposures**](https://docs.getdbt.com/docs/build/exposures) can now depend on `metrics`. * [**"Tarball" packages**](https://docs.getdbt.com/docs/build/packages#internally-hosted-tarball-URL) : Some organizations have security requirements to pull resources only from internal services. To address the need to install packages from hosted environments (such as Artifactory or cloud storage buckets), it's possible to specify any accessible URL where a compressed dbt package can be downloaded. * [**Granular "warn error" configuration**](https://docs.getdbt.com/reference/global-configs/warnings) : Thanks to a full cleanup and consolidation of warning and exception classes within `dbt-core`, it is now possible to define a more granular `--warn-error-options` configuration that specifies the exact warnings you do (or don't) want dbt to treat as errors. * [**Deferral**](https://docs.getdbt.com/reference/node-selection/defer#favor-state) supports an optional configuration, `--favor-state`. ### Advanced configurations for incremental models[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.4#advanced-configurations-for-incremental-models "Direct link to Advanced configurations for incremental models") * [**`incremental_predicates`** config](https://docs.getdbt.com/docs/build/incremental-strategy#about-incremental_predicates) is now supported on the most popular adapters, enabling greater flexibility when tuning performance in `merge` and `delete` statements against large datasets. * **BigQuery:** The `insert_overwrite` incremental strategy supports a new (old) mechanism, [`time_ingestion_partitioning`](https://docs.getdbt.com/reference/resource-configs/bigquery-configs#partitioning-by-an-ingestion-date-or-timestamp) + [`copy_partitions`](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.4#copying-ingestion-time-partitions) , that can yield significant savings in cost + time for large datasets. ### Updates to Python models[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.4#updates-to-python-models "Direct link to Updates to Python models") * Python models are [configured to materialize](https://docs.getdbt.com/docs/build/python-models) as `table` by default. * Python models [running on Snowpark](https://docs.getdbt.com/docs/build/python-models) will use "anonymous" stored procedures by default, enabling a small speedup and a cleaner query history. Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Resources](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.4#resources) * [What to know before upgrading](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.4#what-to-know-before-upgrading) * [For consumers of dbt artifacts (metadata)](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.4#for-consumers-of-dbt-artifacts-metadata) * [For maintainers of adapter plugins](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.4#for-maintainers-of-adapter-plugins) * [New and changed documentation](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.4#new-and-changed-documentation) * [Advanced configurations for incremental models](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.4#advanced-configurations-for-incremental-models) * [Updates to Python models](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.4#updates-to-python-models) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/dbt-versions/core-upgrade/11-Older%20versions/12-upgrading-to-v1.4.md) --- # Visualize downstream exposures | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/explore/view-downstream-exposures#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page Downstream exposures integrate natively with Tableau (Power BI coming soon) and auto-generate downstream lineage in Catalog for a richer experience. As a data team, it’s critical that you have context into the downstream use cases and users of your data products. By leveraging downstream [exposures](https://docs.getdbt.com/docs/build/exposures) automatically, data teams can: * Gain a better understanding of how models are used in downstream analytics, improving governance and decision-making. * Reduce incidents and optimize workflows by linking upstream models to downstream dependencies. * Automate exposure tracking for supported BI tools, ensuring lineage is always up to date. * [Orchestrate exposures](https://docs.getdbt.com/docs/cloud-integrations/orchestrate-exposures) to refresh the underlying data sources during scheduled dbt jobs, improving timeliness and reducing costs. Orchestrating exposures is essentially a way to ensure that your BI tools are updated regularly by using the [dbt job scheduler](https://docs.getdbt.com/docs/deploy/deployments) . * For more info on the differences between visualizing and orchestrating exposures, see [Visualize and orchestrate downstream exposures](https://docs.getdbt.com/docs/cloud-integrations/downstream-exposures) . To configure downstream exposures automatically from dashboards in Tableau, prerequisites, and more — refer to [Configure downstream exposures](https://docs.getdbt.com/docs/cloud-integrations/downstream-exposures-tableau) . ### Supported plans[​](https://docs.getdbt.com/docs/explore/view-downstream-exposures#supported-plans "Direct link to Supported plans") Downstream exposures is available on all dbt [Enterprise-tier plans](https://www.getdbt.com/pricing/) . Currently, you can only connect to a single Tableau site on the same server. Tableau Server If you're using Tableau Server, you need to [allowlist dbt's IP addresses](https://docs.getdbt.com/docs/cloud/about-cloud/access-regions-ip-addresses) for your dbt region. View downstream exposures[​](https://docs.getdbt.com/docs/explore/view-downstream-exposures#view-downstream-exposures "Direct link to View downstream exposures") ------------------------------------------------------------------------------------------------------------------------------------------------------------------ After setting up downstream exposures in dbt, you can view them in [Catalog](https://docs.getdbt.com/docs/explore/explore-projects) for a richer experience. Navigate to Catalog by clicking on the **Explore** link in the navigation. From the **Overview** page, you can view downstream exposures from a couple of places: * [Exposures menu](https://docs.getdbt.com/docs/explore/view-downstream-exposures#exposures-menu) * [File tree](https://docs.getdbt.com/docs/explore/view-downstream-exposures#file-tree) * [Project lineage](https://docs.getdbt.com/docs/explore/view-downstream-exposures#project-lineage) ### Exposures menu[​](https://docs.getdbt.com/docs/explore/view-downstream-exposures#exposures-menu "Direct link to Exposures menu") View downstream exposures from the **Exposures** menu item under **Resources**. This menu provides a comprehensive list of all the exposures so you can quickly access and manage them. The menu displays the following information: * **Name**: The name of the exposure. * **Health**: The [data health signal](https://docs.getdbt.com/docs/explore/data-health-signals) of the exposure. * **Type**: The type of exposure, such as `dashboard` or `notebook`. * **Owner**: The owner of the exposure. * **Owner email**: The email address of the owner of the exposure. * **Integration**: The BI tool that the exposure is integrated with. * **Exposure mode**: The type of exposure defined: **Auto** or **Manual**. [![View from the dbt Catalog under the 'Resources' menu.](https://docs.getdbt.com/img/docs/cloud-integrations/auto-exposures/explorer-view-resources.jpg?v=2 "View from the dbt Catalog under the 'Resources' menu.")](https://docs.getdbt.com/docs/explore/view-downstream-exposures#) View from the dbt Catalog under the 'Resources' menu. ### File tree[​](https://docs.getdbt.com/docs/explore/view-downstream-exposures#file-tree "Direct link to File tree") Locate directly from within the **File tree** under the **imported\_from\_tableau** sub-folder. This view integrates exposures seamlessly with your project files, making it easy to find and reference them from your project's structure. [![View from the dbt Catalog under the 'File tree' menu.](https://docs.getdbt.com/img/docs/cloud-integrations/auto-exposures/explorer-view-file-tree.jpg?v=2 "View from the dbt Catalog under the 'File tree' menu.")](https://docs.getdbt.com/docs/explore/view-downstream-exposures#) View from the dbt Catalog under the 'File tree' menu. ### Project lineage[​](https://docs.getdbt.com/docs/explore/view-downstream-exposures#project-lineage "Direct link to Project lineage") From the **Project lineage** view, which visualizes the dependencies and relationships in your project. Exposures are represented with the Tableau icon, offering an intuitive way to see how they fit into your project's overall data flow. [![View from the dbt Catalog in your Project lineage view, displayed with the Tableau icon.](https://docs.getdbt.com/img/docs/cloud-integrations/auto-exposures/explorer-lineage2.jpg?v=2 "View from the dbt Catalog in your Project lineage view, displayed with the Tableau icon.")](https://docs.getdbt.com/docs/explore/view-downstream-exposures#) View from the dbt Catalog in your Project lineage view, displayed with the Tableau icon. [![View from the dbt Catalog in your Project lineage view, displayed with the Tableau icon.](https://docs.getdbt.com/img/docs/cloud-integrations/auto-exposures/explorer-lineage.jpg?v=2 "View from the dbt Catalog in your Project lineage view, displayed with the Tableau icon.")](https://docs.getdbt.com/docs/explore/view-downstream-exposures#) View from the dbt Catalog in your Project lineage view, displayed with the Tableau icon. Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Supported plans](https://docs.getdbt.com/docs/explore/view-downstream-exposures#supported-plans) * [View downstream exposures](https://docs.getdbt.com/docs/explore/view-downstream-exposures#view-downstream-exposures) * [Exposures menu](https://docs.getdbt.com/docs/explore/view-downstream-exposures#exposures-menu) * [File tree](https://docs.getdbt.com/docs/explore/view-downstream-exposures#file-tree) * [Project lineage](https://docs.getdbt.com/docs/explore/view-downstream-exposures#project-lineage) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/explore/view-downstream-exposures.md) --- # Upgrading to v1.3 | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.3#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page ### Resources[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.3#resources "Direct link to Resources") * [Changelog](https://github.com/dbt-labs/dbt-core/blob/1.3.latest/CHANGELOG.md) * [dbt Core CLI Installation guide](https://docs.getdbt.com/docs/core/installation-overview) * [Cloud upgrade guide](https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-version-in-cloud) What to know before upgrading[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.3#what-to-know-before-upgrading "Direct link to What to know before upgrading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- We are committed to providing backward compatibility for all versions 1.x. If you encounter an error upon upgrading, please let us know by [opening an issue](https://github.com/dbt-labs/dbt-core/issues/new) . There are three changes in dbt Core v1.3 that may require action from some users: 1. If you have a `profiles.yml` file located in the root directory where you run dbt, dbt will start preferring that profiles file over the default location on your machine. [You can read more details here](https://docs.getdbt.com/docs/core/connect-data-platform/connection-profiles#advanced-customizing-a-profile-directory) . 2. If you already have `.py` files defined in the `model-paths` of your dbt project, dbt will start trying to read them as Python models. You can use [the new `.dbtignore` file](https://docs.getdbt.com/reference/dbtignore) to tell dbt to ignore those files. 3. If you have custom code accessing the `raw_sql` property of models (with the [model](https://docs.getdbt.com/reference/dbt-jinja-functions/model) or [graph](https://docs.getdbt.com/reference/dbt-jinja-functions/graph) objects), it has been renamed to `raw_code`. This is a change to the manifest contract, described in more detail below. ### For users of dbt Metrics[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.3#for-users-of-dbt-metrics "Direct link to For users of dbt Metrics") The names of metric properties have changed, with backward compatibility. Those changes are: * Renamed `type` to `calculation_method` * Renamed `sql` to `expression` * Renamed `expression` calculation method metrics to `derived` calculation method metrics We plan to keep backward compatibility for a full minor version. Defining metrics with the old names will raise an error in dbt Core v1.4. ### For consumers of dbt artifacts (metadata)[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.3#for-consumers-of-dbt-artifacts-metadata "Direct link to For consumers of dbt artifacts (metadata)") We have updated the manifest schema version to `v7`. This includes the changes to metrics described above and a few other changes related to the addition of Python models: * Renamed `raw_sql` to `raw_code` * Renamed `compiled_sql` to `compiled_code` * A new top-level node property, `language` (`'sql'` or `'python'`) For users of [state-based selection](https://docs.getdbt.com/reference/node-selection/syntax#about-node-selection) : This release includes logic providing backward and forward compatibility for older manifest versions. While running dbt Core v1.3, it should be possible to use `state:modified --state ...` selection against a manifest produced by dbt Core v1.0 and higher. ### For maintainers of adapter plugins[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.3#for-maintainers-of-adapter-plugins "Direct link to For maintainers of adapter plugins") GitHub discussion with details: [dbt-labs/dbt-core#6011](https://github.com/dbt-labs/dbt-core/discussions/6011) New and changed documentation[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.3#new-and-changed-documentation "Direct link to New and changed documentation") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- * **[Python models](https://docs.getdbt.com/docs/build/python-models) ** are natively supported in `dbt-core` for the first time, on data warehouses that support Python runtimes. * Updates made to **[Metrics](https://docs.getdbt.com/docs/build/build-metrics-intro) ** reflect their new syntax for definition, as well as additional properties that are now available. * Plus, a few related updates to **[exposure properties](https://docs.getdbt.com/reference/exposure-properties) **: `config`, `label`, and `name` validation. * **[Custom `node_color`](https://docs.getdbt.com/reference/resource-configs/docs) ** in `dbt-docs`. For the first time, you can control the colors displayed in dbt's DAG. Want bronze, silver, and gold layers? It's at your fingertips. * **[`Profiles.yml`](https://docs.getdbt.com/docs/core/connect-data-platform/connection-profiles#advanced-customizing-a-profile-directory) ** search order now looks in the current working directory before `~/.dbt`. ### Quick hits[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.3#quick-hits "Direct link to Quick hits") * **["Full refresh"](https://docs.getdbt.com/reference/resource-configs/full_refresh) ** flag supports a short name, `-f`. * **[The "config" selection method](https://docs.getdbt.com/reference/node-selection/methods#config) ** supports boolean and list config values, in addition to strings. * Two new dbt-Jinja context variables for accessing invocation metadata: [`invocation_args_dict`](https://docs.getdbt.com/reference/dbt-jinja-functions/flags#invocation_args_dict) and [`dbt_metadata_envs`](https://docs.getdbt.com/reference/dbt-jinja-functions/env_var#custom-metadata) . Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Resources](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.3#resources) * [What to know before upgrading](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.3#what-to-know-before-upgrading) * [For users of dbt Metrics](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.3#for-users-of-dbt-metrics) * [For consumers of dbt artifacts (metadata)](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.3#for-consumers-of-dbt-artifacts-metadata) * [For maintainers of adapter plugins](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.3#for-maintainers-of-adapter-plugins) * [New and changed documentation](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.3#new-and-changed-documentation) * [Quick hits](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.3#quick-hits) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/dbt-versions/core-upgrade/11-Older%20versions/13-upgrading-to-v1.3.md) --- # Models object schema | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-models#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page The models object allows you to query information about all models in a given job. ### Arguments[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-models#arguments "Direct link to Arguments") When querying for `models`, the following arguments are available. Fetching data... ================ Below we show some illustrative example queries and outline the schema of the models object. ### Example queries[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-models#example-queries "Direct link to Example queries") The database, schema, and identifier arguments are all optional. This means that with this endpoint you can: * Find a specific model by providing `..` * Find all of the models in a database and/or schema by providing `` and/or `` #### Find models by their database, schema, and identifier[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-models#find-models-by-their-database-schema-and-identifier "Direct link to Find models by their database, schema, and identifier") The example query below finds a model by its unique database, schema, and identifier. { job(id: 123) { models(database:"analytics", schema: "analytics", identifier:"dim_customers") { uniqueId } }} #### Find models by their schema[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-models#find-models-by-their-schema "Direct link to Find models by their schema") The example query below finds all models in this schema and their respective execution times. { job(id: 123) { models(schema: "analytics") { uniqueId executionTime } }} ### Fields[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-models#fields "Direct link to Fields") The models object can access the _same fields_ as the [Model node](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-model) . The difference is that the models object can output a list so instead of querying for fields for one specific model, you can query for those parameters for all models within a jobID, database, and so on. When querying for `models`, the following fields are available: Fetching data... ================ Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Arguments](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-models#arguments) * [Example queries](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-models#example-queries) * [Fields](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-models#fields) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/dbt-cloud-apis/schema-discovery-job-models.mdx) --- # Source object schema | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-source#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page The source object allows you to query information about a particular source in a given job. ### Arguments[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-source#arguments "Direct link to Arguments") When querying for a `source`, the following arguments are available. Fetching data... ================ Below we show some illustrative example queries and outline the schema of the source object. ### Example query[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-source#example-query "Direct link to Example query") The query below pulls relevant information about a given source. For instance, you can view the load time and the state (pass, fail, error) of that source. { job(id: 123) { source(uniqueId: "source.jaffle_shop.snowplow.event") { uniqueId sourceName name state maxLoadedAt criteria { warnAfter { period count } errorAfter { period count } } maxLoadedAtTimeAgoInS } }} ### Fields[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-source#fields "Direct link to Fields") When querying for a `source`, the following fields are available: Fetching data... ================ Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Arguments](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-source#arguments) * [Example query](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-source#example-query) * [Fields](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-source#fields) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/dbt-cloud-apis/schema-discovery-job-source.mdx) --- # Upgrading to v1.6 | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.6#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page dbt Core v1.6 has three significant areas of focus: 1. Next milestone of [multi-project deployments](https://github.com/dbt-labs/dbt-core/discussions/6725) : improvements to contracts, groups/access, versions; and building blocks for cross-project `ref` 2. Semantic layer re-launch: dbt Core and [MetricFlow](https://docs.getdbt.com/docs/build/about-metricflow) integration 3. Mechanisms to support mature deployment at scale (`dbt clone` and `dbt retry`) Resources[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.6#resources "Direct link to Resources") --------------------------------------------------------------------------------------------------------------------------------------------- * [Changelog](https://github.com/dbt-labs/dbt-core/blob/1.6.latest/CHANGELOG.md) * [dbt Core installation guide](https://docs.getdbt.com/docs/core/installation-overview) * [Cloud upgrade guide](https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-version-in-cloud) * [Release schedule](https://github.com/dbt-labs/dbt-core/issues/7481) What to know before upgrading[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.6#what-to-know-before-upgrading "Direct link to What to know before upgrading") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- dbt Labs is committed to providing backward compatibility for all versions 1.x, with the exception of any changes explicitly mentioned below. If you encounter an error upon upgrading, please let us know by [opening an issue](https://github.com/dbt-labs/dbt-core/issues/new) . ### Behavior changes[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.6#behavior-changes "Direct link to Behavior changes") Action required if your project defines `metrics` The [spec for metrics](https://github.com/dbt-labs/dbt-core/discussions/7456) has changed and now uses [MetricFlow](https://docs.getdbt.com/docs/build/about-metricflow) . If your dbt project defines metrics, you must migrate to dbt v1.6 because the YAML spec has moved from dbt\_metrics to MetricFlow. Any tests you have won't compile on v1.5 or older. * dbt Core v1.6 does not support Python 3.7, which reached End Of Life on June 23. Support Python versions are 3.8, 3.9, 3.10, and 3.11. * As part of the [dbt Semantic layer](https://docs.getdbt.com/docs/use-dbt-semantic-layer/dbt-sl) re-launch (in beta), the spec for `metrics` has changed significantly. Refer to the [migration guide](https://docs.getdbt.com/guides/sl-migration) for more info on how to migrate to the re-launched dbt Semantic Layer. * The manifest schema version is now v10. * dbt Labs is ending support for Homebrew installation of dbt Core and adapters. See [the discussion](https://github.com/dbt-labs/dbt-core/discussions/8277) for more details. ### For consumers of dbt artifacts (metadata)[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.6#for-consumers-of-dbt-artifacts-metadata "Direct link to For consumers of dbt artifacts (metadata)") The [manifest](https://docs.getdbt.com/reference/artifacts/manifest-json) schema version has been updated to `v10`. Specific changes: * Addition of `semantic_models` and changes to `metrics` attributes * Addition of `deprecation_date` as a model property * Addition of `on_configuration_change` as default node configuration (to support materialized views) * Small type changes to `contracts` and `constraints` * Manifest `metadata` includes `project_name` ### For maintainers of adapter plugins[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.6#for-maintainers-of-adapter-plugins "Direct link to For maintainers of adapter plugins") For more detailed information and to ask questions, please read and comment on the GH discussion: [dbt-labs/dbt Core#7958](https://github.com/dbt-labs/dbt-core/discussions/7958) . New and changed documentation[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.6#new-and-changed-documentation "Direct link to New and changed documentation") --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### MetricFlow[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.6#metricflow "Direct link to MetricFlow") * [**Build your metrics**](https://docs.getdbt.com/docs/build/build-metrics-intro) with MetricFlow, a key component of the Semantic Layer. You can define your metrics and build semantic models with MetricFlow, available on the command line (CLI) for dbt Core v1.6 beta or higher. ### Materialized views[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.6#materialized-views "Direct link to Materialized views") Supported on: * [Postgres](https://docs.getdbt.com/reference/resource-configs/postgres-configs#materialized-view) * [Redshift](https://docs.getdbt.com/reference/resource-configs/redshift-configs#materialized-view) * [Snowflake](https://docs.getdbt.com/reference/resource-configs/snowflake-configs#dynamic-tables) * [Databricks](https://docs.getdbt.com/reference/resource-configs/databricks-configs#materialized-views-and-streaming-tables) ### New commands for mature deployment[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.6#new-commands-for-mature-deployment "Direct link to New commands for mature deployment") [`dbt retry`](https://docs.getdbt.com/reference/commands/retry) executes the previously run command from the point of failure. Rebuild just the nodes that errored or skipped in a previous run/build/test, rather than starting over from scratch. [`dbt clone`](https://docs.getdbt.com/reference/commands/clone) leverages each data platform's functionality for creating lightweight copies of dbt models from one environment into another. Useful when quickly spinning up a new development environment, or promoting specific models from a staging environment into production. ### Multi-project collaboration[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.6#multi-project-collaboration "Direct link to Multi-project collaboration") [**Deprecation date**](https://docs.getdbt.com/reference/resource-properties/deprecation_date) : Models can declare a deprecation date that will warn model producers and downstream consumers. This enables clear migration windows for versioned models, and provides a mechanism to facilitate removal of immature or little-used models, helping to avoid project bloat. [Model names](https://docs.getdbt.com/faqs/Project/unique-resource-names) can be duplicated across different namespaces (projects/packages), so long as they are unique within each project/package. We strongly encourage using [two-argument `ref`](https://docs.getdbt.com/reference/dbt-jinja-functions/ref#ref-project-specific-models) when referencing a model from a different package/project. More consistency and flexibility around packages. Resources defined in a package will respect variable and global macro definitions within the scope of that package. * `vars` defined in a package's `dbt_project.yml` are now available in the resolution order when compiling nodes in that package, though CLI `--vars` and the root project's `vars` will still take precedence. See ["Variable Precedence"](https://docs.getdbt.com/docs/build/project-variables#variable-precedence) for details. * `generate_x_name` macros (defining custom rules for database, schema, alias naming) follow the same pattern as other "global" macros for package-scoped overrides. See [macro dispatch](https://docs.getdbt.com/reference/dbt-jinja-functions/dispatch) for an overview of the patterns that are possible. Closed Beta - dbt Enterprise [**Project dependencies**](https://docs.getdbt.com/docs/mesh/govern/project-dependencies) : Introduces `dependencies.yml` and dependent `projects` as a feature of dbt Enterprise. Allows enforcing model access (public vs. protected/private) across project/package boundaries. Enables cross-project `ref` of public models, without requiring the installation of upstream source code. ### Deprecated functionality[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.6#deprecated-functionality "Direct link to Deprecated functionality") The ability for installed packages to override built-in materializations without explicit opt-in from the user is being deprecated. * Overriding a built-in materialization from an installed package raises a deprecation warning. * Using a custom materialization from an installed package does not raise a deprecation warning. * Using a built-in materialization package override from the root project via a wrapping materialization is still supported. For example: {% materialization view, default %}{{ return(my_cool_package.materialization_view_default()) }}{% endmaterialization %} ### Quick hits[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.6#quick-hits "Direct link to Quick hits") * [`state:unmodified` and `state:old`](https://docs.getdbt.com/reference/node-selection/methods#state) for [MECE](https://en.wikipedia.org/wiki/MECE_principle) stateful selection * [`invocation_args_dict`](https://docs.getdbt.com/reference/dbt-jinja-functions/flags#invocation_args_dict) includes full `invocation_command` as string * [`dbt debug --connection`](https://docs.getdbt.com/reference/commands/debug) to test just the data platform connection specified in a profile * [`dbt docs generate --empty-catalog`](https://docs.getdbt.com/reference/commands/cmd-docs) to skip catalog population while generating docs * [`--defer-state`](https://docs.getdbt.com/reference/node-selection/defer) enables more-granular control * [`dbt ls`](https://docs.getdbt.com/reference/commands/list) adds the Semantic model selection method to allow for `dbt ls -s "semantic_model:*"` and the ability to execute `dbt ls --resource-type semantic_model`. * Syntax for `DBT_ENV_SECRET_` has changed to `DBT_ENV_SECRET` and no longer requires the closing underscore. Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Resources](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.6#resources) * [What to know before upgrading](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.6#what-to-know-before-upgrading) * [Behavior changes](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.6#behavior-changes) * [For consumers of dbt artifacts (metadata)](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.6#for-consumers-of-dbt-artifacts-metadata) * [For maintainers of adapter plugins](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.6#for-maintainers-of-adapter-plugins) * [New and changed documentation](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.6#new-and-changed-documentation) * [MetricFlow](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.6#metricflow) * [Materialized views](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.6#materialized-views) * [New commands for mature deployment](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.6#new-commands-for-mature-deployment) * [Multi-project collaboration](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.6#multi-project-collaboration) * [Deprecated functionality](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.6#deprecated-functionality) * [Quick hits](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.6#quick-hits) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/dbt-versions/core-upgrade/11-Older%20versions/09-upgrading-to-v1.6.md) --- # Exposures object schema | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-exposures#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page The exposures object allows you to query information about all exposures in a given job. To learn more, refer to [Add Exposures to your DAG](https://docs.getdbt.com/docs/build/exposures) . ### Arguments[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-exposures#arguments "Direct link to Arguments") When querying for `exposures`, the following arguments are available. Fetching data... ================ Below we show some illustrative example queries and outline the schema of the exposures object. ### Example query[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-exposures#example-query "Direct link to Example query") The example below queries information about all exposures in a given job including the owner's name and email, the URL, and information about parent sources and parent models for each exposure. { job(id: 123) { exposures(jobId: 123) { runId projectId name uniqueId resourceType ownerName url ownerEmail parentsSources { uniqueId sourceName name state maxLoadedAt criteria { warnAfter { period count } errorAfter { period count } } maxLoadedAtTimeAgoInS } parentsModels { uniqueId } } }} ### Fields[​](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-exposures#fields "Direct link to Fields") When querying for `exposures`, the following fields are available: Fetching data... ================ Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Arguments](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-exposures#arguments) * [Example query](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-exposures#example-query) * [Fields](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-schema-job-exposures#fields) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/dbt-cloud-apis/schema-discovery-job-exposures.mdx) --- # 2023 dbt Cloud release notes | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page Archived release notes for dbt from 2023 December 2023[​](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#december-2023 "Direct link to December 2023") ---------------------------------------------------------------------------------------------------------------------------- *  Semantic Layer updates The dbt Labs team continues to work on adding new features, fixing bugs, and increasing reliability for the dbt Semantic Layer. The following list explains the updates and fixes for December 2023 in more detail. Bug fixes[​](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#bug-fixes "Direct link to Bug fixes") ---------------------------------------------------------------------------------------------------------------- * Tableau integration — The dbt Semantic Layer integration with Tableau now supports queries that resolve to a "NOT IN" clause. This applies to using "exclude" in the filtering user interface. Previously it wasn’t supported. * `BIGINT` support — The dbt Semantic Layer can now support `BIGINT` values with precision greater than 18. Previously it would return an error. * Memory leak — Fixed a memory leak in the JDBC API that would previously lead to intermittent errors when querying it. * Data conversion support — Added support for converting various Redshift and Postgres-specific data types. Previously, the driver would throw an error when encountering columns with those types. Improvements[​](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#improvements "Direct link to Improvements") ------------------------------------------------------------------------------------------------------------------------- * Deprecation — We deprecated dbt Metrics and the legacy dbt Semantic Layer, both supported on dbt version 1.5 or lower. This change came into effect on December 15th, 2023. * Improved dbt converter tool — The [dbt converter tool](https://github.com/dbt-labs/dbt-converter) can now help automate some of the work in converting from LookML (Looker's modeling language) for those who are migrating. Previously this wasn’t available. *  External attributes The extended attributes feature in dbt Cloud is now GA! It allows for an environment level override on any YAML attribute that a dbt adapter accepts in its `profiles.yml`. You can provide a YAML snippet to add or replace any [profile](https://docs.getdbt.com/docs/core/connect-data-platform/profiles.yml) value. To learn more, refer to [Extended attributes](https://docs.getdbt.com/docs/dbt-cloud-environments#extended-attributes) . The **Extended Attributes** text box is available from your environment's settings page: [![Example of the Extended attributes text box](https://docs.getdbt.com/img/docs/dbt-cloud/using-dbt-cloud/extended-attributes.png?v=2 "Example of the Extended attributes text box")](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#) Example of the Extended attributes text box *  Legacy semantic layer dbt Labs has deprecated dbt Metrics and the legacy dbt Semantic Layer, both supported on dbt version 1.5 or lower. This change starts on December 15th, 2023. This deprecation means dbt Metrics and the legacy Semantic Layer are no longer supported. We also removed the feature from the dbt Cloud user interface and documentation site. ### Why this change?[​](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#why-this-change "Direct link to Why this change?") The [re-released dbt Semantic Layer](https://docs.getdbt.com/docs/use-dbt-semantic-layer/dbt-sl) , powered by MetricFlow, offers enhanced flexibility, performance, and user experience, marking a significant advancement for the dbt community. ### Key changes and impact[​](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#key-changes-and-impact "Direct link to Key changes and impact") * **Deprecation date** — The legacy Semantic Layer and dbt Metrics will be officially deprecated on December 15th, 2023. * **Replacement** — [MetricFlow](https://docs.getdbt.com/docs/build/build-metrics-intro) replaces dbt Metrics for defining semantic logic. The `dbt_metrics` package will no longer be supported post-deprecation. * **New feature** — Exports replaces the materializing data with `metrics.calculate` functionality and will be available in dbt Cloud in December or January. ### Breaking changes and recommendations[​](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#breaking-changes-and-recommendations "Direct link to Breaking changes and recommendations") * For users on dbt version 1.5 and lower with dbt Metrics and Snowflake proxy: * **Impact**: Post-deprecation, queries using the proxy _will not_ run. * **Action required:** _Immediate_ migration is necessary. Refer to the [dbt Semantic Layer migration guide](https://docs.getdbt.com/guides/sl-migration?step=1) * For users on dbt version 1.5 and lower using dbt Metrics without Snowflake proxy: * **Impact**: No immediate disruption, but the package will not receive updates or support after deprecation * **Recommendation**: Plan migration to the re-released Semantic Layer for compatibility with dbt version 1.6 and higher. ### Engage and support[​](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#engage-and-support "Direct link to Engage and support") * Feedback and community support — Engage and share feedback with the dbt Labs team and dbt Community slack using channels like [#dbt-cloud-semantic-layer](https://getdbt.slack.com/archives/C046L0VTVR6) and [#dbt-metricflow](https://getdbt.slack.com/archives/C02CCBBBR1D) . Or reach out to your dbt Cloud account representative. * Resources for upgrading — Refer to some additional info and resources to help you upgrade your dbt version: * [Upgrade version in dbt Cloud](https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-version-in-cloud) * [Version migration guides](https://docs.getdbt.com/docs/dbt-versions/core-upgrade) November 2023[​](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#november-2023 "Direct link to November 2023") ---------------------------------------------------------------------------------------------------------------------------- *  New features and UI changes to dbt Catalog There are new quality-of-life improvements in dbt Cloud for email and Slack notifications about your jobs: * You can add external email addresses and send job notifications to them. External emails can be: * Addresses that are outside of your dbt Cloud account * Third-party integration addresses for configuring notifications to services like Microsoft Teams or PagerDuty * You can configure notifications for multiple Slack channels. Previously, you could only configure one Slack channel. * Any account admin can now edit slack notifications, not just the person who created them. To learn more, check out [Job notifications](https://docs.getdbt.com/docs/deploy/job-notifications) . *  Job notifications There are new quality-of-life improvements in dbt Cloud for email and Slack notifications about your jobs: * You can add external email addresses and send job notifications to them. External emails can be: * Addresses that are outside of your dbt Cloud account * Third-party integration addresses for configuring notifications to services like Microsoft Teams or PagerDuty * You can configure notifications for multiple Slack channels. Previously, you could only configure one Slack channel. * Any account admin can now edit slack notifications, not just the person who created them. To learn more, check out [Job notifications](https://docs.getdbt.com/docs/deploy/job-notifications) . *  Repo caching Now available for dbt Cloud Enterprise plans is a new option to enable Git repository caching for your job runs. When enabled, dbt Cloud caches your dbt project's Git repository and uses the cached copy instead if there's an outage with the Git provider. This feature improves the reliability and stability of your job runs. To learn more, refer to [Repo caching](https://docs.getdbt.com/docs/cloud/account-settings#git-repository-caching) . [![Example of the Repository caching option](https://docs.getdbt.com/img/docs/deploy/account-settings-repository-caching.png?v=2 "Example of the Repository caching option")](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#) Example of the Repository caching option October 2023[​](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#october-2023 "Direct link to October 2023") ------------------------------------------------------------------------------------------------------------------------- *  dbt Cloud APIs Beginning December 1, 2023, the [Administrative API](https://docs.getdbt.com/docs/dbt-cloud-apis/admin-cloud-api) v2 and v3 will expect you to limit all "list" or `GET` API methods to 100 results per API request. This limit enhances the efficiency and stability of our services. If you need to handle more than 100 results, then use the `limit` and `offset` query parameters to paginate those results; otherwise, you will receive an error. This maximum limit applies to [multi-tenant instances](https://docs.getdbt.com/docs/cloud/about-cloud/access-regions-ip-addresses) only, and _does not_ apply to single tenant instances. Refer to the [API v3 Pagination](https://docs.getdbt.com/dbt-cloud/api-v3#/) or [API v2 Pagination](https://docs.getdbt.com/dbt-cloud/api-v2#/) sections for more information on how to paginate your API responses. *  dbt CLI We are excited to announce the dbt CLI, **unified command line for dbt**, is available in public preview. It’s a local development experience, powered by dbt Cloud. It’s easy to get started: `pip3 install dbt` or `brew install dbt` and you’re ready to go. We will continue to invest in the dbt Cloud IDE as the easiest and most accessible way to get started using dbt, especially for data analysts who have never developed software using the command line before. We will keep improving the speed, stability, and feature richness of the IDE, as we have been [all year long](https://www.getdbt.com/blog/improvements-to-the-dbt-cloud-ide/) . We also know that many people developing in dbt have a preference for local development, where they can use their favorite terminal, text editor, keybindings, color scheme, and so on. This includes people with data engineering backgrounds, as well as those analytics engineers who started writing code in the dbt Cloud IDE and have expanded their skills. The new dbt CLI offers the best of both worlds, including: * The power of developing against the dbt Cloud platform * The flexibility of your own local setup Run whichever community-developed plugins, pre-commit hooks, or other arbitrary scripts you like. Some of the unique capabilities of this dbt CLI include: * Automatic deferral of build artifacts to your Cloud project's production environment * Secure credential storage in the dbt Cloud platform * Support for dbt Mesh ([cross-project `ref`](https://docs.getdbt.com/docs/mesh/govern/project-dependencies) ) * Development workflow for dbt Semantic Layer * Speedier, lower cost builds Refer to [dbt CLI](https://docs.getdbt.com/docs/cloud/cloud-cli-installation) to learn more. *  Custom branch fix If you don't set a [custom branch](https://docs.getdbt.com/docs/dbt-cloud-environments#custom-branch-behavior) for your dbt Cloud environment, it now defaults to the default branch of your Git repository (for example, `main`). Previously, [CI jobs](https://docs.getdbt.com/docs/deploy/ci-jobs) would run for pull requests (PRs) that were opened against _any branch_ or updated with new commits if the **Custom Branch** option wasn't set. Azure DevOps[​](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#azure-devops "Direct link to Azure DevOps") ------------------------------------------------------------------------------------------------------------------------- Your Git pull requests (PRs) might not trigger against your default branch if you're using Azure DevOps and the default branch isn't `main` or `master`. To resolve this, [set up a custom branch](https://docs.getdbt.com/faqs/Environments/custom-branch-settings) with the branch you want to target. *  dbt deps auto install The dbt Cloud IDE and dbt CLI now automatically installs `dbt deps` when your environment starts or when necessary. Previously, it would prompt you to run `dbt deps` during initialization. This improved workflow is available to all multi-tenant dbt Cloud users (Single-tenant support coming next week) and applies to dbt versions. However, you should still run the `dbt deps` command in these situations: * When you make changes to the `packages.yml` or `dependencies.yml` file during a session * When you update the package version in the `packages.yml` or `dependencies.yml` file. * If you edit the `dependencies.yml` file and the number of packages remains the same, run `dbt deps`. (Note that this is a known bug dbt Labs will fix in the future.) *  Native retry support Previously in dbt Cloud, you could only rerun an errored job from start but now you can also rerun it from its point of failure. You can view which job failed to complete successfully, which command failed in the run step, and choose how to rerun it. To learn more, refer to [Retry jobs](https://docs.getdbt.com/docs/deploy/retry-jobs) . [![Example of the Rerun options in dbt Cloud](https://docs.getdbt.com/img/docs/deploy/native-retry.gif?v=2 "Example of the Rerun options in dbt Cloud")](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#) Example of the Rerun options in dbt Cloud *  Product docs updates Hello from the dbt Docs team: @mirnawong1, @matthewshaver, @nghi-ly, and @runleonarun! First, we’d like to thank the 15 new community contributors to docs.getdbt.com. We merged [107 PRs](https://github.com/dbt-labs/docs.getdbt.com/pulls?q=is%3Apr+merged%3A2023-09-01..2023-09-31) in September. Here's what's new to [docs.getdbt.com](http://docs.getdbt.com/) : * Migrated docs.getdbt.com from Netlify to Vercel. ☁ Cloud projects[​](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#cloud-projects "Direct link to ☁ Cloud projects") ----------------------------------------------------------------------------------------------------------------------------------- * Continuous integration jobs are now generally available and no longer in beta! * Added [Postgres PrivateLink set up page](https://docs.getdbt.com/docs/cloud/secure/postgres-privatelink) * Published beta docs for [dbt Explorer](https://docs.getdbt.com/docs/explore/explore-projects) . * Added a new Semantic Layer [GraphQL API doc](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-graphql) and updated the [integration docs](https://docs.getdbt.com/docs/cloud-integrations/avail-sl-integrations) to include Hex. Responded to dbt community feedback and clarified Metricflow use cases for dbt Core and dbt Cloud. * Added an [FAQ](https://docs.getdbt.com/faqs/Git/git-migration) describing how to migrate from one git provider to another in dbt Cloud. * Clarified an example and added a [troubleshooting section](https://docs.getdbt.com/docs/cloud/connect-data-platform/connect-snowflake#troubleshooting) to Snowflake connection docs to address common errors and provide solutions. 🎯 Core projects[​](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#core-projects "Direct link to 🎯 Core projects") ---------------------------------------------------------------------------------------------------------------------------------- * Deprecated dbt Core v1.0 and v1.1 from the docs. * Added configuration instructions for the [AWS Glue](https://docs.getdbt.com/docs/core/connect-data-platform/glue-setup) community plugin. * Revised the dbt Core quickstart, making it easier to follow. Divided this guide into steps that align with the [other guides](https://docs.getdbt.com/guides/manual-install?step=1) . New 📚 Guides, ✏️ blog posts, and FAQs[​](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#newguides%EF%B8%8Fblog-posts-and-faqs "Direct link to New 📚 Guides, ✏️ blog posts, and FAQs") ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ Added a [style guide template](https://docs.getdbt.com/best-practices/how-we-style/6-how-we-style-conclusion#style-guide-template) that you can copy & paste to make sure you adhere to best practices when styling dbt projects! Upcoming changes[​](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#upcoming-changes "Direct link to Upcoming changes") ------------------------------------------------------------------------------------------------------------------------------------- Stay tuned for a flurry of releases in October and a filterable guides section that will make guides easier to find! *  Semantic layer GA If you're using the legacy Semantic Layer, we _highly_ recommend you [upgrade your dbt version](https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-version-in-cloud) to dbt v1.6 or higher and [migrate](https://docs.getdbt.com/guides/sl-migration) to the latest Semantic Layer. dbt Labs is thrilled to announce that the [dbt Semantic Layer](https://docs.getdbt.com/docs/use-dbt-semantic-layer/dbt-sl) is now generally available. It offers consistent data organization, improved governance, reduced costs, enhanced efficiency, and accessible data for better decision-making and collaboration across organizations. It aims to bring the best of modeling and semantics to downstream applications by introducing: * Brand new [integrations](https://docs.getdbt.com/docs/cloud-integrations/avail-sl-integrations) such as Tableau, Google Sheets, Hex, Mode, and Lightdash. * New [Semantic Layer APIs](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-api-overview) using GraphQL and JDBC to query metrics and build integrations. * dbt Cloud [multi-tenant regional](https://docs.getdbt.com/docs/cloud/about-cloud/access-regions-ip-addresses) support for North America, EMEA, and APAC. Single-tenant support coming soon. * Coming soon — Schedule exports (a way to build tables in your data platform) as part of your dbt Cloud job. Use the APIs to call an export, then access them in your preferred BI tool. [![Use the universal dbt Semantic Layer to define and queried metrics in integration tools.](https://docs.getdbt.com/img/docs/dbt-cloud/semantic-layer/sl-architecture.jpg?v=2 "Use the universal dbt Semantic Layer to define and queried metrics in integration tools.")](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#) Use the universal dbt Semantic Layer to define and queried metrics in integration tools. The dbt Semantic Layer is available to [dbt Cloud Team or Enterprise](https://www.getdbt.com/) multi-tenant plans on dbt v1.6 or higher. * Team and Enterprise customers can use 1,000 Queried Metrics per month for no additional cost on a limited trial basis, subject to reasonable use limitations. Refer to [Billing](https://docs.getdbt.com/docs/cloud/billing#what-counts-as-a-queried-metric) for more information. * dbt Developer plans and dbt Core users can define metrics but won't be able to query them with integrated tools. September 2023[​](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#september-2023 "Direct link to September 2023") ------------------------------------------------------------------------------------------------------------------------------- *  CI updates dbt Cloud now has two distinct job types: [deploy jobs](https://docs.getdbt.com/docs/deploy/deploy-jobs) for building production data assets, and [continuous integration (CI) jobs](https://docs.getdbt.com/docs/deploy/ci-jobs) for checking code changes. These jobs perform fundamentally different tasks so dbt Labs improved the setup experience with better defaults for each. With two types of jobs, instead of one generic type, we can better guide you through the setup flow. Best practices are built into the default settings so you can go from curious to being set up in seconds. [![Example of setting up a CI job](https://docs.getdbt.com/img/docs/release-notes/ci-job-setup.gif?v=2 "Example of setting up a CI job")](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#) Example of setting up a CI job And, we now have more efficient state comparisons on CI checks: never waste a build or test on code that hasn’t been changed. We now diff between the Git pull request (PR) code and what’s running in production more efficiently with the introduction of deferral to an environment versus a job. To learn more, refer to [Continuous integration in dbt](https://docs.getdbt.com/docs/deploy/continuous-integration) . Below is a comparison table that describes how deploy jobs and CI jobs behave differently: | | Deploy Jobs | CI Jobs | | --- | --- | --- | | Purpose | Builds production data assets. | Builds and tests new code before merging changes into production. | | Trigger types | Triggered by a schedule or by API. | Triggered by a commit to a PR or by API. | | Destination | Builds into a production database and schema. | Builds into a staging database and ephemeral schema, lived for the lifetime of the PR. | | Execution mode | Runs execute sequentially, so as to not have collisions on the underlying DAG. | Runs execute in parallel to promote team velocity. | | Efficiency run savings | Detects over-scheduled jobs and cancels unnecessary runs to avoid queue clog. | Cancels existing runs when a newer commit is pushed to avoid redundant work. | | State comparison | Only sometimes needs to detect state. | Almost always needs to compare state against the production environment to build on modified code and its dependents. | What you need to update[​](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#what-you-need-to-update "Direct link to What you need to update") ---------------------------------------------------------------------------------------------------------------------------------------------------------- * If you want to set up a CI environment for your jobs, dbt Labs recommends that you create your CI job in a dedicated [deployment environment](https://docs.getdbt.com/docs/deploy/deploy-environments#create-a-deployment-environment) that's connected to a staging database. To learn more about these environment best practices, refer to the guide [Get started with continuous integration tests](https://docs.getdbt.com/guides/set-up-ci) . * If you had set up a CI job before October 2, 2023, the job might've been misclassified as a deploy job with this update. Below describes how to fix the job type: If you used the [Create Job](https://docs.getdbt.com/dbt-cloud/api-v2#/operations/Create%20Job) API endpoint but didn't set `"triggers":triggers.git_provider_webhook`, the job was misclassified as a deploy job and you must re-create it as described in [Trigger a CI job with the API](https://docs.getdbt.com/docs/deploy/ci-jobs#trigger-a-ci-job-with-the-api) . If you used the dbt UI but didn't enable the **Run on Pull Requests** option that was in the **Continuous Integration** (CI) tab, the job was misclassified as a deploy job and you must re-create it as described in [Set up CI jobs](https://docs.getdbt.com/docs/deploy/ci-jobs#set-up-ci-jobs) . To check for the job type, review your CI jobs in dbt's [Run History](https://docs.getdbt.com/docs/deploy/run-visibility#run-history) and check for the **CI Job** tag below the job name. If it doesn't have this tag, it was misclassified and you need to re-create the job. [![Example of a correct CI job type](https://docs.getdbt.com/img/docs/release-notes/ci-job-tag.png?v=2 "Example of a correct CI job type")](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#) Example of a correct CI job type **CI update phase 3 — Update: Improved automatic deletion of temporary schemas** Temporary schemas are now being automatically deleted (dropped) for all adapters (like Databricks), PrivateLink connections, and environment variables in connection strings. dbt Labs has rearchitected how schema deletion works for [continuous integration (CI)](https://docs.getdbt.com/docs/deploy/continuous-integration) runs. We created a new service to delete any schema with a prefix of `dbt_cloud_pr_` that's been generated by a PR run. However, temporary schemas will not be automatically deleted if: * Your project overrides the [generate\_schema\_name macro](https://docs.getdbt.com/docs/build/custom-schemas) but it doesn't contain the required prefix `dbt_cloud_pr_`. For details, refer to [Troubleshooting](https://docs.getdbt.com/docs/deploy/ci-jobs#troubleshooting) . * You're using a [non-native Git integration](https://docs.getdbt.com/docs/deploy/ci-jobs#trigger-a-ci-job-with-the-api) . This is because automatic deletion relies on incoming webhooks from Git providers, which is only available through the native integrations. *  Product docs updates Hello from dbt's Product Documentation team (the stewards of the docs.getdbt.com site): @mirnawong1, @matthewshaver, @nghi-ly, and @runleonarun. What a busy summer! We merged 256 PRs between July 1st and August 31. We'd like to recognize all of the docs and support from our partner team, Developer Experience: @jasnonaz @gwenwindflower @dbeatty10 @dataders @joellabes @Jstein77 @dave-connors-3! We'd also like to give a special thanks to the 22 community members who contributed to the [dbt Product docs](https://docs.getdbt.com/) for the first time. 🙏 Based on feedback from the dbt community, we made these changes: * Added a [permissions table](https://docs.getdbt.com/docs/cloud/manage-access/enterprise-permissions) for Enterprise accounts * Added a [browser session page](https://docs.getdbt.com/docs/cloud/about-cloud/browsers#browser-sessions) that clarifies dbt Cloud’s browser session time and when it logs users off. You can provide feedback by opening a pull request or issue in [our repo](https://github.com/dbt-labs/docs.getdbt.com) or reaching out in the dbt community Slack channel [#dbt-product-docs](https://getdbt.slack.com/archives/C0441GSRU04) ). ⚡ General docs projects[​](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#zap-general-docs-projects "Direct link to zap-general-docs-projects") -------------------------------------------------------------------------------------------------------------------------------------------------------------- * Added the ability to collapse sections you’re not currently looking at. There were quite a few people who wanted this, and it bugged us too, so we were happy to get this shipped! * Introduced the idea of [“Trusted” adapters](https://docs.getdbt.com/docs/supported-data-platforms#types-of-adapters) . ☁ Cloud projects[​](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#cloud-projects-1 "Direct link to ☁ Cloud projects") ------------------------------------------------------------------------------------------------------------------------------------- * The **What’s new?** product update widget is back in the dbt Cloud UI! The Docs team will begin updating the content to keep you informed about new features. * Launched the re-released [Semantic Layer beta docs](https://docs.getdbt.com/docs/use-dbt-semantic-layer/dbt-sl) , which introduces users to the new API, new guide to set up MetricFlow and the new Semantic Layer, as well as revamp the ‘Use the dbt Semantic Layer’ section for users. * Updated [Admin API v2 and v3](https://docs.getdbt.com/docs/dbt-cloud-apis/admin-cloud-api) to help you understand the differences between them and which version includes the endpoints you use. * To improve discoverability, the docs team made changes to the [deploy dbt sidebar](https://docs.getdbt.com/docs/deploy/deployments) . We added cards and aligned better with the dbt Cloud UI and the way it’s used. * Deprecated legacy job schemas in the [Discovery API](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-api) . * Added a page to describe [experimental and beta features](https://docs.getdbt.com/docs/dbt-versions/experimental-features) in dbt Cloud and what you need to know about them. * Added a section to introduce a new beta feature [**Extended Attributes**](https://docs.getdbt.com/docs/dbt-cloud-environments#extended-attributes-beta) , which allows users to set a flexible `profiles.yml` snippet in their dbt Cloud Environment settings. 🎯 Core projects[​](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#core-projects-1 "Direct link to 🎯 Core projects") ------------------------------------------------------------------------------------------------------------------------------------ * We released [dbt 1.6](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.6) ! We added docs for the new commands `dbt retry` and `dbt clone` New 📚 Guides, ✏️ blog posts, and FAQs[​](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#newguides%EF%B8%8Fblog-posts-and-faqs-1 "Direct link to New 📚 Guides, ✏️ blog posts, and FAQs") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- * Check out how these community members use the dbt community in the [Community spotlight](https://docs.getdbt.com/community/spotlight) . * Blog posts published this summer include [Optimizing Materialized Views with dbt](https://docs.getdbt.com/blog/announcing-materialized-views) , [Data Vault 2.0 with dbt Cloud](https://docs.getdbt.com/blog/data-vault-with-dbt-cloud) , and [Create dbt Documentation and Tests 10x faster with ChatGPT](https://docs.getdbt.com/blog/create-dbt-documentation-10x-faster-with-ChatGPT) * We now have two new best practice guides: [How we build our metrics](https://docs.getdbt.com/best-practices/how-we-build-our-metrics/semantic-layer-1-intro) and [Set up Continuous Integration](https://docs.getdbt.com/guides/set-up-ci) . *  Removing prerelease versions Previously, when dbt Labs released a new [version](https://docs.getdbt.com/docs/dbt-versions/core#how-dbt-core-uses-semantic-versioning) in dbt Cloud, the older patch _prerelease_ version and the _latest_ version remained as options in the dropdown menu available in the **Environment settings**. Now, when the _latest_ version is released, the _prerelease_ version will be removed and all customers remaining on it will be migrated seamlessly. There will be no interruptions to service when this migration occurs. To see which version you are currently using and to upgrade, select **Deploy** in the top navigation bar and select **Environments**. Choose the preferred environment and click **Settings**. Click **Edit** to make a change to the current dbt version. dbt Labs recommends always using the latest version whenever possible to take advantage of new features and functionality. [![dbt Cloud versions dropdown](https://docs.getdbt.com/img/docs/release-notes/dbt-cloud-versions.png?v=2 "dbt Cloud versions dropdown")](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#) dbt Cloud versions dropdown August 2023[​](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#august-2023 "Direct link to August 2023") ---------------------------------------------------------------------------------------------------------------------- *  Deprecation of endpoints in the Discovery API dbt Labs has deprecated and will be deprecating certain query patterns and replacing them with new conventions to enhance the performance of the dbt Cloud [Discovery API](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-api) . All these changes will be in effect on _September 7, 2023_. We understand that these changes might require adjustments to your existing integration with the Discovery API. Please [contact us](mailto:support@getdbt.com) with any questions. We're here to help you during this transition period. Job-based queries[​](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#job-based-queries "Direct link to Job-based queries") ---------------------------------------------------------------------------------------------------------------------------------------- Job-based queries that use the data type `Int` for IDs will be deprecated. They will be marked as deprecated in the [GraphQL explorer](https://metadata.cloud.getdbt.com/graphql) . The new convention will be for you to use the data type `BigInt` instead. This change will be in effect starting September 7, 2023. Example of query before deprecation: query ($jobId: Int!) {models(jobId: $jobId){ uniqueId}} Example of query after deprecation: query ($jobId: BigInt!) {job(id: $jobId) { models { uniqueId }}} modelByEnvironment queries[​](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#modelbyenvironment-queries "Direct link to modelByEnvironment queries") ------------------------------------------------------------------------------------------------------------------------------------------------------------------- The `modelByEnvironment` object has been renamed and moved into the `environment` object. This change is in effect and has been since August 15, 2023. Example of query before deprecation: query ($environmentId: Int!, $uniqueId: String) {modelByEnvironment(environmentId: $environmentId, uniqueId: $uniqueId) { uniqueId executionTime executeCompletedAt}} Example of query after deprecation: query ($environmentId: BigInt!, $uniqueId: String) {environment(id: $environmentId) { applied { modelHistoricalRuns(uniqueId: $uniqueId) { uniqueId executionTime executeCompletedAt } }}} Environment and account queries[​](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#environment-and-account-queries "Direct link to Environment and account queries") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Environment and account queries that use `Int` as a data type for ID have been deprecated. IDs must now be in `BigInt`. This change is in effect and has been since August 15, 2023. Example of query before deprecation: query ($environmentId: Int!, $first: Int!) {environment(id: $environmentId) { applied { models(first: $first) { edges { node { uniqueId executionInfo { lastRunId } } } } }}} Example of query after deprecation: query ($environmentId: BigInt!, $first: Int!) {environment(id: $environmentId) { applied { models(first: $first) { edges { node { uniqueId executionInfo { lastRunId } } } } }}} *  dbt Cloud IDE v1.2 We're excited to announce that we replaced the backend service that powers the Cloud IDE with a more reliable server -- dbt-server. Because this release contains foundational changes, IDE v1.2 requires dbt v1.6 or higher. This significant update follows the rebuild of the IDE frontend last year. We're committed to improving the IDE to provide you with a better experience. Previously, the Cloud IDE used dbt-rpc, an outdated service that was unable to stay up-to-date with changes from dbt-core. The dbt-rpc integration used legacy dbt-core entry points and logging systems, causing it to be sluggish, brittle, and poorly tested. The Core team had been working around this outdated technology to avoid breaking it, which prevented them from developing with velocity and confidence. New features[​](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#new-features "Direct link to New features") ------------------------------------------------------------------------------------------------------------------------- * **Better dbt-core parity:** The Cloud IDE has better command parity with dbt-core, including support for commands like `dbt list` and improved treatment of flags like `--vars`, `--fail-fast`, etc. * **Improved maintainability:** With the new dbt-server, it's easier to fix bugs and improve the overall quality of the product. With dbt-rpc, fixing bugs was a time-consuming and challenging process that required extensive testing. With the new service, we can identify and fix bugs more quickly, resulting in a more stable and reliable IDE. * **A more reliable service:** Simplified architecture that's less prone to failure. ### Product refinements[​](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#product-refinements "Direct link to Product refinements") * Improved `Preview` capabilities with Core v1.6 + IDE v1.2. [This Loom](https://www.loom.com/share/12838feb77bf463c8585fc1fc6aa161b) provides more information. ### Bug fixes[​](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#bug-fixes-1 "Direct link to Bug fixes") * Global page can become "inert" and stop handling clicks * Switching back and forth between files in the git diff view can cause overwrite * Browser gets stuck during markdown preview for doc with large table * Editor right click menu is offset * Unable to Cancel on the Save New File component when Closing All Files in the IDE * Mouse flicker in the modal's file tree makes it difficult to select a folder where you want to save a new file * Snapshots not showing in Lineage when inside a subfolder and is mixed cased named * Tooltips do not work for Format and Save * When a dbt invocation is in progress or if parsing is ongoing, attempting to switch branches will cause the `Git Branch` dropdown to close automatically ### Known issues[​](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#known-issues "Direct link to Known issues") * `{{this}}` function does not display properly in preview/compile with dbt-server July 2023[​](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#july-2023 "Direct link to July 2023") ---------------------------------------------------------------------------------------------------------------- *  Faster runs and unlimited job concurrency for Enterprise account We’ve introduced significant improvements to the dbt Cloud Scheduler, offering improved performance, durability, and scalability. Read more on how you can experience faster run start execution and how enterprise users can now run as many jobs concurrently as they want to. Faster run starts[​](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#faster-run-starts "Direct link to Faster run starts") ---------------------------------------------------------------------------------------------------------------------------------------- The Scheduler takes care of preparing each dbt Cloud job to run in your cloud data platform. This [prep](https://docs.getdbt.com/docs/deploy/job-scheduler#scheduler-queue) involves readying a Kubernetes pod with the right version of dbt installed, setting environment variables, loading data platform credentials, and git provider authorization, amongst other environment-setting tasks. Only after the environment is set up, can dbt execution begin. We display this time to the user in dbt Cloud as “prep time”. [![The scheduler prepares a job for execution and displays it as 'prep time' in dbt Cloud.](https://docs.getdbt.com/img/run-start.jpg?v=2 "The scheduler prepares a job for execution and displays it as 'prep time' in dbt Cloud.")](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#) The scheduler prepares a job for execution and displays it as 'prep time' in dbt Cloud. For all its strengths, Kubernetes has challenges, especially with pod management impacting run execution time. We’ve rebuilt our scheduler by ensuring faster job execution with a ready pool of pods to execute customers’ jobs. This means you won't experience long prep times at the top of the hour, and we’re determined to keep runs starting near instantaneously. Don’t just take our word, review the data yourself. [![Job prep time data has seen a 75% speed improvement from Jan 2023 to July 2023. Prep time took 106 secs in Jan and now takes 27 secs as of July.](https://docs.getdbt.com/img/prep-start.jpg?v=2 "Job prep time data has seen a 75% speed improvement from Jan 2023 to July 2023. Prep time took 106 secs in Jan and now takes 27 secs as of July.")](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#) Job prep time data has seen a 75% speed improvement from Jan 2023 to July 2023. Prep time took 106 secs in Jan and now takes 27 secs as of July. Jobs scheduled at the top of the hour used to take over 106 seconds to prepare because of the volume of runs the scheduler has to process. Now, even with increased runs, we have reduced prep time to 27 secs (at a maximum) — a 75% speed improvement for runs at peak traffic times! Unlimited job concurrency for Enterprise accounts[​](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#unlimited-job-concurrency-for-enterprise-accounts "Direct link to Unlimited job concurrency for Enterprise accounts") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- Our enhanced scheduler offers more durability and empowers users to run jobs effortlessly. This means Enterprise, multi-tenant accounts can now enjoy the advantages of unlimited job concurrency. Previously limited to a fixed number of run slots, Enterprise accounts now have the freedom to operate without constraints. Single-tenant support will be coming soon. Something to note, each running job occupies a run slot for its duration, and if all slots are occupied, jobs will queue accordingly. For more feature details, refer to the [dbt pricing page](https://www.getdbt.com/pricing/) . Note, Team accounts created after July 2023 benefit from unlimited job concurrency: * Legacy Team accounts have a fixed number of run slots. * Both Team and Developer plans are limited to one project each. For larger-scale needs, our [Enterprise plan](https://www.getdbt.com/pricing/) offers features such as audit logging, unlimited job concurrency and projects, and more. June 2023[​](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#june-2023 "Direct link to June 2023") ---------------------------------------------------------------------------------------------------------------- *  Lint format dbt Labs is excited to announce you can now lint and format your dbt code in the dbt Cloud IDE. This is an enhanced development workflow which empowers you to effortlessly prioritize code quality. You can perform linting and formatting on five different file types: SQL, YAML, Markdown, Python, and JSON. For SQL files, you can easily lint and format your code using [SQLFluff](https://sqlfluff.com/) and apply consistent formatting using [sqlfmt](http://sqlfmt.com/) . Additionally, for other file types like YAML, Markdown, JSON, and Python, you can utilize the respective tools powered by [Prettier](https://prettier.io/) and [Black](https://black.readthedocs.io/en/latest/) to ensure clean and standardized code formatting. For more info, read [Lint and format your code](https://docs.getdbt.com/docs/cloud/dbt-cloud-ide/lint-format) . [![Use SQLFluff to lint/format your SQL code, and view code errors in the Code Quality tab.](https://docs.getdbt.com/img/docs/dbt-cloud/cloud-ide/sqlfluff.gif?v=2 "Use SQLFluff to lint/format your SQL code, and view code errors in the Code Quality tab.")](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#) Use SQLFluff to lint/format your SQL code, and view code errors in the Code Quality tab. [![Use sqlfmt to format your SQL code.](https://docs.getdbt.com/img/docs/dbt-cloud/cloud-ide/sqlfmt.gif?v=2 "Use sqlfmt to format your SQL code.")](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#) Use sqlfmt to format your SQL code. [![Format YAML, Markdown, and JSON files using Prettier.](https://docs.getdbt.com/img/docs/dbt-cloud/cloud-ide/prettier.gif?v=2 "Format YAML, Markdown, and JSON files using Prettier.")](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#) Format YAML, Markdown, and JSON files using Prettier. *  CI updates dbt Cloud CI is a critical part of the analytics engineering workflow. Large teams rely on process to ensure code quality is high, and they look to dbt Cloud CI to automate testing code changes in an efficient way, enabling speed while keep the bar high. With status checks directly posted to their dbt PRs, developers gain the confidence that their code changes will work as expected in production, and once you’ve grown accustomed to seeing that green status check in your PR, you won’t be able to work any other way. [![CI checks directly from within Git](https://docs.getdbt.com/img/docs/release-notes/ci-checks.png?v=2 "CI checks directly from within Git")](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#) CI checks directly from within Git What separates dbt CI from other CI providers is its ability to keep track of state of what’s running in your production environment, so that when you run a CI job, only the modified data assets in your pull request and their downstream dependencies get built and tested in a staging schema. dbt aims to make each CI check as efficient as possible, so as to not waste any data warehouse resources. As soon as the CI run completes, its status posts directly back to the PR in GitHub, GitLab, or Azure DevOps, depending on which Git provider you’re using. Teams can set up guardrails to let only PRs with successful CI checks be approved for merging, and the peer review process is greatly streamlined because dbt does the first testing pass. We're excited to introduce a few critical capabilities to dbt CI that will improve productivity and collaboration in your team’s testing and integration workflow. As of this week, you can now: * **Run multiple CI checks in parallel**. If more than one contributor makes changes to the same dbt project in dbt Cloud in short succession, the later arriving CI check no longer has to wait for the first check to complete. Both checks will execute concurrently. * **Automatically cancel stale CI runs**. If you push multiple commits to the same PR, dbt will cancel older, now-out-of-date CI checks automatically. No resources wasted on checking stale code. * **Run CI checks without blocking production runs**. CI checks will no longer consume run slots, meaning you can have as many CI checks running as you want, without impeding your production jobs. To learn more, refer to [Continuous integration](https://docs.getdbt.com/docs/deploy/continuous-integration) and [CI jobs](https://docs.getdbt.com/docs/deploy/ci-jobs) . *  Admin API dbt Labs updated the docs for the [dbt Cloud Administrative API](https://docs.getdbt.com/docs/dbt-cloud-apis/admin-cloud-api) and they are now available for both [v2](https://docs.getdbt.com/dbt-cloud/api-v2#/) and [v3](https://docs.getdbt.com/dbt-cloud/api-v3#/) . * Now using Spotlight for improved UI and UX. * All endpoints are now documented for v2 and v3. Added automation to the docs so they remain up to date. * Documented many of the request and response bodies. * You can now test endpoints directly from within the API docs. And, you can choose which [regional server](https://docs.getdbt.com/docs/cloud/about-cloud/access-regions-ip-addresses) to use (North America, APAC, or EMEA). * With the new UI, you can more easily generate code for any endpoint. *  Product docs updates Hello from the dbt Docs team: @mirnawong1, @matthewshaver, @nghi-ly, and @runleonarun! First, we’d like to thank the 17 new community contributors to docs.getdbt.com — ✨ @aaronbini, @sjaureguimodo, @aranke, @eiof, @tlochner95, @mani-dbt, @iamtodor, @monilondo, @vrfn, @raginjason, @AndrewRTsao, @MitchellBarker, @ajaythomas, @smitsrr, @leoguyaux, @GideonShils, @michaelmherrera! Here's what's new to [docs.getdbt.com](http://docs.getdbt.com/) in June: ☁ Cloud projects[​](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#cloud-projects-2 "Direct link to ☁ Cloud projects") ------------------------------------------------------------------------------------------------------------------------------------- * We clarified the nuances of [CI and CI jobs](https://docs.getdbt.com/docs/deploy/continuous-integration) , updated the [Scheduler content](https://docs.getdbt.com/docs/deploy/job-scheduler) , added two new pages for the job settings and run visibility, moved the project state page to the [Syntax page](https://docs.getdbt.com/reference/node-selection/syntax) , and provided a landing page for [Deploying with Cloud](https://docs.getdbt.com/docs/deploy/jobs) to help readers navigate the content better. * We reformatted the [Supported data platforms page](https://docs.getdbt.com/docs/supported-data-platforms) by adding dbt Cloud to the page, splitting it into multiple pages, using cards to display verified adapters, and moving the [Warehouse setup pages](https://docs.getdbt.com/docs/core/connect-data-platform/about-core-connections) to the Docs section. * We launched a new [Lint and format page](https://docs.getdbt.com/docs/cloud/dbt-cloud-ide/lint-format) , which highlights the awesome new dbt Cloud IDE linting/formatting function. * We enabled a connection between [dbt Cloud release notes](https://docs.getdbt.com/docs/dbt-versions/dbt-cloud-release-notes) and the dbt Slack community. This means new dbt Cloud release notes are automatically sent to the slack community [#dbt-cloud channel](https://getdbt.slack.com/archives/CMZ2V0X8V) via RSS feed, keeping users up to date with changes that may affect them. * We’ve added two new docs links in the dbt Cloud Job settings user interface (UI). This will provide additional guidance and help users succeed when setting up a dbt Cloud job: [job commands](https://docs.getdbt.com/docs/deploy/job-commands) and job triggers. * We added information related to the newly created [IT license](https://docs.getdbt.com/docs/cloud/manage-access/about-user-access#license-based-access-control) , available for Team and Enterprise plans. * We added a new [Supported browser page](https://docs.getdbt.com/docs/cloud/about-cloud/browsers) , which lists the recommended browsers for dbt Cloud. * We launched a new page informing users of [new Experimental features option](https://docs.getdbt.com/docs/dbt-versions/experimental-features) in dbt Cloud. * We worked with dbt Engineering to help publish new beta versions of the dbt [dbt Cloud Administrative API docs](https://docs.getdbt.com/docs/dbt-cloud-apis/admin-cloud-api) . 🎯 Core projects[​](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#core-projects-2 "Direct link to 🎯 Core projects") ------------------------------------------------------------------------------------------------------------------------------------ * We launched the new [MetricFlow docs](https://docs.getdbt.com/docs/build/build-metrics-intro) on dbt Core v1.6 beta. * Split [Global configs](https://docs.getdbt.com/reference/global-configs/about-global-configs) into individual pages, making it easier to find, especially using search. New 📚 Guides, ✏️ blog posts, and FAQs[​](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#newguides%EF%B8%8Fblog-posts-and-faqs-2 "Direct link to New 📚 Guides, ✏️ blog posts, and FAQs") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- * Add an Azure DevOps example in the [Customizing CI/CD with custom pipelines](https://docs.getdbt.com/guides/custom-cicd-pipelines) guide. May 2023[​](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#may-2023 "Direct link to May 2023") ------------------------------------------------------------------------------------------------------------- *  dbt Cloud IDE To continue improving your [Cloud IDE](https://docs.getdbt.com/docs/cloud/dbt-cloud-ide/develop-in-the-cloud) development experience, the dbt Labs team continues to work on adding new features, fixing bugs, and increasing reliability ✨. Stay up-to-date with [IDE-related changes](https://docs.getdbt.com/tags/ide) . New features[​](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#new-features-1 "Direct link to New features") --------------------------------------------------------------------------------------------------------------------------- * Lint via SQL Fluff is now available in beta (GA over the next 2-3 weeks) * Format markdown files with prettier * Leverage developer experience shortcuts, including `` Ctrl + ` `` (toggle history drawer), `CMD + Option + /` (toggle block comment), `CMD + Shift + P` (open command palette), `Option + W` (close editor tab) * Display parent folder name for files with same name in Changes section * Navigate the new IDE features quickly using [the IDE User Interface](https://docs.getdbt.com/docs/cloud/dbt-cloud-ide/ide-user-interface) help page * Use `top X` in SQL when previewing in the IDE * Opt into the new IDE backend layer over the past month (still with dbt-rpc). Ready for beta later in June! Product refinements[​](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#product-refinements-1 "Direct link to Product refinements") ------------------------------------------------------------------------------------------------------------------------------------------------ * Performance-related upgrades: * Reduced cold start time by 60+% * Improved render time of modals in the IDE by 98% * Improved IDE performance with dbt Core v1.5+ (faster and snappier – highly encourage you to [upgrade your dbt version](https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-version-in-cloud) !) * Upgraded sqlfmt (which powers the Format button) to 0.18.0 * Updated Build button to change menu options based on file/model type (snapshot, macro, etc.) * Display message to disable adblocker for file contents error * Moved Format button to console bar * Made many security enhancements in the IDE Bug fixes[​](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#bug-fixes-2 "Direct link to Bug fixes") ------------------------------------------------------------------------------------------------------------------ * File icon sizes no longer get wonky in small screen * Toast notifications no longer take over command bar menu * Hover info inside the text editor no longer gets cut off * Transition between a file and a recently modified scratchpad no longer triggers a console error * dbt v1.5+ now can access the IDE * Confirm button on the Unsaved Changes modal now closes after clicking it * Long node names no longer overflow in the parsed logs section in history drawer * Status pill in history drawer no longer scales with longer command * Tooltip for tab name with a long file name is no longer cut off * Lint button should no longer available in main branch *  Run history improvements New usability and design improvements to the **Run History** dashboard in dbt Cloud are now available. These updates allow people to discover the information they need more easily by reducing the number of clicks, surfacing more relevant information, keeping people in flow state, and designing the look and feel to be more intuitive to use. [![Improvements to Run History in dbt Cloud](https://docs.getdbt.com/img/docs/release-notes/run-history-improvements.gif?v=2 "Improvements to Run History in dbt Cloud")](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#) Improvements to Run History in dbt Cloud Highlights include: * Usability improvements for CI runs with hyperlinks to the branch, PR, and commit SHA, along with more discoverable temporary schema names * Preview of runs' error messages on hover * Hyperlinks to the environment * Better iconography on run status * Clearer run trigger cause (API, scheduled, pull request, triggered by user) * More details on the schedule time on hover * Run timeout visibility dbt Labs is making a change to the metadata retrieval policy for Run History in dbt Cloud. **Beginning June 1, 2023,** developers on the dbt multi-tenant application will be able to self-serve access to their account’s run history through the dbt user interface (UI) and API for only 365 days, on a rolling basis. Older run history will be available for download by reaching out to Customer Support. We're seeking to minimize the amount of metadata we store while maximizing application performance. Specifically, all `GET` requests to the dbt Cloud [Runs endpoint](https://docs.getdbt.com/dbt-cloud/api-v2#/operations/List%20Runs) will return information on runs, artifacts, logs, and run steps only for the past 365 days. Additionally, the run history displayed in the dbt Cloud UI will only show runs for the past 365 days. [![The dbt Cloud UI displaying a Run History](https://docs.getdbt.com/img/docs/dbt-cloud/rn-run-history.jpg?v=2 "The dbt Cloud UI displaying a Run History")](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#) The dbt Cloud UI displaying a Run History We will retain older run history in cold storage and can make it available to customers who reach out to our Support team. To request older run history info, contact the Support team at [support@getdbt.com](mailto:support@getdbt.com) or use the dbt Cloud application chat by clicking the `?` icon in the dbt Cloud UI. *  Run details and log improvements New usability and design improvements to the run details and logs in dbt Cloud are now available. The ability to triage errors in logs is a big benefit of using dbt Cloud's job and scheduler functionality. The updates help make the process of finding the root cause much easier. Highlights include: * Surfacing a warn state on a run step * Search in logs * Easier discoverability of errors and warnings in logs * Lazy loading of logs, making the whole run details page load faster and feel more performant * Cleaner look and feel with iconography * Helpful tool tips [![Improvements to run details and logs in dbt Cloud](https://docs.getdbt.com/img/docs/release-notes/run-details-and-logs-improvements.gif?v=2 "Improvements to run details and logs in dbt Cloud")](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#) Improvements to run details and logs in dbt Cloud *  Product docs updates Hello from the dbt Docs team: @mirnawong1, @matthewshaver, @nghi-ly, and @runleonarun! First, we’d like to thank the 13 new community contributors to docs.getdbt.com! Here's what's new to [docs.getdbt.com](http://docs.getdbt.com/) in May: 🔎 Discoverability[​](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#-discoverability "Direct link to 🔎 Discoverability") ----------------------------------------------------------------------------------------------------------------------------------------- * We made sure everyone knows that Cloud-users don’t need a [profiles.yml file](https://docs.getdbt.com/docs/core/connect-data-platform/profiles.yml) by adding a callout on several key pages. * Fleshed out the [model Jinja variable page](https://docs.getdbt.com/reference/dbt-jinja-functions/model) , which originally lacked conceptual info and didn’t link to the schema page. * Added a new [Quickstarts landing page](https://docs.getdbt.com/guides) . This new format sets up for future iterations that will include filtering! But for now, we are excited you can step through quickstarts in a focused way. Cloud projects[​](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#cloud-projects-3 "Direct link to Cloud projects") --------------------------------------------------------------------------------------------------------------------------------- * We launched [dbt Cloud IDE user interface doc](https://docs.getdbt.com/docs/cloud/dbt-cloud-ide/ide-user-interface) , which provides a thorough walkthrough of the IDE UI elements and their definitions. * Launched a sparkling new [dbt Cloud Scheduler page](https://docs.getdbt.com/docs/deploy/job-scheduler)  ✨! We went from previously having little content around the scheduler to a subsection that breaks down the awesome scheduler features and how it works. * Updated the [dbt Cloud user license page](https://docs.getdbt.com/docs/cloud/manage-access/seats-and-users#licenses) to clarify how to add or remove cloud users. * Shipped these Discovery API docs to coincide with the launch of the Discovery API: * [About the Discovery API](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-api) * [Use cases and examples for the Discovery API](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-use-cases-and-examples) * [Query the Discovery API](https://docs.getdbt.com/docs/dbt-cloud-apis/discovery-querying) 🎯 Core projects[​](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#core-projects-3 "Direct link to 🎯 Core projects") ------------------------------------------------------------------------------------------------------------------------------------ * See what’s coming up [in Core v 1.6](https://github.com/dbt-labs/docs.getdbt.com/issues?q=is%3Aissue+label%3A%22dbt-core+v1.6%22) ! * We turned the `profiles.yml` [page](https://docs.getdbt.com/docs/core/connect-data-platform/profiles.yml) into a landing page, added more context to profile.yml page, and moved the ‘About CLI’ higher up in the `Set up dbt` section. New 📚 Guides, ✏️ blog posts, and FAQs[​](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#newguides%EF%B8%8Fblog-posts-and-faqs-3 "Direct link to New 📚 Guides, ✏️ blog posts, and FAQs") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- If you want to contribute to a blog post, we’re focusing on content * Published a blog post: [Accelerate your documentation workflow: Generate docs for whole folders at once](https://docs.getdbt.com/blog/generating-dynamic-docs-dbt) * Published a blog post: [Data engineers + dbt v1.5: Evolving the craft for scale](https://docs.getdbt.com/blog/evolving-data-engineer-craft) * Added an [FAQ](https://docs.getdbt.com/faqs/Warehouse/db-connection-dbt-compile) to clarify the common question users have on _Why does dbt compile needs to connect to the database?_ * Published a [discourse article](https://discourse.getdbt.com/t/how-to-configure-external-user-email-notifications-in-dbt-cloud/8393) about configuring job notifications for non-dbt Cloud users April 2023[​](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#april-2023 "Direct link to April 2023") ------------------------------------------------------------------------------------------------------------------- *  dbt Cloud IDE New features[​](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#new-features-2 "Direct link to New features") --------------------------------------------------------------------------------------------------------------------------- * New warning message suggests you invoke `dbt deps` when it's needed (as informed by `dbt-score`). * New warning message appears when you select models but don't save them before clicking **Build** or invoking dbt (like, dbt build/run/test). * Previews of Markdown and CSV files are now available in the IDE console. * The file tree menu now includes a Duplicate File option. * Display loading time when previewing a model Product refinements[​](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#product-refinements-2 "Direct link to Product refinements") ------------------------------------------------------------------------------------------------------------------------------------------------ * Enhance autocomplete experience which has performed slowly for people with large projects and who implement a limit to max `manifest.json` for this feature * Introduce pagination for invocation node summary view (displaying 100 nodes at a time) * Improve rendering for the Changes / Version Control section of the IDE * Update icons to be consistent in dbt Cloud * Add table support to the Markdown preview * Add the lineage tab back to seed resources in the IDE * Implement modal priority when there are multiple warning modals * Improve a complex command's description in the command palette Bug fixes[​](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#bug-fixes-3 "Direct link to Bug fixes") ------------------------------------------------------------------------------------------------------------------ * File tree no longer collapses on first click when there's a project subdirectory defined * **Revert all** button now works as expected * CSV preview no longer fails with only one column * Cursor and scroll bar location are now persistent with their positions * `git diff` view now shows just change diffs and no longer shows full diff (as if file is new) until page refreshes * ToggleMinimap Command no longer runs another Command at the same time * `git diff` view no longer shows infinite spins in specific scenarios (new file, etc.) * File contents no longer get mixed up when using diff view and one file has unsaved changes * YML lineage now renders model without tests (in dbt Core v1.5 and above) * Radio buttons for **Summary** and **Details** in the logs section now consistently update to show the accurate tab selection * IDE no longer throws the console error `Error: Illegal argument` and redirects to the `Something went wrong` page *  API updates Starting May 15, 2023, we will support only the following `order_by` functionality for the List Runs endpoint: * `id` and `-id` * `created_at` and `-created_at` * `finished_at` and `-finished_at` We recommend that you change your API requests to https:///api/v2/accounts/{accountId}/runs/ to use a supported `order_by` before this date. Access URLs dbt Cloud is hosted in multiple regions around the world, and each region has a different access URL. Users on Enterprise plans can choose to have their account hosted in any one of these regions. For a complete list of available dbt Cloud access URLs, refer to [Regions & IP addresses](https://docs.getdbt.com/docs/cloud/about-cloud/access-regions-ip-addresses) . For more info, refer to our [documentation](https://docs.getdbt.com/dbt-cloud/api-v2#/operations/List%20Runs) . *  Scheduler optimization The dbt Cloud Scheduler now prevents queue clog by canceling unnecessary runs of over-scheduled jobs. The duration of a job run tends to grow over time, usually caused by growing amounts of data in the warehouse. If the run duration becomes longer than the frequency of the job’s schedule, the queue will grow faster than the scheduler can process the job’s runs, leading to a runaway queue with runs that don’t need to be processed. Previously, when a job was in this over-scheduled state, the scheduler would stop queuing runs after 50 were already in the queue. This led to a poor user experience where the scheduler canceled runs indiscriminately. You’d have to log into dbt Cloud to manually cancel all the queued runs and change the job schedule to "unclog" the scheduler queue. Now, the dbt Cloud scheduler detects when a scheduled job is set to run too frequently and appropriately cancels runs that don’t need to be processed. Specifically, scheduled jobs can only ever have one run of the job in the queue, and if a more recent run gets queued, the early queued run will get canceled with a helpful error message. Users will still need to either refactor the job so it runs faster or change the job schedule to run less often if the job often gets into an over-scheduled state. *  Starburst adapter GA The Starburst (Trino compatible) connection is now generally available in dbt Cloud. This means you can now use dbt Cloud to connect with Starburst Galaxy, Starburst Enterprise, and self-hosted Trino. This feature is powered by the [`dbt-trino`](https://github.com/starburstdata/dbt-trino) adapter. To learn more, check out our Quickstart guide for [dbt Cloud and Starburst Galaxy](https://docs.getdbt.com/guides/starburst-galaxy) . *  Product docs updates Hello from the dbt Docs team: @mirnawong1, @matthewshaver, @nghi-ly, and @runleonarun! We want to share some highlights introduced to docs.getdbt.com in the last month: 🔎 Discoverability[​](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#-discoverability-1 "Direct link to 🔎 Discoverability") ------------------------------------------------------------------------------------------------------------------------------------------- * [API docs](https://docs.getdbt.com/docs/dbt-cloud-apis/overview)  now live in the left sidebar to improve discoverability. * [The deploy dbt jobs sidebar](https://docs.getdbt.com/docs/deploy/deployments)  has had a glow up 💅 that splits the ‘about deployment’ into two paths (deploy w dbt cloud and deploy w other tools), adds more info about the dbt cloud scheduler, its features, and how to create a job, adds ADF deployment guidance. We hope the changes improve the user experience and provide users with guidance when deploying with other tools. ☁ Cloud projects[​](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#cloud-projects-4 "Direct link to ☁ Cloud projects") ------------------------------------------------------------------------------------------------------------------------------------- * Added Starburst/Trino adapter docs, including: * [dbt Cloud quickstart guide](https://docs.getdbt.com/guides/starburst-galaxy) ,  * [connection page](https://docs.getdbt.com/docs/cloud/connect-data-platform/connect-starburst-trino) ,  * [set up page](https://docs.getdbt.com/docs/core/connect-data-platform/trino-setup) , and [config page](https://docs.getdbt.com/reference/resource-configs/trino-configs) . * Enhanced [dbt Cloud jobs page](https://docs.getdbt.com/docs/deploy/jobs)  and section to include conceptual info on the queue time, improvements made around it, and about failed jobs. * Check out the April dbt [Cloud release notes](https://docs.getdbt.com/docs/dbt-versions/dbt-cloud-release-notes) 🎯 Core projects[​](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#core-projects-4 "Direct link to 🎯 Core projects") ------------------------------------------------------------------------------------------------------------------------------------ * Clearer descriptions in the [Jinja functions page](https://docs.getdbt.com/reference/dbt-jinja-functions) , that improve content for each card.  * [1.5 Docs](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-v1.5)  have been released as a Release Candidate (RC)! * See the beautiful [work captured in Core v 1.5](https://github.com/dbt-labs/docs.getdbt.com/issues?q=is%3Aissue+label%3A%22dbt-core+v1.5%22+is%3Aclosed) . New 📚 Guides and ✏️ blog posts[​](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#newguides-and%EF%B8%8Fblog-posts "Direct link to New 📚 Guides and ✏️ blog posts") ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- * [Use Databricks workflows to run dbt Cloud jobs](https://docs.getdbt.com/guides/how-to-use-databricks-workflows-to-run-dbt-cloud-jobs) * [Refresh Tableau workbook with extracts after a job finishes](https://docs.getdbt.com/guides/zapier-refresh-tableau-workbook) * [dbt Python Snowpark workshop/tutorial](https://docs.getdbt.com/guides/dbt-python-snowpark) * [How to optimize and troubleshoot dbt Models on Databricks](https://docs.getdbt.com/guides/optimize-dbt-models-on-databricks) * [The missing guide to debug() in dbt](https://docs.getdbt.com/blog/guide-to-jinja-debug) * [dbt Squared: Leveraging dbt Core and dbt Cloud together at scale](https://docs.getdbt.com/blog/dbt-squared) * [Audit\_helper in dbt: Bringing data auditing to a higher level](https://docs.getdbt.com/blog/audit-helper-for-migration) March 2023[​](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#march-2023 "Direct link to March 2023") ------------------------------------------------------------------------------------------------------------------- *  dbt v1.0 deprecation dbt Cloud now requires dbt version 1.0 or later. As of March 1, 2023, we removed all instances of older dbt versions from dbt Cloud. Any environments or jobs configured with a dbt version lower than 1.0 were automatically updated to dbt v1.4, which is the latest minor version available on dbt Cloud. For more info on dbt versions, releases, and dbt Cloud support timeline, refer to [About dbt Core versions](https://docs.getdbt.com/docs/dbt-versions/core#latest-releases) . Refer to some additional info and resources to help you upgrade your dbt version: * [How to upgrade dbt without fear](https://docs.getdbt.com/blog/upgrade-dbt-without-fear) * [Upgrade Q&A on breaking changes](https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-version-in-cloud#upgrading-legacy-versions-under-10) * [Version migration guides](https://docs.getdbt.com/docs/dbt-versions/core-upgrade) *  dbt Cloud IDE To continue improving your [Cloud IDE](https://docs.getdbt.com/docs/cloud/dbt-cloud-ide/develop-in-the-cloud) development experience, the dbt Labs team continue to work on adding new features, fixing bugs, and increasing reliability ✨. Read more about the [upcoming improvements to the Cloud IDE](https://www.getdbt.com/blog/improvements-to-the-dbt-cloud-ide/) and stay up-to-date with [IDE-related changes](https://docs.getdbt.com/tags/ide) . New features[​](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#new-features-3 "Direct link to New features") --------------------------------------------------------------------------------------------------------------------------- * Commit and revert individual files under **Version Control**. * Use the [command palette](https://docs.getdbt.com/docs/cloud/dbt-cloud-ide/develop-in-the-cloud#cloud-ide-features) to invoke common complex dbt commands, such as resuming from the last failure. * Create PRs even when there are uncommitted changes (under the **git** dropdown). * The IDE will display more autocomplete suggestions when editing a YML file, powered by [dbt-jsonschema](https://github.com/dbt-labs/dbt-jsonschema) . * The file tree now has additional options in the right-click menu, such as Copy model as ref or Copy file path. * The DAG view has been adjusted to a default of `2+model+2`. * A lineage selector has been implemented in the DAG/lineage sub-tab. * Edit directly in the git diff view located in the right pane. * A warning message will now appear when users press Command-W/Control-W when there are unsaved changes. * A new onboarding flow guide is now available. Product refinements[​](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#product-refinements-3 "Direct link to Product refinements") ------------------------------------------------------------------------------------------------------------------------------------------------ * The DAG selector now uses `name` instead of `file_uri` to build selectors. * The DAG is now vertically centered under the new Selector Input element * sqlfmt has been upgraded to v0.17.0. * When the Format button fails, a toast notification will display a syntax error. * The editor now has the option to toggle minimap/word-wrap via right-click. * The history drawer displays elapsed time in real-time and s/m/h increments. * When deleting development environments, the delete modal will now warn users that any uncommitted changes will be lost. * The context for the Git button has been adjusted to show that it will link to an external site (such as GitHub or GitLab) when users create a pull request. Bug fixes[​](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#bug-fixes-4 "Direct link to Bug fixes") ------------------------------------------------------------------------------------------------------------------ * The IDE now displays an error message when the git repository is not reachable. Previously, it failed silently. * The kebab menu is now visible when the invocation history drawer is open. Previously, it wasn't showing. * DAGs are now updated/populated consistently. Previously, it occasionally failed. * The purple highlight for DAG selection is now consistent across files. Previously, it was inconsistent. * Users can now rename files back to their original name. Previously, this wasn't possible. * The link to the IDE from the project setup page has been corrected. * The IDE no longer has issues with single-space file names. * Adding invalid characters in the sub-directory config no longer causes the IDE to fail. * YML autocomplete triggers consistently now. Previously, it occasionally didn't trigger. * Reverting single files now reloads the file contents in the tab. Previously, it didn't reload. * The file tree no longer collapses on the first click when there is a project subdirectory defined. *  API updates To make the API more scalable and reliable, we've implemented a maximum limit of `100` for all API requests to our `list` endpoints. If API requests exceed the maximum limit parameter of `100`, a user will receive an API error message. This maximum limit applies to [multi-tenant instances](https://docs.getdbt.com/docs/cloud/about-cloud/access-regions-ip-addresses) only, and _does not_ apply to single tenant instances. Refer to the [Pagination](https://docs.getdbt.com/dbt-cloud/api-v2#/) section of the overview for more information on this change. Feb 2023[​](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#feb-2023 "Direct link to Feb 2023") ------------------------------------------------------------------------------------------------------------- *  Disable partial parsing in job commands You can now use the `--no-partial-parse` flag to disable partial parsing in your dbt Cloud job commands.  Previously, the [`--no-partial-parse` global config](https://docs.getdbt.com/reference/global-configs/parsing) was only available in dbt Core. For more information, refer to [partial parsing](https://docs.getdbt.com/reference/parsing#partial-parsing) . *  dbt Cloud IDE To continue improving our [Cloud IDE](https://docs.getdbt.com/docs/cloud/dbt-cloud-ide/develop-in-the-cloud) experience, the dbt Labs team worked on fixing bugs, increasing reliability, and adding new features ✨. Learn more about the [February changes](https://getdbt.slack.com/archives/C03SAHKKG2Z/p1677605383451109) . New features[​](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#new-features-4 "Direct link to New features") --------------------------------------------------------------------------------------------------------------------------- * Support for custom node colors in the IDE DAG visualization * Ref autocomplete includes models from seeds and snapshots * Prevent menus from getting cropped (git controls dropdown, file tree dropdown, build button, editor tab options) * Additional option to access the file menu by right-clicking on the files and folders in the file tree * Rename files by double-clicking on files in the file tree and the editor tabs * Right-clicking on file tabs has new options and will now open at your cursor instead of in the middle of the tab * The git branch name above **Version Control** links to the repo for specific git providers * Currently available for all [multi-tenant](https://docs.getdbt.com/docs/cloud/about-cloud/access-regions-ip-addresses) instances using GitHub or GitLab providers Product refinements[​](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#product-refinements-4 "Direct link to Product refinements") ------------------------------------------------------------------------------------------------------------------------------------------------ * Added an error modal for RPC parsing errors when users attempt to invoke dbt commands (preview, compile, or general dbt invocations) * Enabled syntax highlighting for Jinja expression and statement delimiters * Clarified and renamed the options under the **Build** button * Changed the term for RPC status from `Compiling` to `Parsing` to match dbt-core construct * Implemented a new File Tree component to improve render time by 60% * Disabled the Local Storage of File Tree to prevent users from running into max LocalStorage issue for large projects * Changed snapshot snippet template (`__snapshot`) to a select from source Bug fixes[​](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#bug-fixes-5 "Direct link to Bug fixes") ------------------------------------------------------------------------------------------------------------------ * You no longer have file contents carrying over when you switch to a different project that has the same file name * The preview max limit no longer allows you to override the maximum * You no longer encounter node statuses failing to update in the history drawer for those on version 1.4 core. (This is a partial fix that may be fully addressed by core version 1.5) * You can now use the **Copy File Name** option to copy up to the last dot, rather than the first dot * You can now use the `--no-partial-parse` flag to disable partial parsing in your dbt Cloud job commands.  * Previously, the [`--no-partial-parse` global config](https://docs.getdbt.com/reference/global-configs/parsing) was only available in dbt Core. For more information, refer to [partial parsing](https://docs.getdbt.com/reference/parsing#partial-parsing) . January 2023[​](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#january-2023 "Direct link to January 2023") ------------------------------------------------------------------------------------------------------------------------- *  dbt Cloud IDE In the spirit of continuing to improve our [Cloud IDE](https://docs.getdbt.com/docs/cloud/dbt-cloud-ide/develop-in-the-cloud) experience, the dbt Labs team worked on fixing bugs, increasing reliability, and adding new features ✨. Learn more about the [January changes](https://getdbt.slack.com/archives/C03SAHKKG2Z/p1675272600286119) and what's coming soon. New features[​](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#new-features-5 "Direct link to New features") --------------------------------------------------------------------------------------------------------------------------- * Improved syntax highlighting within the IDE for better Jinja-SQL combination (double quotes now show proper syntax highlight!) * Adjusted the routing URL for the IDE page and removed the `next` from the URL * Added a _new_ easter egg within the IDE 🐶🦆 Product refinements[​](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#product-refinements-5 "Direct link to Product refinements") ------------------------------------------------------------------------------------------------------------------------------------------------ * Performance improvements and reduced IDE slowness. The IDE should feel faster and snappier. * Reliability improvements – Improved error handling that previously put IDE in a bad state * Corrected the list of dropdown options for the Build button * Adjusted startup page duration * Added code snippets for `unique` and `not_null` tests for YAML files * Added code snippets for metrics based on environment dbt versions * Changed “commit and push” to “commit and sync” to better reflect the action * Improved error message when saving or renaming files to duplicate names Bug fixes[​](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#bug-fixes-6 "Direct link to Bug fixes") ------------------------------------------------------------------------------------------------------------------ * You no longer arbitrarily encounter an `RPC server got an unknown async ID` message * You can now see the build button dropdown, which had been hidden behind the placeholder DAG screen * You can now close toast notifications for command failure when the history drawer is open * You no longer encounter a `Something went wrong` message when previewing a model * You can now see repository status in the IDE, and the IDE finds the SSH folder * Scroll bars and download CSV no longer flicker within the preview pane Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [December 2023](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#december-2023) * [Bug fixes](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#bug-fixes) * [Improvements](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#improvements) * [Why this change?](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#why-this-change) * [Key changes and impact](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#key-changes-and-impact) * [Breaking changes and recommendations](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#breaking-changes-and-recommendations) * [Engage and support](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#engage-and-support) * [November 2023](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#november-2023) * [October 2023](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#october-2023) * [Azure DevOps](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#azure-devops) * [☁ Cloud projects](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#cloud-projects) * [🎯 Core projects](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#core-projects) * [New 📚 Guides, ✏️ blog posts, and FAQs](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#newguides%EF%B8%8Fblog-posts-and-faqs) * [Upcoming changes](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#upcoming-changes) * [September 2023](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#september-2023) * [What you need to update](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#what-you-need-to-update) * [⚡ General docs projects](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#zap-general-docs-projects) * [☁ Cloud projects](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#cloud-projects-1) * [🎯 Core projects](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#core-projects-1) * [New 📚 Guides, ✏️ blog posts, and FAQs](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#newguides%EF%B8%8Fblog-posts-and-faqs-1) * [August 2023](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#august-2023) * [Job-based queries](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#job-based-queries) * [modelByEnvironment queries](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#modelbyenvironment-queries) * [Environment and account queries](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#environment-and-account-queries) * [New features](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#new-features) * [Product refinements](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#product-refinements) * [Bug fixes](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#bug-fixes-1) * [Known issues](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#known-issues) * [July 2023](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#july-2023) * [Faster run starts](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#faster-run-starts) * [Unlimited job concurrency for Enterprise accounts](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#unlimited-job-concurrency-for-enterprise-accounts) * [June 2023](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#june-2023) * [☁ Cloud projects](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#cloud-projects-2) * [🎯 Core projects](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#core-projects-2) * [New 📚 Guides, ✏️ blog posts, and FAQs](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#newguides%EF%B8%8Fblog-posts-and-faqs-2) * [May 2023](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#may-2023) * [New features](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#new-features-1) * [Product refinements](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#product-refinements-1) * [Bug fixes](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#bug-fixes-2) * [🔎 Discoverability](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#-discoverability) * [Cloud projects](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#cloud-projects-3) * [🎯 Core projects](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#core-projects-3) * [New 📚 Guides, ✏️ blog posts, and FAQs](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#newguides%EF%B8%8Fblog-posts-and-faqs-3) * [April 2023](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#april-2023) * [New features](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#new-features-2) * [Product refinements](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#product-refinements-2) * [Bug fixes](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#bug-fixes-3) * [🔎 Discoverability](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#-discoverability-1) * [☁ Cloud projects](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#cloud-projects-4) * [🎯 Core projects](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#core-projects-4) * [New 📚 Guides and ✏️ blog posts](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#newguides-and%EF%B8%8Fblog-posts) * [March 2023](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#march-2023) * [New features](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#new-features-3) * [Product refinements](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#product-refinements-3) * [Bug fixes](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#bug-fixes-4) * [Feb 2023](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#feb-2023) * [New features](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#new-features-4) * [Product refinements](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#product-refinements-4) * [Bug fixes](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#bug-fixes-5) * [January 2023](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#january-2023) * [New features](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#new-features-5) * [Product refinements](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#product-refinements-5) * [Bug fixes](https://docs.getdbt.com/docs/dbt-versions/2023-release-notes#bug-fixes-6) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/dbt-versions/2023-release-notes.md) --- # 2024 dbt Cloud release notes | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/dbt-versions/2024-release-notes#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page dbt release notes for recent and historical changes. Release notes fall into one of the following categories: * **New:** New products and features * **Enhancement:** Performance improvements and feature enhancements * **Fix:** Bug and security fixes * **Behavior change:** A change to existing behavior that doesn't fit into the other categories, such as feature deprecations or changes to default settings Release notes are grouped by month for both multi-tenant and virtual private cloud (VPC)\* environments \* The official release date for this new format of release notes is May 15th, 2024. Historical release notes for prior dates may not reflect all available features released earlier this year or their tenancy availability. December 2024[​](https://docs.getdbt.com/docs/dbt-versions/2024-release-notes#december-2024 "Direct link to December 2024") ---------------------------------------------------------------------------------------------------------------------------- * **New**: Saved queries now support [tags](https://docs.getdbt.com/reference/resource-configs/tags) , which allow you to categorize your resources and filter them. Add tags to your [saved queries](https://docs.getdbt.com/docs/build/saved-queries) in the `semantic_model.yml` file or `dbt_project.yml` file. For example: dbt\_project.yml saved-queries: jaffle_shop: customer_order_metrics: +tags: order_metrics * **New**: [Dimensions](https://docs.getdbt.com/reference/resource-configs/meta) now support the `meta` config property in [dbt Cloud "Latest" release track](https://docs.getdbt.com/docs/dbt-versions/cloud-release-tracks) and from dbt Core 1.9. You can add metadata to your dimensions to provide additional context and information about the dimension. Refer to [meta](https://docs.getdbt.com/reference/resource-configs/meta) for more information. * **New**: [Downstream exposures](https://docs.getdbt.com/docs/cloud-integrations/downstream-exposures-tableau) are now generally available to dbt Enterprise plans. Downstream exposures integrate natively with Tableau (Power BI coming soon) and auto-generate downstream lineage in dbt Explorer for a richer experience. * **New**: The Semantic Layer supports Sigma as a [partner integration](https://docs.getdbt.com/docs/cloud-integrations/avail-sl-integrations) , available in Preview. Refer to [Sigma](https://help.sigmacomputing.com/docs/configure-a-dbt-semantic-layer-integration) for more information. * **New**: The Semantic Layer now supports Azure Single-tenant deployments. Refer to [Set up the Semantic Layer](https://docs.getdbt.com/docs/use-dbt-semantic-layer/setup-sl) for more information on how to get started. * **Fix**: Resolved intermittent issues in Single-tenant environments affecting Semantic Layer and query history. * **Fix**: [The dbt Semantic Layer](https://docs.getdbt.com/docs/use-dbt-semantic-layer/dbt-sl) now respects the BigQuery [`execution_project` attribute](https://docs.getdbt.com/docs/core/connect-data-platform/bigquery-setup#execution-project) , including for exports. * **New**: [Model notifications](https://docs.getdbt.com/docs/deploy/model-notifications) are now generally available in dbt. These notifications alert model owners through email about any issues encountered by models and tests as soon as they occur while running a job. * **New**: You can now use your [Azure OpenAI key](https://docs.getdbt.com/docs/cloud/account-integrations?ai-integration=azure#ai-integrations) (available in beta) to use dbt features like [Copilot](https://docs.getdbt.com/docs/cloud/dbt-copilot) and [Ask dbt](https://docs.getdbt.com/docs/cloud-integrations/snowflake-native-app) . Additionally, you can use your own [OpenAI API key](https://docs.getdbt.com/docs/cloud/account-integrations?ai-integration=openai#ai-integrations) or use [dbt Labs-managed OpenAI](https://docs.getdbt.com/docs/cloud/account-integrations?ai-integration=dbtlabs#ai-integrations) key. Refer to [AI integrations](https://docs.getdbt.com/docs/cloud/account-integrations#ai-integrations) for more information. * **New**: The [`hard_deletes`](https://docs.getdbt.com/reference/resource-configs/hard-deletes) config gives you more control on how to handle deleted rows from the source. Supported options are `ignore` (default), `invalidate` (replaces the legacy `invalidate_hard_deletes=true`), and `new_record`. Note that `new_record` will create a new metadata column in the snapshot table. November 2024[​](https://docs.getdbt.com/docs/dbt-versions/2024-release-notes#november-2024 "Direct link to November 2024") ---------------------------------------------------------------------------------------------------------------------------- * **Enhancement**: Data health signals in dbt Explorer are now available for Exposures, providing a quick view of data health while browsing resources. To view trust signal icons, go to dbt Explorer and click **Exposures** under the **Resource** tab. Refer to [Data health signals for resources](https://docs.getdbt.com/docs/explore/data-health-signals) for more info. * **Bug**: Identified and fixed an error with Semantic Layer queries that take longer than 10 minutes to complete. * **Fix**: Job environment variable overrides in credentials are now respected for Exports. Previously, they were ignored. * **Behavior change**: If you use a custom microbatch macro, set a [`require_batched_execution_for_custom_microbatch_strategy` behavior flag](https://docs.getdbt.com/reference/global-configs/behavior-changes#custom-microbatch-strategy) in your `dbt_project.yml` to enable batched execution. If you don't have a custom microbatch macro, you don't need to set this flag as dbt will handle microbatching automatically for any model using the [microbatch strategy](https://docs.getdbt.com/docs/build/incremental-microbatch#how-microbatch-compares-to-other-incremental-strategies) . * **Enhancement**: For users that have Advanced CI's [compare changes](https://docs.getdbt.com/docs/deploy/advanced-ci#compare-changes) feature enabled, you can optimize performance when running comparisons by using custom dbt syntax to customize deferral usage, exclude specific large models (or groups of models with tags), and more. Refer to [Compare changes custom commands](https://docs.getdbt.com/docs/deploy/job-commands#compare-changes-custom-commands) for examples of how to customize the comparison command. * **New**: SQL linting in CI jobs is now generally available in dbt. You can enable SQL linting in your CI jobs, using [SQLFluff](https://sqlfluff.com/) , to automatically lint all SQL files in your project as a run step before your CI job builds. SQLFluff linting is available on [dbt release tracks](https://docs.getdbt.com/docs/dbt-versions/cloud-release-tracks) and to dbt [Team or Enterprise](https://www.getdbt.com/pricing/) accounts. Refer to [SQL linting](https://docs.getdbt.com/docs/deploy/continuous-integration#sql-linting) for more information. * **New**: Use the [`dbt_valid_to_current`](https://docs.getdbt.com/reference/resource-configs/dbt_valid_to_current) config to set a custom indicator for the value of `dbt_valid_to` in current snapshot records (like a future date). By default, this value is `NULL`. When configured, dbt will use the specified value instead of `NULL` for `dbt_valid_to` for current records in the snapshot table. This feature is available in [the dbt Cloud "Latest" release track](https://docs.getdbt.com/docs/dbt-versions/cloud-release-tracks) (formerly called `Versionless`) and dbt Core v1.9 and later. * **New**: Use the [`event_time`](https://docs.getdbt.com/reference/resource-configs/event-time) configuration to specify "at what time did the row occur." This configuration is required for [Incremental microbatch](https://docs.getdbt.com/docs/build/incremental-microbatch) and can be added to ensure you're comparing overlapping times in [Advanced CI's compare changes](https://docs.getdbt.com/docs/deploy/advanced-ci) . Available in [the dbt Cloud "Latest" release track](https://docs.getdbt.com/docs/dbt-versions/cloud-release-tracks) (formerly called `Versionless`) and dbt Core v1.9 and higher. * **Fix**: This update improves [Semantic Layer Tableau integration](https://docs.getdbt.com/docs/cloud-integrations/semantic-layer/tableau) making query parsing more reliable. Some key fixes include: * Error messages for unsupported joins between saved queries and ALL tables. * Improved handling of queries when multiple tables are selected in a data source. * Fixed a bug when an IN filter contained a lot of values. * Better error messaging for queries that can't be parsed correctly. * **Enhancement**: The Semantic Layer supports creating new credentials for users who don't have permissions to create service tokens. In the **Credentials & service tokens** side panel, the **+Add Service Token** option is unavailable for those users who don't have permission. Instead, the side panel displays a message indicating that the user doesn't have permission to create a service token and should contact their administration. Refer to [Set up Semantic Layer](https://docs.getdbt.com/docs/use-dbt-semantic-layer/setup-sl) for more details. October 2024[​](https://docs.getdbt.com/docs/dbt-versions/2024-release-notes#october-2024 "Direct link to October 2024") -------------------------------------------------------------------------------------------------------------------------  Coalesce 2024 announcements Documentation for new features and functionality announced at Coalesce 2024: * Iceberg table support for [Snowflake](https://docs.getdbt.com/reference/resource-configs/snowflake-configs#iceberg-table-format) * [Athena](https://docs.getdbt.com/reference/resource-configs/athena-configs) and [Teradata](https://docs.getdbt.com/reference/resource-configs/teradata-configs) adapter support in dbt Cloud * dbt Cloud now hosted on [Azure](https://docs.getdbt.com/docs/cloud/about-cloud/access-regions-ip-addresses) * Get comfortable with [dbt Cloud Release Tracks](https://docs.getdbt.com/docs/dbt-versions/cloud-release-tracks) that keep your project up-to-date, automatically — on a cadence appropriate for your team * Scalable [microbatch incremental models](https://docs.getdbt.com/docs/build/incremental-microbatch) * Advanced CI [features](https://docs.getdbt.com/docs/deploy/advanced-ci) * [Linting with CI jobs](https://docs.getdbt.com/docs/deploy/continuous-integration#sql-linting) * dbt Assist is now [dbt Copilot](https://docs.getdbt.com/docs/cloud/dbt-copilot) * Developer blog on [Snowflake Feature Store and dbt: A bridge between data pipelines and ML](https://docs.getdbt.com/blog/snowflake-feature-store) * [Downstream exposures with Tableau](https://docs.getdbt.com/docs/explore/view-downstream-exposures) * Semantic Layer integration with [Excel desktop and M365](https://docs.getdbt.com/docs/cloud-integrations/semantic-layer/excel) * [Data health tiles](https://docs.getdbt.com/docs/explore/data-tile) * [Semantic Layer and Cloud IDE integration](https://docs.getdbt.com/docs/build/metricflow-commands#metricflow-commands) * Query history in [Explorer](https://docs.getdbt.com/docs/explore/model-query-history#view-query-history-in-explorer) * Semantic Layer Metricflow improvements, including [improved granularity and custom calendar](https://docs.getdbt.com/docs/build/metricflow-time-spine#custom-calendar) * [Python SDK](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-python) is now generally available * **Behavior change:** [Multi-factor authentication](https://docs.getdbt.com/docs/cloud/manage-access/mfa) is now enforced on all users who log in with username and password credentials. * **Enhancement**: The dbt Semantic Layer JDBC now allows users to paginate `semantic_layer.metrics()` and `semantic_layer.dimensions()` for metrics and dimensions using `page_size` and `page_number` parameters. Refer to [Paginate metadata calls](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc#querying-the-api-for-metric-metadata) for more information. * **Enhancement**: The dbt Semantic Layer JDBC now allows you to filter your metrics to include only those that contain a specific substring, using the `search` parameter. If no substring is provided, the query returns all metrics. Refer to [Fetch metrics by substring search](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc#querying-the-api-for-metric-metadata) for more information. * **Fix**: The [Semantic Layer Excel integration](https://docs.getdbt.com/docs/cloud-integrations/semantic-layer/excel) now correctly surfaces errors when a query fails to execute. Previously, it was not clear why a query failed to run. * **Fix:** Previously, POST requests to the Jobs API with invalid `cron` strings would return HTTP response status code 500s but would update the underlying entity. Now, POST requests to the Jobs API with invalid `cron` strings will result in status code 400s, without the underlying entity being updated. * **Fix:** Fixed an issue where the `Source` view page in dbt Explorer did not correctly display source freshness status if older than 30 days. * **Fix:** The UI now indicates when the description of a model is inherited from a catalog comment. * **Behavior change:** User API tokens have been deprecated. Update to [personal access tokens](https://docs.getdbt.com/docs/dbt-cloud-apis/user-tokens) if you have any still in use. * **New**: The Cloud IDE supports signed commits for Git, available for Enterprise plans. You can sign your Git commits when pushing them to the repository to prevent impersonation and enhance security. Supported Git providers are GitHub and GitLab. Refer to [Git commit signing](https://docs.getdbt.com/docs/cloud/dbt-cloud-ide/git-commit-signing) for more information. * **New:** With Mesh, you can now enable bidirectional dependencies across your projects. Previously, dbt enforced dependencies to only go in one direction. dbt checks for cycles across projects and raises errors if any are detected. For details, refer to [Cycle detection](https://docs.getdbt.com/docs/mesh/govern/project-dependencies#cycle-detection) . There's also the [Intro to Mesh](https://docs.getdbt.com/best-practices/how-we-mesh/mesh-1-intro) guide to help you learn more best practices. * **New**: The [Semantic Layer Python software development kit](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-python) is now [generally available](https://docs.getdbt.com/docs/dbt-versions/product-lifecycles) . It provides users with easy access to the Semantic Layer with Python and enables developers to interact with the Semantic Layer APIs to query metrics/dimensions in downstream tools. * **Enhancement**: You can now add a description to a singular data test. Use the [`description` property](https://docs.getdbt.com/reference/resource-properties/description) to document [singular data tests](https://docs.getdbt.com/docs/build/data-tests#singular-data-tests) . You can also use [docs block](https://docs.getdbt.com/docs/build/documentation#using-docs-blocks) to capture your test description. The enhancement is available now in [the "Latest" release track in dbt Cloud](https://docs.getdbt.com/docs/dbt-versions/cloud-release-tracks) , and it will be included in dbt Core v1.9. * **New**: Introducing the [microbatch incremental model strategy](https://docs.getdbt.com/docs/build/incremental-microbatch) (beta), available now in [dbt Cloud Latest](https://docs.getdbt.com/docs/dbt-versions/cloud-release-tracks) and will soon be supported in dbt Core v1.9. The microbatch strategy allows for efficient, batch-based processing of large time-series datasets for improved performance and resiliency, especially when you're working with data that changes over time (like new records being added daily). To enable this feature in dbt Cloud, set the `DBT_EXPERIMENTAL_MICROBATCH` environment variable to `true` in your project. * **New**: The dbt Semantic Layer supports custom calendar configurations in MetricFlow, available in [Preview](https://docs.getdbt.com/docs/dbt-versions/product-lifecycles#dbt-cloud) . Custom calendar configurations allow you to query data using non-standard time periods like `fiscal_year` or `retail_month`. Refer to [custom calendar](https://docs.getdbt.com/docs/build/metricflow-time-spine#custom-calendar) to learn how to define these custom granularities in your MetricFlow timespine YAML configuration. * **New**: In the "Latest" release track in dbt, [Snapshots](https://docs.getdbt.com/docs/build/snapshots) have been updated to use YAML configuration files instead of SQL snapshot blocks. This new feature simplifies snapshot management and improves performance, and will soon be released in dbt Core 1.9. * Who does this affect? Users of the "Latest" release track in dbt can define snapshots using the new YAML specification. Users upgrading to "Latest" who have existing snapshot definitions can keep their existing configurations, or they can choose to migrate their snapshot definitions to YAML. * Users on older versions: No action is needed; existing snapshots will continue to work as before. However, we recommend upgrading to the "Latest" release track to take advantage of the new snapshot features. * **Behavior change:** Set [`state_modified_compare_more_unrendered_values`](https://docs.getdbt.com/reference/global-configs/behavior-changes#source-definitions-for-state) to true to reduce false positives for `state:modified` when configs differ between `dev` and `prod` environments. * **Behavior change:** Set the [`skip_nodes_if_on_run_start_fails`](https://docs.getdbt.com/reference/global-configs/behavior-changes#failures-in-on-run-start-hooks) flag to `True` to skip all selected resources from running if there is a failure on an `on-run-start` hook. * **Enhancement**: In the "Latest" release track in dbt Cloud, snapshots defined in SQL files can now use `config` defined in `schema.yml` YAML files. This update resolves the previous limitation that required snapshot properties to be defined exclusively in `dbt_project.yml` and/or a `config()` block within the SQL file. This will also be released in dbt Core 1.9. * **New**: In the "Latest" release track in dbt Cloud, the `snapshot_meta_column_names` config allows for customizing the snapshot metadata columns. This feature allows an organization to align these automatically-generated column names with their conventions, and will be included in the upcoming dbt Core 1.9 release. * **Enhancement**: the "Latest" release track in dbt Cloud infers a model's `primary_key` based on configured data tests and/or constraints within `manifest.json`. The inferred `primary_key` is visible in dbt Explorer and utilized by the dbt Cloud [compare changes](https://docs.getdbt.com/docs/deploy/run-visibility#compare-tab) feature. This will also be released in dbt Core 1.9. Read about the [order dbt infers columns can be used as primary key of a model](https://github.com/dbt-labs/dbt-core/blob/7940ad5c7858ff11ef100260a372f2f06a86e71f/core/dbt/contracts/graph/nodes.py#L534-L541) . * **New:** dbt Explorer now includes trust signal icons, which is currently available as a [Preview](https://docs.getdbt.com/docs/dbt-versions/product-lifecycles#dbt-cloud) . Trust signals offer a quick, at-a-glance view of data health when browsing your dbt models in dbt Explorer. These icons indicate whether a model is **Healthy**, **Caution**, **Degraded**, or **Unknown**. For accurate health data, ensure the resource is up-to-date and has had a recent job run. Refer to [Data health signals](https://docs.getdbt.com/docs/explore/data-health-signals) for more information. * **New:** Downstream exposures are now available in Preview in dbt. Downstream exposures helps users understand how their models are used in downstream analytics tools to inform investments and reduce incidents. It imports and auto-generates exposures based on Tableau dashboards, with user-defined curation. To learn more, refer to [Downstream exposures](https://docs.getdbt.com/docs/cloud-integrations/downstream-exposures-tableau) . September 2024[​](https://docs.getdbt.com/docs/dbt-versions/2024-release-notes#september-2024 "Direct link to September 2024") ------------------------------------------------------------------------------------------------------------------------------- * **Fix**: MetricFlow updated `get_and_expire` to replace the unsupported `GETEX` command with a `GET` and conditional expiration, ensuring compatibility with Azure Redis 6.0. * **Enhancement**: The [dbt Semantic Layer Python SDK](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-python) now supports `TimeGranularity` custom grain for metrics. This feature allows you to define custom time granularities for metrics, such as `fiscal_year` or `retail_month`, to query data using non-standard time periods. * **New**: Use the Copilot AI engine to generate semantic model for your models, now available in beta. Copilot automatically generates documentation, tests, and now semantic models based on the data in your model, . To learn more, refer to [Copilot](https://docs.getdbt.com/docs/cloud/dbt-copilot) . * **New**: Use the new recommended syntax for [defining `foreign_key` constraints](https://docs.getdbt.com/reference/resource-properties/constraints) using `refs`, available in the "Latest" release track in dbt Cloud. This will soon be released in dbt Core v1.9. This new syntax will capture dependencies and works across different environments. * **Enhancement**: You can now run [Semantic Layer commands](https://docs.getdbt.com/docs/build/metricflow-commands) commands in the [dbt Cloud IDE](https://docs.getdbt.com/docs/cloud/dbt-cloud-ide/develop-in-the-cloud) . The supported commands are `dbt sl list`, `dbt sl list metrics`, `dbt sl list dimension-values`, `dbt sl list saved-queries`, `dbt sl query`, `dbt sl list dimensions`, `dbt sl list entities`, and `dbt sl validate`. * **New**: Microsoft Excel, a Semantic Layer integration, is now generally available. The integration allows you to connect to Microsoft Excel to query metrics and collaborate with your team. Available for [Excel Desktop](https://pages.store.office.com/addinsinstallpage.aspx?assetid=WA200007100&rs=en-US&correlationId=4132ecd1-425d-982d-efb4-de94ebc83f26) or [Excel Online](https://pages.store.office.com/addinsinstallpage.aspx?assetid=WA200007100&rs=en-US&correlationid=4132ecd1-425d-982d-efb4-de94ebc83f26&isWac=True) . For more information, refer to [Microsoft Excel](https://docs.getdbt.com/docs/cloud-integrations/semantic-layer/excel) . * **New**: [Data health tile](https://docs.getdbt.com/docs/explore/data-tile) is now generally available in dbt Explorer. Data health tiles provide a quick at-a-glance view of your data quality, highlighting potential issues in your data. You can embed these tiles in your dashboards to quickly identify and address data quality issues in your dbt project. * **New**: dbt Explorer's Model query history feature is now in Preview for dbt Enterprise customers. Model query history allows you to view the count of consumption queries for a model based on the data warehouse's query logs. This feature provides data teams insight, so they can focus their time and infrastructure spend on the worthwhile used data products. To learn more, refer to [Model query history](https://docs.getdbt.com/docs/explore/model-query-history) . * **Enhancement**: You can now use [Extended Attributes](https://docs.getdbt.com/docs/dbt-cloud-environments#extended-attributes) and [Environment Variables](https://docs.getdbt.com/docs/build/environment-variables) when connecting to the Semantic Layer. If you set a value directly in the Semantic Layer Credentials, it will have a higher priority than Extended Attributes. When using environment variables, the default value for the environment will be used. If you're using exports, job environment variable overrides aren't supported yet, but they will be soon. * **New:** There are two new [environment variable defaults](https://docs.getdbt.com/docs/build/environment-variables#dbt-cloud-context) — `DBT_CLOUD_ENVIRONMENT_NAME` and `DBT_CLOUD_ENVIRONMENT_TYPE`. * **New:** The [Amazon Athena warehouse connection](https://docs.getdbt.com/docs/cloud/connect-data-platform/connect-amazon-athena) is available as a public preview for dbt accounts that have upgraded to [the "Latest" release track](https://docs.getdbt.com/docs/dbt-versions/cloud-release-tracks) . August 2024[​](https://docs.getdbt.com/docs/dbt-versions/2024-release-notes#august-2024 "Direct link to August 2024") ---------------------------------------------------------------------------------------------------------------------- * **Fix:** Fixed an issue in [dbt Explorer](https://docs.getdbt.com/docs/explore/explore-projects) where navigating to a consumer project from a public node resulted in displaying a random public model rather than the original selection. * **New**: You can now configure metrics at granularities at finer time grains, such as hour, minute, or even by the second. This is particularly useful for more detailed analysis and for datasets where high-resolution time data is required, such as minute-by-minute event tracking. Refer to [dimensions](https://docs.getdbt.com/docs/build/dimensions) for more information about time granularity. * **Enhancement**: Microsoft Excel now supports [saved selections](https://docs.getdbt.com/docs/cloud-integrations/semantic-layer/excel#using-saved-selections) and [saved queries](https://docs.getdbt.com/docs/cloud-integrations/semantic-layer/excel#using-saved-queries) . Use Saved selections to save your query selections within the Excel application. The application also clears stale data in [trailing rows](https://docs.getdbt.com/docs/cloud-integrations/semantic-layer/excel#other-settings) by default. To return your results and keep any previously selected data intact, un-select the **Clear trailing rows** option. * **Behavior change:** GitHub is no longer supported for OAuth login to dbt. Use a supported [SSO or OAuth provider](https://docs.getdbt.com/docs/cloud/manage-access/sso-overview) to securely manage access to your dbt account. July 2024[​](https://docs.getdbt.com/docs/dbt-versions/2024-release-notes#july-2024 "Direct link to July 2024") ---------------------------------------------------------------------------------------------------------------- * **Behavior change:** `target_schema` is no longer a required configuration for [snapshots](https://docs.getdbt.com/docs/build/snapshots) . You can now target different schemas for snapshots across development and deployment environments using the [schema config](https://docs.getdbt.com/reference/resource-configs/schema) . * **New:** [Connections](https://docs.getdbt.com/docs/cloud/connect-data-platform/about-connections#connection-management) are now available under **Account settings** as a global setting. Previously, they were found under **Project settings**. This is being rolled out in phases over the coming weeks. * **New:** Admins can now assign [environment-level permissions](https://docs.getdbt.com/docs/cloud/manage-access/environment-permissions) to groups for specific roles. * **New:** [Merge jobs](https://docs.getdbt.com/docs/deploy/merge-jobs) for implementing [continuous deployment (CD)](https://docs.getdbt.com/docs/deploy/continuous-deployment) workflows are now GA in dbt. Previously, you had to either set up a custom GitHub action or manually build the changes every time a pull request is merged. * **New**: The ability to lint your SQL files from the dbt CLI is now available. To learn more, refer to [Lint SQL files](https://docs.getdbt.com/docs/cloud/configure-cloud-cli#lint-sql-files) . * **Behavior change:** dbt Cloud IDE automatically adds a `--limit 100` to preview queries to avoid slow and expensive queries during development. Recently, dbt Core changed how the `limit` is applied to ensure that `order by` clauses are consistently respected. Because of this, queries that already contain a limit clause might now cause errors in the IDE previews. To address this, dbt Labs plans to provide an option soon to disable the limit from being applied. Until then, dbt Labs recommends removing the (duplicate) limit clause from your queries during previews to avoid these IDE errors. * **Enhancement**: Introducing a revamped overview page for dbt Explorer, available in beta. It includes a new design and layout for the dbt Explorer homepage. The new layout provides a more intuitive experience for users to navigate their dbt projects, as well as a new **Latest updates** section to view the latest changes or issues related to project resources. To learn more, refer to [Overview page](https://docs.getdbt.com/docs/explore/explore-projects#overview-page) . #### dbt Semantic Layer[​](https://docs.getdbt.com/docs/dbt-versions/2024-release-notes#dbt-semantic-layer "Direct link to dbt Semantic Layer") * **New**: Introduced the [`dbt-sl-sdk` Python software development kit (SDK)](https://github.com/dbt-labs/semantic-layer-sdk-python) Python library, which provides you with easy access to the dbt Semantic Layer with Python. It allows developers to interact with the dbt Semantic Layer APIs and query metrics and dimensions in downstream tools. Refer to the [dbt Semantic Layer Python SDK](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-python) for more information. * **New**: Introduced Semantic validations in CI pipelines. Automatically test your semantic nodes (metrics, semantic models, and saved queries) during code reviews by adding warehouse validation checks in your CI job using the `dbt sl validate` command. You can also validate modified semantic nodes to guarantee code changes made to dbt models don't break these metrics. Refer to [Semantic validations in CI](https://docs.getdbt.com/docs/deploy/ci-jobs#semantic-validations-in-ci) to learn about the additional commands and use cases. * **New**: We now expose the `meta` field within the [config property](https://docs.getdbt.com/reference/resource-configs/meta) for dbt Semantic Layer metrics in the [JDBC and GraphQL APIs](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-api-overview) under the `meta` field. * **New**: Added a new command in the dbt CLI called `export-all`, which allows you to export multiple or all of your saved queries. Previously, you had to explicitly specify the [list of saved queries](https://docs.getdbt.com/docs/build/metricflow-commands#list-saved-queries) . * **Enhancement**: The Semantic Layer now offers more granular control by supporting multiple data platform credentials, which can represent different roles or service accounts. Available for dbt Enterprise plans, you can map credentials to service tokens for secure authentication. Refer to [Set up Semantic Layer](https://docs.getdbt.com/docs/use-dbt-semantic-layer/setup-sl#set-up-dbt-semantic-layer) for more details. * **Fix**: Addressed a bug where unicode query filters (such as Chinese characters) were not working correctly in the Semantic Layer Tableau integration. * **Fix**: Resolved a bug with parsing certain private keys for BigQuery when running an export. * **Fix**: Addressed a bug that caused a "closed connection" error to be returned when querying or running an Export. * **Fix**: Resolved an issue in dbt Core where, during partial parsing, all generated metrics in a file were incorrectly deleted instead of just those related to the changed semantic model. Now, only the metrics associated with the modified model are affected. June 2024[​](https://docs.getdbt.com/docs/dbt-versions/2024-release-notes#june-2024 "Direct link to June 2024") ---------------------------------------------------------------------------------------------------------------- * **New:** Introduced new granularity support for cumulative metrics in MetricFlow. Granularity options for cumulative metrics are slightly different than granularity for other metric types. For other metrics, we use the `date_trunc` function to implement granularity. However, because cumulative metrics are non-additive (values can't be added up), we can't use the `date_trunc` function to change their time grain granularity. Instead, we use the `first()`, `last()`, and `avg()` aggregation functions to aggregate cumulative metrics over the requested period. By default, we take the first value of the period. You can change this behavior by using the `period_agg` parameter. For more information, refer to [Granularity options for cumulative metrics](https://docs.getdbt.com/docs/build/cumulative#granularity-options) . #### dbt Semantic Layer[​](https://docs.getdbt.com/docs/dbt-versions/2024-release-notes#dbt-semantic-layer-1 "Direct link to dbt Semantic Layer") * **New:** Added support for Predicate pushdown SQL optimization in MetricFlow. We will now push down categorical dimension filters to the metric source table. Previously filters were applied after we selected from the metric source table. This change helps reduce full table scans on certain query engines. * **New:** Enabled `where` filters on dimensions (included in saved queries) to use the cache during query time. This means you can now dynamically filter your dashboards without losing the performance benefits of caching. Refer to [caching](https://docs.getdbt.com/docs/use-dbt-semantic-layer/sl-cache#result-caching) for more information. * **Enhancement:** In [Google Sheets](https://docs.getdbt.com/docs/cloud-integrations/semantic-layer/gsheets) , we added information icons and descriptions to metrics and dimensions options in the Query Builder menu. Click on the **Info** icon button to view a description of the metric or dimension. Available in the following Query Builder menu sections: metric, group by, where, saved selections, and saved queries. * **Enhancement:** In [Google Sheets](https://docs.getdbt.com/docs/cloud-integrations/semantic-layer/gsheets) , you can now apply granularity to all time dimensions, not just metric time. This update uses our [APIs](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-api-overview) to support granularity selection on any chosen time dimension. * **Enhancement**: MetricFlow time spine warnings now prompt users to configure missing or small-grain-time spines. An error message is displayed for multiple time spines per granularity. * **Enhancement**: Errors now display if no time spine is configured at the requested or smaller granularity. * **Enhancement:** Improved querying error message when no semantic layer credentials were set. * **Enhancement:** Querying grains for cumulative metrics now returns multiple granularity options (day, week, month, quarter, year) like all other metric types. Previously, you could only query one grain option for cumulative metrics. * **Fix:** Removed errors that prevented querying cumulative metrics with other granularities. * **Fix:** Fixed various Tableau errors when querying certain metrics or when using calculated fields. * **Fix:** In Tableau, we relaxed naming field expectations to better identify calculated fields. * **Fix:** Fixed an error when refreshing database metadata for columns that we can't convert to Arrow. These columns will now be skipped. This mainly affected Redshift users with custom types. * **Fix:** Fixed Private Link connections for Databricks. #### Also available this month:[​](https://docs.getdbt.com/docs/dbt-versions/2024-release-notes#also-available-this-month "Direct link to Also available this month:") * **Enhancement:** Updates to the UI when [creating merge jobs](https://docs.getdbt.com/docs/deploy/merge-jobs) are now available. The updates include improvements to helper text, new deferral settings, and performance improvements. * **New**: The Semantic Layer now offers a seamless integration with Microsoft Excel, available in [preview](https://docs.getdbt.com/docs/dbt-versions/product-lifecycles#dbt-cloud) . Build semantic layer queries and return data on metrics directly within Excel, through a custom menu. To learn more and install the add-on, check out [Microsoft Excel](https://docs.getdbt.com/docs/cloud-integrations/semantic-layer/excel) . * **New:** [Job warnings](https://docs.getdbt.com/docs/deploy/job-notifications) are now GA. Previously, you could receive email or Slack alerts about your jobs when they succeeded, failed, or were canceled. Now with the new **Warns** option, you can also receive alerts when jobs have encountered warnings from tests or source freshness checks during their run. This gives you more flexibility on _when_ to be notified. * **New:** A [preview](https://docs.getdbt.com/docs/dbt-versions/product-lifecycles#dbt-cloud) of the dbt Snowflake Native App is now available. With this app, you can access dbt Explorer, the **Ask dbt** chatbot, and orchestration observability features, extending your dbt experience into the Snowflake UI. To learn more, check out [About the dbt Snowflake Native App](https://docs.getdbt.com/docs/cloud-integrations/snowflake-native-app) and [Set up the dbt Snowflake Native App](https://docs.getdbt.com/docs/cloud-integrations/set-up-snowflake-native-app) . May 2024[​](https://docs.getdbt.com/docs/dbt-versions/2024-release-notes#may-2024 "Direct link to May 2024") ------------------------------------------------------------------------------------------------------------- * **Enhancement:** We've now introduced a new **Prune branches** [Git button](https://docs.getdbt.com/docs/cloud/dbt-cloud-ide/ide-user-interface#prune-branches-modal) in the IDE. This button allows you to delete local branches that have been deleted from the remote repository, keeping your branch management tidy. Available in all regions now and will be released to single tenant accounts during the next release cycle. #### dbt Cloud Launch Showcase event[​](https://docs.getdbt.com/docs/dbt-versions/2024-release-notes#dbt-cloud-launch-showcase-event "Direct link to dbt Cloud Launch Showcase event") The following features are new or enhanced as part of our [dbt Launch Showcase](https://www.getdbt.com/resources/webinars/dbt-cloud-launch-showcase) event on May 14th, 2024: * **New:** [Copilot](https://docs.getdbt.com/docs/cloud/dbt-copilot) is a powerful AI engine helping you generate documentation, tests, and semantic models, saving you time as you deliver high-quality data. Available in private beta for a subset of dbt Enterprise users and in the IDE. [Register your interest](https://docs.google.com/forms/d/e/1FAIpQLScPjRGyrtgfmdY919Pf3kgqI5E95xxPXz-8JoVruw-L9jVtxg/viewform) to join the private beta. * **New:** The new low-code editor, now in private beta, enables less SQL-savvy analysts to create or edit dbt models through a visual, drag-and-drop experience inside of dbt. These models compile directly to SQL and are indistinguishable from other dbt models in your projects: they are version-controlled, can be accessed across projects in Mesh, and integrate with dbt Explorer and the Cloud IDE. [Register your interest](https://docs.google.com/forms/d/e/1FAIpQLScPjRGyrtgfmdY919Pf3kgqI5E95xxPXz-8JoVruw-L9jVtxg/viewform) to join the private beta. * **New:** [dbt CLI](https://docs.getdbt.com/docs/cloud/cloud-cli-installation) is now Generally Available (GA) to all users. The dbt CLI is a command-line interface that allows you to interact with dbt, use automatic deferral, leverage Mesh, and more! * **New:** [Unit tests](https://docs.getdbt.com/docs/build/unit-tests) are now GA in dbt. Unit tests enable you to test your SQL model logic against a set of static inputs. *  New: Native support for Azure Synapse Analytics[preview](https://docs.getdbt.com/docs/dbt-versions/product-lifecycles "Go to https://docs.getdbt.com/docs/dbt-versions/product-lifecycles") Native support in dbt Cloud for Azure Synapse Analytics is now available as a [preview](https://docs.getdbt.com/docs/dbt-versions/product-lifecycles#dbt-cloud) ! To learn more, refer to [Connect Azure Synapse Analytics](https://docs.getdbt.com/docs/cloud/connect-data-platform/connect-azure-synapse-analytics) and [Microsoft Azure Synapse DWH configurations](https://docs.getdbt.com/reference/resource-configs/azuresynapse-configs) . Also, check out the [Quickstart for dbt Cloud and Azure Synapse Analytics](https://docs.getdbt.com/guides/azure-synapse-analytics?step=1) . The guide walks you through: * Loading the Jaffle Shop sample data (provided by dbt Labs) into Azure Synapse Analytics. * Connecting dbt Cloud to Azure Synapse Analytics. * Turning a sample query into a model in your dbt project. A model in dbt is a SELECT statement. * Adding tests to your models. * Documenting your models. * Scheduling a job to run. * **New:** MetricFlow enables you to now add metrics as dimensions to your metric filters to create more complex metrics and gain more insights. Available for all Semantic Layer users. * **New:** [Staging environment](https://docs.getdbt.com/docs/deploy/deploy-environments#staging-environment) is now GA. Use staging environments to grant developers access to deployment workflows and tools while controlling access to production data. Available to all dbt users. * **New:** Oauth login support via [Databricks](https://docs.getdbt.com/docs/cloud/manage-access/set-up-databricks-oauth) is now GA to Enterprise customers. *  New: GA of dbt Explorer's features dbt Explorer's current capabilities — including column-level lineage, model performance analysis, and project recommendations — are now Generally Available for dbt Cloud Enterprise and Teams plans. With Explorer, you can more easily navigate your dbt Cloud project – including models, sources, and their columns – to gain a better understanding of its latest production or staging state. To learn more about its features, check out: * [Explore projects](https://docs.getdbt.com/docs/explore/explore-projects) * [Explore multiple projects](https://docs.getdbt.com/docs/explore/explore-multiple-projects) * [Column-level lineage](https://docs.getdbt.com/docs/explore/column-level-lineage) * [Model performance](https://docs.getdbt.com/docs/explore/model-performance) * [Project recommendations](https://docs.getdbt.com/docs/explore/project-recommendations) * **New:** Native support for Microsoft Fabric in dbt is now GA. This feature is powered by the [dbt-fabric](https://github.com/Microsoft/dbt-fabric) adapter. To learn more, refer to [Connect Microsoft Fabric](https://docs.getdbt.com/docs/cloud/connect-data-platform/connect-microsoft-fabric) and [Microsoft Fabric DWH configurations](https://docs.getdbt.com/reference/resource-configs/fabric-configs) . There's also a [quickstart guide](https://docs.getdbt.com/guides/microsoft-fabric?step=1) to help you get started. * **New:** Mesh is now GA to dbt Enterprise users. Mesh is a framework that helps organizations scale their teams and data assets effectively. It promotes governance best practices and breaks large projects into manageable sections. Get started with Mesh by reading the [Mesh quickstart guide](https://docs.getdbt.com/guides/mesh-qs?step=1) . * **New:** The Semantic Layer [Tableau Desktop, Tableau Server](https://docs.getdbt.com/docs/cloud-integrations/semantic-layer/tableau) , and [Google Sheets integration](https://docs.getdbt.com/docs/cloud-integrations/semantic-layer/gsheets) is now GA to dbt Team or Enterprise accounts. These first-class integrations allow you to query and unlock valuable insights from your data ecosystem. * **Enhancement:** As part of our ongoing commitment to improving the [IDE](https://docs.getdbt.com/docs/cloud/dbt-cloud-ide/develop-in-the-cloud#considerations) , the filesystem now comes with improvements to speed up dbt development, such as introducing a Git repository limit of 10GB. #### Also available this month:[​](https://docs.getdbt.com/docs/dbt-versions/2024-release-notes#also-available-this-month-1 "Direct link to Also available this month:") * **Update**: The [dbt CLI](https://docs.getdbt.com/docs/cloud/cloud-cli-installation) is now available for Azure single tenant and is accessible in all [deployment regions](https://docs.getdbt.com/docs/cloud/about-cloud/access-regions-ip-addresses) for both multi-tenant and single-tenant accounts. * **New**: The [Semantic Layer](https://docs.getdbt.com/docs/use-dbt-semantic-layer/dbt-sl) introduces [declarative caching](https://docs.getdbt.com/docs/use-dbt-semantic-layer/sl-cache) , allowing you to cache common queries to speed up performance and reduce query compute costs. Available for dbt Team or Enterprise accounts. *  New: Latest Release Track The **Latest** Release Track is now Generally Available (previously Public Preview). On this release track, you get automatic upgrades of dbt, including early access to the latest features, fixes, and performance improvements for your dbt project. dbt Labs will handle upgrades behind-the-scenes, as part of testing and redeploying the dbt Cloud application — just like other dbt Cloud capabilities and other SaaS tools that you're using. No more manual upgrades and no more need for _a second sandbox project_ just to try out new features in development. To learn more about the new setting, refer to [Release Tracks](https://docs.getdbt.com/docs/dbt-versions/cloud-release-tracks) for details. [![Example of the Latest setting](https://docs.getdbt.com/img/docs/dbt-cloud/cloud-configuring-dbt-cloud/choosing-dbt-version/example-environment-settings.png?v=2 "Example of the Latest setting")](https://docs.getdbt.com/docs/dbt-versions/2024-release-notes#) Example of the Latest setting * **Behavior change:** Introduced the `require_resource_names_without_spaces` flag, opt-in and disabled by default. If set to `True`, dbt will raise an exception if it finds a resource name containing a space in your project or an installed package. This will become the default in a future version of dbt. Read [No spaces in resource names](https://docs.getdbt.com/reference/global-configs/behavior-changes#no-spaces-in-resource-names) for more information. April 2024[​](https://docs.getdbt.com/docs/dbt-versions/2024-release-notes#april-2024 "Direct link to April 2024") ------------------------------------------------------------------------------------------------------------------- *  New: Merge jobs[beta](https://docs.getdbt.com/docs/dbt-versions/product-lifecycles "Go to https://docs.getdbt.com/docs/dbt-versions/product-lifecycles") You can now set up a continuous deployment (CD) workflow for your projects natively in dbt Cloud. You can now access a beta release of [Merge jobs](https://docs.getdbt.com/docs/deploy/merge-jobs) , which is a new [job type](https://docs.getdbt.com/docs/deploy/jobs) , that enables you to trigger dbt job runs as soon as changes (via Git pull requests) merge into production. [![Example of creating a merge job](https://docs.getdbt.com/img/docs/dbt-cloud/using-dbt-cloud/example-create-merge-job.png?v=2 "Example of creating a merge job")](https://docs.getdbt.com/docs/dbt-versions/2024-release-notes#) Example of creating a merge job * **Behavior change:** Introduced the `require_explicit_package_overrides_for_builtin_materializations` flag, opt-in and disabled by default. If set to `True`, dbt will only use built-in materializations defined in the root project or within dbt, rather than implementations in packages. This will become the default in May 2024 (dbt Core v1.8 and dbt Cloud release tracks). Read [Package override for built-in materialization](https://docs.getdbt.com/reference/global-configs/behavior-changes#package-override-for-built-in-materialization) for more information. **Semantic Layer** * **New**: Use Saved selections to [save your query selections](https://docs.getdbt.com/docs/cloud-integrations/semantic-layer/gsheets#using-saved-selections) within the [Google Sheets application](https://docs.getdbt.com/docs/cloud-integrations/semantic-layer/gsheets) . They can be made private or public and refresh upon loading. * **New**: Metrics are now displayed by their labels as `metric_name`. * **Enhancement**: [Metrics](https://docs.getdbt.com/docs/build/metrics-overview) now supports the [`meta` option](https://docs.getdbt.com/reference/resource-configs/meta) under the [config](https://docs.getdbt.com/reference/resource-properties/config) property. Previously, we only supported the now deprecated `meta` tag. * **Enhancement**: In the Google Sheets application, we added [support](https://docs.getdbt.com/docs/cloud-integrations/semantic-layer/gsheets#using-saved-queries) to allow jumping off from or exploring MetricFlow-defined saved queries directly. * **Enhancement**: In the Google Sheets application, we added support to query dimensions without metrics. Previously, you needed a dimension. * **Enhancement**: In the Google Sheets application, we added support for time presets and complex time range filters such as "between", "after", and "before". * **Enhancement**: In the Google Sheets application, we added supported to automatically populate dimension values when you select a "where" filter, removing the need to manually type them. Previously, you needed to manually type the dimension values. * **Enhancement**: In the Google Sheets application, we added support to directly query entities, expanding the flexibility of data requests. * **Enhancement**: In the Google Sheets application, we added an option to exclude column headers, which is useful for populating templates with only the required data. * **Deprecation**: For the Tableau integration, the [`METRICS_AND_DIMENSIONS` data source](https://docs.getdbt.com/docs/cloud-integrations/semantic-layer/tableau#using-the-integration) has been deprecated for all accounts not actively using it. We encourage users to transition to the "ALL" data source for future integrations. March 2024[​](https://docs.getdbt.com/docs/dbt-versions/2024-release-notes#march-2024 "Direct link to March 2024") ------------------------------------------------------------------------------------------------------------------- * **New:** The Semantic Layer services now support using Privatelink for customers who have it enabled. * **New:** You can now develop against and test your Semantic Layer in the dbt CLI if your developer credential uses SSO. * **Enhancement:** You can select entities to Group By, Filter By, and Order By. * **Fix:** `dbt parse` no longer shows an error when you use a list of filters (instead of just a string filter) on a metric. * **Fix:** `join_to_timespine` now properly gets applied to conversion metric input measures. * **Fix:** Fixed an issue where exports in Redshift were not always committing to the DWH, which also had the side-effect of leaving table locks open. * **Behavior change:** Introduced the `source_freshness_run_project_hooks` flag, opt-in and disabled by default. If set to `True`, dbt will include `on-run-*` project hooks in the `source freshness` command. This will become the default in a future version of dbt. Read [Project hooks with source freshness](https://docs.getdbt.com/reference/global-configs/behavior-changes#project-hooks-with-source-freshness) for more information. February 2024[​](https://docs.getdbt.com/docs/dbt-versions/2024-release-notes#february-2024 "Direct link to February 2024") ---------------------------------------------------------------------------------------------------------------------------- * **New:** [Exports](https://docs.getdbt.com/docs/use-dbt-semantic-layer/exports#define-exports) allow you to materialize a saved query as a table or view in your data platform. By using exports, you can unify metric definitions in your data platform and query them as you would any other table or view. * **New:** You can access a list of your [exports](https://docs.getdbt.com/docs/use-dbt-semantic-layer/exports) with the new list saved-queries command by adding `--show-exports` * **New:** The Semantic Layer and [Tableau Connector](https://docs.getdbt.com/docs/cloud-integrations/semantic-layer/tableau) now supports relative date filters in Tableau. *  New: Use exports to write saved queries You can now use the [exports](https://docs.getdbt.com/docs/use-dbt-semantic-layer/exports) feature with [dbt Semantic Layer](https://docs.getdbt.com/docs/use-dbt-semantic-layer/dbt-sl) , allowing you to query reliable metrics and fast data reporting. Exports enhance the saved queries feature, allowing you to write commonly used queries directly within your data platform using dbt Cloud's job scheduler. By exposing tables of metrics and dimensions, exports enable you to integrate with additional tools that don't natively connect with the dbt Semantic Layer, such as PowerBI. Exports are available for dbt Cloud multi-tenant [Team or Enterprise](https://www.getdbt.com/pricing/) plans on dbt versions 1.7 or newer. Refer to the [exports blog](https://www.getdbt.com/blog/announcing-exports-for-the-dbt-semantic-layer) for more details. [![Add an environment variable to run exports in your production run.](https://docs.getdbt.com/img/docs/dbt-cloud/semantic-layer/deploy_exports.png?v=2 "Add an environment variable to run exports in your production run.")](https://docs.getdbt.com/docs/dbt-versions/2024-release-notes#) Add an environment variable to run exports in your production run. *  New: Trigger on job completion teamenterprise Now available for dbt Cloud Team and Enterprise plans is the ability to trigger deploy jobs when other deploy jobs are complete. You can enable this feature [in the UI](https://docs.getdbt.com/docs/deploy/deploy-jobs) with the **Run when another job finishes** option in the **Triggers** section of your job or with the [Create Job API endpoint](https://docs.getdbt.com/dbt-cloud/api-v2#/operations/Create%20Job) . When enabled, your job will run after the specified upstream job completes. You can configure which run status(es) will trigger your job. It can be just on `Success` or on all statuses. If you have dependencies between your dbt projects, this allows you to _natively_ orchestrate your jobs within dbt Cloud — no need to set up a third-party tool. An example of the **Triggers** section when creating the job: [![Example of Triggers on the Deploy Job page](https://docs.getdbt.com/img/docs/dbt-cloud/using-dbt-cloud/example-triggers-section.png?v=2 "Example of Triggers on the Deploy Job page")](https://docs.getdbt.com/docs/dbt-versions/2024-release-notes#) Example of Triggers on the Deploy Job page *  New: Latest Release Track[beta](https://docs.getdbt.com/docs/dbt-versions/product-lifecycles "Go to https://docs.getdbt.com/docs/dbt-versions/product-lifecycles") _Now available in the dbt version dropdown in dbt Cloud — starting with select customers, rolling out to wider availability through February and March._ On this release track, you get automatic upgrades of dbt, including early access to the latest features, fixes, and performance improvements for your dbt project. dbt Labs will handle upgrades behind-the-scenes, as part of testing and redeploying the dbt Cloud application — just like other dbt Cloud capabilities and other SaaS tools that you're using. No more manual upgrades and no more need for _a second sandbox project_ just to try out new features in development. To learn more about the new setting, refer to [Release Tracks](https://docs.getdbt.com/docs/dbt-versions/cloud-release-tracks) for details. [![Example of the Latest setting](https://docs.getdbt.com/img/docs/dbt-cloud/cloud-configuring-dbt-cloud/choosing-dbt-version/example-environment-settings.png?v=2 "Example of the Latest setting")](https://docs.getdbt.com/docs/dbt-versions/2024-release-notes#) Example of the Latest setting *  New: Override dbt version with new User development settings You can now [override the dbt version](https://docs.getdbt.com/docs/dbt-versions/upgrade-dbt-version-in-cloud#override-dbt-version) that's configured for the development environment within your project and use a different version — affecting only your user account. This lets you test new dbt features without impacting other people working on the same project. And when you're satisfied with the test results, you can safely upgrade the dbt version for your project(s). Use the **dbt version** dropdown to specify the version to override with. It's available on your project's credentials page in the **User development settings** section. For example: [![Example of overriding the dbt version on your user account](https://docs.getdbt.com/img/docs/dbt-cloud/cloud-configuring-dbt-cloud/choosing-dbt-version/example-override-version.png?v=2 "Example of overriding the dbt version on your user account")](https://docs.getdbt.com/docs/dbt-versions/2024-release-notes#) Example of overriding the dbt version on your user account *  Enhancement: Edit in primary git branch in IDE You can now edit, format, or lint files and execute dbt commands directly in your primary git branch in the [dbt Cloud IDE](https://docs.getdbt.com/docs/cloud/dbt-cloud-ide/develop-in-the-cloud) . This enhancement is available across various repositories, including native integrations, imported git URLs, and managed repos. This enhancement is currently available to all dbt Cloud multi-tenant regions and will soon be available to single-tenant accounts. The primary branch of the connected git repo has traditionally been _read-only_ in the IDE. This update changes the branch to _protected_ and allows direct edits. When a commit is made, dbt Cloud will prompt you to create a new branch. dbt Cloud will pre-populate the new branch name with the GIT\_USERNAME-patch-#; however, you can edit the field with a custom branch name. Previously, the primary branch was displayed as read-only, but now the branch is displayed with a lock icon to identify it as protected: [![Previous read-only experience](https://docs.getdbt.com/img/docs/dbt-cloud/using-dbt-cloud/read-only.png?v=2 "Previous read-only experience")](https://docs.getdbt.com/docs/dbt-versions/2024-release-notes#) Previous read-only experience [![New protected experience](https://docs.getdbt.com/img/docs/dbt-cloud/using-dbt-cloud/protected.png?v=2 "New protected experience")](https://docs.getdbt.com/docs/dbt-versions/2024-release-notes#) New protected experience When you make a commit while on the primary branch, a modal window will open prompting you to create a new branch and enter a commit message: [![Create new branch window](https://docs.getdbt.com/img/docs/dbt-cloud/using-dbt-cloud/create-new-branch.png?v=2 "Create new branch window")](https://docs.getdbt.com/docs/dbt-versions/2024-release-notes#) Create new branch window * **Enhancement:** The Semantic Layer [Google Sheets integration](https://docs.getdbt.com/docs/cloud-integrations/semantic-layer/gsheets) now exposes a note on the cell where the data was requested, indicating clearer data requests. The integration also now exposes a new **Time Range** option, which allows you to quickly select date ranges. * **Enhancement:** The [GraphQL API](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-graphql) includes a `requiresMetricTime` parameter to better handle metrics that must be grouped by time. (Certain metrics defined in MetricFlow can't be looked at without a time dimension). * **Enhancement:** Enable querying metrics with offset and cumulative metrics with the time dimension name, instead of `metric_time`. [Issue #1000](https://github.com/dbt-labs/metricflow/issues/1000) * Enable querying `metric_time` without metrics. [Issue #928](https://github.com/dbt-labs/metricflow/issues/928) * **Enhancement:** Added support for consistent SQL query generation, which enables ID generation consistency between otherwise identical MF queries. Previously, the SQL generated by `MetricFlowEngine` was not completely consistent between identical queries. [Issue 1020](https://github.com/dbt-labs/metricflow/issues/1020) * **Fix:** The Tableau Connector returns a date filter when filtering by dates. Previously it was erroneously returning a timestamp filter. * **Fix:** MetricFlow now validates if there are `metrics`, `group by`, or `saved_query` items in each query. Previously, there was no validation. [Issue 1002](https://github.com/dbt-labs/metricflow/issues/1002) * **Fix:** Measures using `join_to_timespine` in MetricFlow now have filters applied correctly after time spine join. * **Fix:** Querying multiple granularities with offset metrics: * If you query a time offset metric with multiple instances of `metric_time`/`agg_time_dimension`, only one of the instances will be offset. All of them should be. * If you query a time offset metric with one instance of `metric_time`/`agg_time_dimension` but filter by a different one, the query will fail. * **Fix:** MetricFlow prioritizes a candidate join type over the default type when evaluating nodes to join. For example, the default join type for distinct values queries is `FULL OUTER JOIN`, however, time spine joins require `CROSS JOIN`, which is more appropriate. * **Fix:** Fixed a bug that previously caused errors when entities were referenced in `where` filters. January 2024[​](https://docs.getdbt.com/docs/dbt-versions/2024-release-notes#january-2024 "Direct link to January 2024") ------------------------------------------------------------------------------------------------------------------------- *  January docs updates Hello from the dbt Docs team: @mirnawong1, @matthewshaver, @nghi-ly, and @runleonarun! First, we’d like to thank the 10 new community contributors to docs.getdbt.com 🙏 What a busy start to the year! We merged 110 PRs in January. Here's how we improved the [docs.getdbt.com](http://docs.getdbt.com/) experience: * Added new hover behavior for images * Added new expandables for FAQs * Pruned outdated notices and snippets as part of the docs site maintenance January saw some great new content: * New [dbt Mesh FAQs](https://docs.getdbt.com/best-practices/how-we-mesh/mesh-5-faqs) page * Beta launch of [Explorer’s column-level lineage](https://docs.getdbt.com/docs/explore/column-level-lineage) feature * Developer blog posts: * [More time coding, less time waiting: Mastering defer in dbt](https://docs.getdbt.com/blog/defer-to-prod) * [Deprecation of dbt Server](https://docs.getdbt.com/blog/deprecation-of-dbt-server) * From the community: [Serverless, free-tier data stack with dlt + dbt core](https://docs.getdbt.com/blog/serverless-dlt-dbt-stack) * The Extrica team added docs for the [dbt-extrica community adapter](https://docs.getdbt.com/docs/core/connect-data-platform/extrica-setup) * Semantic Layer: New [conversion metrics docs](https://docs.getdbt.com/docs/build/conversion) and added the parameter `fill_nulls_with` to all metric types (launched the week of January 12, 2024) * New [dbt environment command](https://docs.getdbt.com/reference/commands/dbt-environment) and its flags for the dbt CLI January also saw some refreshed content, either aligning with new product features or requests from the community: * Native support for [partial parsing in dbt Cloud](https://docs.getdbt.com/docs/cloud/account-settings#partial-parsing) * Updated guidance on using dots or underscores in the [Best practice guide for models](https://docs.getdbt.com/best-practices/how-we-style/1-how-we-style-our-dbt-models) * Updated [PrivateLink for VCS docs](https://docs.getdbt.com/docs/cloud/secure/vcs-privatelink) * Added a new `job_runner` role in our [Enterprise project role permissions docs](https://docs.getdbt.com/docs/cloud/manage-access/enterprise-permissions#project-role-permissions) * Added saved queries to [Metricflow commands](https://docs.getdbt.com/docs/build/metricflow-commands#list-saved-queries) * Removed [as\_text docs](https://github.com/dbt-labs/docs.getdbt.com/pull/4726) that were wildly outdated * **New:** New metric type that allows you to measure conversion events. For example, users who viewed a web page and then filled out a form. For more details, refer to [Conversion metrics](https://docs.getdbt.com/docs/build/conversion) . * **New:** Instead of specifying the fully qualified dimension name (for example, `order__user__country`) in the group by or filter expression, you now only need to provide the primary entity and dimensions name, like `user__county`. * **New:** You can now query the [saved queries](https://docs.getdbt.com/docs/build/saved-queries) you've defined in the Semantic Layer using [Tableau](https://docs.getdbt.com/docs/cloud-integrations/semantic-layer/tableau) , [GraphQL API](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-graphql) , [JDBC API](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-jdbc) , and the [dbt CLI](https://docs.getdbt.com/docs/cloud/cloud-cli-installation) . *  New: Native support for partial parsing By default, dbt parses all the files in your project at the beginning of every dbt invocation. Depending on the size of your project, this operation can take a long time to complete. With the new partial parsing feature in dbt Cloud, you can reduce the time it takes for dbt to parse your project. When enabled, dbt Cloud parses only the changed files in your project instead of parsing all the project files. As a result, your dbt invocations will take less time to run. To learn more, refer to [Partial parsing](https://docs.getdbt.com/docs/cloud/account-settings#partial-parsing) . [![Example of the Partial parsing option](https://docs.getdbt.com/img/docs/deploy/account-settings-partial-parsing.png?v=2 "Example of the Partial parsing option")](https://docs.getdbt.com/docs/dbt-versions/2024-release-notes#) Example of the Partial parsing option * **Enhancement:** The YAML spec parameter `label` is now available for Semantic Layer metrics in [JDBC and GraphQL APIs](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-api-overview) . This means you can conveniently use `label` as a display name for your metrics when exposing them. * **Enhancement:** Added support for `create_metric: true` for a measure, which is a shorthand to quickly create metrics. This is useful in cases when metrics are only used to build other metrics. * **Enhancement:** Added support for Tableau parameter filters. You can use the [Tableau connector](https://docs.getdbt.com/docs/cloud-integrations/semantic-layer/tableau) to create and use parameters with your Semantic Layer data. * **Enhancement:** Added support to expose `expr` and `agg` for [Measures](https://docs.getdbt.com/docs/build/measures) in the [GraphQL API](https://docs.getdbt.com/docs/dbt-cloud-apis/sl-graphql) . * **Enhancement:** You have improved error messages in the command line interface when querying a dimension that is not reachable for a given metric. * **Enhancement:** You can now query entities using our Tableau integration (similar to querying dimensions). * **Enhancement:** A new data source is available in our Tableau integration called "ALL", which contains all semantic objects defined. This has the same information as "METRICS\_AND\_DIMENSIONS". In the future, we will deprecate "METRICS\_AND\_DIMENSIONS" in favor of "ALL" for clarity. * **Fix:** Support for numeric types with precision greater than 38 (like `BIGDECIMAL`) in BigQuery is now available. Previously, it was unsupported so would return an error. * **Fix:** In some instances, large numeric dimensions were being interpreted by Tableau in scientific notation, making them hard to use. These should now be displayed as numbers as expected. * **Fix:** We now preserve dimension values accurately instead of being inadvertently converted into strings. * **Fix:** Resolved issues with naming collisions in queries involving multiple derived metrics using the same metric input. Previously, this could cause a naming collision. Input metrics are now deduplicated, ensuring each is referenced only once. * **Fix:** Resolved warnings related to using two duplicate input measures in a derived metric. Previously, this would trigger a warning. Input measures are now deduplicated, enhancing query processing and clarity. * **Fix:** Resolved an error where referencing an entity in a filter using the object syntax would fail. For example, `{{Entity('entity_name')}}` would fail to resolve. Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [December 2024](https://docs.getdbt.com/docs/dbt-versions/2024-release-notes#december-2024) * [November 2024](https://docs.getdbt.com/docs/dbt-versions/2024-release-notes#november-2024) * [October 2024](https://docs.getdbt.com/docs/dbt-versions/2024-release-notes#october-2024) * [September 2024](https://docs.getdbt.com/docs/dbt-versions/2024-release-notes#september-2024) * [August 2024](https://docs.getdbt.com/docs/dbt-versions/2024-release-notes#august-2024) * [July 2024](https://docs.getdbt.com/docs/dbt-versions/2024-release-notes#july-2024) * [June 2024](https://docs.getdbt.com/docs/dbt-versions/2024-release-notes#june-2024) * [May 2024](https://docs.getdbt.com/docs/dbt-versions/2024-release-notes#may-2024) * [April 2024](https://docs.getdbt.com/docs/dbt-versions/2024-release-notes#april-2024) * [March 2024](https://docs.getdbt.com/docs/dbt-versions/2024-release-notes#march-2024) * [February 2024](https://docs.getdbt.com/docs/dbt-versions/2024-release-notes#february-2024) * [January 2024](https://docs.getdbt.com/docs/dbt-versions/2024-release-notes#january-2024) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/dbt-versions/2024-release-notes.md) --- # About Iceberg catalogs | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/mesh/iceberg/about-catalogs#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page Data catalogs have recently become at the top of the data industry's mind, especially given the excitement about Iceberg and data governance for AI. It has become an overused term that represents a broad set of tools. So, before we dive into Iceberg catalogs, let's start at the beginning: About data catalogs[​](https://docs.getdbt.com/docs/mesh/iceberg/about-catalogs#about-data-catalogs "Direct link to About data catalogs") ------------------------------------------------------------------------------------------------------------------------------------------ The short answer is it’s **data about your data**. A Data Catalog is a centralized metadata management layer that enables users and tools to discover, understand, and govern data effectively. At its core, it organizes metadata about datasets, including information about the schemas, lineage, access controls, and business context to help technical and non-technical users work with data more efficiently. ### History of data catalogs[​](https://docs.getdbt.com/docs/mesh/iceberg/about-catalogs#history-of-data-catalogs "Direct link to History of data catalogs") Data catalogs aren’t a new concept. Data dictionaries were the earliest forms of catalogs, and they were part of relational databases. These dictionaries stored schema-level metadata (like table names). They weren’t made for business users and were very manual. Fast forward to the early 2010s, and the industry began to delve deeply into [Hadoop](https://hadoop.apache.org/) and data lakes. [Hive Metastore](https://hive.apache.org/) became the standard for managing schema metadata in Hadoop ecosystems. However, it was still limited to structural metadata, as it lacked lineage, discovery, and business context metadata. Next, there was the emergence of open source technical catalogs like [Iceberg](https://iceberg.apache.org/terms/) , [Polaris](https://polaris.apache.org/) , and [Unity Catalog](https://www.unitycatalog.io/) , and business catalogs like [Atlan](https://atlan.com/what-is-a-data-catalog/) . In the era of AI, it’s more important than ever to have catalogs that can support structural metadata and business logic. For data teams, the catalogs can fall into two buckets: * **Technical data catalogs:** Focus on structural metadata, including information about data like table and column names, data types, storage locations (particularly important for open table formats), and access controls. They usually come either “built-in” (no setup needed) or externally managed and integrated into your data platform. They are used by compute engines to locate and interact with data. * **Business data catalogs:** Serve broader organizational users (BI analysts, product managers, etc.). They enrich technical metadata with business context in the form of metrics, business definitions, data quality indicators, usage patterns, and ownership. ### Why data catalogs are important to dbt[​](https://docs.getdbt.com/docs/mesh/iceberg/about-catalogs#why-data-catalogs-are-important-to-dbt "Direct link to Why data catalogs are important to dbt") For dbt users working in a lakehouse or multi-engine architecture, understanding and interacting with data catalogs is essential for several reasons, including: * **Table Discovery:** dbt models are registered in catalogs. Understanding the catalog structure is critical for managing datasets and informing dbt about what has already been built and where it resides. * **Cross-Engine Interoperability:** Iceberg catalogs allow datasets created by one compute engine to be read by another. This is what dbt Mesh’s cross-platform functionality is built on. About Iceberg catalogs[​](https://docs.getdbt.com/docs/mesh/iceberg/about-catalogs#about-iceberg-catalogs "Direct link to About Iceberg catalogs") --------------------------------------------------------------------------------------------------------------------------------------------------- Apache Iceberg is an open table format designed for petabyte-scale analytic datasets. It supports schema evolution, time travel, partition pruning, and transactional operations across distributed compute engines. Iceberg catalogs are a critical abstraction layer that maps logical table names to their metadata locations and provides a namespace mechanism. They decouple compute engines from the physical layout of data, enabling multiple tools to interoperate consistently on the same dataset. There are multiple types of Iceberg catalogs: * Iceberg REST * Iceberg REST compatible * Delta/Iceberg Hybrid\* Hybrid catalogs support storing duplicate table metadata in Iceberg and Delta Lake formats, enabling workflows like an Iceberg engine to read from Delta Lake or vice versa. There will be limitations specific to how the platform has implemented this. ### How dbt works with Iceberg catalogs[​](https://docs.getdbt.com/docs/mesh/iceberg/about-catalogs#how-dbt-works-with-iceberg-catalogs "Direct link to How dbt works with Iceberg catalogs") dbt interacts with Iceberg catalogs through the adapters in two ways: * **Model Materialization:** When dbt materializes a model as a table or view, if the catalog integration is declared, the underlying adapter (Spark, Trino, Snowflake, etc.) creates an Iceberg table entry in the specified catalog, both built-in or external. * **Catalog Integration**: With our initial release of the new catalog framework, users can declare which catalog the table's metadata is written to. Why is this important? dbt uses and creates a significant amount of metadata. Before every run, dbt needs to know what already exists so it knows how to compile code (ex. resolving your `{{ref()}}` to the actual table name) and where to materialize the object. By supporting these two methods, dbt can cleverly adjust based on the environment, code logic, and use case defined in your dbt project. ### Limitations[​](https://docs.getdbt.com/docs/mesh/iceberg/about-catalogs#limitations "Direct link to Limitations") To ensure that your compute engine has access to the catalog, you must provide the networking and permissions are set up correctly. This means that if you are using X warehouse with Y catalog but want to read Y catalog from Z warehouse, you need to ensure that Z warehouse can connect to Y catalog. If IP restrictions are turned on, you must resolve this by removing restrictions on allowlisting (only possible if the warehouse supports static IP addresses) or setting something like Privatelink to support this. Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [About data catalogs](https://docs.getdbt.com/docs/mesh/iceberg/about-catalogs#about-data-catalogs) * [History of data catalogs](https://docs.getdbt.com/docs/mesh/iceberg/about-catalogs#history-of-data-catalogs) * [Why data catalogs are important to dbt](https://docs.getdbt.com/docs/mesh/iceberg/about-catalogs#why-data-catalogs-are-important-to-dbt) * [About Iceberg catalogs](https://docs.getdbt.com/docs/mesh/iceberg/about-catalogs#about-iceberg-catalogs) * [How dbt works with Iceberg catalogs](https://docs.getdbt.com/docs/mesh/iceberg/about-catalogs#how-dbt-works-with-iceberg-catalogs) * [Limitations](https://docs.getdbt.com/docs/mesh/iceberg/about-catalogs#limitations) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/mesh/iceberg/about-catalogs.md) --- # BigQuery and Apache Iceberg | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/mesh/iceberg/bigquery-iceberg-support#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page dbt supports materializing Iceberg tables on BigQuery via the catalog integration, starting with the dbt-bigquery 1.10 release. Creating Iceberg Tables[​](https://docs.getdbt.com/docs/mesh/iceberg/bigquery-iceberg-support#creating-iceberg-tables "Direct link to Creating Iceberg Tables") ---------------------------------------------------------------------------------------------------------------------------------------------------------------- dbt supports creating Iceberg tables for two of the BigQuery materializations: * [Table](https://docs.getdbt.com/docs/build/materializations#table) * [Incremental](https://docs.getdbt.com/docs/build/materializations#incremental) BigQuery Iceberg catalogs[​](https://docs.getdbt.com/docs/mesh/iceberg/bigquery-iceberg-support#bigquery-iceberg-catalogs "Direct link to BigQuery Iceberg catalogs") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- BigQuery supports Iceberg tables via its built-in catalog [BigLake Metastore](https://cloud.google.com/bigquery/docs/iceberg-tables#architecture) today. No setup is needed to access the BigLake Metastore. However, you will need to have a [storage bucket and the required BigQuery roles](https://cloud.google.com/bigquery/docs/iceberg-tables#create-iceberg-tables) configured prior to creating an Iceberg table. ### dbt catalog integration configurations[​](https://docs.getdbt.com/docs/mesh/iceberg/bigquery-iceberg-support#dbt-catalog-integration-configurations "Direct link to dbt catalog integration configurations") The following table outlines the configuration fields required to set up a catalog integration for [Iceberg tables in Snowflake](https://docs.getdbt.com/reference/resource-configs/snowflake-configs#iceberg-table-format) . | Field | Required | Accepted values | | --- | --- | --- | | `name` | yes | Name of catalog integration | | `catalog_name` | yes | The name of the catalog integration in BigQuery. For example, `biglake_metastore`. | | `external_volume` | yes | `gs://` | | `table_format` | yes | `iceberg` | | `catalog_type` | yes | `biglake_metastore` | | `file_format` | yes | `default`,`parquet` | dbt has an additonal configuration: `storage_uri` that the user can use on the model configuration to override the catalog integration path to supply the entire `storage_uri` path directly. ### Configure catalog integration for managed Iceberg tables[​](https://docs.getdbt.com/docs/mesh/iceberg/bigquery-iceberg-support#configure-catalog-integration-for-managed-iceberg-tables "Direct link to Configure catalog integration for managed Iceberg tables") 1. Create a `catalogs.yml` at the top level of your dbt project. An example: catalogs: - name: my_bigquery_iceberg_catalog active_write_integration: biglake_metastore write_integrations: - name: biglake_metastore external_volume: 'gs://mydbtbucket' table_format: iceberg file_format: parquet catalog_type: biglake_metastore 2. Apply the catalog configuration at either the model, folder, or project level: iceberg\_model.yml {{ config( materialized='table', catalog_name = 'my_bigquery_iceberg_catalog' )}}select * from {{ ref('jaffle_shop_customers') }} 3. Execute the dbt model with a `dbt run -s iceberg_model`. ### Limitations[​](https://docs.getdbt.com/docs/mesh/iceberg/bigquery-iceberg-support#limitations "Direct link to Limitations") BigQuery today does not support connecting to external Iceberg catalogs. In terms of SQL operations and table management features, please refer to the [BigQuery docs](https://cloud.google.com/bigquery/docs/iceberg-tables#limitations) for more information. Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Creating Iceberg Tables](https://docs.getdbt.com/docs/mesh/iceberg/bigquery-iceberg-support#creating-iceberg-tables) * [BigQuery Iceberg catalogs](https://docs.getdbt.com/docs/mesh/iceberg/bigquery-iceberg-support#bigquery-iceberg-catalogs) * [dbt catalog integration configurations](https://docs.getdbt.com/docs/mesh/iceberg/bigquery-iceberg-support#dbt-catalog-integration-configurations) * [Configure catalog integration for managed Iceberg tables](https://docs.getdbt.com/docs/mesh/iceberg/bigquery-iceberg-support#configure-catalog-integration-for-managed-iceberg-tables) * [Limitations](https://docs.getdbt.com/docs/mesh/iceberg/bigquery-iceberg-support#limitations) * [Base location](https://docs.getdbt.com/docs/mesh/iceberg/bigquery-iceberg-support#base-location) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/mesh/iceberg/bigquery-iceberg-support.md) --- # Snowflake and Apache Iceberg | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/mesh/iceberg/snowflake-iceberg-support#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page dbt supports materializing the table in Iceberg table format in two different ways: * The model configuration field `table_format = 'iceberg'` (legacy) * Catalog integration can be configured in the SQL config (inside the `.sql` model file), property file (model folder), or project file ([`dbt_project.yml`](https://docs.getdbt.com/reference/dbt_project.yml) ). Catalog integration configuration You need to create a `catalogs.yml` file to use the integration and apply that integration on the config level. Refer to [Snowflake configurations](https://docs.getdbt.com/reference/resource-configs/snowflake-configs) for more information. We recommend that you use the Iceberg catalog configuration and apply the catalog in the model config for ease of use and future-proof your code. Using `table_format = 'iceberg'` directly on the model configuration is a legacy approach. Creating Iceberg Tables[​](https://docs.getdbt.com/docs/mesh/iceberg/snowflake-iceberg-support#creating-iceberg-tables "Direct link to Creating Iceberg Tables") ----------------------------------------------------------------------------------------------------------------------------------------------------------------- dbt supports creating Iceberg tables for three of the Snowflake materializations: * [Table](https://docs.getdbt.com/docs/build/materializations#table) * [Incremental](https://docs.getdbt.com/docs/build/materializations#incremental) * [Dynamic Table](https://docs.getdbt.com/reference/resource-configs/snowflake-configs#dynamic-tables) Iceberg catalogs[​](https://docs.getdbt.com/docs/mesh/iceberg/snowflake-iceberg-support#iceberg-catalogs "Direct link to Iceberg catalogs") -------------------------------------------------------------------------------------------------------------------------------------------- Snowflake has support for Iceberg tables via built-in and external catalogs, including: * Snowflake built-in catalog (metadata managed by Snowflake’s built-in information schema) * Polaris/Open Catalog (managed Polaris)\* * Glue Data Catalog\* * Iceberg REST Compatible\* \*_dbt catalog support coming soon._ To use an externally managed catalog (anything outside of the built-in catalog), you must set up a catalog integration. To do so, you must run a SQL command similar to the following. ### External catalogs[​](https://docs.getdbt.com/docs/mesh/iceberg/snowflake-iceberg-support#external-catalogs "Direct link to External catalogs") Example configurations for external catalogs. * Polaris/Open Catalog * Glue data catalog * Iceberg REST API You must set up a catalog integration to use Polaris/Open Catalog (managed Polaris). Example code: CREATE CATALOG INTEGRATION my_polaris_catalog_int CATALOG_SOURCE = POLARIS TABLE_FORMAT = ICEBERG REST_CONFIG = ( CATALOG_URI = 'https://-.snowflakecomputing.com/polaris/api/catalog' CATALOG_NAME = '' ) REST_AUTHENTICATION = ( TYPE = OAUTH OAUTH_CLIENT_ID = '' OAUTH_CLIENT_SECRET = '' OAUTH_ALLOWED_SCOPES = ('PRINCIPAL_ROLE:ALL') ) ENABLED = TRUE; Executing this will register the external Polaris catalog with Snowflake. Once configured, dbt can create Iceberg tables in Snowflake that register the existence of the new database object with the catalog as metadata and query Polaris-managed tables. To configure Glue Data Catalog as the external catalog, you will need to set up two prerequisites: * **Create AWS IAM Role for Glue Access:** Configure AWS permissions so Snowflake can read the Glue Catalog. This typically means creating an AWS IAM role that Snowflake will assume, with policies allowing Glue catalog read operations (at minimum, glue:GetTable and glue:GetTables on the relevant Glue databases). Attach a trust policy to enable Snowflake to assume this role (via an external ID). * **Set up the catalog integration:** In Snowflake, create a catalog integration of type GLUE. This registers the Glue Data Catalog information and the IAM role with Snowflake. For example: CREATE CATALOG INTEGRATION my_glue_catalog_int CATALOG_SOURCE = GLUE CATALOG_NAMESPACE = 'dbt_database' TABLE_FORMAT = ICEBERG GLUE_AWS_ROLE_ARN = 'arn:aws:iam::123456789012:role/myGlueRole' GLUE_CATALOG_ID = '123456789012' GLUE_REGION = 'us-east-2' ENABLED = TRUE; Glue Data Catalog supports the Iceberg REST specification so that you can connect to Glue via the Iceberg REST API. You can set up a catalog integration for or Catalogs that are compatible with the open-source Apache Iceberg™ REST specification, Example code: CREATE CATALOG INTEGRATION my_iceberg_catalog_int CATALOG_SOURCE = ICEBERG_REST TABLE_FORMAT = ICEBERG CATALOG_NAMESPACE = 'dbt_database' REST_CONFIG = ( restConfigParams ) REST_AUTHENTICATION = ( restAuthenticationParams ) ENABLED = TRUE REFRESH_INTERVAL_SECONDS = COMMENT = 'catalog integration for dbt iceberg tables' For Unity Catalog with a bearer token : CREATE OR REPLACE CATALOG INTEGRATION my_unity_catalog_int_pat CATALOG_SOURCE = ICEBERG_REST TABLE_FORMAT = ICEBERG CATALOG_NAMESPACE = 'my_namespace' REST_CONFIG = ( CATALOG_URI = 'https://my-api/api/2.1/unity-catalog/iceberg' CATALOG_NAME= '' ) REST_AUTHENTICATION = ( TYPE = BEARER BEARER_TOKEN = '' ) ENABLED = TRUE; After you have created the external catalog integration, you will be able to do two things: * **Query an externally managed table:** Snowflake can query Iceberg tables whose metadata lives in the external catalog. In this scenario, Snowflake is a "reader" of the external catalog. The table’s data remains in external cloud storage (AWS S3 or GCP Bucket) as defined in the catalog storage configuration. Snowflake will use the catalog integration to fetch metadata via the REST API. Snowflake then reads the data files from cloud storage. * **Sync Snowflake-managed tables to an external catalog:** You can create a Snowflake Iceberg table that Snowflake manages via a cloud storage location and then register/sync that table to the external catalog. This allows other engines to discover the table. dbt Catalog Integration Configurations for Snowflake[​](https://docs.getdbt.com/docs/mesh/iceberg/snowflake-iceberg-support#dbt-catalog-integration-configurations-for-snowflake "Direct link to dbt Catalog Integration Configurations for Snowflake") -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The following table outlines the configuration fields required to set up a catalog integration for [Iceberg tables in Snowflake](https://docs.getdbt.com/reference/resource-configs/snowflake-configs#iceberg-table-format) . | Field | Required | Accepted values | | --- | --- | --- | | `name` | yes | Name of catalog integration | | `catalog_name` | yes | The name of the catalog integration in Snowflake. For example, `my_dbt_iceberg_catalog`) | | `external_volume` | yes | `` | | `table_format` | yes | `iceberg` | | `catalog_type` | yes | `built_in`, `iceberg_rest`\* | | `adapter_properties` | optional | See below | \*Coming soon! Stay tuned for updates. ### Adapter Properties[​](https://docs.getdbt.com/docs/mesh/iceberg/snowflake-iceberg-support#adapter-properties "Direct link to Adapter Properties") These are the additional optional configurations, unique to Snowflake, that can be supplied and nested under `adapter_properties` to add in more configurability. | Field | Accepted values | | --- | --- | | `storage_serialization_policy` | `COMPATIBLE` or `OPTIMIZED` | | `max_data_extension_time_in_days` | `0` to `90` with a default of `14` | | `data_retention_time_in_days` | Standard Account: `1`, Enterprise or higher: `0` to `90`, default `1` | | `change_tracking` | `True` or `False` | * **storage\_serialization\_policy** The serialization policy tells Snowflake what kind of encoding and compression to perform on the table data files. If not specified at table creation, the table inherits the value set at the schema, database, or account level. If the value isn’t specified at any level, the table uses the default value. You can’t change the value of this parameter after table creation. Accepted values: . * **max\_data\_extension\_time\_in\_days** The maximum number of days Snowflake can extend the data retention period for tables to prevent streams on the tables from becoming stale. The `MAX_DATA_EXTENSION_TIME_IN_DAYS` parameter enables you to limit this automatic extension period to control storage costs for data retention, or for compliance reasons. * **data\_retention\_time\_in\_days** For managed Iceberg tables, you can set a retention period for Snowflake Time Travel and undropping the table over the default account values. For tables that use an external catalog, Snowflake uses the value of the DATA\_RETENTION\_TIME\_IN\_DAYS parameter to set a retention period for Snowflake Time Travel and undropping the table. When the retention period expires, Snowflake does not delete the Iceberg metadata or snapshots from your external cloud storage. * **change\_tracking** Specifies whether to enable change tracking on the table. ### Configure catalog integration for managed Iceberg tables[​](https://docs.getdbt.com/docs/mesh/iceberg/snowflake-iceberg-support#configure-catalog-integration-for-managed-iceberg-tables "Direct link to Configure catalog integration for managed Iceberg tables") 1. Create a `catalogs.yml` at the top level of your dbt project. An example of Snowflake Horizon as the catalog: catalogs: - name: catalog_horizon active_write_integration: snowflake_write_integration write_integrations: - name: snowflake_write_integration external_volume: dbt_external_volume table_format: iceberg catalog_type: built_in 2. Add the `catalog_name` config parameter in either the SQL config (inside the .sql model file), property file (model folder), or your `dbt_project.yml`. An example of `iceberg_model.sql`: {{ config( materialized='table', catalog_name = catalog_horizon )}}select * from {{ ref('jaffle_shop_customers') }} 3. Execute the dbt model with a `dbt run -s iceberg_model`. For more information, refer to our documentation on [Snowflake configurations](https://docs.getdbt.com/reference/resource-configs/snowflake-configs) . ### Limitations[​](https://docs.getdbt.com/docs/mesh/iceberg/snowflake-iceberg-support#limitations "Direct link to Limitations") For external catalogs, Snowflake only supports `read`, which means it can query the table but cannot insert or modify data. The syncing experience will be different depending on the catalog you choose. Some catalogs are automatically refreshed, and you can set parameters to do so with your catalog integration. Other catalogs might require a separate job to manage the metadata sync. Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Creating Iceberg Tables](https://docs.getdbt.com/docs/mesh/iceberg/snowflake-iceberg-support#creating-iceberg-tables) * [Iceberg catalogs](https://docs.getdbt.com/docs/mesh/iceberg/snowflake-iceberg-support#iceberg-catalogs) * [External catalogs](https://docs.getdbt.com/docs/mesh/iceberg/snowflake-iceberg-support#external-catalogs) * [dbt Catalog Integration Configurations for Snowflake](https://docs.getdbt.com/docs/mesh/iceberg/snowflake-iceberg-support#dbt-catalog-integration-configurations-for-snowflake) * [Adapter Properties](https://docs.getdbt.com/docs/mesh/iceberg/snowflake-iceberg-support#adapter-properties) * [Configure catalog integration for managed Iceberg tables](https://docs.getdbt.com/docs/mesh/iceberg/snowflake-iceberg-support#configure-catalog-integration-for-managed-iceberg-tables) * [Limitations](https://docs.getdbt.com/docs/mesh/iceberg/snowflake-iceberg-support#limitations) * [Iceberg table format](https://docs.getdbt.com/docs/mesh/iceberg/snowflake-iceberg-support#iceberg-table-format) * [Example configuration](https://docs.getdbt.com/docs/mesh/iceberg/snowflake-iceberg-support#example-configuration) * [Base location](https://docs.getdbt.com/docs/mesh/iceberg/snowflake-iceberg-support#base-location) * [Limitations](https://docs.getdbt.com/docs/mesh/iceberg/snowflake-iceberg-support#limitations-1) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/mesh/iceberg/snowflake-iceberg-support.md) --- # Upgrading to dbt utils v1.0 | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-dbt-utils-v1.0#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page For the first time, [dbt utils](https://hub.getdbt.com/dbt-labs/dbt_utils/latest/) is crossing the major version boundary. From [last month’s blog post](https://www.getdbt.com/blog/announcing-dbt-v1.3-and-utils/) : > It’s time to formalize what was already unofficial policy: you can rely on dbt utils in the same way as you do dbt Core, with stable interfaces and consistent and intuitive naming. Just like the switch to dbt Core 1.0 last year, there are some breaking changes as we standardized and prepared for the future. Most changes can be handled with find-and-replace. If you need help, post on the [Community Forum](https://discourse.getdbt.com/) or in [#package-ecosystem](https://getdbt.slack.com/archives/CU4MRJ7QB) channel on Slack. New features[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-dbt-utils-v1.0#new-features "Direct link to New features") ---------------------------------------------------------------------------------------------------------------------------------------------------------------- * `get_single_value()` — An easy way to pull a single value from a SQL query, instead of having to access the `[0][0]`th element of a `run_query` result. * `safe_divide()` — Returns null when the denominator is 0, instead of throwing a divide-by-zero error. * New `not_empty_string` test — An easier wrapper than using `expression_is_true` to check the length of a column. Enhancements[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-dbt-utils-v1.0#enhancements "Direct link to Enhancements") ---------------------------------------------------------------------------------------------------------------------------------------------------------------- * Many tests are more meaningful when you run them against subgroups of a table. For example, you may need to validate that recent data exists for every turnstile instead of a single data source being sufficient. Add the new `group_by_columns` argument to your tests to do so. Review [this article](https://www.emilyriederer.com/post/grouping-data-quality/) by the test's author for more information. * With the addition of an on-by-default `quote_identifiers` argument in the `star()` macro, you can now disable quoting if necessary. * The `recency` test now has an optional `ignore_time_component` argument which can be used when testing against a date column. This prevents the time of day the test runs from causing false negatives/positives. Fixes[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-dbt-utils-v1.0#fixes "Direct link to Fixes") ------------------------------------------------------------------------------------------------------------------------------------------- * `union()` now includes/excludes columns case-insensitively * `slugify()` prefixes an underscore when the first char is a digit * The `expression_is_true` test doesn’t output `*` unless storing failures, a cost improvement for BigQuery. Breaking Changes[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-dbt-utils-v1.0#breaking-changes "Direct link to Breaking Changes") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ### Changes to `surrogate_key()`:[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-dbt-utils-v1.0#changes-to-surrogate_key "Direct link to changes-to-surrogate_key") * `surrogate_key()` has been replaced by `generate_surrogate_key()`. The original treated null values and blank strings the same, which could lead to duplicate keys being created. `generate_surrogate_key()` does not have this flaw. Compare the [surrogate keys calculated for these columns](https://docs.google.com/spreadsheets/d/1qWfdbieUOSgkzdY0kmJ9iCgdqyWccA0R-6EW0EgaMQc/edit#gid=0) : ![A table comparing the behavior of surrogate_key and generate_surrogate_key](https://docs.getdbt.com/assets/images/surrogate_key_behaviour-2248a1a7c8bfa9df30140fadc6021a99.png) Changing the calculation method for surrogate keys, even for the better, could have significant consequences in downstream uses (such as snapshots and incremental models which use this column as their `unique_key`). As a result, it's possible to opt into the legacy behavior by setting the following variable in your dbt project: #dbt_project.ymlvars: surrogate_key_treat_nulls_as_empty_strings: true #turn on legacy behavior By creating a new macro instead of updating the behavior of the old one, we are requiring all projects who use this macro to make an explicit decision about which approach is better for their context. **Our recommendation is that existing users should opt into the legacy behavior** unless you are confident that either: * your surrogate keys never contained nulls, or * your surrogate keys are not used for incremental models, snapshots or other stateful artifacts and so can be regenerated with new values without issue. Warning to package maintainers You can not assume one behavior or the other, as each project can customize its behavior. ### Functionality now native to dbt Core:[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-dbt-utils-v1.0#functionality-now-native-to-dbt-core "Direct link to Functionality now native to dbt Core:") * The `expression_is_true` test no longer has a dedicated `condition` argument. Instead, use `where` which is [now available natively to all tests](https://docs.getdbt.com/reference/resource-configs/where) : version: 2models: - name: old_syntax tests: - dbt_utils.expression_is_true: expression: "col_a + col_b = total" #replace this... condition: "created_at > '2018-12-31'" - name: new_syntax tests: - dbt_utils.expression_is_true: expression: "col_a + col_b = total" # ...with this... where: "created_at > '2018-12-31'" **Note** — This may cause some tests to get the same autogenerated names. To resolve this, you can [define a custom name for a test](https://docs.getdbt.com/reference/resource-properties/data-tests#define-a-custom-name-for-one-test) . * The deprecated `unique_where` and `not_null_where` tests have been removed, because [where is now available natively to all tests](https://docs.getdbt.com/reference/resource-configs/where) . To migrate, find and replace `dbt_utils.unique_where` with `unique` and `dbt_utils.not_null_where` with `not_null`. * `dbt_utils.current_timestamp()` is replaced by `dbt.current_timestamp()`. * Note that Postgres and Snowflake’s implementation of `dbt.current_timestamp()` differs from the old `dbt_utils` one ([full details here](https://github.com/dbt-labs/dbt-utils/pull/597#issuecomment-1231074577) ). If you use Postgres or Snowflake and need identical backwards-compatible behavior, use `dbt.current_timestamp_backcompat()`. This discrepancy will hopefully be reconciled in a future version of dbt Core. * All other cross-db macros have moved to the dbt namespace, with no changes necessary other than replacing `dbt_utils.` with `dbt.`. Review the [cross database macros documentation](https://docs.getdbt.com/reference/dbt-jinja-functions/cross-database-macros) for the full list. * In your code editor, you can do a global find and replace with regex: `\{\{\s*dbt_utils\.(any_value|bool_or|cast_bool_to_text|concat|dateadd|datediff|date_trunc|escape_single_quotes|except|hash|intersect|last_day|length|listagg|position|replace|right|safe_cast|split_part|string_literal|type_bigint|type_float|type_int|type_numeric|type_string|type_timestamp|type_bigint|type_float|type_int|type_numeric|type_string|type_timestamp|except|intersect|concat|hash|length|position|replace|right|split_part|escape_single_quotes|string_literal|any_value|bool_or|listagg|cast_bool_to_text|safe_cast|dateadd|datediff|date_trunc|last_day)` → `{{ dbt.$1` ### Removal of `insert_by_period` materialization[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-dbt-utils-v1.0#removal-of-insert_by_period-materialization "Direct link to removal-of-insert_by_period-materialization") * The `insert_by_period` materialization has been moved to the [experimental-features repo](https://github.com/dbt-labs/dbt-labs-experimental-features/tree/main/insert_by_period) . To continue to use it, add the below to your packages.yml file: packages: - git: https://github.com/dbt-labs/dbt-labs-experimental-features subdirectory: insert_by_period revision: XXXX #optional but highly recommended. Provide a full git sha hash, e.g. 1c0bfacc49551b2e67d8579cf8ed459d68546e00. If not provided, uses the current HEAD. ### Removal of deprecated legacy behavior:[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-dbt-utils-v1.0#removal-of-deprecated-legacy-behavior "Direct link to Removal of deprecated legacy behavior:") * `safe_add()` only works with a list of arguments; use `{{ dbt_utils.safe_add(['column_1', 'column_2']) }}` instead of varargs `{{ dbt_utils.safe_add('column_1', 'column_2') }}`. * Several long-promised deprecations to `deduplicate()` have been applied: * The `group_by` argument is replaced by `partition_by`. * `relation_alias` is removed. If you need an alias, you can pass it directly to the `relation` argument. * `order_by` is now mandatory. Pass a static value like `1` if you don’t care how they are deduplicated. * The deprecated `table` argument has been removed from `unpivot()`. Use `relation` instead. Resolving error messages[​](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-dbt-utils-v1.0#resolving-error-messages "Direct link to Resolving error messages") ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- After upgrading, these are common error messages you may encounter, along with their resolutions. `dict object has no attribute MACRO_NAME` **Cause**: No macro called `MACRO_NAME` exists. This is most likely because the macro has moved to the `dbt` namespace (see above). It could also be because you haven't run dbt deps or have misspelled a macro's name. **Resolution**: For [cross-database macros](https://docs.getdbt.com/reference/dbt-jinja-functions/cross-database-macros) , change `dbt_utils.MACRO_NAME()` to `dbt.MACRO_NAME()`. `macro 'dbt_macro__generate_surrogate_key' takes not more than 1 argument(s)` **Cause**: `generate_surrogate_key()` requires a single argument containing a list of columns, not a set of varargs. **Resolution**: Change to `dbt_utils.generate_surrogate_key(['column_1', 'column_2'])` - note the square brackets. `The dbt_utils.surrogate_key has been replaced by dbt_utils.generate_surrogate_key` **Cause**: `surrogate_key()` has been replaced. **Resolution**: 1. Decide whether you need to enable backwards compatibility [as detailed above](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-dbt-utils-v1.0#changes-to-surrogate_key) . 2. Find and replace `dbt_utils.surrogate_key` with `dbt_utils.generate_surrogate_key`. `macro dbt_macro__test_expression_is_true takes no keyword argument condition` **Cause**: `condition` has been removed from the `expression_is_true` test, now that `where` is available on all tests automatically. **Resolution**: Replace `condition` with `where`. `No materialization insert_by_period was found for adapter` **Cause**: `insert_by_period` has moved to the experimental features repo (see above). **Resolution**: Install the package as [described above](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-dbt-utils-v1.0#removal-of-insert_by_period-materialization) . `dbt found two tests with the name "XXX".` **Cause**: Changing from `condition` to `where` in the `expression_is_true` test, as configs are not part of a test's unique name. **Resolution**: Define a [custom name for your test](https://docs.getdbt.com/reference/resource-properties/tests#define-a-custom-name-for-one-test) . Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [New features](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-dbt-utils-v1.0#new-features) * [Enhancements](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-dbt-utils-v1.0#enhancements) * [Fixes](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-dbt-utils-v1.0#fixes) * [Breaking Changes](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-dbt-utils-v1.0#breaking-changes) * [Changes to `surrogate_key()`:](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-dbt-utils-v1.0#changes-to-surrogate_key) * [Functionality now native to dbt Core:](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-dbt-utils-v1.0#functionality-now-native-to-dbt-core) * [Removal of `insert_by_period` materialization](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-dbt-utils-v1.0#removal-of-insert_by_period-materialization) * [Removal of deprecated legacy behavior:](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-dbt-utils-v1.0#removal-of-deprecated-legacy-behavior) * [Resolving error messages](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/Older%20versions/upgrading-to-dbt-utils-v1.0#resolving-error-messages) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/docs/dbt-versions/core-upgrade/11-Older%20versions/upgrading-to-dbt-utils-v1.0.md) --- # docs | dbt Developer Hub [Skip to main content](https://docs.getdbt.com/reference/resource-configs/docs#__docusaurus_skipToContent_fallback) [Register now for Coalesce 2025 ✨ The Analytics Engineering Conference!](https://coalesce.getdbt.com/5Y3oaq/?utm_medium=internal&utm_source=docs&utm_campaign=q3-2026_coalesce-2025_aw&utm_content=coalesce____&utm_term=all_all__) On this page * Models * Sources * Seeds * Snapshots * Analyses * Macros You can configure `docs` behavior for many resources at once by setting in `dbt_project.yml`. You can also use the `docs` config in `properties.yaml` files, to set or override documentation behaviors for specific resources: dbt\_project.yml models: : +docs: show: true | false node_color: color_id # Use name (such as node_color: purple) or hex code with quotes (such as node_color: "#cd7f32") models/schema.yml version: 2models:- name: model_name config: docs: # changed to config in v1.10 show: true | false node_color: color_id # Use name (such as node_color: purple) or hex code with quotes (such as node_color: "#cd7f32") This property is not implemented for sources. You can use the docs property in YAML files, including the `dbt_project.yml`: dbt\_project.yml seeds: : +docs: show: true | false node_color: color_id # Use name (such as node_color: purple) or hex code with quotes (such as node_color: "#cd7f32") seeds/schema.yml version: 2seeds: - name: seed_name config: docs: # changed to config in v1.10 show: true | false node_color: color_id # Use name (such as node_color: purple) or hex code with quotes (such as node_color: "#cd7f32") You can use the docs property in YAML files, including the `dbt_project.yml`: dbt\_project.yml snapshots: : +docs: show: true | false node_color: color_id # Use name (such as node_color: purple) or hex code with quotes (such as node_color: "#cd7f32") snapshots/schema.yml version: 2snapshots: - name: snapshot_name config: docs: # changed to config in v1.10 show: true | false node_color: color_id # Use name (such as node_color: purple) or hex code with quotes (such as node_color: "#cd7f32") You can use the docs property in YAML files, _except_ in `dbt_project.yml`. Refer to [Analysis properties](https://docs.getdbt.com/reference/analysis-properties) for more info. analysis/schema.yml version: 2analyses: - name: analysis_name config: docs: # changed to config in v1.10 show: true | false node_color: color_id # Use name (such as node_color: purple) or hex code with quotes (such as node_color: "#cd7f32") You can use the docs property in YAML files, _except_ in `dbt_project.yml`. Refer to [Macro properties](https://docs.getdbt.com/reference/macro-properties) for more info. macros/schema.yml version: 2macros: - name: macro_name config: docs: # changed to config in v1.10 show: true | false Note that for backwards compatibility, `docs` is supported as a top-level key, but without the capabilities of config inheritance. Definition[​](https://docs.getdbt.com/reference/resource-configs/docs#definition "Direct link to Definition") -------------------------------------------------------------------------------------------------------------- The `docs` property can be used to provide documentation-specific configuration to models. It supports the attribute `show`, which controls whether or not nodes are shown in the auto-generated documentation website. It also supports `node_color` for models, seeds, snapshots, and analyses. Other node types are not supported. **Note:** Hidden models will still appear in the dbt DAG visualization but will be identified as "hidden.” Default[​](https://docs.getdbt.com/reference/resource-configs/docs#default "Direct link to Default") ----------------------------------------------------------------------------------------------------- The default value for `show` is `true`. Examples[​](https://docs.getdbt.com/reference/resource-configs/docs#examples "Direct link to Examples") -------------------------------------------------------------------------------------------------------- ### Mark a model as hidden[​](https://docs.getdbt.com/reference/resource-configs/docs#mark-a-model-as-hidden "Direct link to Mark a model as hidden") models: - name: sessions__tmp docs: show: false ### Mark a subfolder of models as hidden[​](https://docs.getdbt.com/reference/resource-configs/docs#mark-a-subfolder-of-models-as-hidden "Direct link to Mark a subfolder of models as hidden") **Note:** This can also hide dbt packages. dbt\_project.yml models: # hiding models within the staging subfolder tpch: staging: +materialized: view +docs: show: false # hiding a dbt package dbt_artifacts: +docs: show: false Custom node colors[​](https://docs.getdbt.com/reference/resource-configs/docs#custom-node-colors "Direct link to Custom node colors") -------------------------------------------------------------------------------------------------------------------------------------- The `docs` attribute supports `node_color` to customize the display color of some node types in the DAG within [dbt Docs](https://docs.getdbt.com/docs/build/view-documentation) . You can define node colors in the following files and apply overrides where needed. * `node_color` hierarchy: * `` overrides `schema.yml` overrides `dbt_project.yml` Note, you need to run or re-run the `dbt docs generate` command to apply and view the customized colors. Custom node colors not applicable in Catalog The custom `node_color` attribute isn't applicable in Catalog. Instead, Explorer provides [lenses](https://docs.getdbt.com/docs/explore/explore-projects#lenses) , which are map layers for your DAG. Lenses help you better understand your project's contextual metadata at scale and distinguish specific models or subsets of models. Examples[​](https://docs.getdbt.com/reference/resource-configs/docs#examples-1 "Direct link to Examples") ---------------------------------------------------------------------------------------------------------- Add custom `node_colors` to models that support it within subdirectories based on hex codes or a plain color name. ![Example](https://docs.getdbt.com/assets/images/node_color_example-80b597978b6a0f15b6db30ce0d3375ed.png) `marts/core/fct_orders.sql` with `node_color: red` overrides `dbt_project.yml` with `node_color: gold` `marts/core/schema.yml` with `node_color: #000000` overrides `dbt_project.yml` with `node_color: gold` dbt\_project.yml models: tpch: staging: +materialized: view +docs: node_color: "#cd7f32" marts: core: materialized: table +docs: node_color: "gold" marts/core/schema.yml models: - name: dim_customers description: Customer dimensions table docs: node_color: '#000000' marts/core/fct\_orders.sql {{ config( materialized = 'view', tags=['finance'], docs={'node_color': 'red'} )}}with orders as ( select * from {{ ref('stg_tpch_orders') }} ),order_item as ( select * from {{ ref('order_items') }}),order_item_summary as ( select order_key, sum(gross_item_sales_amount) as gross_item_sales_amount, sum(item_discount_amount) as item_discount_amount, sum(item_tax_amount) as item_tax_amount, sum(net_item_sales_amount) as net_item_sales_amount from order_item group by 1),final as ( select orders.order_key, orders.order_date, orders.customer_key, orders.status_code, orders.priority_code, orders.clerk_name, orders.ship_priority, 1 as order_count, order_item_summary.gross_item_sales_amount, order_item_summary.item_discount_amount, order_item_summary.item_tax_amount, order_item_summary.net_item_sales_amount from orders inner join order_item_summary on orders.order_key = order_item_summary.order_key)select *from finalorder by order_date If a `node_color` is incompatible with dbt docs, you will see a compile error, as in the example below. Invalid color name for docs.node_color: aweioohafio23f. It is neither a valid HTML color name nor a valid HEX code. dbt\_project.yml models: tpch: marts: core: materialized: table +docs: node_color: "aweioohafio23f" Was this page helpful? ---------------------- YesNo [Privacy policy](https://www.getdbt.com/cloud/privacy-policy) [Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues) This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply. 0 * [Definition](https://docs.getdbt.com/reference/resource-configs/docs#definition) * [Default](https://docs.getdbt.com/reference/resource-configs/docs#default) * [Examples](https://docs.getdbt.com/reference/resource-configs/docs#examples) * [Mark a model as hidden](https://docs.getdbt.com/reference/resource-configs/docs#mark-a-model-as-hidden) * [Mark a subfolder of models as hidden](https://docs.getdbt.com/reference/resource-configs/docs#mark-a-subfolder-of-models-as-hidden) * [Custom node colors](https://docs.getdbt.com/reference/resource-configs/docs#custom-node-colors) * [Examples](https://docs.getdbt.com/reference/resource-configs/docs#examples-1) [Edit this page](https://github.com/dbt-labs/docs.getdbt.com/edit/current/website/docs/reference/resource-configs/docs.md) ---