@bonnard/cli 0.1.3 → 0.1.5

package/dist/docs/topics/pre-aggregations.md

@@ -0,0 +1,126 @@
+# pre-aggregations
+
+> Materialize query results for faster analytics performance.
+
+## Overview
+
+Pre-aggregations are materialized tables that store pre-computed query results. They dramatically improve query performance by avoiding repeated aggregation of raw data.
+
+## Example
+
+```yaml
+cubes:
+  - name: orders
+    sql_table: orders
+
+    measures:
+      - name: count
+        type: count
+
+      - name: total_revenue
+        type: sum
+        sql: amount
+
+    dimensions:
+      - name: status
+        type: string
+        sql: status
+
+      - name: created_at
+        type: time
+        sql: created_at
+
+    pre_aggregations:
+      - name: orders_by_day
+        measures:
+          - count
+          - total_revenue
+        dimensions:
+          - status
+        time_dimension: created_at
+        granularity: day
+```
+
+## Pre-Aggregation Types
+
+### rollup (default)
+Summarizes data into aggregated form. Most effective for performance.
+
+```yaml
+pre_aggregations:
+  - name: main
+    type: rollup
+    measures:
+      - count
+      - total_revenue
+    dimensions:
+      - status
+    time_dimension: created_at
+    granularity: day
+```
+
+### original_sql
+Persists the cube's SQL query without aggregation. Useful for complex SQL.
+
+```yaml
+pre_aggregations:
+  - name: base_data
+    type: original_sql
+```
+
+### rollup_join
+Joins pre-aggregations from different data sources (preview feature).
+
+### rollup_lambda
+Combines real-time and historical data (advanced).
+
+## Key Properties
+
+| Property | Description |
+|----------|-------------|
+| `name` | Unique identifier |
+| `type` | `rollup`, `original_sql`, `rollup_join`, `rollup_lambda` |
+| `measures` | Measures to include |
+| `dimensions` | Dimensions to include |
+| `time_dimension` | Time dimension for partitioning |
+| `granularity` | Time granularity: `day`, `week`, `month`, etc. |
+| `partition_granularity` | How to partition data |
+| `refresh_key` | When to refresh |
+| `scheduled_refresh` | Auto-refresh (default: true) |
+
+## Additive vs Non-Additive
+
+**Additive measures** (count, sum, min, max) can be combined from pre-aggregated data:
+
+```yaml
+# These work efficiently with rollups
+measures:
+  - name: count
+    type: count
+  - name: total
+    type: sum
+    sql: amount
+```
+
+**Non-additive measures** (count_distinct, avg) may require the original data:
+
+```yaml
+# count_distinct needs special handling
+measures:
+  - name: unique_users
+    type: count_distinct
+    sql: user_id
+```
+
+## Best Practices
+
+1. **Start with common queries** — pre-aggregate your most frequent access patterns
+2. **Include all needed members** — queries must match the pre-aggregation exactly
+3. **Use partitioning** — for large datasets, partition by time
+4. **Monitor refresh** — ensure data stays current
+
+## See Also
+
+- pre-aggregations.rollup
+- cubes.measures
+- cubes.dimensions.time

package/dist/docs/topics/pre-aggregations.rollup.md

