​
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
buster init
# Automatically detects dbt project settings

​
2. Catalog Utilization

Buster uses dbt’s catalog.json as the source of truth for your data models:

  • It looks for existing catalog.json files generated by dbt docs generate
  • If no catalog exists, Buster can trigger the catalog generation for you
  • The catalog provides comprehensive metadata about your models, columns, and documentation
# Buster uses this catalog data
dbt docs generate
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. Ensure you have a current dbt catalog:

    dbt docs generate

    This creates/updates the catalog.json file that Buster will use.

  3. Initialize your Buster project:

    buster init

    The CLI will automatically detect your dbt project and suggest appropriate settings.

  4. Generate semantic models:

    buster generate

    This transforms your dbt models into Buster semantic models.

​
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. Update your dbt models and run your dbt pipeline:

    dbt run
dbt docs generate  # Update the catalog

  2. Regenerate or update your semantic models:

    buster generate

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

  3. Deploy your updated models:

    buster deploy

​
Debugging dbt Integration

If you encounter issues with the dbt integration:

  • Ensure your dbt catalog is up-to-date with dbt docs generate
  • Check that your dbt profiles.yml has valid database credentials
  • Review the schema and database settings in both dbt and Buster configurations

​
Example Workflow

Here’s an example of a complete workflow integrating dbt and Buster:

# 1. Update your dbt models
vim models/marts/core/orders.sql

# 2. Run your dbt pipeline
dbt run --select orders
dbt test --select orders
dbt docs generate

# 3. Update your semantic models
buster generate

# 4. Enhance your semantic models with custom metrics
vim semantic_models/marts/core/orders.yml

# 5. Deploy to Buster
buster deploy

​
Benefits of Integration

The integration between Buster and dbt provides several advantages:

  • No Duplicate Work: Leverage existing dbt models and their documentation
  • Automatic Updates: Keep your semantic layer in sync with schema changes
  • Consistent Naming: Maintain consistency between transformation and semantic layers
  • Familiar Workflow: Use tools that complement your existing data engineering practices
  • Version Control: Keep both dbt and Buster models in the same repository

​
Next Steps

After setting up the integration:

  1. Enhance your generated semantic models with metrics and relationships
  2. Deploy your semantic layer with buster deploy
  3. Start asking questions of your data using Buster’s AI capabilities