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

# dbt

> Connect 4MINDS to dbt to import model, source, and test metadata for AI-powered analysis

## Overview

The 4MINDS platform integrates with **dbt** (dbt Cloud), letting you import your project's metadata — model definitions, sources, tests, exposures, and account structure — directly into your 4MINDS models. This makes your dbt project's semantic layer available for AI-powered querying, knowledge graph construction, and retrieval.

4MINDS supports two ways to connect:

| Method            | Best for                                                       | What it can access                                                                |
| ----------------- | -------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| **OAuth**         | Read-only, no long-lived secret to manage, tokens auto-refresh | Models, sources, tests, exposures, and account structure (projects, environments) |
| **Service Token** | Full read access, including job runs and run artifacts         | Everything OAuth can, **plus** job listings and the raw run **manifest**          |

> Both methods are read-only against your dbt account. OAuth cannot list jobs or import a run manifest — those operations require a service token.

***

## Getting Started

### Prerequisites

* A dbt Cloud account
* Your account's **Access URL** and numeric **Account ID** (see [Finding your Access URL and Account ID](#finding-your-access-url-and-account-id))
* A 4MINDS account with access to the Integrations page
* For **OAuth**: your dbt account must allow OAuth app registration (App integrations). No manual setup is required — 4MINDS registers itself automatically (see below). App integrations may require an Enterprise-tier dbt plan.
* For **Service Token**: permission to create a service token in dbt

### Finding your Access URL and Account ID

Both connection methods need these two values:

* **Access URL** — your dbt account's base URL. For multi-tenant accounts this is `https://cloud.getdbt.com`. Cell-based or single-tenant accounts use a URL like `https://abc123.us1.dbt.com`. You can find it in dbt under **Account Settings**.
* **Account ID** — the numeric account identifier. It appears in your dbt URL (for example, `https://cloud.getdbt.com/settings/accounts/12345` → the Account ID is `12345`) and in **Account Settings**.

***

## Option 1 — Connect with OAuth

OAuth is the recommended method for read-only metadata access. 4MINDS never stores a long-lived secret, and access tokens are refreshed automatically.

**No manual setup in dbt is required.** 4MINDS registers itself automatically using your account's OAuth app registration (RFC 7591 Dynamic Client Registration), so there's no integration to add or Redirect URI to configure by hand. When you connect, a read-only client named **4MINDS** is created on your dbt account — you'll see it under **Account Settings → Integrations** in the **Dynamically registered** list.

### Connect from 4MINDS

