@bonnard/cli 0.1.3 → 0.1.5

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

@@ -0,0 +1,184 @@
+# cubes.dimensions
+
+> Define attributes for grouping and filtering data.
+
+## Overview
+
+Dimensions are the attributes used to slice and filter your data. They answer questions like "by what?", "which ones?", and "when?". Dimensions enable grouping measures and applying filters.
+
+## Example
+
+```yaml
+dimensions:
+  - name: id
+    type: number
+    sql: id
+    primary_key: true
+    description: Unique order identifier
+
+  - name: status
+    type: string
+    sql: status
+    description: Order status (pending, completed, cancelled)
+
+  - name: amount
+    type: number
+    sql: amount
+    description: Order amount in dollars
+
+  - name: is_active
+    type: boolean
+    sql: is_active
+    description: Whether the order is currently active
+
+  - name: created_at
+    type: time
+    sql: created_at
+    description: When the order was created
+```
+
+## Required Properties
+
+| Property | Description |
+|----------|-------------|
+| `name` | Unique identifier in snake_case |
+| `type` | Data type (string, number, time, etc.) |
+| `sql` | SQL expression for the value |
+
+## Optional Properties
+
+| Property | Description |
+|----------|-------------|
+| `primary_key` | Marks as unique identifier (required for joins) |
+| `title` | Human-readable display name |
+| `description` | Documentation for consumers |
+| `format` | Output format hints |
+| `public` | Whether exposed in API (default: true) |
+
+## Dimension Types
+
+### string
+
+Text values for categorization:
+
+```yaml
+- name: status
+  type: string
+  sql: status
+
+- name: full_name
+  type: string
+  sql: "CONCAT(first_name, ' ', last_name)"
+```
+
+### number
+
+Numeric values (not aggregated):
+
+```yaml
+- name: quantity
+  type: number
+  sql: quantity
+
+- name: unit_price
+  type: number
+  sql: price
+```
+
+### boolean
+
+True/false values:
+
+```yaml
+- name: is_active
+  type: boolean
+  sql: is_active
+
+- name: has_subscription
+  type: boolean
+  sql: "subscription_id IS NOT NULL"
+```
+
+### time
+
+Dates and timestamps (enables time-based analysis):
+
+```yaml
+- name: created_at
+  type: time
+  sql: created_at
+
+- name: order_date
+  type: time
+  sql: DATE(ordered_at)
+```
+
+### geo
+
+Geographic coordinates:
+
+```yaml
+- name: location
+  type: geo
+  latitude:
+    sql: lat
+  longitude:
+    sql: lng
+```
+
+### switch
+
+Enumerated values with labels:
+
+```yaml
+- name: status_label
+  type: switch
+  case:
+    when:
+      - sql: "{CUBE}.status = 'active'"
+        label: Active
+      - sql: "{CUBE}.status = 'inactive'"
+        label: Inactive
+    else:
+      label: Unknown
+```
+
+## Primary Key
+
+Mark the unique identifier — required for joins and count_distinct:
+
+```yaml
+- name: id
+  type: number
+  sql: id
+  primary_key: true
+```
+
+## Calculated Dimensions
+
+Create derived attributes:
+
+```yaml
+- name: order_size
+  type: string
+  sql: >
+    CASE
+      WHEN {CUBE}.amount > 1000 THEN 'large'
+      WHEN {CUBE}.amount > 100 THEN 'medium'
+      ELSE 'small'
+    END
+```
+
+## Best Practices
+
+1. **Always define a primary key** — enables joins and count_distinct
+2. **Use appropriate types** — time for dates, string for categories
+3. **Name clearly** — `customer_email` not `email1`
+4. **Document business logic** — explain calculated dimensions
+
+## See Also
+
+- cubes.dimensions.types
+- cubes.dimensions.primary-key
+- cubes.dimensions.time
+- cubes.joins

package/dist/docs/topics/cubes.dimensions.primary-key.md

