@bonnard/cli 0.1.2 → 0.1.4

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

@@ -0,0 +1,126 @@
+# cubes.measures.types
+
+> The 12 measure types available for aggregating data.
+
+## Overview
+
+Cube supports 12 measure types that determine how values are aggregated. Choose the right type based on your analytical needs.
+
+## Measure Types
+
+### count
+Counts the number of rows.
+
+```yaml
+- name: count
+  type: count
+```
+
+### count_distinct
+Counts unique values of a column.
+
+```yaml
+- name: unique_users
+  type: count_distinct
+  sql: user_id
+```
+
+### count_distinct_approx
+Approximate count distinct (faster for large datasets).
+
+```yaml
+- name: approx_unique_users
+  type: count_distinct_approx
+  sql: user_id
+```
+
+### sum
+Adds up numeric values.
+
+```yaml
+- name: total_revenue
+  type: sum
+  sql: amount
+```
+
+### avg
+Calculates the average of numeric values.
+
+```yaml
+- name: average_order_value
+  type: avg
+  sql: amount
+```
+
+### min
+Returns the minimum value.
+
+```yaml
+- name: first_order_date
+  type: min
+  sql: created_at
+```
+
+### max
+Returns the maximum value.
+
+```yaml
+- name: last_order_date
+  type: max
+  sql: created_at
+```
+
+### number
+A calculated number (not aggregated from rows).
+
+```yaml
+- name: conversion_rate
+  type: number
+  sql: "{completed_orders} / NULLIF({total_orders}, 0)"
+```
+
+### string
+A calculated string value.
+
+```yaml
+- name: status_label
+  type: string
+  sql: "'Active'"
+```
+
+### time
+A calculated time value.
+
+```yaml
+- name: current_timestamp
+  type: time
+  sql: NOW()
+```
+
+### boolean
+A calculated boolean value.
+
+```yaml
+- name: has_orders
+  type: boolean
+  sql: "{count} > 0"
+```
+
+### number_agg
+Custom aggregate function (advanced).
+
+```yaml
+- name: median_price
+  type: number_agg
+  sql: "PERCENTILE_CONT(0.5) WITHIN GROUP (ORDER BY {CUBE}.price)"
+```
+
+## See Also
+
+- cubes.measures
+- cubes.measures.calculated
+- cubes.measures.filters
+
+## More Information
+
+https://cube.dev/docs/reference/data-model/types-and-formats#measure-types

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

@@ -0,0 +1,176 @@
+# cubes.public
+
+> Control visibility of cubes, measures, and dimensions in the API.
+
+## Overview
+
+The `public` property controls whether a cube or its members are exposed through the API. Set to `false` to hide internal or intermediate data from consumers.
+
+## Example
+
+```yaml
+cubes:
+  # Hidden cube - used for joins only
+  - name: internal_mappings
+    public: false
+    sql_table: internal.mappings
+
+    dimensions:
+      - name: id
+        type: number
+        sql: id
+        primary_key: true
+
+  # Public cube with some hidden members
+  - name: orders
+    sql_table: orders
+
+    measures:
+      - name: count
+        type: count
+
+      - name: internal_score
+        type: avg
+        sql: score
+        public: false  # Hidden from API
+
+    dimensions:
+      - name: id
+        type: number
+        sql: id
+        primary_key: true
+        public: false  # Primary keys auto-hide by default
+
+      - name: status
+        type: string
+        sql: status
+```
+
+## Syntax
+
+### Cube Level
+
+```yaml
+cubes:
+  - name: internal_cube
+    public: false
+```
+
+### Measure Level
+
+```yaml
+measures:
+  - name: debug_metric
+    type: count
+    public: false
+```
+
+### Dimension Level
+
+```yaml
+dimensions:
+  - name: internal_id
+    type: string
+    sql: internal_id
+    public: false
+```
+
+### Segment Level
+
+```yaml
+segments:
+  - name: test_users
+    sql: "{CUBE}.is_test = true"
+    public: false
+```
+
+## Default Behavior
+
+| Member Type | Default `public` |
+|-------------|------------------|
+| Cube | `true` |
+| Measure | `true` |
+| Dimension | `true` |
+| Dimension with `primary_key: true` | `false` |
+| Segment | `true` |
+
+## Use Cases
+
+### Internal Cubes
+
+Hide cubes used only for joins or intermediate calculations:
+
+```yaml
+cubes:
+  - name: user_scores_internal
+    public: false
+    sql: "SELECT user_id, calculate_score() as score FROM users"
+```
+
+### Sensitive Fields
+
+Hide fields that shouldn't be queried directly:
+
+```yaml
+dimensions:
+  - name: password_hash
+    type: string
+    sql: password_hash
+    public: false
+
+  - name: api_secret
+    type: string
+    sql: api_secret
+    public: false
+```
+
+### Intermediate Measures
+
+Hide measures used only in calculations:
+
+```yaml
+measures:
+  - name: raw_numerator
+    type: sum
+    sql: value
+    public: false
+
+  - name: raw_denominator
+    type: count
+    public: false
+
+  - name: ratio
+    type: number
+    sql: "{raw_numerator} / NULLIF({raw_denominator}, 0)"
+    # This is public (default)
+```
+
+### Debug/Test Members
+
+```yaml
+segments:
+  - name: test_data
+    sql: "{CUBE}.is_test = true"
+    public: false
+```
+
+## Dynamic Visibility
+
+Use `COMPILE_CONTEXT` for dynamic visibility based on context:
+
+```yaml
+cubes:
+  - name: admin_metrics
+    public: "{{ 'true' if COMPILE_CONTEXT.role == 'admin' else 'false' }}"
+```
+
+## See Also
+
+- cubes
+- cubes.measures
+- cubes.dimensions
+- views
+
+## More Information
+
+https://cube.dev/docs/reference/data-model/cube#public

