@useatlas/create 0.0.5 → 0.0.7

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

@@ -0,0 +1,155 @@
+name: Product Reviews
+type: fact_table
+table: product_reviews
+grain: one row per review
+description: |
+  Customer reviews of products. Each review has a 1-5 integer rating, optional
+  decimal rating, title, body text, and verification status.
+
+  Data quality notes:
+  - rating is an integer 1-5 (always populated). Use this for analysis.
+  - rating_decimal is a float with more precision but 70% NULL. Only use when
+    the user specifically requests decimal precision.
+  - is_verified indicates the reviewer actually purchased the product.
+
+dimensions:
+  - name: id
+    sql: id
+    type: number
+    description: Primary key — unique review identifier
+    primary_key: true
+
+  - name: product_id
+    sql: product_id
+    type: number
+    description: Foreign key to products — which product was reviewed
+
+  - name: customer_id
+    sql: customer_id
+    type: number
+    description: Foreign key to customers — who wrote the review
+
+  - name: rating
+    sql: rating
+    type: number
+    description: Integer rating from 1 (worst) to 5 (best). Always populated.
+
+  - name: rating_decimal
+    sql: rating_decimal
+    type: number
+    description: |
+      Decimal rating with more precision. WARNING: 70% NULL.
+      Use integer rating unless decimal precision is specifically needed.
+
+  - name: title
+    sql: title
+    type: string
+    description: Review title/headline
+
+  - name: body
+    sql: body
+    type: string
+    description: Full review text
+
+  - name: is_verified
+    sql: is_verified
+    type: boolean
+    description: Whether the reviewer is a verified purchaser of the product
+
+  - name: created_at
+    sql: created_at
+    type: timestamp
+    description: When the review was submitted
+
+  - name: review_month
+    sql: TO_CHAR(created_at, 'YYYY-MM')
+    type: string
+    description: Year-month the review was submitted
+    virtual: true
+
+  - name: rating_label
+    sql: |-
+      CASE
+        WHEN rating >= 4 THEN 'Positive'
+        WHEN rating = 3 THEN 'Neutral'
+        ELSE 'Negative'
+      END
+    type: string
+    description: Sentiment bucket based on rating
+    virtual: true
+    sample_values: [Positive, Neutral, Negative]
+
+measures:
+  - name: review_count
+    sql: id
+    type: count_distinct
+    description: Number of unique reviews
+
+  - name: avg_rating
+    sql: rating
+    type: avg
+    description: Average product rating (1-5 scale)
+
+  - name: verified_review_count
+    sql: CASE WHEN is_verified THEN id END
+    type: count_distinct
+    description: Number of verified purchase reviews
+
+joins:
+  - target_entity: Products
+    relationship: many_to_one
+    join_columns:
+      from: product_id
+      to: id
+    description: Each review is for one product
+
+  - target_entity: Customers
+    relationship: many_to_one
+    join_columns:
+      from: customer_id
+      to: id
+    description: Each review was written by one customer
+
+use_cases:
+  - Product quality analysis — average rating, rating distribution
+  - Review volume trends over time
+  - Verified vs unverified review comparison
+  - Low-rated product identification for quality improvement
+  - Join to products for category-level satisfaction analysis
+
+query_patterns:
+  - name: product_ratings
+    description: Average rating and review count per product
+    sql: |-
+      SELECT p.name AS product,
+             COUNT(r.id) AS review_count,
+             AVG(r.rating) AS avg_rating,
+             COUNT(r.id) FILTER (WHERE r.is_verified) AS verified_reviews
+      FROM product_reviews r
+      JOIN products p ON r.product_id = p.id
+      GROUP BY p.name
+      ORDER BY review_count DESC
+      LIMIT 20
+
+  - name: rating_distribution
+    description: Overall distribution of ratings
+    sql: |-
+      SELECT rating,
+             COUNT(*) AS review_count,
+             ROUND(100.0 * COUNT(*) / SUM(COUNT(*)) OVER (), 1) AS pct
+      FROM product_reviews
+      GROUP BY rating
+      ORDER BY rating DESC
+
+  - name: lowest_rated_products
+    description: Products with lowest average ratings (min 5 reviews)
+    sql: |-
+      SELECT p.name AS product,
+             AVG(r.rating) AS avg_rating,
+             COUNT(r.id) AS review_count
+      FROM product_reviews r
+      JOIN products p ON r.product_id = p.id
+      GROUP BY p.name
+      HAVING COUNT(r.id) >= 5
+      ORDER BY avg_rating ASC
+      LIMIT 10

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

