@useatlas/create 0.0.6 → 0.0.7

package/templates/docker/data/ecommerce-semantic/entities/inventory_levels.yml

@@ -0,0 +1,153 @@
+name: Inventory Levels
+type: fact_table
+table: inventory_levels
+grain: one row per variant-warehouse combination
+description: |
+  Current inventory quantities for each product variant at each warehouse. Used for
+  stock monitoring, reorder alerts, and distribution analysis.
+
+  Data quality notes:
+  - variant_id has no foreign key constraint — not all values may match
+    product_variants.id.
+  - This represents a snapshot of current inventory, not historical levels.
+
+dimensions:
+  - name: id
+    sql: id
+    type: number
+    description: Primary key — unique inventory level record
+    primary_key: true
+
+  - name: variant_id
+    sql: variant_id
+    type: number
+    description: |
+      Product variant. No foreign key constraint — join to
+      product_variants with caution.
+
+  - name: warehouse_id
+    sql: warehouse_id
+    type: number
+    description: Foreign key to warehouses — which location holds this stock
+
+  - name: quantity
+    sql: quantity
+    type: number
+    description: Current quantity in stock at this warehouse
+
+  - name: reorder_point
+    sql: reorder_point
+    type: number
+    description: Threshold below which stock should be reordered
+
+  - name: updated_at
+    sql: updated_at
+    type: timestamp
+    description: Last time this inventory level was updated
+
+  - name: is_below_reorder
+    sql: CASE WHEN quantity < reorder_point THEN true ELSE false END
+    type: boolean
+    description: Whether current stock is below the reorder threshold
+    virtual: true
+
+  - name: stock_status
+    sql: |-
+      CASE
+        WHEN quantity = 0 THEN 'Out of Stock'
+        WHEN quantity < reorder_point THEN 'Low Stock'
+        WHEN quantity < reorder_point * 3 THEN 'Adequate'
+        ELSE 'Overstock'
+      END
+    type: string
+    description: Stock level classification
+    virtual: true
+    sample_values: [Out of Stock, Low Stock, Adequate, Overstock]
+
+  - name: reorder_gap
+    sql: reorder_point - quantity
+    type: number
+    description: Units needed to reach reorder point (positive = below threshold)
+    virtual: true
+
+measures:
+  - name: total_quantity
+    sql: quantity
+    type: sum
+    description: Total units in stock across all records
+
+  - name: avg_quantity
+    sql: quantity
+    type: avg
+    description: Average stock level per variant-warehouse
+
+  - name: location_count
+    sql: id
+    type: count_distinct
+    description: Number of unique variant-warehouse inventory records
+
+  - name: low_stock_count
+    sql: CASE WHEN quantity < reorder_point THEN 1 ELSE 0 END
+    type: sum
+    description: Number of variant-warehouse combos below reorder point
+
+joins:
+  - target_entity: Products
+    relationship: many_to_one
+    join_columns:
+      from: variant_id
+      to: id
+    description: |
+      Inventory is per variant, not per product. Join via product_variants
+      to get product-level inventory (variant_id -> product_variants.id ->
+      product_variants.product_id -> products.id).
+
+use_cases:
+  - Stock level monitoring and low-stock alerts
+  - Inventory distribution across warehouses
+  - Out-of-stock and overstock identification
+  - Reorder point analysis and threshold optimization
+  - Warehouse capacity and utilization analysis
+
+query_patterns:
+  - name: low_stock_alerts
+    description: Variant-warehouse combos below reorder point
+    sql: |-
+      SELECT il.variant_id,
+             w.name AS warehouse,
+             il.quantity,
+             il.reorder_point,
+             il.reorder_point - il.quantity AS units_needed
+      FROM inventory_levels il
+      JOIN warehouses w ON il.warehouse_id = w.id
+      WHERE il.quantity < il.reorder_point
+      ORDER BY (il.reorder_point - il.quantity) DESC
+
+  - name: inventory_by_warehouse
+    description: Total stock by warehouse
+    sql: |-
+      SELECT w.name AS warehouse,
+             w.city,
+             w.state,
+             COUNT(il.id) AS sku_count,
+             SUM(il.quantity) AS total_units,
+             SUM(CASE WHEN il.quantity < il.reorder_point THEN 1 ELSE 0 END) AS low_stock_skus
+      FROM inventory_levels il
+      JOIN warehouses w ON il.warehouse_id = w.id
+      GROUP BY w.name, w.city, w.state
+      ORDER BY total_units DESC
+
+  - name: stock_status_summary
+    description: Overall inventory health summary
+    sql: |-
+      SELECT CASE
+               WHEN quantity = 0 THEN 'Out of Stock'
+               WHEN quantity < reorder_point THEN 'Low Stock'
+               WHEN quantity < reorder_point * 3 THEN 'Adequate'
+               ELSE 'Overstock'
+             END AS stock_status,
+             COUNT(*) AS sku_count,
+             SUM(quantity) AS total_units
+      FROM inventory_levels
+      GROUP BY stock_status
+      ORDER BY sku_count DESC

