@bonnard/cli 0.1.3 → 0.1.5

package/dist/docs/topics/cubes.extends.md

@@ -0,0 +1,149 @@
+# cubes.extends
+
+> Reuse members from other cubes to reduce duplication.
+
+## Overview
+
+The `extends` property allows a cube to inherit measures, dimensions, segments, and joins from another cube. This promotes code reusability and keeps your data model DRY.
+
+## Example
+
+```yaml
+cubes:
+  # Base cube with shared members
+  - name: base_events
+    sql_table: events
+
+    measures:
+      - name: count
+        type: count
+
+    dimensions:
+      - name: id
+        type: number
+        sql: "{CUBE}.id"
+        primary_key: true
+
+      - name: created_at
+        type: time
+        sql: "{CUBE}.created_at"
+
+  # Child cube extends base
+  - name: page_views
+    extends: base_events
+    sql_table: page_view_events
+
+    dimensions:
+      - name: page_url
+        type: string
+        sql: "{CUBE}.url"
+
+  # Another child cube
+  - name: purchases
+    extends: base_events
+    sql_table: purchase_events
+
+    measures:
+      - name: total_revenue
+        type: sum
+        sql: "{CUBE}.amount"
+```
+
+## How It Works
+
+When a cube extends another:
+
+1. **Measures merge** — child gets all parent measures plus its own
+2. **Dimensions merge** — child gets all parent dimensions plus its own
+3. **Segments merge** — child gets all parent segments plus its own
+4. **Joins merge** — child gets all parent joins plus its own
+
+## Important: Use {CUBE}
+
+Always use `{CUBE}` when referencing columns in extendable cubes:
+
+```yaml
+# Good - works in parent and child cubes
+dimensions:
+  - name: created_at
+    type: time
+    sql: "{CUBE}.created_at"
+
+# Bad - breaks in child cubes
+dimensions:
+  - name: created_at
+    type: time
+    sql: "{base_events}.created_at"
+```
+
+## Overriding Members
+
+Child cubes can override parent members by defining them with the same name:
+
+```yaml
+cubes:
+  - name: base_orders
+    measures:
+      - name: count
+        type: count
+        description: "Total orders"
+
+  - name: completed_orders
+    extends: base_orders
+    measures:
+      - name: count
+        type: count
+        description: "Completed orders only"
+        filters:
+          - sql: "{CUBE}.status = 'completed'"
+```
+
+## Common Patterns
+
+### Event Tables
+
+```yaml
+cubes:
+  - name: base_event
+    dimensions:
+      - name: id
+        sql: "{CUBE}.id"
+        primary_key: true
+      - name: user_id
+        sql: "{CUBE}.user_id"
+      - name: timestamp
+        type: time
+        sql: "{CUBE}.timestamp"
+
+  - name: clicks
+    extends: base_event
+    sql_table: click_events
+
+  - name: impressions
+    extends: base_event
+    sql_table: impression_events
+```
+
+### Multi-Tenant Tables
+
+```yaml
+cubes:
+  - name: base_orders
+    sql: "SELECT * FROM orders WHERE tenant_id = '{{COMPILE_CONTEXT.tenant}}'"
+
+  - name: tenant_orders
+    extends: base_orders
+```
+
+## Best Practices
+
+1. **Use {CUBE} everywhere** — never hardcode cube names in SQL
+2. **Keep base cubes focused** — only include truly shared members
+3. **Don't over-extend** — deep inheritance chains are hard to maintain
+4. **Document inheritance** — make it clear which cubes extend others
+
+## See Also
+
+- cubes
+- syntax.references
+- syntax.context-variables

package/dist/docs/topics/cubes.hierarchies.md

