@bonnard/cli 0.1.3 → 0.1.5

package/dist/docs/topics/cubes.measures.drill-members.md

@@ -0,0 +1,158 @@
+# cubes.measures.drill-members
+
+> Define which dimensions to show when drilling into a measure.
+
+## Overview
+
+The `drill_members` property specifies which dimensions should be displayed when a user "drills down" into a measure to see the underlying detail records.
+
+## Example
+
+```yaml
+cubes:
+  - name: orders
+    sql_table: orders
+
+    measures:
+      - name: count
+        type: count
+        drill_members:
+          - id
+          - status
+          - created_at
+          - customer_name
+
+      - name: total_revenue
+        type: sum
+        sql: amount
+        drill_members:
+          - id
+          - amount
+          - status
+          - created_at
+
+    dimensions:
+      - name: id
+        type: number
+        sql: id
+        primary_key: true
+
+      - name: status
+        type: string
+        sql: status
+
+      - name: amount
+        type: number
+        sql: amount
+
+      - name: customer_name
+        type: string
+        sql: customer_name
+
+      - name: created_at
+        type: time
+        sql: created_at
+```
+
+## Syntax
+
+List dimensions by name:
+
+```yaml
+measures:
+  - name: count
+    type: count
+    drill_members:
+      - id
+      - name
+      - email
+      - created_at
+```
+
+## How Drill-Down Works
+
+1. User sees aggregated measure (e.g., "Orders: 1,234")
+2. User clicks to drill down
+3. BI tool queries the specified `drill_members` dimensions
+4. User sees detail records that make up that aggregate
+
+## Cross-Cube Drill Members
+
+Reference dimensions from joined cubes:
+
+```yaml
+cubes:
+  - name: orders
+    joins:
+      - name: users
+        relationship: many_to_one
+        sql: "{CUBE}.user_id = {users.id}"
+
+    measures:
+      - name: count
+        type: count
+        drill_members:
+          - id
+          - status
+          - users.name      # From joined cube
+          - users.email     # From joined cube
+          - created_at
+```
+
+## Best Practices
+
+### Include Identifying Information
+
+```yaml
+drill_members:
+  - id              # Primary identifier
+  - name            # Human-readable name
+  - created_at      # When it happened
+```
+
+### Include Relevant Context
+
+```yaml
+# For a revenue measure
+drill_members:
+  - order_id
+  - product_name
+  - amount          # The value being summed
+  - customer_name
+  - order_date
+```
+
+### Keep Lists Focused
+
+Don't include every dimension—focus on what's useful for understanding that specific measure:
+
+```yaml
+# Good - focused on revenue context
+- name: total_revenue
+  drill_members:
+    - id
+    - amount
+    - product
+    - customer
+
+# Bad - too many unrelated fields
+- name: total_revenue
+  drill_members:
+    - id
+    - amount
+    - product
+    - customer
+    - internal_code
+    - debug_flag
+    - sync_status
+```
+
+## BI Tool Support
+
+Drill-down support varies by visualization tool. Check your specific tool's documentation for how it handles `drill_members`.
+
+## See Also
+
+- cubes.measures
+- cubes.dimensions
+- cubes.joins

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

@@ -0,0 +1,86 @@
+# cubes.measures.filters
+
+> Apply permanent filters to measures for conditional aggregations.
+
+## Overview
+
+The `filters` property lets you define measures that only count or aggregate rows matching specific conditions. This creates reusable filtered metrics without requiring query-time filters.
+
+## Example
+
+```yaml
+measures:
+  - name: completed_orders
+    type: count
+    filters:
+      - sql: "{CUBE}.status = 'completed'"
+
+  - name: revenue_this_year
+    type: sum
+    sql: amount
+    filters:
+      - sql: "YEAR({CUBE}.created_at) = YEAR(CURRENT_DATE)"
+```
+
+## Syntax
+
+### Single Filter
+
+```yaml
+- name: active_users
+  type: count_distinct
+  sql: user_id
+  filters:
+    - sql: "{CUBE}.is_active = true"
+```
+
+### Multiple Filters (AND logic)
+
+```yaml
+- name: completed_paid_orders
+  type: count
+  filters:
+    - sql: "{CUBE}.status = 'completed'"
+    - sql: "{CUBE}.payment_status = 'paid'"
+```
+
+## Use Cases
+
+### Percentage Calculations
+
+```yaml
+measures:
+  - name: total_orders
+    type: count
+
+  - name: completed_orders
+    type: count
+    filters:
+      - sql: "{CUBE}.status = 'completed'"
+
+  - name: completion_rate
+    type: number
+    sql: "100.0 * {completed_orders} / NULLIF({total_orders}, 0)"
+    format: percent
+```
+
+### Time-Based Metrics
+
+```yaml
+- name: orders_last_30_days
+  type: count
+  filters:
+    - sql: "{CUBE}.created_at >= CURRENT_DATE - INTERVAL '30 days'"
+```
+
+## Best Practices
+
+1. **Use {CUBE}** to reference the current cube's columns
+2. **Combine with number type** for calculated ratios
+3. **Keep filters simple** — complex logic belongs in the base SQL
+
+## See Also
+
+- cubes.measures
+- cubes.measures.calculated
+- cubes.segments

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

