@bonnard/cli 0.1.3 → 0.1.4

package/dist/docs/topics/syntax.references.md

@@ -0,0 +1,178 @@
+# syntax.references
+
+> Reference columns, members, and other cubes in SQL expressions.
+
+## Overview
+
+Cube provides special syntax for referencing columns, measures, dimensions, and other cubes within SQL expressions. This enables dynamic, maintainable data models.
+
+## Reference Types
+
+### Column References
+
+Simple column name (no braces):
+
+```yaml
+dimensions:
+  - name: status
+    type: string
+    sql: status
+```
+
+### Member References
+
+Reference other members in the same cube with `{member_name}`:
+
+```yaml
+dimensions:
+  - name: first_name
+    type: string
+    sql: first_name
+
+  - name: last_name
+    type: string
+    sql: last_name
+
+  - name: full_name
+    type: string
+    sql: "CONCAT({first_name}, ' ', {last_name})"
+```
+
+### {CUBE} Placeholder
+
+Reference the current cube's columns:
+
+```yaml
+measures:
+  - name: completed_count
+    type: count
+    filters:
+      - sql: "{CUBE}.status = 'completed'"
+```
+
+Equivalent notations:
+
+```yaml
+# These are equivalent
+sql: "{CUBE}.amount"
+sql: "{CUBE.amount}"
+```
+
+### Cross-Cube References
+
+Reference other cubes with `{cube_name.member}`:
+
+```yaml
+joins:
+  - name: users
+    relationship: many_to_one
+    sql: "{CUBE}.user_id = {users.id}"
+```
+
+### Measure References in Calculated Measures
+
+```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)"
+```
+
+## SQL Reuse
+
+### {cube.sql()} Function
+
+Reference another cube's SQL definition:
+
+```yaml
+cubes:
+  - name: active_users
+    sql: >
+      SELECT * FROM {users.sql()}
+      WHERE is_active = true
+```
+
+## Time Dimension Granularities
+
+Reference time dimensions with granularity:
+
+```yaml
+# In pre-aggregations or calculated fields
+sql: "{created_at.day}"
+sql: "{created_at.month}"
+sql: "{created_at.year}"
+```
+
+## Join Path References
+
+In views, specify join paths with dot notation:
+
+```yaml
+views:
+  - name: order_details
+    cubes:
+      # Direct cube
+      - join_path: orders
+
+      # Joined cube (orders -> users)
+      - join_path: orders.users
+
+      # Multi-hop (orders -> users -> countries)
+      - join_path: orders.users.countries
+```
+
+## Escaping Braces
+
+For literal curly braces in SQL (e.g., JSON), escape with backslash:
+
+```yaml
+sql: "metadata->>'\{key\}'"
+```
+
+## Common Patterns
+
+### Safe Division
+
+```yaml
+- name: conversion_rate
+  type: number
+  sql: "{conversions} / NULLIF({visits}, 0)"
+```
+
+### Conditional Logic
+
+```yaml
+- name: revenue_category
+  type: string
+  sql: >
+    CASE
+      WHEN {total_revenue} > 10000 THEN 'high'
+      WHEN {total_revenue} > 1000 THEN 'medium'
+      ELSE 'low'
+    END
+```
+
+### Cross-Cube Calculations
+
+```yaml
+- name: orders_per_user
+  type: number
+  sql: "{orders.count} / NULLIF({users.count}, 0)"
+```
+
+## See Also
+
+- syntax
+- cubes.measures.calculated
+- cubes.joins
+
+## More Information
+
+https://cube.dev/docs/product/data-modeling/syntax#references

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

