> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hightouch.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create models using dbt models and analyses

> Connect Hightouch to your dbt project's Git repository and build Hightouch models using existing dbt models and analyses.

> [!NOTE]
>
> Now you can sync models from [dbt Cloud](https://docs.hightouch.com/extensions/dbt-cloud.md).

> [!NOTE]
>
> This extension requires a paid Hightouch plan

> [!WARNING]
>
> Hightouch can communicate with two distinct Git repository types. The dbt extension interacts with Git repositories that contain dbt projects. These are separate from the Git repository used for [Git Sync](https://docs.hightouch.com/extensions/git-sync.md) to version control your Hightouch settings.

If you've invested in building models with [dbt](https://www.getdbt.com/), you likely want to use those models as the source of truth for your downstream data needs. At Hightouch, we use dbt to build most of our models for analytics and reporting.

Our dbt integration lets you define Hightouch models using your dbt models and [analyses](https://docs.getdbt.com/docs/build/analyses).

![dbt-based models in Hightouch](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/integrations/dbt-models.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=af9c328e1e96576e76c8f579a814af26)

## Supported dbt versions

Hightouch supports dbt Core 1.10 and newer. You can set the version on the dbt setup page. If you need support for a version not listed, [let us know](#pylon-chat).

> [!NOTE]
>
> If you update your dbt version, return to Hightouch to update your dbt version selection. Once you've made the update, it may take up to 15 minutes for the changes to take effect.

## Connect to your Git repository

Navigate to the [dbt extension configuration](https://app.hightouch.com/extensions/dbt-models/configuration?from=docs) page and enter your Git credentials under **Credentials**.

If you're using GitHub, it's best to use [Hightouch's GitHub App](https://github.com/apps/hightouch-connect/) for the most up-to-date feature support.

To set it up, choose **GitHub App** as the **Git Service**, and then select **Configure GitHub App**.

![Hightouch GitHub app](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/integrations/dbt-models-git-credential-selection.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=bb467703294a42ba4a314990d73f1092)

This prompts you to install the Hightouch Connect app in the relevant GitHub repository.

For other Git services, you can choose to use either **SSH** or **HTTP** protocol. SSH protocol requires you provide an **SSH private key** and HTTP requires a **username** and **token**.

![Hightouch GitHub app](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/integrations/dbt-models-git-credentials-username-token.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=4e84d4d8c7167aae79caa141076b5a80)

See [GitHub documentation](https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token) or [GitLab documentation](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html) for instructions on creating personal access tokens.

## Connecting a source

You can use dbt models and analyses from your Git repository for any [source](https://app.hightouch.com/sources?from=docs) in Hightouch. On the [extensions configuration page](https://app.hightouch.com/extensions/dbt-models/configuration?from=docs), there is a list of sources from your workspace within Hightouch that can be connected to dbt models. Choose one that you would like to configure and click "Connect to dbt."

![Connect Source dbt](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/integrations/dbt-model-connect-source.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=ff52c112398f44ac4197762141c8a648)

## Configure dbt model selector

> [!TIP]
>
> When connecting dbt sources for the first time or making changes to your dbt model sync configuration, you usually only need to click **Save** and not **Full Resync** for Hightouch to create or update your configuration.
>
> The **Full Resync** action is only necessary when making significant changes in your dbt Git repository. It restarts the dbt compilation from a fresh state and can take a significant amount of time. After clicking this button, wait for the updated dbt models to compile before making any changes to your configuration.

The default schema is the schema where dbt [materializes](https://docs.getdbt.com/docs/build/materializations) your tables to unless otherwise specified in project file. Some common examples are `public`, `production`, `dbt_production`.

Hightouch lets you optionally specify [dbt selectors](https://docs.getdbt.com/reference/node-selection/syntax#examples) like `tag:hightouch`. Otherwise, we use `*` and sync *all* dbt models to Hightouch.

You can also specify which version of dbt you want to use. By default, Hightouch uses the most recent version available in the drop-down menu.

Hightouch's dbt integration automatically looks for your `dbt_project.yml` file in the repository directory. If your project file is named something else, for example, `dbt_project.yaml`, or you have multiple `dbt_project.yml` files, you can specify a relative path to your project file, for example, `./hightouch/dbt/dbt_project.yaml`.

> [!NOTE]
>
> After saving your settings, it may take a one to two minutes for Hightouch to sync your dbt models and for the sync status to turn green.

## Select a model

Once you've configured the dbt model selector, you can use dbt models and analyses in the Hightouch [model creation process](https://docs.hightouch.com/models/creating-models.md). Select the dbt model tab in the query explorer to view all your available dbt models and analyses.

![dbt model selection](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/integrations/dbt-models-selector.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=2d2876ab13733e1ba019dd7701c7d395)

The compiled SQL shown in the preview is what's ran against your source. We do not leverage the output table written by dbt.

### Model column descriptions

Hightouch pulls in column descriptions from dbt.
You can see them in the **Columns** tab of a model's overview page.

![Column descriptions in the Hightouch app](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/models/column-descriptions.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=0620db07f37203cf666f4aa79db98607)

## Unsupported features

Hightouch doesn't support the following features:

* Private dependency packages
* Pre- and post-hooks (limited support, this may work depending on the hook)
* [Python models](https://docs.getdbt.com/docs/build/python-models)

Hightouch compiles the project using `dbt compile` to resolve your data warehouse's schema and generate compiled SQL for preview purposes. When running the model in Hightouch, we query the materialized table directly.

## dbt model advantages

When deciding between Hightouch's [table selector](https://docs.hightouch.com/models/table-selector.md) and our [dbt model selector](https://docs.hightouch.com/extensions/dbt-models.md), the advantages of leveraging dbt models might not be immediately clear, since many dbt models are often materialized as tables and views in a [Source](https://docs.hightouch.com/getting-started/concepts.md#sources).

However, there are a few key benefits of building Hightouch Models using the dbt model selector:

* It provides a clean, information-rich modal with metadata about the underlying model, including its unique ID, description, and repository link.
* It allows you to automatically pull in [column descriptions](https://docs.hightouch.com/extensions/dbt-models.md#model-column-descriptions) into Hightouch for data governance/organization.
* It allows you to leverage our [dbt observability layer](https://docs.hightouch.com/extensions/dbt-observability.md), which includes dbt exposures and CI checks.
* Not all dbt resources materialize as tables/views in the warehouse. For example, dbt analyses will not form tables/views at all.

## dbt observability layer

Hightouch lets you [validate dbt model changes](https://docs.hightouch.com/extensions/dbt-observability.md#dbt-ci-checks) as they relate to Hightouch syncs and observe [how Hightouch syncs are using your dbt models](https://docs.hightouch.com/extensions/dbt-observability.md#dbt-exposure-sync). Check out our [dbt observability layer documentation](https://docs.hightouch.com/extensions/dbt-observability.md) for more information.

## Tips and troubleshooting

If you run into an issue this page doesn't cover, [contact support](#pylon-chat).

> [!TIP]
>
> Hightouch compiles the project using [`dbt compile`](https://docs.getdbt.com/reference/commands/compile) to resolve your data warehouse's schema and generate compiled SQL for your model. If you encounter error messages on your dbt extension configuration page, try running [`dbt compile`](https://docs.getdbt.com/reference/commands/compile) locally on your dbt project to see if the errors still occur.

### Credential errors

If your Git credentials are out of date, you won't be able to connect your dbt models and analyses.
We recommend using [Hightouch's GitHub app](#connecting-to-your-git-repository) for your credentials if you're using GitHub.

### Duplicated mapping key error

You may receive a `duplicated mapping key` error under your dbt model sync status if there are duplicate keys in your `dbt_project.yml` file.
To resolve the error, you can either remove the duplicates or rename duplicated keys.

### The YAML property file is missing a version tag

This dbt compilation error can occur if you use the same Git repository for [Git Sync](https://docs.hightouch.com/extensions/git-sync.md) and [dbt models sync](#configure-dbt-model-selector).
To solve this, make sure that you're using two different Git repositories for these extensions.
Otherwise, if you would like to use the same repository, you can specify a custom path in the [Git Sync configuration](https://docs.hightouch.com/extensions/git-sync.md#configure-git-sync).

![the YAML property file is missing a version tag](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/integrations/dbt-models-version-tag.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=6e26a85bf8d6cf121378161b70d71a2e)