@@ -0,0 +1,178 @@
+name: Products
+type: dimension_table
+table: products
+grain: one row per product
+description: |
+  NovaMart product catalog. Each product belongs to a category and optionally to a
+  marketplace seller (seller_id). Products with seller_id = NULL are NovaMart's own
+  DTC (direct-to-consumer) products.
+
+  Data quality notes:
+  - price is in dollars. price_cents is in cents but 40% NULL — prefer price for analysis.
+  - seller_id has no foreign key constraint; join carefully.
+  - status controls visibility: active, draft, archived.
+
+dimensions:
+  - name: id
+    sql: id
+    type: number
+    description: Primary key — unique product identifier
+    primary_key: true
+
+  - name: name
+    sql: name
+    type: string
+    description: Product display name
+
+  - name: slug
+    sql: slug
+    type: string
+    description: URL-safe product identifier
+
+  - name: category_id
+    sql: category_id
+    type: number
+    description: Foreign key to categories — product classification
+
+  - name: seller_id
+    sql: seller_id
+    type: number
+    description: |
+      Marketplace seller ID. NULL = NovaMart DTC product.
+      No foreign key constraint — join to sellers with caution.
+
+  - name: price
+    sql: price
+    type: number
+    description: Product price in dollars (always populated)
+
+  - name: price_cents
+    sql: price_cents
+    type: number
+    description: |
+      Product price in cents. WARNING: 40% NULL. Use price (dollars) for
+      reliable analysis. When present, should equal price * 100.
+
+  - name: description
+    sql: description
+    type: string
+    description: Product description text
+
+  - name: status
+    sql: status
+    type: string
+    description: Product lifecycle status
+    sample_values: [active, draft, archived]
+
+  - name: created_at
+    sql: created_at
+    type: timestamp
+    description: When the product was first created
+
+  - name: updated_at
+    sql: updated_at
+    type: timestamp
+    description: Last update to the product record
+
+  - name: is_marketplace
+    sql: CASE WHEN seller_id IS NOT NULL THEN true ELSE false END
+    type: boolean
+    description: Whether this is a marketplace product (has a seller) vs DTC
+    virtual: true
+
+  - name: price_tier
+    sql: |-
+      CASE
+        WHEN price < 25 THEN 'Budget'
+        WHEN price < 75 THEN 'Mid-Range'
+        WHEN price < 200 THEN 'Premium'
+        ELSE 'Luxury'
+      END
+    type: string
+    description: Price tier bucket for segmentation
+    virtual: true
+    sample_values: [Budget, Mid-Range, Premium, Luxury]
+
+measures:
+  - name: product_count
+    sql: id
+    type: count_distinct
+    description: Number of unique products
+
+  - name: avg_price
+    sql: price
+    type: avg
+    description: Average product price in dollars
+
+  - name: min_price
+    sql: price
+    type: min
+    description: Lowest product price in dollars
+
+  - name: max_price
+    sql: price
+    type: max
+    description: Highest product price in dollars
+
+joins:
+  - target_entity: Categories
+    relationship: many_to_one
+    join_columns:
+      from: category_id
+      to: id
+    description: Each product belongs to one category
+
+  - target_entity: Sellers
+    relationship: many_to_one
+    join_columns:
+      from: seller_id
+      to: id
+    description: Marketplace products belong to a seller (NULL for DTC)
+
+use_cases:
+  - Product catalog analysis by category, price tier, and status
+  - DTC vs marketplace product mix and pricing comparison
+  - Product lifecycle tracking — draft to active to archived
+  - Join to order_items for revenue attribution by product
+  - Join to product_reviews for quality/sentiment by product
+
+query_patterns:
+  - name: products_by_category
+    description: Product count and average price by category
+    sql: |-
+      SELECT c.name AS category,
+             COUNT(p.id) AS product_count,
+             AVG(p.price) AS avg_price
+      FROM products p
+      JOIN categories c ON p.category_id = c.id
+      WHERE p.status = 'active'
+      GROUP BY c.name
+      ORDER BY product_count DESC
+
+  - name: dtc_vs_marketplace
+    description: Compare DTC and marketplace product counts and pricing
+    sql: |-
+      SELECT CASE WHEN seller_id IS NULL THEN 'DTC' ELSE 'Marketplace' END AS channel,
+             COUNT(*) AS product_count,
+             AVG(price) AS avg_price,
+             MIN(price) AS min_price,
+             MAX(price) AS max_price
+      FROM products
+      WHERE status = 'active'
+      GROUP BY CASE WHEN seller_id IS NULL THEN 'DTC' ELSE 'Marketplace' END
+
+  - name: products_by_price_tier
+    description: Product distribution across price tiers
+    sql: |-
+      SELECT CASE
+               WHEN price < 25 THEN 'Budget'
+               WHEN price < 75 THEN 'Mid-Range'
+               WHEN price < 200 THEN 'Premium'
+               ELSE 'Luxury'
+             END AS price_tier,
+             COUNT(*) AS product_count,
+             AVG(price) AS avg_price
+      FROM products
+      WHERE status = 'active'
+      GROUP BY price_tier
+      ORDER BY avg_price

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