@@ -0,0 +1,162 @@
+# pre-aggregations.rollup
+
+> Create summarized data tables for high-performance queries.
+
+## Overview
+
+Rollup pre-aggregations summarize raw data into aggregated tables, grouped by specified dimensions. They're the most effective way to improve query performance.
+
+## Example
+
+```yaml
+pre_aggregations:
+  - name: orders_daily
+    type: rollup
+    measures:
+      - count
+      - total_revenue
+    dimensions:
+      - status
+      - category
+    time_dimension: created_at
+    granularity: day
+    partition_granularity: month
+```
+
+## Time-Based Rollups
+
+### Basic Time Rollup
+
+```yaml
+- name: daily_orders
+  measures:
+    - count
+  time_dimension: created_at
+  granularity: day
+```
+
+### Partitioned Rollup
+
+Partition large datasets for efficient refreshes:
+
+```yaml
+- name: orders_monthly_partitioned
+  measures:
+    - count
+    - total_revenue
+  time_dimension: created_at
+  granularity: day
+  partition_granularity: month
+```
+
+### Granularity Options
+
+| Granularity | Description |
+|-------------|-------------|
+| `second` | Per-second aggregation |
+| `minute` | Per-minute aggregation |
+| `hour` | Hourly aggregation |
+| `day` | Daily aggregation |
+| `week` | Weekly aggregation |
+| `month` | Monthly aggregation |
+| `quarter` | Quarterly aggregation |
+| `year` | Yearly aggregation |
+
+## Refresh Strategies
+
+### Time-Based Refresh
+
+```yaml
+- name: orders_hourly
+  measures:
+    - count
+  time_dimension: created_at
+  granularity: hour
+  refresh_key:
+    every: 1 hour
+```
+
+### Incremental Refresh
+
+Only refresh recent partitions:
+
+```yaml
+- name: orders_incremental
+  measures:
+    - count
+    - total_revenue
+  time_dimension: created_at
+  granularity: day
+  partition_granularity: month
+  refresh_key:
+    every: 1 day
+    incremental: true
+    update_window: 7 day
+```
+
+### SQL-Based Refresh
+
+Refresh when data changes:
+
+```yaml
+- name: orders_on_change
+  measures:
+    - count
+  refresh_key:
+    sql: SELECT MAX(updated_at) FROM orders
+```
+
+## Indexes
+
+Add indexes for better query performance:
+
+```yaml
+- name: orders_by_status
+  measures:
+    - count
+  dimensions:
+    - status
+    - category
+  indexes:
+    - name: status_idx
+      columns:
+        - status
+```
+
+## Query Matching
+
+A query uses a rollup if:
+1. All requested measures are in the rollup
+2. All requested dimensions are in the rollup
+3. Time dimension granularity is compatible
+4. Filters match the rollup's data
+
+```yaml
+# This rollup...
+- name: orders_daily
+  measures:
+    - count
+    - total_revenue
+  dimensions:
+    - status
+  time_dimension: created_at
+  granularity: day
+
+# ...matches queries like:
+# - orders.count by day
+# - orders.total_revenue by status by week (day rolls up to week)
+# - orders.count where status = 'completed' by month
+```
+
+## Best Practices
+
+1. **Match your queries** — design rollups around common access patterns
+2. **Use incremental refresh** — for large time-series data
+3. **Partition wisely** — monthly partitions work well for most cases
+4. **Add indexes** — for high-cardinality dimension filters
+
+## See Also
+
+- pre-aggregations
+- cubes.dimensions.time
+- cubes.measures

package/dist/docs/topics/syntax.context-variables.md

@@ -0,0 +1,153 @@
+# syntax.context-variables
+
+> Access runtime context in SQL expressions.
+
+## Overview
+
+Context variables provide access to runtime information within cube definitions. Use them for dynamic SQL generation, filter handling, and security context.
+
+## Context Variables
+
+### {CUBE}
+
+References the current cube without repeating its name:
+
+```yaml
+cubes:
+  - name: orders
+    dimensions:
+      - name: status
+        type: string
+        sql: "{CUBE}.status"  # Same as "{orders}.status"
+
+    measures:
+      - name: completed_count
+        type: count
+        filters:
+          - sql: "{CUBE}.status = 'completed'"
+```
+
+Essential when using `extends` so SQL works in child cubes.
+
+### FILTER_PARAMS
+
+Access filter values from queries during SQL generation:
+
+```yaml
+cubes:
+  - name: orders
+    sql: >
+      SELECT * FROM orders
+      WHERE {FILTER_PARAMS.orders.created_at.filter('created_at')}
+```
+
+Useful for:
+- Partition pruning in data warehouses
+- Predicate pushdown optimization
+- Dynamic table selection
+
+Syntax: `{FILTER_PARAMS.cube_name.member_name.filter('sql_expression')}`
+
+### FILTER_GROUP
+
+Wraps multiple FILTER_PARAMS when combining with OR:
+
+```yaml
+sql: >
+  SELECT * FROM orders
+  WHERE {FILTER_GROUP(
+    FILTER_PARAMS.orders.status.filter('status'),
+    FILTER_PARAMS.orders.type.filter('type')
+  )}
+```
+
+Prevents incorrect SQL when filters use OR logic.
+
+### COMPILE_CONTEXT
+
+Evaluated once per deployment context. Access via Jinja syntax:
+
+```yaml
+cubes:
+  - name: orders
+    sql_table: "{{ COMPILE_CONTEXT.schema }}.orders"
+
+    public: "{{ 'true' if COMPILE_CONTEXT.role == 'admin' else 'false' }}"
+```
+
+Common uses:
+- Multi-tenant table names
+- Environment-specific configuration
+- Role-based visibility
+
+### SQL_UTILS
+
+Helper functions for SQL generation:
+
+```yaml
+dimensions:
+  - name: created_at_local
+    type: time
+    sql: "{SQL_UTILS.convertTz('created_at', 'UTC', 'America/New_York')}"
+```
+
+**convertTz()**: Converts timestamps between timezones.
+
+Note: Don't use SQL_UTILS dimensions as `timeDimensions` in queries to avoid double conversion.
+
+## Examples
+
+### Partition Filtering (Snowflake/BigQuery)
+
+```yaml
+cubes:
+  - name: events
+    sql: >
+      SELECT * FROM events
+      WHERE {FILTER_PARAMS.events.timestamp.filter('timestamp')}
+```
+
+When querying with a date filter, this pushes the filter to the partition column for efficient pruning.
+
+### Multi-Tenant Tables
+
+```yaml
+cubes:
+  - name: orders
+    sql_table: "{{ COMPILE_CONTEXT.tenant_schema }}.orders"
+```
+
+### Dynamic Visibility
+
+```yaml
+cubes:
+  - name: sensitive_data
+    public: "{{ 'true' if COMPILE_CONTEXT.user_role in ['admin', 'analyst'] else 'false' }}"
+```
+
+### Timezone Conversion
+
+```yaml
+dimensions:
+  - name: created_at_et
+    type: time
+    sql: "{SQL_UTILS.convertTz('created_at', 'UTC', 'America/New_York')}"
+    title: "Created At (ET)"
+```
+
+## Best Practices
+
+1. **Use {CUBE}** in extendable cubes — never hardcode cube names
+2. **Use FILTER_PARAMS** for partition pruning — improves query performance
+3. **Use COMPILE_CONTEXT** for deployment config — not for per-query logic
+4. **Test filter pushdown** — verify FILTER_PARAMS generates expected SQL
+
+## Deprecated: SECURITY_CONTEXT
+
+`SECURITY_CONTEXT` is deprecated. Use `query_rewrite` for security filtering instead.
+
+## See Also
+
+- syntax
+- syntax.references
+- cubes.extends