@@ -0,0 +1,153 @@
+# cubes.measures.format
+
+> Specify how measure values should be displayed.
+
+## Overview
+
+The `format` property hints to BI tools how to display measure values. This affects rendering in dashboards and reports.
+
+## Example
+
+```yaml
+measures:
+  - name: total_revenue
+    type: sum
+    sql: amount
+    format: currency
+
+  - name: conversion_rate
+    type: number
+    sql: "{conversions} / NULLIF({visits}, 0)"
+    format: percent
+
+  - name: order_count
+    type: count
+    # No format - displays as plain number
+```
+
+## Supported Formats
+
+### percent
+
+Displays value as a percentage:
+
+```yaml
+- name: completion_rate
+  type: number
+  sql: "{completed} / NULLIF({total}, 0)"
+  format: percent
+```
+
+Output: `75%` instead of `0.75`
+
+### currency
+
+Displays value as monetary amount:
+
+```yaml
+- name: total_revenue
+  type: sum
+  sql: amount
+  format: currency
+```
+
+Output: `$1,234.56` (formatting depends on BI tool locale)
+
+## Usage Notes
+
+### Format vs Calculation
+
+Format is for display only—it doesn't change the underlying value:
+
+```yaml
+# Value is 0.75, displayed as 75%
+- name: rate
+  type: number
+  sql: "{part} / NULLIF({whole}, 0)"
+  format: percent
+
+# If you want the value to be 75, multiply in SQL
+- name: rate_as_whole_number
+  type: number
+  sql: "100.0 * {part} / NULLIF({whole}, 0)"
+  format: percent  # Displays as 7500% - probably not what you want!
+```
+
+### Percentages
+
+For percentages, your SQL should return a decimal (0.75 for 75%):
+
+```yaml
+# Correct - returns 0.75, displays as 75%
+- name: conversion_rate
+  type: number
+  sql: "{conversions} / NULLIF({visits}, 0)"
+  format: percent
+
+# Also correct - explicit multiplication for clarity
+- name: conversion_rate
+  type: number
+  sql: "1.0 * {conversions} / NULLIF({visits}, 0)"
+  format: percent
+```
+
+### Currency
+
+For currency, return the raw numeric value:
+
+```yaml
+# Correct - returns 1234.56, displays as $1,234.56
+- name: revenue
+  type: sum
+  sql: amount
+  format: currency
+```
+
+## Common Patterns
+
+### Financial Measures
+
+```yaml
+measures:
+  - name: revenue
+    type: sum
+    sql: amount
+    format: currency
+
+  - name: cost
+    type: sum
+    sql: cost
+    format: currency
+
+  - name: profit_margin
+    type: number
+    sql: "({revenue} - {cost}) / NULLIF({revenue}, 0)"
+    format: percent
+```
+
+### Conversion Metrics
+
+```yaml
+measures:
+  - name: visits
+    type: count_distinct
+    sql: session_id
+
+  - name: signups
+    type: count
+
+  - name: signup_rate
+    type: number
+    sql: "{signups} / NULLIF({visits}, 0)"
+    format: percent
+```
+
+## BI Tool Support
+
+Format support varies by visualization tool. Most tools recognize `percent` and `currency`, but rendering specifics (decimal places, currency symbol) depend on the tool's configuration.
+
+## See Also
+
+- cubes.measures
+- cubes.measures.types
+- cubes.dimensions.format

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