@@ -0,0 +1,174 @@
+# cubes.hierarchies
+
+> Define drill-down paths for dimensional analysis.
+
+## Overview
+
+Hierarchies group dimensions into levels of granularity, enabling drill-down and roll-up analysis. Users can navigate from high-level summaries (e.g., country) down to details (e.g., city).
+
+## Example
+
+```yaml
+cubes:
+  - name: orders
+    sql_table: orders
+
+    dimensions:
+      - name: country
+        type: string
+        sql: country
+
+      - name: state
+        type: string
+        sql: state
+
+      - name: city
+        type: string
+        sql: city
+
+    hierarchies:
+      - name: location
+        title: "Geographic Location"
+        levels:
+          - country
+          - state
+          - city
+```
+
+## Properties
+
+| Property | Required | Description |
+|----------|----------|-------------|
+| `name` | Yes | Unique identifier |
+| `levels` | Yes | Ordered list of dimensions (least to most granular) |
+| `title` | No | Human-readable display name |
+| `public` | No | API visibility (default: true) |
+
+## Syntax
+
+### Basic Hierarchy
+
+```yaml
+hierarchies:
+  - name: time_hierarchy
+    levels:
+      - year
+      - quarter
+      - month
+      - day
+```
+
+### With Title
+
+```yaml
+hierarchies:
+  - name: product_category
+    title: "Product Categories"
+    levels:
+      - department
+      - category
+      - subcategory
+```
+
+### Multiple Hierarchies
+
+A dimension can appear in multiple hierarchies:
+
+```yaml
+hierarchies:
+  - name: fiscal_time
+    levels:
+      - fiscal_year
+      - fiscal_quarter
+      - fiscal_month
+
+  - name: calendar_time
+    levels:
+      - calendar_year
+      - calendar_quarter
+      - calendar_month
+```
+
+## Cross-Cube Hierarchies
+
+Include dimensions from joined cubes using dot notation:
+
+```yaml
+cubes:
+  - name: orders
+    joins:
+      - name: users
+        relationship: many_to_one
+        sql: "{CUBE}.user_id = {users.id}"
+
+    hierarchies:
+      - name: customer_location
+        levels:
+          - users.country
+          - users.state
+          - users.city
+```
+
+## Common Patterns
+
+### Geographic Hierarchy
+
+```yaml
+hierarchies:
+  - name: geography
+    title: "Location"
+    levels:
+      - continent
+      - country
+      - region
+      - city
+```
+
+### Time Hierarchy
+
+```yaml
+hierarchies:
+  - name: time
+    title: "Time Period"
+    levels:
+      - year
+      - quarter
+      - month
+      - week
+      - day
+```
+
+### Organizational Hierarchy
+
+```yaml
+hierarchies:
+  - name: organization
+    title: "Org Structure"
+    levels:
+      - division
+      - department
+      - team
+```
+
+### Product Hierarchy
+
+```yaml
+hierarchies:
+  - name: product
+    title: "Product Categories"
+    levels:
+      - brand
+      - category
+      - product_line
+      - sku
+```
+
+## BI Tool Support
+
+Hierarchy support varies by visualization tool. Check your specific tool's documentation for compatibility.
+
+## See Also
+
+- cubes.dimensions
+- cubes.joins
+- views.folders

package/dist/docs/topics/cubes.joins.md

@@ -0,0 +1,115 @@
+# cubes.joins
+
+> Connect cubes together to enable cross-cube analysis.
+
+## Overview
+
+Joins define relationships between cubes, allowing queries to combine measures and dimensions from multiple cubes. Cube automatically generates the appropriate SQL JOINs.
+
+## Example
+
+```yaml
+cubes:
+  - name: orders
+    sql: SELECT * FROM orders
+
+    joins:
+      - name: users
+        relationship: many_to_one
+        sql: "{CUBE}.user_id = {users.id}"
+
+      - name: products
+        relationship: many_to_one
+        sql: "{CUBE}.product_id = {products.id}"
+```
+
+## Relationship Types
+
+### many_to_one
+Many rows in this cube relate to one row in the joined cube.
+
+```yaml
+# Many orders belong to one user
+- name: users
+  relationship: many_to_one
+  sql: "{CUBE}.user_id = {users.id}"
+```
+
+### one_to_many
+One row in this cube relates to many rows in the joined cube.
+
+```yaml
+# One user has many orders
+- name: orders
+  relationship: one_to_many
+  sql: "{CUBE}.id = {orders.user_id}"
+```
+
+### one_to_one
+One row in this cube relates to exactly one row in the joined cube.
+
+```yaml
+# One user has one profile
+- name: profiles
+  relationship: one_to_one
+  sql: "{CUBE}.id = {profiles.user_id}"
+```
+
+## Join Properties
+
+| Property | Required | Description |
+|----------|----------|-------------|
+| `name` | Yes | Name of the cube to join |
+| `relationship` | Yes | `many_to_one`, `one_to_many`, or `one_to_one` |
+| `sql` | Yes | Join condition |
+
+## Syntax
+
+### {CUBE} Reference
+Use `{CUBE}` to reference the current cube:
+
+```yaml
+sql: "{CUBE}.user_id = {users.id}"
+```
+
+### Referencing Joined Cube
+Use `{cube_name}` to reference the joined cube:
+
+```yaml
+sql: "{CUBE}.product_id = {products.id}"
+```
+
+## Multi-hop Joins
+
+Cubes can access data through transitive joins:
+
+```yaml
+# orders -> users -> countries
+# Query can use countries.name with orders.count
+
+cubes:
+  - name: orders
+    joins:
+      - name: users
+        relationship: many_to_one
+        sql: "{CUBE}.user_id = {users.id}"
+
+  - name: users
+    joins:
+      - name: countries
+        relationship: many_to_one
+        sql: "{CUBE}.country_id = {countries.id}"
+```
+
+## Best Practices
+
+1. **Define joins on the "many" side** — put the join in orders, not users
+2. **Use primary keys** — ensure joined cubes have `primary_key` defined
+3. **Keep joins simple** — avoid complex conditions
+4. **Consider views** for specific join paths
+
+## See Also
+
+- cubes
+- cubes.dimensions.primary-key
+- views

package/dist/docs/topics/cubes.md