package/dist/docs/topics/cubes.refresh-key.md

@@ -0,0 +1,157 @@
+# cubes.refresh-key
+
+> Control when cube data is refreshed in the cache.
+
+## Overview
+
+The `refresh_key` property determines when Cube's cache should be invalidated. Use it to ensure queries return fresh data while optimizing performance.
+
+## Example
+
+```yaml
+cubes:
+  - name: orders
+    sql_table: orders
+
+    refresh_key:
+      every: 1 hour
+
+    measures:
+      - name: count
+        type: count
+```
+
+## Refresh Strategies
+
+### Time-Based Refresh
+
+Refresh at regular intervals:
+
+```yaml
+refresh_key:
+  every: 1 hour
+```
+
+```yaml
+refresh_key:
+  every: 10 minute
+```
+
+```yaml
+refresh_key:
+  every: 1 day
+```
+
+### SQL-Based Refresh
+
+Refresh when a SQL query returns a different value:
+
+```yaml
+refresh_key:
+  sql: SELECT MAX(updated_at) FROM orders
+```
+
+This is efficient for append-only or update-tracked tables.
+
+### Combined Approach
+
+Use SQL with a time-based check interval:
+
+```yaml
+refresh_key:
+  sql: SELECT MAX(updated_at) FROM orders
+  every: 5 minute
+```
+
+The SQL runs every 5 minutes; cache refreshes only when the result changes.
+
+## Syntax
+
+### every
+
+Time interval format: `<number> <unit>`
+
+| Unit | Examples |
+|------|----------|
+| `second` | `30 second` |
+| `minute` | `5 minute`, `10 minute` |
+| `hour` | `1 hour`, `6 hour` |
+| `day` | `1 day` |
+| `week` | `1 week` |
+
+### sql
+
+Any SQL that returns a single value. Common patterns:
+
+```yaml
+# Max timestamp (for append-only data)
+sql: SELECT MAX(created_at) FROM orders
+
+# Row count (for small tables)
+sql: SELECT COUNT(*) FROM orders
+
+# Checksum (for frequently updated data)
+sql: SELECT CHECKSUM_AGG(CHECKSUM(*)) FROM orders
+```
+
+## Common Patterns
+
+### Real-Time Data
+
+```yaml
+refresh_key:
+  every: 1 minute
+```
+
+### Daily Batch Data
+
+```yaml
+refresh_key:
+  every: 1 day
+  sql: SELECT MAX(load_date) FROM daily_snapshot
+```
+
+### Event Stream Data
+
+```yaml
+refresh_key:
+  sql: SELECT MAX(event_id) FROM events
+  every: 30 second
+```
+
+### Slowly Changing Data
+
+```yaml
+refresh_key:
+  every: 6 hour
+```
+
+## Pre-Aggregation Refresh
+
+Pre-aggregations have their own refresh_key:
+
+```yaml
+pre_aggregations:
+  - name: main
+    measures:
+      - count
+    refresh_key:
+      every: 1 hour
+```
+
+## Best Practices
+
+1. **Match data freshness needs** — don't refresh more often than necessary
+2. **Use SQL-based refresh** — for tables with update timestamps
+3. **Consider pre-aggregations** — they have separate refresh cycles
+4. **Monitor performance** — frequent refreshes impact query latency
+
+## See Also
+
+- cubes
+- pre-aggregations
+- pre-aggregations.rollup
+
+## More Information
+
+https://cube.dev/docs/reference/data-model/cube#refresh-key

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