@@ -0,0 +1,162 @@
+# cubes.measures
+
+> Define metrics and aggregations for analytical queries.
+
+## Overview
+
+Measures are the quantitative values in your data model — counts, sums, averages, and other aggregations. They answer questions like "how many?", "how much?", and "what's the average?".
+
+## Example
+
+```yaml
+measures:
+  - name: count
+    type: count
+    description: Total number of orders
+
+  - name: total_revenue
+    type: sum
+    sql: amount
+    description: Sum of order amounts in dollars
+
+  - name: average_order_value
+    type: number
+    sql: "{total_revenue} / NULLIF({count}, 0)"
+    description: Average revenue per order
+
+  - name: completed_orders
+    type: count
+    filters:
+      - sql: "{CUBE}.status = 'completed'"
+    description: Orders with status completed
+```
+
+## Required Properties
+
+| Property | Description |
+|----------|-------------|
+| `name` | Unique identifier in snake_case |
+| `type` | Aggregation type (count, sum, avg, etc.) |
+
+## Optional Properties
+
+| Property | Description |
+|----------|-------------|
+| `sql` | SQL expression (required for most types) |
+| `filters` | Conditions for filtered aggregations |
+| `title` | Human-readable display name |
+| `description` | Documentation for consumers |
+| `format` | Output format (percent, currency, etc.) |
+| `public` | Whether exposed in API (default: true) |
+| `rolling_window` | Rolling aggregation settings |
+
+## Measure Types
+
+### Aggregation Types
+
+```yaml
+# Count rows
+- name: count
+  type: count
+
+# Count distinct values
+- name: unique_users
+  type: count_distinct
+  sql: user_id
+
+# Sum values
+- name: total_revenue
+  type: sum
+  sql: amount
+
+# Average values
+- name: average_price
+  type: avg
+  sql: price
+
+# Min/Max values
+- name: first_order
+  type: min
+  sql: created_at
+
+- name: last_order
+  type: max
+  sql: created_at
+```
+
+### Calculated Types
+
+```yaml
+# Calculated number (from other measures)
+- name: average_order_value
+  type: number
+  sql: "{total_revenue} / NULLIF({count}, 0)"
+
+# Boolean result
+- name: has_orders
+  type: boolean
+  sql: "{count} > 0"
+```
+
+## Filtered Measures
+
+Add conditions to only count/sum matching rows:
+
+```yaml
+- name: completed_orders
+  type: count
+  filters:
+    - sql: "{CUBE}.status = 'completed'"
+
+- name: revenue_this_year
+  type: sum
+  sql: amount
+  filters:
+    - sql: "YEAR({CUBE}.created_at) = YEAR(CURRENT_DATE)"
+```
+
+## Calculated Measures
+
+Reference other measures to build derived metrics:
+
+```yaml
+- name: total_orders
+  type: count
+
+- name: completed_orders
+  type: count
+  filters:
+    - sql: "{CUBE}.status = 'completed'"
+
+- name: completion_rate
+  type: number
+  sql: "100.0 * {completed_orders} / NULLIF({total_orders}, 0)"
+  format: percent
+```
+
+## Rolling Windows
+
+Calculate metrics over time windows:
+
+```yaml
+- name: rolling_7_day_revenue
+  type: sum
+  sql: amount
+  rolling_window:
+    trailing: 7 day
+```
+
+## Best Practices
+
+1. **Start with count** — every cube should have a basic count
+2. **Use descriptive names** — `total_revenue` not `sum1`
+3. **Handle division by zero** — always use `NULLIF(x, 0)`
+4. **Add formats** — help consumers interpret values
+5. **Document complex measures** — explain business logic
+
+## See Also
+
+- cubes.measures.types
+- cubes.measures.filters
+- cubes.measures.calculated
+- cubes.measures.rolling

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

@@ -0,0 +1,119 @@
+# cubes.measures.rolling
+
+> Calculate rolling window aggregations (7-day average, 30-day sum, etc).
+
+## Overview
+
+Rolling window measures aggregate data over a sliding time period. Use `rolling_window` to define moving averages, cumulative totals, and time-based comparisons.
+
+## Example
+
+```yaml
+measures:
+  - name: rolling_7_day_orders
+    type: count
+    rolling_window:
+      trailing: 7 day
+      offset: start
+
+  - name: rolling_30_day_revenue
+    type: sum
+    sql: amount
+    rolling_window:
+      trailing: 30 day
+```
+
+## Syntax
+
+### rolling_window Properties
+
+| Property | Description |
+|----------|-------------|
+| `trailing` | Time period to look back (e.g., `7 day`, `1 month`) |
+| `leading` | Time period to look forward (rare) |
+| `offset` | `start` or `end` — which end of the window to align |
+
+### Trailing Window
+
+```yaml
+- name: rolling_7_day_avg
+  type: avg
+  sql: amount
+  rolling_window:
+    trailing: 7 day
+```
+
+### Cumulative (Running Total)
+
+Use `unbounded` for cumulative calculations:
+
+```yaml
+- name: cumulative_revenue
+  type: sum
+  sql: amount
+  rolling_window:
+    trailing: unbounded
+```
+
+### Offset Options
+
+```yaml
+# Window ends at current row (default)
+rolling_window:
+  trailing: 7 day
+  offset: end
+
+# Window starts at current row
+rolling_window:
+  trailing: 7 day
+  offset: start
+```
+
+## Common Patterns
+
+### 7-Day Moving Average
+
+```yaml
+- name: daily_orders
+  type: count
+
+- name: rolling_7_day_avg_orders
+  type: avg
+  sql: "{daily_orders}"
+  rolling_window:
+    trailing: 7 day
+```
+
+### Month-to-Date
+
+```yaml
+- name: mtd_revenue
+  type: sum
+  sql: amount
+  rolling_window:
+    trailing: 1 month
+    offset: start
+```
+
+### Year-to-Date
+
+```yaml
+- name: ytd_revenue
+  type: sum
+  sql: amount
+  rolling_window:
+    trailing: 1 year
+    offset: start
+```
+
+## Requirements
+
+- Rolling window measures require a time dimension in the query
+- Works best with pre-aggregations for performance
+
+## See Also
+
+- cubes.measures
+- cubes.measures.calculated
+- cubes.dimensions.time
+- pre-aggregations