@bonnard/cli 0.1.2 → 0.1.4

package/dist/docs/topics/views.md

@@ -0,0 +1,142 @@
+# views
+
+> Compose cubes into focused interfaces for specific use cases.
+
+## Overview
+
+Views are facades that expose selected measures and dimensions from one or more cubes. They define which data is available to consumers, control join paths, and organize members into logical groups.
+
+## Example
+
+```yaml
+views:
+  - name: orders_overview
+    cubes:
+      - join_path: orders
+        includes:
+          - count
+          - total_revenue
+          - status
+          - created_at
+
+      - join_path: orders.users
+        includes:
+          - name: name
+            alias: customer_name
+          - email
+```
+
+## Core Properties
+
+| Property | Required | Description |
+|----------|----------|-------------|
+| `name` | Yes | Unique identifier in snake_case |
+| `cubes` | Yes | List of cubes and their exposed members |
+| `folders` | No | Organize members into groups |
+| `title` | No | Human-readable display name |
+| `description` | No | Documentation for consumers |
+| `public` | No | Whether exposed in API (default: true) |
+
+## Why Use Views?
+
+### 1. Simplify Data Access
+
+Expose only relevant members instead of entire cubes:
+
+```yaml
+views:
+  - name: sales_dashboard
+    cubes:
+      - join_path: orders
+        includes:
+          - count
+          - total_revenue
+        excludes:
+          - internal_notes
+          - debug_flags
+```
+
+### 2. Control Join Paths
+
+Define explicit paths through your data model:
+
+```yaml
+views:
+  - name: customer_orders
+    cubes:
+      # Explicit path: orders -> users
+      - join_path: orders.users
+        includes:
+          - name
+          - email
+```
+
+### 3. Rename and Reorganize
+
+Create user-friendly names and groupings:
+
+```yaml
+views:
+  - name: analytics
+    cubes:
+      - join_path: orders
+        includes:
+          - name: count
+            alias: order_count
+            title: "Total Orders"
+
+          - name: total_revenue
+            alias: revenue
+            title: "Revenue"
+```
+
+### 4. Govern Data Access
+
+Control what different consumers can see:
+
+```yaml
+views:
+  - name: public_metrics
+    public: true
+    cubes:
+      - join_path: orders
+        includes:
+          - count
+          - total_revenue
+
+  - name: internal_metrics
+    public: false  # Only for internal use
+    cubes:
+      - join_path: orders
+        includes: "*"
+```
+
+## File Organization
+
+Store views in the `views/` directory:
+
+```
+views/
+├── orders_overview.yaml
+├── sales_dashboard.yaml
+└── customer_360.yaml
+```
+
+## Best Practices
+
+1. **Create purpose-specific views** — one view per dashboard/use case
+2. **Use meaningful names** — describe what the view is for
+3. **Be explicit with includes** — list members rather than using "*"
+4. **Alias for clarity** — rename members when needed
+5. **Organize with folders** — group related members together
+
+## See Also
+
+- views.cubes
+- views.includes
+- views.folders
+- cubes.joins
+
+## More Information
+
+https://cube.dev/docs/reference/data-model/view

package/dist/docs/topics/workflow.deploy.md

@@ -0,0 +1,132 @@
+# workflow.deploy
+
+> Push models to Bonnard for querying.
+
+## Overview
+
+The `bon deploy` command uploads your cubes and views to Bonnard, making them available for querying via the API. It validates models and tests connections before deploying.
+
+## Usage
+
+```bash
+# Deploy all models
+bon deploy
+```
+
+## Prerequisites
+
+1. **Logged in** — run `bon login` first
+2. **Valid models** — must pass `bon validate`
+3. **Working connections** — data sources must be accessible
+
+## What Happens
+
+1. **Validates models** — checks for errors
+2. **Tests connections** — verifies data source access
+3. **Uploads models** — sends cubes and views to Bonnard
+4. **Activates** — makes models available for queries
+
+## Example Output
+
+```
+bon deploy
+
+✓ Validating models...
+  ✓ models/orders.yaml
+  ✓ models/users.yaml
+  ✓ views/orders_overview.yaml
+
+✓ Testing connections...
+  ✓ datasource "default" connected
+
+✓ Deploying to Bonnard...
+  Uploading 2 cubes, 1 view...
+
+✓ Deploy complete!
+
+Your models are now available at:
+  https://api.bonnard.dev/v1/your-org/cubejs-api
+```
+
+## Deploy Flow
+
+```
+bon deploy
+    │
+    ├── 1. bon validate (must pass)
+    │
+    ├── 2. Test all datasource connections (must succeed)
+    │
+    ├── 3. Upload to Bonnard API
+    │       - cubes from models/
+    │       - views from views/
+    │       - datasource configs
+    │
+    └── 4. Activate deployment
+```
+
+## Error Handling
+
+### Validation Errors
+
+```
+✗ Validating models...
+
+models/orders.yaml:15:5
+  error: Unknown measure type "counts"
+
+Deploy aborted. Fix validation errors first.
+```
+
+### Connection Errors
+
+```
+✗ Testing connections...
+  ✗ datasource "analytics": Connection refused
+
+Deploy aborted. Fix connection issues:
+  - Check credentials in .bon/datasources.yaml
+  - Verify network access to database
+  - Run: bon datasource test analytics
+```
+
+### Auth Errors
+
+```
+✗ Not logged in.
+
+Run: bon login
+```
+
+## What Gets Deployed
+
+| Source | Deployed |
+|--------|----------|
+| `models/*.yaml` | All cube definitions |
+| `views/*.yaml` | All view definitions |
+| `.bon/datasources.yaml` | Connection configs (credentials encrypted) |
+| `bon.yaml` | Project settings |
+
+## Deployment Behavior
+
+- **Replaces** previous deployment (not additive)
+- **All or nothing** — partial deploys don't happen
+- **Instant** — changes take effect immediately
+
+## Best Practices
+
+1. **Validate first** — run `bon validate` before deploy
+2. **Test locally** — verify queries work before deploying
+3. **Use version control** — commit models before deploying
+4. **Monitor after deploy** — check for query errors
+
+## See Also
+
+- workflow
+- workflow.validate
+- cubes
+- views
+
+## More Information
+
+https://docs.bonnard.dev/cli/deploy