1. Sign in to [4MINDS](https://app.4minds.ai).
2. Navigate to the **Integrations** page from the main navigation bar.
3. Locate the **dbt** integration card and click on it.
4. Choose the **OAuth** tab.
5. Enter your **Access URL** and **Account ID**.
6. Click **Connect with dbt**. A popup opens dbt's authorization screen.
7. Sign in to dbt (or use an existing session) and approve the requested read-only access.
8. Once authorized, the popup closes and the connection is established.

> If the popup is blocked, enable popups for the 4MINDS site in your browser and try again.

> If your dbt account has OAuth app registration disabled, the connect attempt will report that app integrations aren't enabled. Ask a dbt admin to enable App integrations under **Account Settings → Integrations**, or connect with a service token instead.

### OAuth scopes

When you connect via OAuth, 4MINDS requests only read-only scopes:

| Scope            | Description                                                                   |
| ---------------- | ----------------------------------------------------------------------------- |
| `offline_access` | Issues a refresh token so 4MINDS can renew access without prompting you again |
| `account:read`   | Read account structure — projects and environments                            |
| `catalog:read`   | Read the project catalog — models, sources, tests, and exposures              |

***

## Option 2 — Connect with a Service Token

Use a service token if you need full read access, including listing jobs and importing a run's **manifest**.

### Step 1 — Create a service token in dbt

1. In dbt, go to **Account Settings → Service tokens** (on some accounts this is under **API Access**).

2. Click **Create service token** (or **New token**).

3. Give it a name — for example, `4MINDS`.

4. Assign **permission sets**. 4MINDS reads from two different dbt APIs, so a token needs coverage for both:

   | Permission set                                                                       | Why it's needed                                                                     | Enables data types                     |
   | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- | -------------------------------------- |
   | **Metadata Only**                                                                    | Read the Discovery / Metadata (GraphQL) API                                         | Models, Sources, Tests, Exposures      |
   | **Job Admin** (or a read-only account set, such as **Account Viewer** on Enterprise) | Read the Administrative API — projects, environments, jobs, runs, and run artifacts | Metadata (account structure), Manifest |

   Assign **both** sets to the same token. Metadata Only alone does not grant Administrative API access, and an admin/job set alone does not grant Discovery access. 4MINDS only ever reads — no write permission is required.

5. Save the token and **copy it immediately** — dbt shows the token value only once.

> The exact permission-set names and their availability depend on your dbt plan. If your plan doesn't expose these granular sets, a broader read-capable set (e.g. Account Admin) also works, but least-privilege (Metadata Only + a read-only job/account set) is recommended.

> Store the token securely. Anyone with the token can read from your dbt account within the granted permission set.

### Step 2 — Connect from 4MINDS

1. Sign in to [4MINDS](https://app.4minds.ai) and open the **Integrations** page.
2. Click the **dbt** integration card.
3. Choose the **Service Token** tab.
4. Enter your **Access URL**, **Account ID**, and the **Service Token** you created.
5. Click **Test Connection** to verify the credentials, then **Save Credentials**.

***

## Disconnecting

To disconnect dbt, open **Integrations** from the main navigation bar, find dbt, and click **Disconnect**. This removes your stored credentials (and, for OAuth, your tokens) from 4MINDS.

***

## Available Data Types

The following dbt data types can be imported into 4MINDS:

| Data Type     | Description                                                               | OAuth | Service Token |
| ------------- | ------------------------------------------------------------------------- | :---: | :-----------: |
| **Models**    | Model definitions — relation, materialization, description, tags, columns |   ✅   |       ✅       |
| **Sources**   | Source definitions — relation, description, freshness                     |   ✅   |       ✅       |
| **Tests**     | Data test definitions — column, type, last run status                     |   ✅   |       ✅       |
| **Exposures** | Exposure definitions — type, owner, maturity, downstream asset            |   ✅   |       ✅       |
| **Metadata**  | Account structure — projects, environments, and jobs                      |   ✅   |       ✅       |
| **Manifest**  | Raw `manifest.json` from the most recent run of a dbt job                 |   —   |       ✅       |

> Listing jobs and importing a run **manifest** are not available over OAuth (read-only scopes). Connect with a service token to use them.

***

## Importing Data

### Creating a Model with dbt Data

1. Navigate to the **Models** page and click **Create Model**.
2. Provide a **name** and **use case** for the model (e.g., "dbt Catalog" / "Analyze our dbt project metadata"). Press **Next**.
3. On the **Upload Data** step, select the **Integrations** option.
4. Scroll to the **Enterprise** group and choose **dbt**.
5. Select the data types you'd like to import (models, sources, tests, exposures, metadata).
6. Confirm the import and create the model.

Once processing completes, the dataset is available for AI-powered querying, knowledge graph construction, and retrieval on the **Models** page.

### Querying Your Data

1. Find the model you created on the **Models** page.
2. Click the **Run** button.
3. On the chat interface, send a prompt or query to get AI-generated responses about your dbt project.

***

## Troubleshooting

| Issue                                                        | Solution                                                                                                                                                                                  |
| ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **"No dbt connection found"**                                | Open Integrations from the main nav and connect your dbt account via OAuth or a service token.                                                                                            |
| **OAuth authorization fails / lands on the dbt home screen** | Re-check the Access URL and Account ID, then try connecting again. 4MINDS registers a fresh OAuth client on each attempt, so a simple retry resolves most transient authorization errors. |
| **"Your dbt account hasn't enabled OAuth app integrations"** | Your dbt account blocks OAuth app registration. Ask a dbt admin to enable App integrations under **Account Settings → Integrations**, or connect with a service token instead.            |
| **Popup blocked during OAuth**                               | Enable popups for the 4MINDS site in your browser settings, then try again.                                                                                                               |
| **Service token rejected**                                   | Re-check the Access URL, Account ID, and token. Ensure the token's permission set grants read access and that the token hasn't been revoked.                                              |
| **Jobs or manifest import unavailable**                      | These require a service token — reconnect using the Service Token option.                                                                                                                 |
| **Connection expired (OAuth)**                               | 4MINDS refreshes OAuth tokens automatically. If issues persist, disconnect and reconnect.                                                                                                 |

***

## Security & Privacy

* **Read-only:** Both connection methods only read from your dbt account.
* **OAuth 2.0 with PKCE:** OAuth connections use industry-standard OAuth 2.0 with PKCE. 4MINDS stores no long-lived secret for OAuth.
* **Encrypted at rest:** Service tokens and OAuth tokens are encrypted at rest.
* **Automatic token refresh:** OAuth tokens are refreshed automatically before they expire.
* **Per-user access:** Each user connects their own dbt account; connections are not shared across users.

***

## FAQ

**Q: Should I use OAuth or a service token?** A: Use OAuth for read-only metadata (models, sources, tests, exposures, account structure) with no secret to manage. Use a service token if you also need to list jobs or import a run manifest.

**Q: Do I need to set up the OAuth integration in dbt first?** A: No. 4MINDS registers itself automatically via Dynamic Client Registration when you connect — there's no integration to add or Redirect URI to configure. The dbt account just needs OAuth app registration (App integrations) enabled. The registered client appears under **Account Settings → Integrations** as **4MINDS** in the **Dynamically registered** list.

**Q: Where do I find my Access URL and Account ID?** A: In dbt under **Account Settings**. The Account ID also appears as the number in your dbt account URL.

**Q: Can I switch from a service token to OAuth (or vice versa)?** A: Yes. Disconnect the current connection, then reconnect using the other method.

**Q: What happens to imported data if I disconnect?** A: Previously imported data remains in your models. You won't be able to import new data from dbt until you reconnect.