Altertable

dbt

dbt helps data teams model and transform analytical data. Use the Altertable adapter to run dbt models directly in your Altertable lakehouse.

Installation

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

pip install dbt-altertable

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

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 in the dbt documentation.

Profile Example

1
2
3
4
5
6
7
8
9
your_project_name:
  target: dev
  outputs:
    dev:
      type: altertable
      username: your_lakehouse_username
      password: your_lakehouse_password
      database: your_catalog_name
      schema: your_schema_name

Configuration Parameters

type: Must be set to altertable (required)
username: Your lakehouse username (required) — find this in the Credentials section of the dashboard
password: Your lakehouse password (required) — find this in the Credentials section of the dashboard
database: The name of your Altertable catalog where models will be materialized (required)
schema: The schema within your catalog where models will be created (required)

Usage

Once configured, you can run dbt commands against Altertable:

1
2
3
4
5
6
7
8
9
10
11
12
# 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 in the dbt documentation.

SQL Dialect

Altertable uses DuckDB as its query engine, so all SQL queries in your dbt models must use DuckDB-flavored SQL. This includes using DuckDB's functions, syntax, and data types.

Learn more about DuckDB SQL 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.

1
2
3
seeds:
  your_project_name:
    +fast: true

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

Persisting descriptions

The adapter supports dbt's persist_docs setting for model and column descriptions.

Enable it in dbt_project.yml or on a model:

1
2
3
4
5
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