@@ -0,0 +1,166 @@
+# views.cubes
+
+> Select which cubes and members to expose in a view.
+
+## Overview
+
+The `cubes` property defines which cubes are combined in a view and which of their members (measures, dimensions, segments) are exposed. This is the core mechanism for building focused analytical interfaces.
+
+## Example
+
+```yaml
+views:
+  - name: orders_overview
+    cubes:
+      - join_path: orders
+        includes:
+          - count
+          - total_revenue
+          - status
+          - created_at
+
+      - join_path: orders.users
+        includes:
+          - name
+          - email
+```
+
+## Properties
+
+### join_path (required)
+
+Specifies which cube to include and how to reach it via joins:
+
+```yaml
+cubes:
+  # Direct cube reference
+  - join_path: orders
+
+  # Joined cube (orders -> users)
+  - join_path: orders.users
+
+  # Multi-hop join (orders -> users -> countries)
+  - join_path: orders.users.countries
+```
+
+### includes
+
+List specific members to expose:
+
+```yaml
+- join_path: orders
+  includes:
+    - count           # measure
+    - total_revenue   # measure
+    - status          # dimension
+    - created_at      # dimension
+```
+
+Include all members with `"*"`:
+
+```yaml
+- join_path: orders
+  includes: "*"
+```
+
+### excludes
+
+Remove specific members when using `includes: "*"`:
+
+```yaml
+- join_path: orders
+  includes: "*"
+  excludes:
+    - internal_notes
+    - debug_flag
+```
+
+### prefix
+
+Add cube name prefix to avoid naming collisions:
+
+```yaml
+- join_path: orders
+  prefix: true
+  includes:
+    - count  # Becomes "orders_count" in the view
+```
+
+## Member Customization
+
+Override member properties when including:
+
+```yaml
+- join_path: orders
+  includes:
+    - name: count
+      alias: order_count
+      title: "Total Orders"
+      description: "Number of orders placed"
+
+    - name: total_revenue
+      alias: revenue
+      format: currency
+```
+
+### Customization Options
+
+| Option | Description |
+|--------|-------------|
+| `alias` | Rename the member in this view |
+| `title` | Override display name |
+| `description` | Override description |
+| `format` | Override data format |
+| `meta` | Override metadata |
+
+## Common Patterns
+
+### Focused Dashboard View
+
+```yaml
+views:
+  - name: sales_dashboard
+    cubes:
+      - join_path: orders
+        includes:
+          - count
+          - total_revenue
+          - average_order_value
+          - created_at
+
+      - join_path: orders.products
+        includes:
+          - name: name
+            alias: product_name
+          - category
+```
+
+### Multi-Cube Aggregation
+
+```yaml
+views:
+  - name: customer_360
+    cubes:
+      - join_path: users
+        includes: "*"
+        excludes: [password_hash, api_key]
+
+      - join_path: users.orders
+        includes:
+          - count
+          - total_revenue
+
+      - join_path: users.support_tickets
+        includes:
+          - count
+```
+
+## See Also
+
+- views
+- views.includes
+- cubes.joins
+
+## More Information
+
+https://cube.dev/docs/reference/data-model/view#cubes

package/dist/docs/topics/views.folders.md

@@ -0,0 +1,158 @@
+# views.folders
+
+> Organize view members into logical groups.
+
+## Overview
+
+Folders organize view members into logical categories, making large views easier to navigate. They appear as hierarchical groupings in BI tools and the Cube Playground.
+
+## Example
+
+```yaml
+views:
+  - name: sales_analytics
+    cubes:
+      - join_path: orders
+        includes: "*"
+
+    folders:
+      - name: Revenue Metrics
+        members:
+          - total_revenue
+          - average_order_value
+          - revenue_growth
+
+      - name: Volume Metrics
+        members:
+          - count
+          - items_sold
+
+      - name: Time
+        members:
+          - created_at
+          - shipped_at
+```
+
+## Syntax
+
+### Basic Folder
+
+```yaml
+folders:
+  - name: "Folder Name"
+    members:
+      - member_one
+      - member_two
+```
+
+### Nested Folders
+
+```yaml
+folders:
+  - name: Metrics
+    folders:
+      - name: Revenue
+        members:
+          - total_revenue
+          - net_revenue
+
+      - name: Volume
+        members:
+          - count
+          - quantity
+```
+
+## Properties
+
+| Property | Description |
+|----------|-------------|
+| `name` | Display name for the folder |
+| `members` | List of member names to include |
+| `folders` | Nested sub-folders |
+
+## Common Patterns
+
+### By Data Type
+
+```yaml
+folders:
+  - name: Measures
+    members:
+      - count
+      - total_revenue
+      - average_order_value
+
+  - name: Dimensions
+    members:
+      - status
+      - category
+      - region
+
+  - name: Time
+    members:
+      - created_at
+      - updated_at
+```
+
+### By Business Domain
+
+```yaml
+folders:
+  - name: Customer Info
+    members:
+      - customer_name
+      - customer_email
+      - customer_segment
+
+  - name: Order Details
+    members:
+      - order_status
+      - order_total
+      - items_count
+
+  - name: Shipping
+    members:
+      - shipped_at
+      - delivery_status
+      - shipping_cost
+```
+
+### By Analysis Type
+
+```yaml
+folders:
+  - name: KPIs
+    members:
+      - total_revenue
+      - order_count
+      - conversion_rate
+
+  - name: Trends
+    members:
+      - created_at
+      - revenue_growth
+      - yoy_change
+
+  - name: Breakdowns
+    members:
+      - category
+      - region
+      - channel
+```
+
+## Best Practices
+
+1. **Keep folders shallow** — avoid deep nesting
+2. **Use clear names** — business-friendly labels
+3. **Group logically** — related members together
+4. **Limit folder count** — 3-7 folders per view
+
+## See Also
+
+- views
+- views.cubes
+- views.includes
+
+## More Information
+
+https://cube.dev/docs/reference/data-model/view#folders