@@ -0,0 +1,125 @@
+# cubes.segments
+
+> Define reusable row-level filters.
+
+## Overview
+
+Segments are predefined filters that can be applied to queries. They make common filtering patterns reusable and ensure consistent definitions across analyses.
+
+## Example
+
+```yaml
+cubes:
+  - name: orders
+    sql: SELECT * FROM orders
+
+    segments:
+      - name: completed
+        sql: "{CUBE}.status = 'completed'"
+
+      - name: high_value
+        sql: "{CUBE}.amount > 1000"
+
+      - name: this_year
+        sql: "YEAR({CUBE}.created_at) = YEAR(CURRENT_DATE)"
+```
+
+## Syntax
+
+### Basic Segment
+
+```yaml
+segments:
+  - name: active
+    sql: "{CUBE}.is_active = true"
+```
+
+### Multiple Conditions
+
+```yaml
+segments:
+  - name: premium_active
+    sql: "{CUBE}.is_active = true AND {CUBE}.plan = 'premium'"
+```
+
+### Using References
+
+```yaml
+segments:
+  - name: has_recent_order
+    sql: "{CUBE}.last_order_date > CURRENT_DATE - INTERVAL '30 days'"
+```
+
+## Segments vs Filters
+
+| Segments | Query Filters |
+|----------|---------------|
+| Predefined in model | Applied at query time |
+| Named and reusable | Ad-hoc |
+| Part of the schema | Part of the query |
+| Self-documenting | Requires context |
+
+## Segments vs Filtered Measures
+
+| Use Case | Solution |
+|----------|----------|
+| Filter all measures in a query | Segment |
+| Create a specific filtered metric | Filtered measure |
+
+```yaml
+# Segment: filters entire query
+segments:
+  - name: completed
+    sql: "{CUBE}.status = 'completed'"
+
+# Filtered measure: only this metric
+measures:
+  - name: completed_count
+    type: count
+    filters:
+      - sql: "{CUBE}.status = 'completed'"
+```
+
+## Common Patterns
+
+### Status Segments
+
+```yaml
+segments:
+  - name: pending
+    sql: "{CUBE}.status = 'pending'"
+  - name: completed
+    sql: "{CUBE}.status = 'completed'"
+  - name: cancelled
+    sql: "{CUBE}.status = 'cancelled'"
+```
+
+### Time-based Segments
+
+```yaml
+segments:
+  - name: last_7_days
+    sql: "{CUBE}.created_at >= CURRENT_DATE - INTERVAL '7 days'"
+  - name: last_30_days
+    sql: "{CUBE}.created_at >= CURRENT_DATE - INTERVAL '30 days'"
+```
+
+### Business Logic Segments
+
+```yaml
+segments:
+  - name: churned
+    sql: "{CUBE}.last_activity_at < CURRENT_DATE - INTERVAL '90 days'"
+  - name: high_value_customer
+    sql: "{CUBE}.lifetime_value > 10000"
+```
+
+## See Also
+
+- cubes
+- cubes.measures.filters
+- views
+
+## More Information
+
+https://cube.dev/docs/reference/data-model/segments

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

@@ -0,0 +1,65 @@
+# cubes.sql
+
+> Define the SQL table or subquery that powers a cube.
+
+## Overview
+
+The `sql` property defines the base table or SQL subquery that a cube is built on. This is the foundation for all measures and dimensions in the cube.
+
+## Example
+
+```yaml
+cubes:
+  - name: orders
+    sql: SELECT * FROM public.orders
+
+  - name: orders_with_users
+    sql: >
+      SELECT o.*, u.name as user_name
+      FROM public.orders o
+      LEFT JOIN public.users u ON o.user_id = u.id
+```
+
+## Options
+
+### sql (required)
+The SQL SELECT statement or table reference.
+
+```yaml
+# Simple table reference
+sql: SELECT * FROM orders
+
+# Subquery with joins
+sql: >
+  SELECT o.*, p.name as product_name
+  FROM orders o
+  JOIN products p ON o.product_id = p.id
+
+# Using references to other cubes
+sql: SELECT * FROM {users.sql()} WHERE active = true
+```
+
+### sql_table
+Alternative to `sql` — directly reference a table without SELECT.
+
+```yaml
+cubes:
+  - name: orders
+    sql_table: public.orders
+```
+
+## Best Practices
+
+1. **Prefer sql_table** when selecting all columns from a single table
+2. **Use subqueries** for complex joins or filtering at the cube level
+3. **Avoid aggregations** in the base SQL — let measures handle that
+
+## See Also
+
+- cubes
+- cubes.data-source
+- syntax.references
+
+## More Information
+
+https://cube.dev/docs/reference/data-model/cube#sql