​
Overview

Buster is designed to seamlessly integrate with dbt (data build tool) projects, allowing you to leverage your existing data models and transform them into semantic models with minimal effort. This integration creates a powerful workflow that combines dbt’s transformation capabilities with Buster’s AI-powered analytics.

​
How the Integration Works

The Buster CLI offers native integration with dbt that works through these key mechanisms:

​
1. Project Discovery

When you run buster init in a directory containing a dbt project:

  • Buster automatically detects the presence of dbt_project.yml
  • It uses the dbt project name as the default data source name
  • It identifies model paths based on your dbt project configuration
  • It configures database connections using settings from your dbt profiles
  • It can optionally generate initial semantic models from your dbt catalog
# Automatically detects dbt project settings and optionally generates semantic models
buster init

​
2. Catalog Utilization

Both buster init and buster generate use dbt’s catalog.json as the source of truth for your data models:

  • They look for existing catalog.json files generated by dbt docs generate
  • If no catalog exists, they can trigger the catalog generation for you
  • The catalog provides comprehensive metadata about your models, columns, and documentation
# Generate semantic models from dbt catalog
buster generate

​
3. Semantic Model Generation

When transforming dbt models into Buster semantic models:

  • Each dbt model becomes a semantic model in Buster
  • Column types are intelligently mapped to dimensions or measures:
    • Numeric columns become measures with appropriate aggregations
    • Text, date, boolean columns become dimensions
  • Descriptions from dbt are preserved in the semantic layer
  • Primary keys and relationships are inferred where possible

​
Setup Process

To set up a Buster project with your existing dbt project:

  1. Navigate to your dbt project directory:

    cd your-dbt-project

  2. Initialize your Buster project:

    buster init

    The CLI will:

    • Automatically detect your dbt project
    • Suggest appropriate settings
    • Optionally generate initial semantic models from your dbt catalog

  3. Generate or update semantic models:

    buster generate

    This command:

    • Can be run at any time to update semantic models
    • Is useful when adding new models or columns
    • Preserves existing customizations while adding new elements
    • Will generate the dbt catalog if it doesn’t exist

​
Directory Structure Integration

Buster is flexible in how it integrates with your dbt directory structure:

your-dbt-project/
├── dbt_project.yml
├── models/
│   ├── marts/
│   │   └── core/
│   │       ├── orders.sql
│   │       └── orders.yml  # dbt YAML
│   └── staging/
│       └── ...
├── buster.yml              # Created by buster init
└── semantic_models/        # Created by buster generate
    ├── marts/
    │   └── core/
    │       └── orders.yml  # Buster semantic model
    └── staging/
        └── ...

You can choose to:

  • Generate semantic models alongside your SQL files
  • Use a separate directory for semantic models
  • Customize paths to fit your project structure

​
Updating Models

When your dbt models change:

  1. Generate updated semantic models:

    buster generate

    This preserves your custom enhancements while adding new columns or models.

  2. Deploy your updated models:

    buster deploy

​
Debugging dbt Integration

If you encounter issues with the dbt integration:

  • If dbt docs generate isn’t working, try running dbt clean first to ensure your dbt catalog is up-to-date
  • Check that your dbt profiles.yml has valid database credentials
  • Review the schema and database settings in both dbt and Buster configurations