package/dist/docs/topics/views.includes.md

@@ -0,0 +1,143 @@
+# views.includes
+
+> Control which cube members appear in a view.
+
+## Overview
+
+The `includes` and `excludes` properties control which measures, dimensions, and segments from a cube are exposed in a view. This enables creating focused interfaces that show only relevant data.
+
+## Basic Syntax
+
+### Include Specific Members
+
+```yaml
+- join_path: orders
+  includes:
+    - count
+    - total_revenue
+    - status
+```
+
+### Include All Members
+
+```yaml
+- join_path: orders
+  includes: "*"
+```
+
+### Exclude Specific Members
+
+```yaml
+- join_path: orders
+  includes: "*"
+  excludes:
+    - internal_id
+    - debug_flag
+```
+
+## Member Types
+
+All cube member types can be included:
+
+```yaml
+- join_path: orders
+  includes:
+    # Measures
+    - count
+    - total_revenue
+    - average_order_value
+
+    # Dimensions
+    - status
+    - created_at
+    - customer_email
+
+    # Segments
+    - completed
+    - high_value
+```
+
+## Renaming with Alias
+
+Rename members to avoid collisions or improve clarity:
+
+```yaml
+- join_path: orders
+  includes:
+    - name: count
+      alias: order_count
+
+    - name: created_at
+      alias: order_date
+```
+
+## Prefix Mode
+
+Automatically prefix all members with cube name:
+
+```yaml
+- join_path: orders
+  prefix: true
+  includes: "*"
+  # count -> orders_count
+  # status -> orders_status
+```
+
+Custom prefix:
+
+```yaml
+- join_path: orders
+  prefix: true
+  includes:
+    - name: count
+      alias: total_orders  # Override automatic prefix
+```
+
+## Combining Multiple Cubes
+
+When including the same member name from multiple cubes, use aliases:
+
+```yaml
+views:
+  - name: combined_metrics
+    cubes:
+      - join_path: orders
+        includes:
+          - name: count
+            alias: order_count
+
+      - join_path: users
+        includes:
+          - name: count
+            alias: user_count
+```
+
+## Wildcard Patterns
+
+Use `"*"` to include all, then exclude what you don't need:
+
+```yaml
+- join_path: users
+  includes: "*"
+  excludes:
+    - password_hash
+    - api_secret
+    - internal_notes
+```
+
+## Best Practices
+
+1. **Be explicit** — list specific members rather than using `"*"` in production
+2. **Use aliases** — make member names clear and consistent
+3. **Exclude sensitive data** — never expose passwords, keys, or PII
+4. **Document with descriptions** — override descriptions for clarity
+
+## See Also
+
+- views
+- views.cubes
+- views.folders
+
+## More Information
+
+https://cube.dev/docs/reference/data-model/view#includes