package/dist/docs/topics/syntax.md

@@ -0,0 +1,133 @@
+# syntax
+
+> YAML syntax and conventions for Cube data models.
+
+## Overview
+
+Cube data models are defined in YAML files. Understanding the syntax conventions helps you write correct and maintainable models.
+
+## File Structure
+
+### Cubes File
+
+```yaml
+cubes:
+  - name: orders
+    sql_table: public.orders
+
+    measures:
+      - name: count
+        type: count
+
+    dimensions:
+      - name: id
+        type: number
+        sql: id
+        primary_key: true
+```
+
+### Views File
+
+```yaml
+views:
+  - name: orders_overview
+    cubes:
+      - join_path: orders
+        includes:
+          - count
+          - status
+```
+
+## Naming Conventions
+
+### Cube and View Names
+
+- Use `snake_case`
+- Be descriptive: `user_orders`, not `uo`
+- Use plural for collections: `orders`, `users`
+
+```yaml
+cubes:
+  - name: orders           # Good
+  - name: user_activity    # Good
+  - name: Orders           # Bad - use lowercase
+  - name: userOrders       # Bad - use snake_case
+```
+
+### Member Names
+
+- Use `snake_case`
+- Be descriptive but concise
+
+```yaml
+measures:
+  - name: count                    # Good
+  - name: total_revenue            # Good
+  - name: average_order_value      # Good
+  - name: aov                      # Bad - unclear abbreviation
+```
+
+## SQL Expressions
+
+### Inline SQL
+
+```yaml
+dimensions:
+  - name: full_name
+    type: string
+    sql: "CONCAT(first_name, ' ', last_name)"
+```
+
+### Multi-line SQL
+
+Use YAML block scalar for complex SQL:
+
+```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
+```
+
+## Common Patterns
+
+### Quoting
+
+Quote SQL expressions with special characters:
+
+```yaml
+# Quoted - required for expressions
+sql: "{CUBE}.amount * 0.1"
+
+# Unquoted - simple column reference
+sql: amount
+```
+
+### Arrays
+
+```yaml
+# Inline array
+includes: [count, total_revenue]
+
+# Block array
+includes:
+  - count
+  - total_revenue
+```
+
+### Booleans
+
+```yaml
+primary_key: true
+public: false
+```
+
+## See Also
+
+- syntax.references
+- cubes
+- views