@@ -0,0 +1,117 @@
+# cubes
+
+> Define data models that map to your database tables.
+
+## Overview
+
+Cubes are the foundational building blocks of your semantic layer. Each cube represents a dataset (typically a database table or SQL query) and defines the measures (metrics) and dimensions (attributes) available for analysis.
+
+## Example
+
+```yaml
+cubes:
+  - name: orders
+    sql_table: public.orders
+
+    measures:
+      - name: count
+        type: count
+
+      - name: total_revenue
+        type: sum
+        sql: amount
+
+      - name: average_order_value
+        type: number
+        sql: "{total_revenue} / NULLIF({count}, 0)"
+
+    dimensions:
+      - name: id
+        type: number
+        sql: id
+        primary_key: true
+
+      - name: status
+        type: string
+        sql: status
+
+      - name: created_at
+        type: time
+        sql: created_at
+
+    joins:
+      - name: users
+        relationship: many_to_one
+        sql: "{CUBE}.user_id = {users.id}"
+```
+
+## Core Properties
+
+| Property | Required | Description |
+|----------|----------|-------------|
+| `name` | Yes | Unique identifier in snake_case |
+| `sql` or `sql_table` | Yes | Data source query or table |
+| `measures` | No | Aggregations (count, sum, avg, etc.) |
+| `dimensions` | No | Attributes for grouping/filtering |
+| `joins` | No | Relationships to other cubes |
+| `segments` | No | Predefined filters |
+| `pre_aggregations` | No | Materialized query results |
+
+## Data Source
+
+### sql_table (recommended)
+
+For simple table references:
+
+```yaml
+cubes:
+  - name: orders
+    sql_table: public.orders
+```
+
+### sql
+
+For complex queries:
+
+```yaml
+cubes:
+  - name: orders
+    sql: >
+      SELECT o.*, u.name as user_name
+      FROM orders o
+      LEFT JOIN users u ON o.user_id = u.id
+```
+
+## Naming Conventions
+
+- Use `snake_case` for names
+- Use plural nouns: `orders`, `users`, `products`
+- Be descriptive: `order_line_items` not `oli`
+
+## File Organization
+
+One cube per file in the `models/` directory:
+
+```
+models/
+├── orders.yaml
+├── users.yaml
+├── products.yaml
+└── line_items.yaml
+```
+
+## Best Practices
+
+1. **Define a primary key** — required for joins and count_distinct
+2. **Start with basic measures** — count, sum of key metrics
+3. **Add dimensions for common filters** — status, dates, categories
+4. **Use joins sparingly** — define on the "many" side
+5. **Document with descriptions** — help consumers understand the data
+
+## See Also
+
+- cubes.sql
+- cubes.measures
+- cubes.dimensions
+- cubes.joins
+- cubes.segments

package/dist/docs/topics/cubes.measures.calculated.md

@@ -0,0 +1,99 @@
+# cubes.measures.calculated
+
+> Build complex metrics from other measures.
+
+## Overview
+
+Calculated measures combine existing measures to create derived metrics. Use the `number` type and reference other measures with `{measure_name}` syntax.
+
+## Example
+
+```yaml
+measures:
+  - name: total_orders
+    type: count
+
+  - name: total_revenue
+    type: sum
+    sql: amount
+
+  - name: average_order_value
+    type: number
+    sql: "{total_revenue} / NULLIF({total_orders}, 0)"
+```
+
+## Syntax
+
+### Referencing Measures
+
+Use curly braces to reference other measures:
+
+```yaml
+- name: profit_margin
+  type: number
+  sql: "({revenue} - {cost}) / NULLIF({revenue}, 0)"
+```
+
+### Handling Division by Zero
+
+Always use `NULLIF` to prevent division by zero:
+
+```yaml
+- name: conversion_rate
+  type: number
+  sql: "{conversions} / NULLIF({visits}, 0)"
+```
+
+## Common Patterns
+
+### Percentages
+
+```yaml
+- name: completion_rate
+  type: number
+  sql: "100.0 * {completed} / NULLIF({total}, 0)"
+  format: percent
+```
+
+### Ratios
+
+```yaml
+- name: orders_per_user
+  type: number
+  sql: "{order_count} / NULLIF({user_count}, 0)"
+```
+
+### Profit Calculations
+
+```yaml
+- name: gross_profit
+  type: number
+  sql: "{revenue} - {cost_of_goods}"
+
+- name: gross_margin
+  type: number
+  sql: "{gross_profit} / NULLIF({revenue}, 0)"
+  format: percent
+```
+
+### Year-over-Year
+
+```yaml
+- name: yoy_growth
+  type: number
+  sql: "({revenue_this_year} - {revenue_last_year}) / NULLIF({revenue_last_year}, 0)"
+  format: percent
+```
+
+## Best Practices
+
+1. **Build on base measures** — don't duplicate aggregation logic
+2. **Use descriptive names** — `conversion_rate` not `calc1`
+3. **Add format** — helps consumers understand the value
+4. **Document complex formulas** with `description`
+
+## See Also
+
+- cubes.measures
+- cubes.measures.types
+- cubes.measures.rolling