# dbt

[dbt](https://www.getdbt.com/) helps data teams model and transform analytical data. Use the Altertable adapter to run dbt models directly in your Altertable lakehouse. You can also [connect a dbt repository](#sync-project-knowledge) to make project definitions, lineage, and semantic metadata available to Altertable and its agents.

## Installation

For a worked example of organizing raw data, transformations, and marts, follow the [medallion architecture guide](/docs/lakehouse/modeling/medallion-architecture.md).

The Altertable adapter for dbt is available on PyPI and currently requires Python `3.10+` with `dbt-core >=1.8,<2.0`.

```bash
pip install dbt-altertable
```

If you manage Python dependencies with `uv`, you can install it with:

```bash
uv add dbt-altertable
```

## Configuration

Add an Altertable profile to your `profiles.yml` file. By default, dbt looks for profiles in `~/.dbt/profiles.yml`, but you can also place it in your project directory or specify a custom location using the `--profiles-dir` flag. Learn more about [dbt profiles](https://docs.getdbt.com/docs/local/profiles.yml) in the dbt documentation.

### Profile Example

```yaml
your_project_name:
  target: dev
  outputs:
    dev:
      type: altertable
      username: {{LAKEHOUSE_USERNAME}}
      password: {{LAKEHOUSE_PASSWORD}}
      database: your_catalog_name
      schema: your_schema_name
      compute_size: XL
```

### Configuration Parameters

- **type**: Must be set to `altertable` (required)
- **username**: Your lakehouse username (required) — find this in the [Credentials](/docs/administration/lakehouse-credentials.md) section of the dashboard
- **password**: Your lakehouse password (required) — find this in the [Credentials](/docs/administration/lakehouse-credentials.md) section of the dashboard
- **database**: The name of your [Altertable catalog](/docs/lakehouse/catalogs.md) where models will be materialized (required)
- **schema**: The schema within your catalog where models will be created (required)
- **compute\_size**: Optional compute size for your workload. Omit it to use the server default.

## Usage

Once configured, you can run dbt commands against Altertable:

```bash
# Test your connection
dbt debug

# Run your models
dbt run

# Test your models
dbt test

# Generate and serve documentation
dbt docs generate
dbt docs serve
```

Learn more about [dbt commands](https://docs.getdbt.com/reference/dbt-commands) in the dbt documentation.

## Sync project knowledge

Connect your dbt project as a [knowledge repository](/docs/agents/knowledge/entries.md). Altertable detects `dbt_project.yml` at the repository root or in a subdirectory and turns project source files into searchable knowledge entries. A repository can contain multiple dbt projects.

In **Knowledge**, select **New knowledge**, choose **Repository**, and connect your GitHub or GitLab account. Choose the repository and branch, then select **Add repository**. Leave the branch empty to use the repository's default branch.

### Which files need to be committed?

For Git-based sync, commit your dbt project source files to the connected branch. Include the artifacts below for lineage, model enrichment, and generated metric definitions. [Contact us](mailto:contact@altertable.ai) if you need to sync artifacts from a bucket.

| File                                                                                       | Purpose                                                                     |
| ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------- |
| `dbt_project.yml` and project source files                                                 | Detect the project and extract knowledge from SQL, YAML, and documentation. |
| `target/manifest.json`                                                                     | Add model lineage and enrich existing semantic models with dbt metadata.    |
| [`target/semantic_manifest.json`](https://docs.getdbt.com/reference/artifacts/sl-manifest) | Make generated metric and semantic definitions available as knowledge.      |

Repository sync does not run dbt to generate artifacts. Without a valid `manifest.json`, Altertable still extracts knowledge from the source files, but skips manifest-based lineage and semantic model enrichment.

### Generate and refresh the artifacts

From the directory containing `dbt_project.yml`, install project dependencies and [parse the project](https://docs.getdbt.com/reference/commands/parse). Use the target whose catalog and schema names match the data you want to describe in Altertable. Replace `prod` with that target's name in your dbt profile:

```bash
dbt deps
dbt parse --target prod
git add -f target/manifest.json target/semantic_manifest.json
git commit -m "docs(dbt): refresh project artifacts"
git push
```

Commit both artifacts under `target/` relative to `dbt_project.yml`.

After pushing, select **Sync now** from the repository menu. Regenerate and commit the artifacts when your dbt project changes.

### Enrich existing semantic models

With a valid `manifest.json`, Altertable can update existing [semantic models](/docs/agents/knowledge/semantic-layer.md) with dbt descriptions, column metadata, supported measures and dimensions, and relationships derived from entities. It matches each dbt model to an existing Altertable model by catalog, schema, and table name, using the dbt alias when configured. This enrichment does not materialize tables or create missing semantic models.

Metric definitions remain available as knowledge even when this enrichment cannot import them as native measures. For example, filtered simple metrics are not imported as unfiltered Altertable measures.

## Run dbt in a task

> **Beta:**
>
> dbt tasks are available in beta. Their setup and behavior may change as the implementation evolves.

A **dbt task** runs a project from a [connected repository](#sync-project-knowledge) in an isolated environment and writes its models to an Altertable catalog. Altertable supplies the dbt profile, so the task needs no `profiles.yml` or credentials. Creating one requires [permission](/docs/administration/access-control.md) to manage catalogs.

Open **Tasks → New task** and choose **dbt task** under **Set up manually**:

1. Under **Project**, select the **Repository**. Set **Project directory** when `dbt_project.yml` is not at the repository root, and optionally a **Git ref**.
2. Under **Command**, choose `build`, `run`, or `source freshness`, and enter a **Selector** such as `tag:daily`.
3. Under **Destination**, choose the **Catalog** and **Schema** to write models to.
4. Set a **Schedule**, then select **Create dbt run**.

## SQL Dialect

Altertable uses DuckDB as its query engine, so write models with DuckDB-compatible functions, syntax, and data types. The adapter builds on `dbt-duckdb` and automatically dispatches `duckdb__` macros from your project and installed packages.

Learn more about [DuckDB SQL](https://duckdb.org/docs/sql/introduction) in the DuckDB documentation.

## MetricFlow

The adapter can run dbt Semantic Layer and MetricFlow workloads by rendering MetricFlow SQL with DuckDB-compatible syntax. Keep your semantic models in dbt as usual, then run MetricFlow against the same Altertable profile.

This works best when your metrics use DuckDB-compatible functions and data types. If a metric relies on warehouse-specific SQL, adapt the expression to DuckDB SQL before running it on Altertable.

## Seeds

By default, `dbt seed` inserts rows in batches so seeds work reliably across local files and remote execution. When you want a direct DuckDB `COPY` path for a local seed file, set the seed config `fast: true`.

```yaml
seeds:
  your_project_name:
    +fast: true
```

Use the default batched path unless you know the seed file is accessible from the process running dbt.

## Incremental models

The adapter supports `delete+insert`, `merge`, and sequential `microbatch` incremental strategies. With `delete+insert`, configure a stable `unique_key` so each run deletes matching destination rows before inserting the updated batch:

```sql
{{ config(
    materialized='incremental',
    incremental_strategy='delete+insert',
    unique_key='id'
) }}

SELECT *
FROM {{ source('app', 'orders') }}
{% if is_incremental() %}
WHERE updated_at > (SELECT max(updated_at) FROM {{ this }})
{% endif %}
```

Each dbt connection uses an isolated Flight session, so concurrent model work does not share temporary session state.

For more information about incremental strategies and adapter configuration, see the [dbt documentation](https://docs.getdbt.com/docs/build/incremental-models) and the [Altertable dbt adapter](https://github.com/altertable-ai/dbt-altertable).

## Persisting descriptions

The adapter supports dbt's [`persist_docs`](https://docs.getdbt.com/reference/resource-configs/persist_docs) setting for model and column descriptions.

Enable it in `dbt_project.yml` or on a model:

```yaml
models:
  your_project_name:
    +persist_docs:
      relation: true
      columns: true
```

After `dbt run`, dbt writes model and column descriptions to Altertable with DuckDB `COMMENT ON TABLE` and `COMMENT ON COLUMN` statements. View column comments are skipped gracefully when DuckDB cannot apply them.

## Source Code

The adapter source code is available at [github.com/altertable-ai/dbt-altertable](https://github.com/altertable-ai/dbt-altertable)