Quickstart

This guide walks you through setting up Buster with an existing dbt project. Buster is designed to work with dbt, leveraging your existing models and catalog to create a powerful semantic layer.

Buster works best with well-structured data models from dbt. If you already have a dbt project, Buster will automatically detect and use existing models to build a semantic layer for your data.

VIDEO HERE

​

Step 1: Install the CLI

brew tap buster-so/buster
brew install buster

​

Step 2: Initialize Your Project & Connect Data Source

Let’s initialize your Buster project and connect to your data source in one step using the buster init command:

buster init

This interactive command:

1. Asks you to select your data warehouse type (Postgres, BigQuery, Snowflake, etc.)
2. Prompts for connection details like host, port, credentials, etc.
3. Tests the connection to ensure everything works
4. Detects dbt project configurations if present
   • Recognizes your dbt project structure
   • Finds model paths automatically
   • Discovers your dbt catalog for semantic model generation
5. Creates a buster.yml file with your project configuration:

projects:
  - path: .
    data_source_name: demo_db
    schema: analytics
    database: buster
    model_paths:
      - models
    semantic_model_paths:
      - semantic_models  # Optional path for semantic model YAML files

The command handles both project initialization and data source onboarding in a single workflow, making setup much easier.

See our Data Sources guide for specific database connection instructions and our Init Command documentation for more details on the setup process.

​

Step 3: Create Semantic Models

If you didn’t generate semantic models during initialization, you can create them now. These YAML files define how Buster understands your data. Use the buster generate command to automatically create them from your dbt catalog:

buster generate

Buster analyzes your SQL models (like the examples below) and creates semantic model files for each one:

-- Example model: models/page_views.sql
WITH base_page_views AS (
    SELECT * FROM {{ ref('stg_page_views') }}
),
users AS (
    SELECT user_id, user_created_at FROM {{ ref('users') }}
)
SELECT
    bpv.view_id,
    bpv.user_id,
    bpv.product_id,
    bpv.timestamp AS view_timestamp,
    bpv.url,
    bpv.view_duration_seconds,
    (bpv.timestamp <= TIMESTAMP_ADD(u.user_created_at, INTERVAL 7 DAY)) AS viewed_within_7_days_of_signup
FROM
    base_page_views bpv
LEFT JOIN
    users u ON bpv.user_id = u.user_id

-- Example model: models/users.sql
SELECT
    user_id,
    email,
    created_at AS user_created_at,
    country,
    total_purchase_amount AS lifetime_value
FROM
    {{ ref('stg_users') }}

These semantic model files add business context to your SQL models. Buster will create a separate YAML file for each model:

# models/users.yml
name: users
  description: Information about registered users.
  
  dimensions:
    - name: user_id
      description: Unique identifier for the user.
      type: string
    
    - name: email
      description: User's email address.
      type: string
    
    - name: user_created_at
      description: Timestamp when the user account was created.
      type: timestamp
      searchable: true
    
    - name: country
      description: The country the user is registered in.
      type: string
  
  measures:
    - name: lifetime_value
      description: Total purchase amount attributed to the user in USD.
      type: number
  
  relationships:
    - name: page_views
      primary_key: user_id
      foreign_key: user_id
      cardinality: one-to-many
      description: Page views generated by this user.

Note that each model is defined as an item in a list (with a leading dash), and Buster creates separate YAML files for each model instead of grouping them under a models: key.

​

Step 4: Deploy Your Project

Once your data models and semantic layer are ready, deploy your project:

buster deploy

This command publishes your semantic models to the Buster platform, making them available for natural language querying.

​

Step 5: Start Analyzing Your Data

Congratulations! You’ve successfully built and deployed your first Buster project. You can now use natural language to analyze your data through the Buster interface.