@@ -0,0 +1,106 @@
+# cubes.dimensions.primary-key
+
+> Mark the unique identifier dimension for a cube.
+
+## Overview
+
+The `primary_key` property identifies the dimension that uniquely identifies each row. This is required for `count_distinct` measures and joins to work correctly.
+
+## Example
+
+```yaml
+cubes:
+  - name: users
+    sql: SELECT * FROM users
+
+    dimensions:
+      - name: id
+        type: number
+        sql: id
+        primary_key: true
+
+      - name: email
+        type: string
+        sql: email
+```
+
+## Why It Matters
+
+### Enables count_distinct
+
+Without a primary key, count_distinct may produce incorrect results:
+
+```yaml
+measures:
+  - name: unique_users
+    type: count_distinct
+    sql: "{users.id}"  # Requires primary_key on users.id
+```
+
+### Required for Joins
+
+Cube uses primary keys to correctly join data:
+
+```yaml
+cubes:
+  - name: orders
+    sql: SELECT * FROM orders
+
+    dimensions:
+      - name: id
+        type: number
+        sql: id
+        primary_key: true
+
+    joins:
+      - name: users
+        relationship: many_to_one
+        sql: "{CUBE}.user_id = {users.id}"
+```
+
+### Affects Pre-aggregations
+
+Primary keys determine how pre-aggregations handle duplicates.
+
+## Rules
+
+1. **At least one per cube** — required for joins and count_distinct to work
+2. **Composite keys supported** — multiple dimensions can be marked as primary key
+3. **Must be unique** — the combination of primary key values should not repeat
+4. **Usually numeric** — but can be string (UUID, etc.)
+5. **Auto-hides from API** — primary key dimensions default to `public: false`
+
+## Common Patterns
+
+### Auto-increment ID
+
+```yaml
+- name: id
+  type: number
+  sql: id
+  primary_key: true
+```
+
+### UUID
+
+```yaml
+- name: id
+  type: string
+  sql: id
+  primary_key: true
+```
+
+### Composite Key (use concat)
+
+```yaml
+- name: composite_id
+  type: string
+  sql: "CONCAT(order_id, '-', line_item_id)"
+  primary_key: true
+```
+
+## See Also
+
+- cubes.dimensions
+- cubes.dimensions.types
+- cubes.joins

package/dist/docs/topics/cubes.dimensions.sub-query.md

@@ -0,0 +1,174 @@
+# cubes.dimensions.sub-query
+
+> Bring measures from other cubes into a dimension.
+
+## Overview
+
+Subquery dimensions allow you to reference measures from joined cubes as dimension values. This enables nested aggregations and bringing aggregate values into row-level context.
+
+## Example
+
+```yaml
+cubes:
+  - name: users
+    sql_table: users
+
+    dimensions:
+      - name: id
+        type: number
+        sql: id
+        primary_key: true
+
+      - name: name
+        type: string
+        sql: name
+
+      # Subquery dimension - brings order count as a user attribute
+      - name: order_count
+        type: number
+        sql: "{orders.count}"
+        sub_query: true
+
+    joins:
+      - name: orders
+        relationship: one_to_many
+        sql: "{CUBE}.id = {orders.user_id}"
+
+  - name: orders
+    sql_table: orders
+
+    measures:
+      - name: count
+        type: count
+
+    dimensions:
+      - name: id
+        type: number
+        sql: id
+        primary_key: true
+
+      - name: user_id
+        type: number
+        sql: user_id
+```
+
+## Properties
+
+| Property | Description |
+|----------|-------------|
+| `sub_query: true` | Enables measure reference in dimension |
+| `propagate_filters_to_sub_query` | Pass query filters to the subquery |
+
+## Syntax
+
+### Basic Subquery Dimension
+
+```yaml
+dimensions:
+  - name: total_orders
+    type: number
+    sql: "{orders.count}"
+    sub_query: true
+```
+
+### With Filter Propagation
+
+```yaml
+dimensions:
+  - name: recent_order_count
+    type: number
+    sql: "{orders.count}"
+    sub_query: true
+    propagate_filters_to_sub_query: true
+```
+
+When `propagate_filters_to_sub_query: true`, filters applied in the main query also apply to the subquery aggregation.
+
+## How It Works
+
+Cube generates an optimized LEFT JOIN with an aggregation subquery:
+
+```sql
+SELECT
+  users.id,
+  users.name,
+  orders_subquery.count AS order_count
+FROM users
+LEFT JOIN (
+  SELECT user_id, COUNT(*) as count
+  FROM orders
+  GROUP BY user_id
+) AS orders_subquery ON users.id = orders_subquery.user_id
+```
+
+## Use Cases
+
+### User Metrics
+
+```yaml
+# On users cube
+dimensions:
+  - name: lifetime_order_count
+    type: number
+    sql: "{orders.count}"
+    sub_query: true
+
+  - name: lifetime_revenue
+    type: number
+    sql: "{orders.total_revenue}"
+    sub_query: true
+```
+
+### Product Statistics
+
+```yaml
+# On products cube
+dimensions:
+  - name: times_purchased
+    type: number
+    sql: "{order_items.count}"
+    sub_query: true
+
+  - name: total_quantity_sold
+    type: number
+    sql: "{order_items.total_quantity}"
+    sub_query: true
+```
+
+### Categorization Based on Aggregates
+
+```yaml
+dimensions:
+  - name: order_count
+    type: number
+    sql: "{orders.count}"
+    sub_query: true
+
+  - name: customer_tier
+    type: string
+    sql: >
+      CASE
+        WHEN {order_count} >= 100 THEN 'platinum'
+        WHEN {order_count} >= 50 THEN 'gold'
+        WHEN {order_count} >= 10 THEN 'silver'
+        ELSE 'bronze'
+      END
+```
+
+## Requirements
+
+1. **Join must exist** between the cubes
+2. **Measure must exist** in the joined cube
+3. **Primary key required** on both cubes
+
+## Best Practices
+
+1. **Use for commonly needed aggregates** — avoid creating subquery dimensions for rarely used metrics
+2. **Consider performance** — subqueries add complexity to generated SQL
+3. **Document the relationship** — make it clear where the data comes from
+
+## See Also
+
+- cubes.dimensions
+- cubes.joins
+- cubes.measures

