@useatlas/create 0.0.5 → 0.0.7

package/templates/nextjs-standalone/data/ecommerce-semantic/entities/sellers.yml

@@ -0,0 +1,124 @@
+name: Sellers
+type: dimension_table
+table: sellers
+grain: one row per marketplace seller
+description: |
+  Third-party marketplace sellers on NovaMart. Each seller has a commission rate
+  (NovaMart's take) and a status. Sellers list products and receive payouts after
+  commission. Products link to sellers via products.seller_id.
+
+dimensions:
+  - name: id
+    sql: id
+    type: number
+    description: Primary key — unique seller identifier
+    primary_key: true
+
+  - name: company_name
+    sql: company_name
+    type: string
+    description: Seller's business name
+
+  - name: contact_email
+    sql: contact_email
+    type: string
+    description: Primary contact email for the seller
+
+  - name: commission_rate
+    sql: commission_rate
+    type: number
+    description: |
+      NovaMart's commission as a decimal (e.g. 0.15 = 15%).
+      Seller receives (1 - commission_rate) of each sale.
+
+  - name: status
+    sql: status
+    type: string
+    description: Seller account status
+    sample_values: [active, suspended, pending, inactive]
+
+  - name: joined_at
+    sql: joined_at
+    type: timestamp
+    description: When the seller joined the marketplace
+
+  - name: updated_at
+    sql: updated_at
+    type: timestamp
+    description: Last update to the seller record
+
+  - name: commission_pct
+    sql: ROUND(commission_rate * 100, 1)
+    type: number
+    description: Commission rate as a percentage (e.g. 15.0)
+    virtual: true
+
+  - name: join_year
+    sql: EXTRACT(YEAR FROM joined_at)
+    type: number
+    description: Year the seller joined the marketplace
+    virtual: true
+
+  - name: commission_tier
+    sql: |-
+      CASE
+        WHEN commission_rate < 0.10 THEN 'Low (<10%)'
+        WHEN commission_rate < 0.20 THEN 'Standard (10-20%)'
+        ELSE 'Premium (20%+)'
+      END
+    type: string
+    description: Commission rate tier for segmentation
+    virtual: true
+    sample_values: ["Low (<10%)", "Standard (10-20%)", "Premium (20%+)"]
+
+measures:
+  - name: seller_count
+    sql: id
+    type: count_distinct
+    description: Number of unique sellers
+
+  - name: avg_commission_rate
+    sql: commission_rate
+    type: avg
+    description: Average commission rate across sellers
+
+use_cases:
+  - Marketplace seller health and retention analysis
+  - Commission rate distribution and revenue impact
+  - Seller onboarding trends over time
+  - Join to products for seller catalog size and pricing analysis
+  - Seller status management — active vs suspended vs pending
+
+query_patterns:
+  - name: sellers_by_status
+    description: Seller count by account status
+    sql: |-
+      SELECT status,
+             COUNT(*) AS seller_count,
+             AVG(commission_rate) AS avg_commission
+      FROM sellers
+      GROUP BY status
+      ORDER BY seller_count DESC
+
+  - name: top_sellers_by_product_count
+    description: Sellers with the most active products
+    sql: |-
+      SELECT s.company_name,
+             s.commission_rate,
+             COUNT(p.id) AS product_count,
+             AVG(p.price) AS avg_product_price
+      FROM sellers s
+      JOIN products p ON p.seller_id = s.id AND p.status = 'active'
+      WHERE s.status = 'active'
+      GROUP BY s.company_name, s.commission_rate
+      ORDER BY product_count DESC
+      LIMIT 20
+
+  - name: seller_onboarding_trend
+    description: Monthly new seller signups
+    sql: |-
+      SELECT TO_CHAR(joined_at, 'YYYY-MM') AS month,
+             COUNT(*) AS new_sellers
+      FROM sellers
+      GROUP BY TO_CHAR(joined_at, 'YYYY-MM')
+      ORDER BY month

package/templates/nextjs-standalone/data/ecommerce-semantic/entities/shipments.yml

@@ -0,0 +1,159 @@
+name: Shipments
+type: fact_table
+table: shipments
+grain: one row per shipment
+description: |
+  Shipment tracking for orders. Each shipment originates from a warehouse, is handled
+  by a carrier, and progresses through statuses from label creation to delivery.
+
+  Data quality notes:
+  - carrier is a free-text field (not normalized). carrier_id has no foreign key
+    constraint to shipping_carriers.
+  - shipped_at and delivered_at may be NULL for shipments not yet in transit/delivered.
+  - An order can have multiple shipments (split shipments from different warehouses).
+
+dimensions:
+  - name: id
+    sql: id
+    type: number
+    description: Primary key — unique shipment identifier
+    primary_key: true
+
+  - name: order_id
+    sql: order_id
+    type: number
+    description: Foreign key to orders — which order this shipment fulfills
+
+  - name: warehouse_id
+    sql: warehouse_id
+    type: number
+    description: Foreign key to warehouses — origin fulfillment center
+
+  - name: carrier
+    sql: carrier
+    type: string
+    description: Carrier name (free text — not normalized)
+    sample_values: [UPS, FedEx, USPS, DHL, OnTrac]
+
+  - name: carrier_id
+    sql: carrier_id
+    type: number
+    description: |
+      Carrier identifier. No foreign key constraint to shipping_carriers.
+
+  - name: tracking_number
+    sql: tracking_number
+    type: string
+    description: Carrier tracking number
+
+  - name: status
+    sql: status
+    type: string
+    description: Shipment status
+    sample_values: [label_created, in_transit, out_for_delivery, delivered, exception]
+
+  - name: shipped_at
+    sql: shipped_at
+    type: timestamp
+    description: When the shipment was handed to the carrier (NULL if not yet shipped)
+
+  - name: delivered_at
+    sql: delivered_at
+    type: timestamp
+    description: When the shipment was delivered (NULL if not yet delivered)
+
+  - name: created_at
+    sql: created_at
+    type: timestamp
+    description: When the shipment record was created
+
+  - name: transit_days
+    sql: EXTRACT(DAY FROM (delivered_at - shipped_at))
+    type: number
+    description: Days in transit from ship to delivery (NULL if not delivered)
+    virtual: true
+
+  - name: fulfillment_days
+    sql: EXTRACT(DAY FROM (shipped_at - created_at))
+    type: number
+    description: Days from shipment creation to actual ship (processing time)
+    virtual: true
+
+  - name: is_delivered
+    sql: CASE WHEN status = 'delivered' THEN true ELSE false END
+    type: boolean
+    description: Whether this shipment has been delivered
+    virtual: true
+
+  - name: ship_month
+    sql: TO_CHAR(shipped_at, 'YYYY-MM')
+    type: string
+    description: Year-month the shipment was sent
+    virtual: true
+
+measures:
+  - name: shipment_count
+    sql: id
+    type: count_distinct
+    description: Number of unique shipments
+
+  - name: avg_transit_days
+    sql: EXTRACT(DAY FROM (delivered_at - shipped_at))
+    type: avg
+    description: Average transit time in days (ship to delivery)
+
+  - name: avg_fulfillment_days
+    sql: EXTRACT(DAY FROM (shipped_at - created_at))
+    type: avg
+    description: Average fulfillment processing time in days
+
+joins:
+  - target_entity: Orders
+    relationship: many_to_one
+    join_columns:
+      from: order_id
+      to: id
+    description: Each shipment fulfills part or all of one order
+
+use_cases:
+  - Fulfillment speed analysis — time from order to ship to delivery
+  - Carrier performance comparison — transit time, delivery rate
+  - Warehouse throughput and efficiency
+  - Shipment exception tracking and resolution
+  - Join to orders for end-to-end order fulfillment metrics
+
+query_patterns:
+  - name: carrier_performance
+    description: Average transit time and delivery rate by carrier
+    sql: |-
+      SELECT carrier,
+             COUNT(*) AS shipment_count,
+             AVG(EXTRACT(DAY FROM (delivered_at - shipped_at))) AS avg_transit_days,
+             COUNT(*) FILTER (WHERE status = 'delivered') AS delivered_count,
+             ROUND(100.0 * COUNT(*) FILTER (WHERE status = 'delivered') / COUNT(*), 1) AS delivery_rate
+      FROM shipments
+      WHERE shipped_at IS NOT NULL
+      GROUP BY carrier
+      ORDER BY shipment_count DESC
+
+  - name: fulfillment_time_trend
+    description: Monthly average fulfillment and transit time
+    sql: |-
+      SELECT TO_CHAR(shipped_at, 'YYYY-MM') AS month,
+             COUNT(*) AS shipments,
+             AVG(EXTRACT(DAY FROM (shipped_at - created_at))) AS avg_processing_days,
+             AVG(EXTRACT(DAY FROM (delivered_at - shipped_at))) AS avg_transit_days
+      FROM shipments
+      WHERE shipped_at IS NOT NULL
+      GROUP BY TO_CHAR(shipped_at, 'YYYY-MM')
+      ORDER BY month
+
+  - name: shipments_by_status
+    description: Shipment distribution by current status
+    sql: |-
+      SELECT status,
+             COUNT(*) AS shipment_count,
+             ROUND(100.0 * COUNT(*) / SUM(COUNT(*)) OVER (), 1) AS pct
+      FROM shipments
+      GROUP BY status
+      ORDER BY shipment_count DESC

package/templates/nextjs-standalone/data/ecommerce-semantic/glossary.yml

@@ -0,0 +1,193 @@
+terms:
+  GMV:
+    status: defined
+    definition: >
+      Gross Merchandise Value. Total value of all orders before refunds and returns.
+      Use SUM(orders.total_cents) / 100 for dollar amount. Filter by status != 'cancelled'
+      for net GMV.
+    tables:
+      - orders
+
+  AOV:
+    status: defined
+    definition: >
+      Average Order Value. GMV divided by order count. Use AVG(orders.total_cents) / 100
+      for dollar amount. Typically filtered to completed/non-cancelled orders.
+    tables:
+      - orders
+
+  LTV:
+    status: defined
+    definition: >
+      Customer Lifetime Value. Total revenue generated by a customer across all their
+      orders. Use SUM(orders.total_cents) / 100 grouped by customer_id. Can be found
+      pre-computed in customer_ltv_cache but the orders table is authoritative.
+    tables:
+      - orders
+      - customers
+
+  churn:
+    status: defined
+    definition: >
+      A customer who has not placed an order in 180+ days and was previously active.
+      Not a column — derived by comparing last order date to current date. is_active
+      on customers is a related but separate flag.
+    tables:
+      - customers
+      - orders
+
+  conversion:
+    status: defined
+    definition: >
+      The rate at which site visitors become paying customers. Calculated from
+      cart_events and orders: orders placed / cart sessions started. Not directly
+      in the core entities — requires joining to site analytics tables.
+    tables:
+      - orders
+      - cart_events
+
+  return_rate:
+    status: defined
+    definition: >
+      Percentage of orders that result in a return request. Use COUNT(DISTINCT
+      returns.order_id) / COUNT(DISTINCT orders.id). Note: a single order can
+      have multiple return items but only one return record.
+    tables:
+      - returns
+      - orders
+
+  SKU:
+    status: defined
+    definition: >
+      Stock Keeping Unit. A unique identifier for each product variant. Found in
+      product_variants.sku. Products can have multiple SKUs (size, color variants).
+    tables:
+      - product_variants
+
+  DTC:
+    status: defined
+    definition: >
+      Direct-to-Consumer. NovaMart's own branded products sold directly to customers,
+      as opposed to third-party marketplace sellers. DTC products have seller_id = NULL
+      on the products table.
+    tables:
+      - products
+
+  marketplace:
+    status: defined
+    definition: >
+      Third-party seller products listed on NovaMart's platform. Marketplace products
+      have a non-NULL seller_id on the products table. Sellers earn revenue minus
+      commission_rate.
+    tables:
+      - products
+      - sellers
+
+  revenue:
+    status: ambiguous
+    note: >
+      Could mean GMV (total order value from orders.total_cents), net revenue
+      (GMV minus refunds), or seller revenue (after commission). ASK the user
+      which definition they mean.
+    possible_mappings:
+      - orders.total_cents
+      - payments.amount_cents
+      - refunds (subtracted)
+
+  price:
+    status: ambiguous
+    note: >
+      products.price is in dollars. products.price_cents is in cents but 40% NULL.
+      order_items.unit_price_cents and order_items.total_cents are in cents.
+      Always clarify which price and confirm units.
+    possible_mappings:
+      - products.price
+      - products.price_cents
+      - order_items.unit_price_cents
+
+  status:
+    status: ambiguous
+    note: >
+      "status" appears on many tables with different meanings. ASK which entity:
+      orders (pending/processing/shipped/delivered/cancelled), payments
+      (pending/captured/failed/refunded), products (active/draft/archived),
+      sellers (active/suspended/pending), returns (requested/approved/completed/rejected),
+      shipments (label_created/in_transit/delivered), promotions (via is_active flag).
+    possible_mappings:
+      - orders.status
+      - payments.status
+      - products.status
+      - sellers.status
+      - returns.status
+      - shipments.status
+
+  name:
+    status: ambiguous
+    note: >
+      "name" appears on products, categories, sellers (company_name), promotions,
+      email_campaigns, and warehouses. ASK which entity the user means.
+    possible_mappings:
+      - products.name
+      - categories.name
+      - sellers.company_name
+      - promotions.name
+      - email_campaigns.name
+      - warehouses.name
+
+  shipping_cost:
+    status: defined
+    definition: >
+      WARNING: orders.shipping_cost uses mixed units — some rows are in dollars,
+      others in cents. This is a known data quality issue. Compare against
+      orders.subtotal_cents and orders.tax_cents (which are consistently in cents)
+      to detect anomalies. Values > 100 are likely in cents; values < 50 are likely
+      in dollars.
+    tables:
+      - orders
+
+  acquisition_source:
+    status: defined
+    definition: >
+      How a customer was acquired (organic, paid_search, social, referral, email, etc.).
+      WARNING: values have case inconsistencies (e.g. 'Organic' vs 'organic',
+      'Paid_Search' vs 'paid_search'). Use LOWER() for reliable grouping.
+    tables:
+      - customers
+
+  rating:
+    status: ambiguous
+    note: >
+      product_reviews has both rating (integer 1-5, always populated) and
+      rating_decimal (float, 70% NULL). Use rating for analysis unless the user
+      specifically asks for decimal precision.
+    possible_mappings:
+      - product_reviews.rating
+      - product_reviews.rating_decimal
+
+  return_reason:
+    status: defined
+    definition: >
+      The reason a customer initiated a return. Found in returns.reason.
+      WARNING: values have case inconsistencies (e.g. 'Defective' vs 'defective',
+      'Wrong Item' vs 'wrong item'). Use LOWER() or INITCAP() for reliable grouping.
+    tables:
+      - returns
+
+  commission:
+    status: defined
+    definition: >
+      The percentage NovaMart takes from marketplace seller transactions.
+      Stored as sellers.commission_rate (decimal, e.g. 0.15 = 15%).
+      Seller payout = order amount * (1 - commission_rate).
+    tables:
+      - sellers
+
+  promotion:
+    status: defined
+    definition: >
+      A discount applied to an order. Promotions have a code, type (percentage or
+      fixed_amount), value, minimum order requirement (min_order_cents), and usage
+      limits. orders.promotion_id links to the promotion used.
+    tables:
+      - promotions
+      - orders

package/templates/nextjs-standalone/data/ecommerce-semantic/metrics/customers.yml

@@ -0,0 +1,116 @@
+metrics:
+  - id: total_customers
+    label: Total Customers
+    description: Total number of registered customers.
+    type: atomic
+    sql: |-
+      SELECT COUNT(DISTINCT id) AS total_customers
+      FROM customers
+    aggregation: count_distinct
+
+  - id: active_customers
+    label: Active Customers
+    description: Number of customers with is_active = true.
+    type: atomic
+    sql: |-
+      SELECT COUNT(*) AS active_customers
+      FROM customers
+      WHERE is_active = true
+    aggregation: count
+
+  - id: customer_ltv
+    label: Customer LTV
+    description: >
+      Average customer lifetime value — total revenue per customer across all
+      their orders. Only includes customers with at least one non-cancelled order.
+    type: derived
+    unit: USD
+    sql: |-
+      SELECT AVG(ltv) AS avg_ltv
+      FROM (
+        SELECT customer_id,
+               SUM(total_cents) / 100.0 AS ltv
+        FROM orders
+        WHERE status != 'cancelled'
+        GROUP BY customer_id
+      ) AS customer_ltv
+    aggregation: avg
+    objective: maximize
+
+  - id: repeat_purchase_rate
+    label: Repeat Purchase Rate
+    description: >
+      Percentage of customers who have placed more than one order.
+      Higher repeat rate indicates stronger retention.
+    type: derived
+    unit: percent
+    sql: |-
+      SELECT ROUND(100.0 * COUNT(*) FILTER (WHERE order_count > 1) / NULLIF(COUNT(*), 0), 1) AS repeat_rate
+      FROM (
+        SELECT customer_id, COUNT(*) AS order_count
+        FROM orders
+        WHERE status != 'cancelled'
+        GROUP BY customer_id
+      ) AS customer_orders
+    aggregation: ratio
+    objective: maximize
+
+  - id: customers_by_acquisition_source
+    label: Customers by Acquisition Source
+    description: >
+      Customer count by normalized acquisition channel. Uses LOWER() to handle
+      case inconsistencies in acquisition_source.
+    type: breakdown
+    sql: |-
+      SELECT LOWER(acquisition_source) AS channel,
+             COUNT(*) AS customer_count,
+             COUNT(*) FILTER (WHERE is_active) AS active_count,
+             ROUND(100.0 * COUNT(*) FILTER (WHERE is_active) / COUNT(*), 1) AS active_pct
+      FROM customers
+      GROUP BY LOWER(acquisition_source)
+      ORDER BY customer_count DESC
+
+  - id: cohort_retention
+    label: Monthly Cohort Retention
+    description: >
+      Customer retention by signup cohort. Shows what percentage of customers
+      from each signup month placed an order in subsequent months.
+    type: breakdown
+    sql: |-
+      SELECT TO_CHAR(c.created_at, 'YYYY-MM') AS signup_cohort,
+             COUNT(DISTINCT c.id) AS cohort_size,
+             COUNT(DISTINCT o.customer_id) AS ordered,
+             ROUND(100.0 * COUNT(DISTINCT o.customer_id) / NULLIF(COUNT(DISTINCT c.id), 0), 1) AS conversion_pct
+      FROM customers c
+      LEFT JOIN orders o ON o.customer_id = c.id AND o.status != 'cancelled'
+      GROUP BY TO_CHAR(c.created_at, 'YYYY-MM')
+      ORDER BY signup_cohort
+
+  - id: top_customers_by_spend
+    label: Top Customers by Spend
+    description: Highest-spending customers by total order value.
+    type: breakdown
+    unit: USD
+    sql: |-
+      SELECT c.full_name,
+             c.email,
+             LOWER(c.acquisition_source) AS channel,
+             COUNT(o.id) AS order_count,
+             SUM(o.total_cents) / 100.0 AS total_spend
+      FROM customers c
+      JOIN orders o ON o.customer_id = c.id
+      WHERE o.status != 'cancelled'
+      GROUP BY c.full_name, c.email, LOWER(c.acquisition_source)
+      ORDER BY total_spend DESC
+      LIMIT 20
+
+  - id: new_customers_by_month
+    label: New Customers by Month
+    description: Monthly new customer signups for growth tracking.
+    type: breakdown
+    sql: |-
+      SELECT TO_CHAR(created_at, 'YYYY-MM') AS month,
+             COUNT(*) AS new_customers
+      FROM customers
+      GROUP BY TO_CHAR(created_at, 'YYYY-MM')
+      ORDER BY month