Workflow

Overview

Building a semantic layer with Bonnard follows a development workflow: initialize a project, connect data sources, define cubes and views, validate, and deploy.

Quick Start

# 1. Initialize project
bon init

# 2. Add a data source
bon datasource add

# 3. Create cubes in bonnard/cubes/ and views in bonnard/views/

# 4. Validate
bon validate

# 5. Deploy to Bonnard
bon deploy

Project Structure

After bon init, your project has:

my-project/
├── bon.yaml              # Project configuration
├── bonnard/              # Semantic layer definitions
│   ├── cubes/            # Cube definitions
│   │   └── orders.yaml
│   └── views/            # View definitions
│       └── orders_overview.yaml
└── .bon/                 # Local config (gitignored)
    └── datasources.yaml  # Data source credentials

Development Cycle

1. Define Cubes

Create cubes that map to your database tables:

# bonnard/cubes/orders.yaml
cubes:
  - name: orders
    sql_table: public.orders

    measures:
      - name: count
        type: count

    dimensions:
      - name: status
        type: string
        sql: status

2. Define Views

Create views that expose cubes to consumers:

# bonnard/views/orders_overview.yaml
views:
  - name: orders_overview
    cubes:
      - join_path: orders
        includes:
          - count
          - status

3. Validate

Check for syntax errors and test connections:

bon validate
bon validate --test-connection

4. Deploy

Push cubes and views to Bonnard:

bon deploy

File Organization

One Cube Per File

bonnard/cubes/
├── orders.yaml
├── users.yaml
├── products.yaml
└── line_items.yaml

bonnard/cubes/
├── sales/
│   ├── orders.yaml
│   └── line_items.yaml
├── users/
│   ├── users.yaml
│   └── profiles.yaml
└── products/
    └── products.yaml

Best Practices

Start simple — begin with one cube, add complexity gradually
Validate often — run bon validate after each change
Use version control — commit cubes and views to git
Document with descriptions — add description to measures/dimensions
Test with queries — verify models produce expected results

Commands Reference

Command	Description
`bon init`	Create project structure
`bon datasource add`	Add a data source
`bon datasource list`	List configured sources
`bon datasource test <name>`	Test connection
`bon validate`	Check cube and view syntax
`bon deploy`	Deploy to Bonnard
`bon docs`	Browse documentation