package/dist/docs/topics/cubes.dimensions.time.md

@@ -0,0 +1,111 @@
+# cubes.dimensions.time
+
+> Enable time-based analysis with time dimensions.
+
+## Overview
+
+Time dimensions (`type: time`) enable powerful time-based analysis including granularity selection, date ranges, and rolling windows. They're essential for any time-series analytics.
+
+## Example
+
+```yaml
+dimensions:
+  - name: created_at
+    type: time
+    sql: created_at
+
+  - name: order_date
+    type: time
+    sql: DATE(ordered_at)
+```
+
+## Time Granularities
+
+When querying a time dimension, you can specify granularity:
+
+| Granularity | Description |
+|-------------|-------------|
+| `second` | Group by second |
+| `minute` | Group by minute |
+| `hour` | Group by hour |
+| `day` | Group by day |
+| `week` | Group by week (Monday start) |
+| `month` | Group by month |
+| `quarter` | Group by quarter |
+| `year` | Group by year |
+
+## Query Usage
+
+Time dimensions can be used in `timeDimensions` for special handling:
+
+```json
+{
+  "measures": ["orders.count"],
+  "timeDimensions": [{
+    "dimension": "orders.created_at",
+    "granularity": "month",
+    "dateRange": ["2024-01-01", "2024-12-31"]
+  }]
+}
+```
+
+## Date Ranges
+
+Common date range options:
+
+- `"today"`, `"yesterday"`
+- `"this week"`, `"last week"`
+- `"this month"`, `"last month"`
+- `"this year"`, `"last year"`
+- `"last 7 days"`, `"last 30 days"`
+- `["2024-01-01", "2024-12-31"]` (custom range)
+
+## Best Practices
+
+### Use Native Timestamps
+
+```yaml
+# Good - preserves precision
+- name: created_at
+  type: time
+  sql: created_at
+
+# Avoid - loses time component
+- name: created_at
+  type: time
+  sql: DATE(created_at)
+```
+
+### Multiple Time Dimensions
+
+A cube can have multiple time dimensions for different purposes:
+
+```yaml
+- name: created_at
+  type: time
+  sql: created_at
+
+- name: shipped_at
+  type: time
+  sql: shipped_at
+
+- name: delivered_at
+  type: time
+  sql: delivered_at
+```
+
+### Timezone Handling
+
+For consistent timezone handling, convert in SQL:
+
+```yaml
+- name: created_at
+  type: time
+  sql: "CONVERT_TIMEZONE('UTC', 'America/New_York', created_at)"
+```
+
+## See Also
+
+- cubes.dimensions
+- cubes.dimensions.types
+- cubes.measures.rolling

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

@@ -0,0 +1,107 @@
+# cubes.dimensions.types
+
+> The 6 dimension types for categorizing and filtering data.
+
+## Overview
+
+Dimensions define the attributes used to group and filter data. Choose the appropriate type based on the data characteristics.
+
+## Dimension Types
+
+### string
+Text values for categorization.
+
+```yaml
+- name: status
+  type: string
+  sql: status
+
+- name: full_name
+  type: string
+  sql: "CONCAT(first_name, ' ', last_name)"
+```
+
+### number
+Numeric values (not aggregated).
+
+```yaml
+- name: quantity
+  type: number
+  sql: quantity
+
+- name: price
+  type: number
+  sql: unit_price
+```
+
+### boolean
+True/false values.
+
+```yaml
+- name: is_active
+  type: boolean
+  sql: is_active
+
+- name: has_orders
+  type: boolean
+  sql: "order_count > 0"
+```
+
+### time
+Date and timestamp values (enables time-based analysis).
+
+```yaml
+- name: created_at
+  type: time
+  sql: created_at
+
+- name: order_date
+  type: time
+  sql: DATE(ordered_at)
+```
+
+### geo
+Geographic coordinates (latitude/longitude).
+
+```yaml
+- name: location
+  type: geo
+  latitude:
+    sql: lat
+  longitude:
+    sql: lng
+```
+
+### switch
+Dimension with predefined set of values.
+
+```yaml
+- name: status_label
+  type: switch
+  sql: status
+  case:
+    when:
+      - sql: "{CUBE}.status = 'active'"
+        label: Active
+      - sql: "{CUBE}.status = 'inactive'"
+        label: Inactive
+    else:
+      label: Unknown
+```
+
+## Type Selection Guide
+
+| Data | Type | Example |
+|------|------|---------|
+| Categories, names, IDs | `string` | status, country, user_id |
+| Prices, quantities | `number` | price, quantity, score |
+| Flags, toggles | `boolean` | is_active, has_subscription |
+| Dates, timestamps | `time` | created_at, order_date |
+| Coordinates | `geo` | location, delivery_point |
+| Enumerated values | `switch` | status_label, tier_name |
+
+## See Also
+
+- cubes.dimensions
+- cubes.dimensions.primary-key
+- cubes.dimensions.time