@@ -0,0 +1,171 @@
+name: Promotions
+type: dimension_table
+table: promotions
+grain: one row per promotion
+description: |
+  Discount codes and promotional offers. Each promotion has a type (percentage or
+  fixed_amount), a value, optional minimum order requirement, and usage tracking.
+  Orders reference promotions via orders.promotion_id.
+
+dimensions:
+  - name: id
+    sql: id
+    type: number
+    description: Primary key — unique promotion identifier
+    primary_key: true
+
+  - name: code
+    sql: code
+    type: string
+    description: Promotion code (entered by customer at checkout)
+    sample_values: [SUMMER20, WELCOME10, FLASH50, FREESHIP]
+
+  - name: name
+    sql: name
+    type: string
+    description: Internal promotion name/label
+
+  - name: type
+    sql: type
+    type: string
+    description: Discount type
+    sample_values: [percentage, fixed_amount]
+
+  - name: value
+    sql: value
+    type: number
+    description: |
+      Discount value. For percentage type: 20 = 20% off.
+      For fixed_amount type: value in dollars off.
+
+  - name: min_order_cents
+    sql: min_order_cents
+    type: number
+    description: Minimum order total in cents to qualify for this promotion (NULL = no minimum)
+
+  - name: max_uses
+    sql: max_uses
+    type: number
+    description: Maximum number of times this promotion can be used (NULL = unlimited)
+
+  - name: times_used
+    sql: times_used
+    type: number
+    description: How many times this promotion has been redeemed
+
+  - name: starts_at
+    sql: starts_at
+    type: timestamp
+    description: When the promotion becomes valid
+
+  - name: ends_at
+    sql: ends_at
+    type: timestamp
+    description: When the promotion expires
+
+  - name: is_active
+    sql: is_active
+    type: boolean
+    description: Whether the promotion is currently enabled
+
+  - name: created_at
+    sql: created_at
+    type: timestamp
+    description: When the promotion was created
+
+  - name: usage_rate
+    sql: |-
+      CASE
+        WHEN max_uses IS NOT NULL AND max_uses > 0
+        THEN ROUND(100.0 * times_used / max_uses, 1)
+        ELSE NULL
+      END
+    type: number
+    description: Percentage of max_uses consumed (NULL if unlimited)
+    virtual: true
+
+  - name: min_order_dollars
+    sql: min_order_cents / 100.0
+    type: number
+    description: Minimum order total in dollars
+    virtual: true
+
+  - name: is_expired
+    sql: CASE WHEN ends_at < CURRENT_TIMESTAMP THEN true ELSE false END
+    type: boolean
+    description: Whether the promotion has passed its end date
+    virtual: true
+
+measures:
+  - name: promotion_count
+    sql: id
+    type: count_distinct
+    description: Number of unique promotions
+
+  - name: total_redemptions
+    sql: times_used
+    type: sum
+    description: Total times all promotions have been redeemed
+
+  - name: avg_discount_value
+    sql: value
+    type: avg
+    description: Average discount value across promotions
+
+joins:
+  - target_entity: Orders
+    relationship: one_to_many
+    join_columns:
+      from: id
+      to: promotion_id
+    description: A promotion can be used on many orders
+
+use_cases:
+  - Promotion effectiveness — which codes drive the most orders
+  - Usage capacity tracking — how close to max_uses
+  - Discount type comparison — percentage vs fixed amount impact on AOV
+  - Active promotion inventory management
+  - Join to orders for revenue impact of promotions
+
+query_patterns:
+  - name: most_used_promotions
+    description: Promotions ranked by usage
+    sql: |-
+      SELECT code,
+             name,
+             type,
+             value,
+             times_used,
+             max_uses,
+             CASE
+               WHEN max_uses IS NOT NULL AND max_uses > 0
+               THEN ROUND(100.0 * times_used / max_uses, 1)
+               ELSE NULL
+             END AS usage_pct
+      FROM promotions
+      ORDER BY times_used DESC
+      LIMIT 20
+
+  - name: promotion_impact_on_aov
+    description: Compare AOV for orders with vs without promotions
+    sql: |-
+      SELECT p.code,
+             p.type,
+             p.value,
+             COUNT(o.id) AS order_count,
+             AVG(o.total_cents) / 100.0 AS avg_order_value
+      FROM promotions p
+      JOIN orders o ON o.promotion_id = p.id
+      WHERE o.status != 'cancelled'
+      GROUP BY p.code, p.type, p.value
+      ORDER BY order_count DESC
+
+  - name: active_promotions
+    description: Currently active and valid promotions
+    sql: |-
+      SELECT code, name, type, value, times_used, max_uses,
+             starts_at, ends_at
+      FROM promotions
+      WHERE is_active = true
+        AND (ends_at IS NULL OR ends_at > CURRENT_TIMESTAMP)
+      ORDER BY times_used DESC

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