package/templates/docker/data/ecommerce-semantic/entities/order_items.yml

@@ -0,0 +1,159 @@
+name: Order Items
+type: fact_table
+table: order_items
+grain: one row per line item in an order
+description: |
+  Individual line items within orders. Each row represents a specific product purchased
+  at a quantity and price. product_name is denormalized for convenience.
+
+  Data quality notes:
+  - product_variant_id has no foreign key constraint — not all values may match
+    product_variants.id.
+  - All monetary values (unit_price_cents, total_cents) are in cents.
+  - total_cents = unit_price_cents * quantity (but verify — may have rounding).
+
+dimensions:
+  - name: id
+    sql: id
+    type: number
+    description: Primary key — unique line item identifier
+    primary_key: true
+
+  - name: order_id
+    sql: order_id
+    type: number
+    description: Foreign key to orders — which order this item belongs to
+
+  - name: product_variant_id
+    sql: product_variant_id
+    type: number
+    description: |
+      Product variant purchased. No foreign key constraint —
+      join to product_variants with caution.
+
+  - name: product_name
+    sql: product_name
+    type: string
+    description: Denormalized product name (copied at time of purchase)
+
+  - name: quantity
+    sql: quantity
+    type: number
+    description: Number of units purchased for this line item
+
+  - name: unit_price_cents
+    sql: unit_price_cents
+    type: number
+    description: Price per unit in cents at time of purchase
+
+  - name: total_cents
+    sql: total_cents
+    type: number
+    description: Line item total in cents (unit_price_cents * quantity)
+
+  - name: created_at
+    sql: created_at
+    type: timestamp
+    description: When the line item was created (order placement time)
+
+  - name: unit_price_dollars
+    sql: unit_price_cents / 100.0
+    type: number
+    description: Price per unit in dollars
+    virtual: true
+
+  - name: total_dollars
+    sql: total_cents / 100.0
+    type: number
+    description: Line item total in dollars
+    virtual: true
+
+  - name: quantity_bucket
+    sql: |-
+      CASE
+        WHEN quantity = 1 THEN 'Single'
+        WHEN quantity <= 3 THEN 'Small (2-3)'
+        WHEN quantity <= 10 THEN 'Medium (4-10)'
+        ELSE 'Bulk (10+)'
+      END
+    type: string
+    description: Quantity bucket for basket analysis
+    virtual: true
+    sample_values: [Single, "Small (2-3)", "Medium (4-10)", "Bulk (10+)"]
+
+measures:
+  - name: line_item_count
+    sql: id
+    type: count_distinct
+    description: Number of unique line items
+
+  - name: total_units_sold
+    sql: quantity
+    type: sum
+    description: Total units sold across all line items
+
+  - name: total_revenue_cents
+    sql: total_cents
+    type: sum
+    description: Total line item revenue in cents
+
+  - name: avg_unit_price_cents
+    sql: unit_price_cents
+    type: avg
+    description: Average unit price in cents
+
+  - name: avg_quantity
+    sql: quantity
+    type: avg
+    description: Average quantity per line item
+
+joins:
+  - target_entity: Orders
+    relationship: many_to_one
+    join_columns:
+      from: order_id
+      to: id
+    description: Each line item belongs to one order
+
+use_cases:
+  - Product-level revenue attribution — which products drive the most revenue
+  - Basket analysis — average items per order, common combinations
+  - Pricing analysis — unit prices across products and time periods
+  - Quantity patterns — single-item vs bulk purchases
+  - Join to orders for customer and time dimensions on product metrics
+
+query_patterns:
+  - name: top_products_by_revenue
+    description: Highest-revenue products
+    sql: |-
+      SELECT product_name,
+             SUM(total_cents) / 100.0 AS total_revenue,
+             SUM(quantity) AS total_units,
+             COUNT(DISTINCT order_id) AS order_count
+      FROM order_items
+      GROUP BY product_name
+      ORDER BY total_revenue DESC
+      LIMIT 20
+
+  - name: avg_items_per_order
+    description: Average line items and units per order
+    sql: |-
+      SELECT AVG(item_count) AS avg_line_items,
+             AVG(total_units) AS avg_units
+      FROM (
+        SELECT order_id,
+               COUNT(*) AS item_count,
+               SUM(quantity) AS total_units
+        FROM order_items
+        GROUP BY order_id
+      ) AS per_order
+
+  - name: revenue_by_product_and_month
+    description: Monthly revenue trend by top products
+    sql: |-
+      SELECT product_name,
+             TO_CHAR(oi.created_at, 'YYYY-MM') AS month,
+             SUM(oi.total_cents) / 100.0 AS revenue
+      FROM order_items oi
+      GROUP BY product_name, TO_CHAR(oi.created_at, 'YYYY-MM')
+      ORDER BY month, revenue DESC

