Generate Models

​

Overview of the buster generate Command

The buster generate command automatically creates semantic models from your dbt catalog. This significantly reduces the time and effort required to set up your semantic layer, especially for projects with many tables.

​

Basic Usage

To generate semantic models from your dbt catalog:

buster generate [path] [--output-dir DIR]

Where:

• [path] is an optional path to your dbt catalog file
• --output-dir DIR specifies where to save the generated models

​

How It Works

The generate command:

1. Locates your dbt catalog.json file (either at the specified path or in the default location)
2. Parses the catalog to extract table schemas and column metadata
3. Intelligently determines whether each column should be a dimension or measure based on its data type
4. Creates YAML semantic model files following Buster’s best practices
5. Places these files either alongside your SQL files or in a specified output directory

​

Type Classification

The command uses these rules to classify your columns:

• Dimensions are created for:
  • String/text types
  • Date/time types (timestamp, date, time)
  • Boolean types
  • UUID types
  • Enum types
• Measures are created for:
  • Numeric types (integer, decimal, float)
  • Money types

Additionally, the command applies sensible defaults for:

• Identifying primary keys
• Setting appropriate aggregation types
• Adding searchable flags to common searchable fields

​

Command Options

The following options are available:

• --output-dir DIR: Save generated models to a specific directory
• --force: Overwrite existing models, even if they were manually modified
• --dry-run: Show what would be generated without writing files
• --verbose: Show detailed information about the generation process

​

Examples

​

Basic Generation

Generate models from the default dbt catalog location:

buster generate

​

Specify Catalog Path

Generate models from a specific dbt catalog file:

buster generate /path/to/catalog.json

​

Custom Output Directory

Save generated models to a specific directory:

buster generate --output-dir ./semantic_models

​

Handling Existing Models

When generating models for an existing project:

1. New Models: Created with sensible defaults
2. Existing Models: Updated while preserving your manual edits
   • New columns will be added as dimensions or measures
   • Existing dimension/measure definitions will be preserved
   • Custom metrics, filters, and relationships won’t be affected

This means you can safely regenerate models as your schema evolves without losing your customizations.

​

Output Example

A generated model file will look like this:

# models/orders.yml
models:
  - name: orders
    description: Orders table from data warehouse
    dimensions:
      - name: order_id
        description: Unique identifier for the order
        type: string
        primary_key: true
      - name: customer_id
        description: Foreign key to the customer
        type: string
      - name: order_date
        description: Date when the order was placed
        type: timestamp
      - name: status
        description: Current order status
        type: string
    measures:
      - name: total_amount
        description: Total amount of the order
        type: number
        agg: sum
      - name: item_count
        description: Number of items in the order
        type: integer
        agg: sum

​

Integration with buster init

When initializing a new project with buster init, you have the option to automatically generate semantic models from your dbt catalog as part of the setup process. This provides a seamless workflow from project initialization to having a functional semantic layer.

​

Best Practices

1. Initial Generation: Use buster generate when first setting up your semantic layer to quickly scaffold models.
2. Enrich Generated Models: After generation, enhance the models with:
   • More detailed descriptions
   • Custom metrics
   • Useful filters
   • Proper relationships between models
3. Regenerate When Schemas Change: Update your semantic models when new columns are added to your dbt models.

​

Next Steps

After generating your semantic models:

1. Review and enhance the generated models
2. Define relationships between models
3. Add metrics and filters
4. Deploy your project

​

Related Commands

• buster init - Initialize a new Buster project
• buster deploy - Deploy your project to the Buster platform
• Integrating with dbt - Learn more about Buster’s integration with dbt