@@ -0,0 +1,144 @@
+name: Returns
+type: fact_table
+table: returns
+grain: one row per return request
+description: |
+  Return requests initiated by customers. Each return is linked to an order and
+  a customer, with a reason and status tracking the resolution lifecycle.
+
+  Data quality notes:
+  - reason has case inconsistencies (e.g. 'Defective' vs 'defective', 'Wrong Item'
+    vs 'wrong item'). Use LOWER(reason) or INITCAP(reason) for reliable grouping.
+  - resolved_at is NULL for unresolved returns.
+  - A single order can have one return record; use return_items for item-level detail.
+
+dimensions:
+  - name: id
+    sql: id
+    type: number
+    description: Primary key — unique return request identifier
+    primary_key: true
+
+  - name: order_id
+    sql: order_id
+    type: number
+    description: Foreign key to orders — which order is being returned
+
+  - name: customer_id
+    sql: customer_id
+    type: number
+    description: Foreign key to customers — who initiated the return
+
+  - name: reason
+    sql: reason
+    type: string
+    description: |
+      Return reason. WARNING: case-inconsistent values.
+      Use LOWER(reason) for reliable grouping.
+    sample_values: [defective, wrong item, not as described, changed mind, too late]
+
+  - name: status
+    sql: status
+    type: string
+    description: Return request status
+    sample_values: [requested, approved, completed, rejected]
+
+  - name: created_at
+    sql: created_at
+    type: timestamp
+    description: When the return was requested
+
+  - name: resolved_at
+    sql: resolved_at
+    type: timestamp
+    description: When the return was resolved (NULL if still pending)
+
+  - name: reason_normalized
+    sql: LOWER(reason)
+    type: string
+    description: Return reason normalized to lowercase for consistent grouping
+    virtual: true
+
+  - name: return_month
+    sql: TO_CHAR(created_at, 'YYYY-MM')
+    type: string
+    description: Year-month the return was initiated
+    virtual: true
+
+  - name: resolution_days
+    sql: EXTRACT(DAY FROM (resolved_at - created_at))
+    type: number
+    description: Days from return request to resolution (NULL if unresolved)
+    virtual: true
+
+  - name: is_resolved
+    sql: CASE WHEN resolved_at IS NOT NULL THEN true ELSE false END
+    type: boolean
+    description: Whether the return has been resolved
+    virtual: true
+
+measures:
+  - name: return_count
+    sql: id
+    type: count_distinct
+    description: Number of unique return requests
+
+  - name: avg_resolution_days
+    sql: EXTRACT(DAY FROM (resolved_at - created_at))
+    type: avg
+    description: Average days to resolve a return
+
+joins:
+  - target_entity: Orders
+    relationship: many_to_one
+    join_columns:
+      from: order_id
+      to: id
+    description: Each return is for one order
+
+  - target_entity: Customers
+    relationship: many_to_one
+    join_columns:
+      from: customer_id
+      to: id
+    description: Each return was initiated by one customer
+
+use_cases:
+  - Return rate analysis — overall and by product/category
+  - Return reason categorization and trending
+  - Resolution time tracking and SLA compliance
+  - Customer-level return frequency (serial returners)
+  - Join to orders for return rate by order value or promotion usage
+
+query_patterns:
+  - name: returns_by_reason
+    description: Return count by normalized reason
+    sql: |-
+      SELECT LOWER(reason) AS return_reason,
+             COUNT(*) AS return_count,
+             ROUND(100.0 * COUNT(*) / SUM(COUNT(*)) OVER (), 1) AS pct
+      FROM returns
+      GROUP BY LOWER(reason)
+      ORDER BY return_count DESC
+
+  - name: monthly_return_rate
+    description: Monthly return rate as percentage of orders
+    sql: |-
+      SELECT TO_CHAR(o.created_at, 'YYYY-MM') AS month,
+             COUNT(DISTINCT o.id) AS total_orders,
+             COUNT(DISTINCT r.order_id) AS returned_orders,
+             ROUND(100.0 * COUNT(DISTINCT r.order_id) / COUNT(DISTINCT o.id), 1) AS return_rate
+      FROM orders o
+      LEFT JOIN returns r ON r.order_id = o.id
+      GROUP BY TO_CHAR(o.created_at, 'YYYY-MM')
+      ORDER BY month
+
+  - name: avg_resolution_time
+    description: Average resolution time by return status
+    sql: |-
+      SELECT status,
+             COUNT(*) AS return_count,
+             AVG(EXTRACT(DAY FROM (resolved_at - created_at))) AS avg_days_to_resolve
+      FROM returns
+      WHERE resolved_at IS NOT NULL
+      GROUP BY status