package/dist/docs/topics/workflow.md

@@ -0,0 +1,151 @@
+# workflow
+
+> Development workflow for building and deploying Bonnard models.
+
+## Overview
+
+Building semantic models with Bonnard follows a development workflow: initialize a project, connect data sources, define models, validate, and deploy.
+
+## Quick Start
+
+```bash
+# 1. Initialize project
+bon init
+
+# 2. Add a data source
+bon datasource add
+
+# 3. Create models in models/ and views in views/
+
+# 4. Validate your models
+bon validate
+
+# 5. Deploy to Bonnard
+bon deploy
+```
+
+## Project Structure
+
+After `bon init`, your project has:
+
+```
+my-project/
+├── bon.yaml              # Project configuration
+├── models/               # Cube definitions
+│   └── orders.yaml
+├── views/                # View definitions
+│   └── orders_overview.yaml
+└── .bon/                 # Local config (gitignored)
+    └── datasources.yaml  # Data source credentials
+```
+
+## Development Cycle
+
+### 1. Define Models
+
+Create cubes that map to your database tables:
+
+```yaml
+# models/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:
+
+```yaml
+# views/orders_overview.yaml
+views:
+  - name: orders_overview
+    cubes:
+      - join_path: orders
+        includes:
+          - count
+          - status
+```
+
+### 3. Validate
+
+Check for syntax errors and test connections:
+
+```yaml
+bon validate
+bon validate --test-connection
+```
+
+### 4. Deploy
+
+Push models to Bonnard:
+
+```bash
+bon deploy
+```
+
+## File Organization
+
+### One Cube Per File
+
+```
+models/
+├── orders.yaml
+├── users.yaml
+├── products.yaml
+└── line_items.yaml
+```
+
+### Related Cubes Together
+
+```
+models/
+├── sales/
+│   ├── orders.yaml
+│   └── line_items.yaml
+├── users/
+│   ├── users.yaml
+│   └── profiles.yaml
+└── products/
+    └── products.yaml
+```
+
+## Best Practices
+
+1. **Start simple** — begin with one cube, add complexity gradually
+2. **Validate often** — run `bon validate` after each change
+3. **Use version control** — commit models to git
+4. **Document with descriptions** — add `description` to measures/dimensions
+5. **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 model syntax |
+| `bon deploy` | Deploy to Bonnard |
+| `bon docs` | Browse Cube documentation |
+
+## See Also
+
+- workflow.validate
+- workflow.deploy
+- cubes
+- views
+
+## More Information
+
+https://docs.bonnard.dev/workflow

package/dist/docs/topics/workflow.query.md

@@ -0,0 +1,203 @@
+# workflow.query
+
+> Query the deployed semantic layer using JSON or SQL.
+
+## Overview
+
+After deploying models with `bon deploy`, you can query the semantic layer using `bon cube query`. This tests that your models work correctly and returns data from your warehouse through Cube.
+
+## Query Formats
+
+Cube supports two query formats:
+
+### JSON Format (Default)
+
+The JSON format uses Cube's REST API structure:
+
+```bash
+bon cube query '{"measures": ["orders.count"]}'
+
+bon cube query '{
+  "measures": ["orders.total_revenue"],
+  "dimensions": ["orders.status"],
+  "filters": [{
+    "member": "orders.created_at",
+    "operator": "inDateRange",
+    "values": ["2024-01-01", "2024-12-31"]
+  }]
+}'
+```
+
+**JSON Query Properties:**
+
+| Property | Description |
+|----------|-------------|
+| `measures` | Array of measures to calculate (e.g., `["orders.count"]`) |
+| `dimensions` | Array of dimensions to group by (e.g., `["orders.status"]`) |
+| `filters` | Array of filter objects |
+| `timeDimensions` | Time-based grouping with granularity |
+| `segments` | Named filters defined in models |
+| `limit` | Max rows to return |
+| `offset` | Skip rows (pagination) |
+| `order` | Sort specification |
+
+**Filter Operators:**
+
+| Operator | Use Case |
+|----------|----------|
+| `equals`, `notEquals` | Exact match |
+| `contains`, `notContains` | String contains |
+| `startsWith`, `endsWith` | String prefix/suffix |
+| `gt`, `gte`, `lt`, `lte` | Numeric comparison |
+| `inDateRange`, `beforeDate`, `afterDate` | Time filtering |
+| `set`, `notSet` | NULL checks |
+
+### SQL Format
+
+The SQL format uses Cube's SQL API, where cubes are tables:
+
+```bash
+bon cube query --sql "SELECT status, MEASURE(count) FROM orders GROUP BY 1"
+
+bon cube query --sql "SELECT
+  city,
+  MEASURE(total_revenue),
+  MEASURE(avg_order_value)
+FROM orders
+WHERE status = 'completed'
+GROUP BY 1
+ORDER BY 2 DESC
+LIMIT 10"
+```
+
+**SQL Syntax Rules:**
+
+1. **Cubes/views are tables** — `FROM orders` references the `orders` cube
+2. **Dimensions are columns** — Include in `SELECT` and `GROUP BY`
+3. **Measures use `MEASURE()`** — Or matching aggregates (`SUM`, `COUNT`, etc.)
+4. **Segments are boolean** — Filter with `WHERE is_completed IS TRUE`
+
+**Examples:**
+
+```sql
+-- Count orders by status
+SELECT status, MEASURE(count) FROM orders GROUP BY 1
+
+-- Revenue by city with filter
+SELECT city, SUM(amount) FROM orders WHERE status = 'shipped' GROUP BY 1
+
+-- Using time dimension with granularity
+SELECT DATE_TRUNC('month', created_at), MEASURE(total_revenue)
+FROM orders
+GROUP BY 1
+ORDER BY 1
+```
+
+## CLI Usage
+
+```bash
+# JSON format (default)
+bon cube query '{"measures": ["orders.count"]}'
+
+# SQL format
+bon cube query --sql "SELECT MEASURE(count) FROM orders"
+
+# Limit rows
+bon cube query '{"measures": ["orders.count"], "dimensions": ["orders.city"]}' --limit 10
+
+# JSON output (instead of table)
+bon cube query '{"measures": ["orders.count"]}' --format json
+```
+
+## Output Formats
+
+### Table Format (Default)
+
+```
+┌─────────┬───────────────┐
+│ status  │ orders.count  │
+├─────────┼───────────────┤
+│ pending │ 42            │
+│ shipped │ 156           │
+│ done    │ 892           │
+└─────────┴───────────────┘
+```
+
+### JSON Format
+
+```bash
+bon cube query '{"measures": ["orders.count"]}' --format json
+```
+
+```json
+[
+  { "orders.status": "pending", "orders.count": 42 },
+  { "orders.status": "shipped", "orders.count": 156 },
+  { "orders.status": "done", "orders.count": 892 }
+]
+```
+
+## Common Patterns
+
+### Time Series Analysis
+
+```bash
+bon cube query '{
+  "measures": ["orders.total_revenue"],
+  "timeDimensions": [{
+    "dimension": "orders.created_at",
+    "granularity": "month",
+    "dateRange": ["2024-01-01", "2024-12-31"]
+  }]
+}'
+```
+
+### Filtering by Dimension
+
+```bash
+bon cube query '{
+  "measures": ["orders.count"],
+  "dimensions": ["orders.city"],
+  "filters": [{
+    "member": "orders.status",
+    "operator": "equals",
+    "values": ["completed"]
+  }]
+}'
+```
+
+### Multiple Measures
+
+```bash
+bon cube query '{
+  "measures": ["orders.count", "orders.total_revenue", "orders.avg_order_value"],
+  "dimensions": ["orders.category"]
+}'
+```
+
+## Error Handling
+
+### Common Errors
+
+**"Projection references non-aggregate values"**
+- All dimensions must be in `GROUP BY`
+- All measures must use `MEASURE()` or matching aggregate
+
+**"Cube not found"**
+- Check cube name matches deployed model
+- Run `bon deploy` if models changed
+
+**"Not logged in"**
+- Run `bon login` first
+
+## See Also
+
+- [workflow.deploy](workflow.deploy) - Deploy models before querying
+- [cubes.measures](cubes.measures) - Define measures
+- [cubes.dimensions](cubes.dimensions) - Define dimensions
+- [views](views) - Create focused query interfaces
+
+## More Information
+
+- [Cube REST API Query Format](https://cube.dev/docs/product/apis-integrations/rest-api/query-format)
+- [Cube SQL API Query Format](https://cube.dev/docs/product/apis-integrations/sql-api/query-format)