package/templates/docker/data/ecommerce-semantic/entities/orders.yml

@@ -0,0 +1,199 @@
+name: Orders
+type: fact_table
+table: orders
+grain: one row per order
+description: |
+  Customer orders — the primary fact table for revenue analysis. Each order has
+  monetary totals in cents (subtotal_cents, tax_cents, total_cents) and a status
+  tracking the fulfillment lifecycle.
+
+  Data quality notes:
+  - shipping_cost uses MIXED UNITS — some values are in dollars, others in cents.
+    Values > 100 are likely cents; values < 50 are likely dollars. Do not sum directly.
+  - customer_email is denormalized from customers for convenience.
+  - promotion_id links to the promotion used (NULL if none).
+
+dimensions:
+  - name: id
+    sql: id
+    type: number
+    description: Primary key — unique order identifier
+    primary_key: true
+
+  - name: customer_id
+    sql: customer_id
+    type: number
+    description: Foreign key to customers — who placed this order
+
+  - name: customer_email
+    sql: customer_email
+    type: string
+    description: Denormalized customer email (convenience field from customers table)
+
+  - name: status
+    sql: status
+    type: string
+    description: Order fulfillment status
+    sample_values: [pending, processing, shipped, delivered, cancelled]
+
+  - name: subtotal_cents
+    sql: subtotal_cents
+    type: number
+    description: Order subtotal in cents (before shipping and tax)
+
+  - name: shipping_cost
+    sql: shipping_cost
+    type: number
+    description: |
+      WARNING: Mixed units — some rows in dollars, some in cents.
+      Do not aggregate directly. See glossary for handling guidance.
+
+  - name: tax_cents
+    sql: tax_cents
+    type: number
+    description: Tax amount in cents
+
+  - name: total_cents
+    sql: total_cents
+    type: number
+    description: Order total in cents (subtotal + shipping + tax). Primary revenue field.
+
+  - name: shipping_address_id
+    sql: shipping_address_id
+    type: number
+    description: Foreign key to customer_addresses — delivery destination
+
+  - name: promotion_id
+    sql: promotion_id
+    type: number
+    description: Foreign key to promotions — discount applied (NULL if none)
+
+  - name: created_at
+    sql: created_at
+    type: timestamp
+    description: When the order was placed
+
+  - name: updated_at
+    sql: updated_at
+    type: timestamp
+    description: Last update to the order record
+
+  - name: order_month
+    sql: TO_CHAR(created_at, 'YYYY-MM')
+    type: string
+    description: Year-month the order was placed — useful for trend analysis
+    virtual: true
+
+  - name: order_year
+    sql: EXTRACT(YEAR FROM created_at)
+    type: number
+    description: Year the order was placed
+    virtual: true
+
+  - name: order_day_of_week
+    sql: TO_CHAR(created_at, 'Day')
+    type: string
+    description: Day of week the order was placed
+    virtual: true
+
+  - name: total_dollars
+    sql: total_cents / 100.0
+    type: number
+    description: Order total in dollars (derived from total_cents)
+    virtual: true
+
+  - name: order_size_bucket
+    sql: |-
+      CASE
+        WHEN total_cents < 2500 THEN 'Small (<$25)'
+        WHEN total_cents < 7500 THEN 'Medium ($25-$75)'
+        WHEN total_cents < 15000 THEN 'Large ($75-$150)'
+        ELSE 'XL ($150+)'
+      END
+    type: string
+    description: Order size bucket based on total value
+    virtual: true
+    sample_values: ["Small (<$25)", "Medium ($25-$75)", "Large ($75-$150)", "XL ($150+)"]
+
+  - name: has_promotion
+    sql: CASE WHEN promotion_id IS NOT NULL THEN true ELSE false END
+    type: boolean
+    description: Whether a promotion/discount was applied to this order
+    virtual: true
+
+measures:
+  - name: order_count
+    sql: id
+    type: count_distinct
+    description: Number of unique orders
+
+  - name: total_gmv_cents
+    sql: total_cents
+    type: sum
+    description: Total GMV in cents (sum of all order totals)
+
+  - name: avg_order_value_cents
+    sql: total_cents
+    type: avg
+    description: Average order value in cents
+
+  - name: total_tax_cents
+    sql: tax_cents
+    type: sum
+    description: Total tax collected in cents
+
+joins:
+  - target_entity: Customers
+    relationship: many_to_one
+    join_columns:
+      from: customer_id
+      to: id
+    description: Each order belongs to one customer
+
+  - target_entity: Promotions
+    relationship: many_to_one
+    join_columns:
+      from: promotion_id
+      to: id
+    description: Optional promotion applied to the order
+
+use_cases:
+  - GMV and revenue analysis — total, by month, by customer segment
+  - AOV tracking and order size distribution
+  - Order status funnel analysis (pending → delivered vs cancelled)
+  - Promotion impact — orders with vs without discounts
+  - Join to order_items for product-level revenue, to payments for payment analysis
+
+query_patterns:
+  - name: monthly_gmv
+    description: Monthly GMV trend
+    sql: |-
+      SELECT TO_CHAR(created_at, 'YYYY-MM') AS order_month,
+             COUNT(*) AS order_count,
+             SUM(total_cents) / 100.0 AS gmv_dollars,
+             AVG(total_cents) / 100.0 AS aov_dollars
+      FROM orders
+      WHERE status != 'cancelled'
+      GROUP BY TO_CHAR(created_at, 'YYYY-MM')
+      ORDER BY order_month
+
+  - name: orders_by_status
+    description: Order distribution by fulfillment status
+    sql: |-
+      SELECT status,
+             COUNT(*) AS order_count,
+             SUM(total_cents) / 100.0 AS total_dollars
+      FROM orders
+      GROUP BY status
+      ORDER BY order_count DESC
+
+  - name: orders_with_promotions
+    description: Promotion usage rate and impact on order value
+    sql: |-
+      SELECT CASE WHEN promotion_id IS NOT NULL THEN 'With Promo' ELSE 'No Promo' END AS promo_status,
+             COUNT(*) AS order_count,
+             AVG(total_cents) / 100.0 AS avg_order_value,
+             SUM(total_cents) / 100.0 AS total_revenue
+      FROM orders
+      WHERE status != 'cancelled'
+      GROUP BY CASE WHEN promotion_id IS NOT NULL THEN 'With Promo' ELSE 'No Promo' END

package/templates/docker/data/ecommerce-semantic/entities/payments.yml

@@ -0,0 +1,140 @@
+name: Payments
+type: fact_table
+table: payments
+grain: one row per payment transaction
+description: |
+  Payment transactions associated with orders. An order can have multiple payment
+  records (split payments, retries after failure, partial refunds).
+
+  Data quality notes:
+  - order_id has no foreign key constraint — not all values may match orders.id.
+  - amount_cents is in cents. Divide by 100 for dollar amounts.
+  - provider_ref is the external payment processor reference (Stripe, PayPal, etc.).
+
+dimensions:
+  - name: id
+    sql: id
+    type: number
+    description: Primary key — unique payment transaction identifier
+    primary_key: true
+
+  - name: order_id
+    sql: order_id
+    type: number
+    description: |
+      Associated order. No foreign key constraint — join to orders with caution.
+
+  - name: method
+    sql: method
+    type: string
+    description: Payment method used
+    sample_values: [credit_card, debit_card, paypal, apple_pay, gift_card]
+
+  - name: status
+    sql: status
+    type: string
+    description: Payment transaction status
+    sample_values: [pending, captured, failed, refunded]
+
+  - name: amount_cents
+    sql: amount_cents
+    type: number
+    description: Payment amount in cents
+
+  - name: provider_ref
+    sql: provider_ref
+    type: string
+    description: External payment provider reference ID (e.g. Stripe charge ID)
+
+  - name: created_at
+    sql: created_at
+    type: timestamp
+    description: When the payment was initiated
+
+  - name: updated_at
+    sql: updated_at
+    type: timestamp
+    description: Last update to the payment record
+
+  - name: amount_dollars
+    sql: amount_cents / 100.0
+    type: number
+    description: Payment amount in dollars
+    virtual: true
+
+  - name: payment_month
+    sql: TO_CHAR(created_at, 'YYYY-MM')
+    type: string
+    description: Year-month of the payment
+    virtual: true
+
+  - name: is_successful
+    sql: CASE WHEN status = 'captured' THEN true ELSE false END
+    type: boolean
+    description: Whether the payment was successfully captured
+    virtual: true
+
+measures:
+  - name: payment_count
+    sql: id
+    type: count_distinct
+    description: Number of unique payment transactions
+
+  - name: total_captured_cents
+    sql: CASE WHEN status = 'captured' THEN amount_cents ELSE 0 END
+    type: sum
+    description: Total successfully captured payment amount in cents
+
+  - name: avg_payment_cents
+    sql: amount_cents
+    type: avg
+    description: Average payment amount in cents
+
+joins:
+  - target_entity: Orders
+    relationship: many_to_one
+    join_columns:
+      from: order_id
+      to: id
+    description: Each payment is associated with one order (no FK constraint)
+
+use_cases:
+  - Payment success/failure rate analysis
+  - Payment method popularity and trends
+  - Revenue reconciliation — compare payment totals to order totals
+  - Failed payment analysis for recovery opportunities
+  - Monthly collected revenue tracking
+
+query_patterns:
+  - name: payment_success_rate
+    description: Payment success rate by method
+    sql: |-
+      SELECT method,
+             COUNT(*) AS total_payments,
+             COUNT(*) FILTER (WHERE status = 'captured') AS captured,
+             COUNT(*) FILTER (WHERE status = 'failed') AS failed,
+             ROUND(100.0 * COUNT(*) FILTER (WHERE status = 'captured') / COUNT(*), 1) AS success_rate
+      FROM payments
+      GROUP BY method
+      ORDER BY total_payments DESC
+
+  - name: monthly_captured_revenue
+    description: Monthly captured payment revenue
+    sql: |-
+      SELECT TO_CHAR(created_at, 'YYYY-MM') AS month,
+             SUM(amount_cents) / 100.0 AS captured_dollars,
+             COUNT(*) AS payment_count
+      FROM payments
+      WHERE status = 'captured'
+      GROUP BY TO_CHAR(created_at, 'YYYY-MM')
+      ORDER BY month
+
+  - name: payments_by_status
+    description: Payment distribution by status
+    sql: |-
+      SELECT status,
+             COUNT(*) AS payment_count,
+             SUM(amount_cents) / 100.0 AS total_dollars
+      FROM payments
+      GROUP BY status
+      ORDER BY payment_count DESC