@luquimbo/bi-superpowers 1.0.0

package/library/examples/retail-analytics/data-model.md

@@ -0,0 +1,288 @@
+# Retail Analytics - Data Model
+
+Complete table definitions for the retail analytics star schema.
+
+---
+
+## Fact Table
+
+### FactSales
+
+| Column | Data Type | Description |
+|--------|-----------|-------------|
+| SalesKey | Text | Surrogate primary key |
+| DateKey | Text | FK to DimDate (YYYYMMDD format) |
+| ProductKey | Integer | FK to DimProduct |
+| CustomerKey | Integer | FK to DimCustomer |
+| StoreKey | Integer | FK to DimStore |
+| Quantity | Integer | Units sold |
+| UnitPrice | Currency | Sale price per unit |
+| Discount | Currency | Discount amount applied |
+| Amount | Currency | Net sale amount (Qty × Price - Discount) |
+| Cost | Currency | Total cost (Qty × UnitCost) |
+
+**Relationships:**
+- FactSales[DateKey] → DimDate[DateKey] (Many:1)
+- FactSales[ProductKey] → DimProduct[ProductKey] (Many:1)
+- FactSales[CustomerKey] → DimCustomer[CustomerKey] (Many:1)
+- FactSales[StoreKey] → DimStore[StoreKey] (Many:1)
+
+---
+
+## Dimension Tables
+
+### DimDate
+
+| Column | Data Type | Description | Example |
+|--------|-----------|-------------|---------|
+| DateKey | Text | Primary key (YYYYMMDD) | "20240115" |
+| Date | Date | Full date | 2024-01-15 |
+| Year | Integer | Calendar year | 2024 |
+| Quarter | Text | Quarter label | "Q1" |
+| QuarterNumber | Integer | Quarter number | 1 |
+| Month | Integer | Month number | 1 |
+| MonthName | Text | Full month name | "January" |
+| MonthShort | Text | 3-letter month | "Jan" |
+| YearMonth | Text | Year-Month label | "2024-01" |
+| Week | Integer | Week of year | 3 |
+| WeekOfMonth | Integer | Week of month | 3 |
+| Day | Integer | Day of month | 15 |
+| DayOfWeek | Integer | Day of week (1=Mon) | 1 |
+| DayOfWeekName | Text | Day name | "Monday" |
+| IsWeekend | Boolean | Weekend flag | FALSE |
+| IsHoliday | Boolean | Holiday flag | FALSE |
+| FiscalYear | Integer | Fiscal year | 2024 |
+| FiscalQuarter | Text | Fiscal quarter | "FQ1" |
+| FiscalMonth | Integer | Fiscal month | 7 |
+
+**Settings:**
+- Mark as Date Table using Date column
+- Sort MonthName by Month
+- Sort DayOfWeekName by DayOfWeek
+
+---
+
+### DimProduct
+
+| Column | Data Type | Description | Example |
+|--------|-----------|-------------|---------|
+| ProductKey | Integer | Surrogate PK | 1001 |
+| ProductID | Text | Business key | "SKU-12345" |
+| ProductName | Text | Product name | "Wireless Mouse" |
+| Category | Text | Top-level category | "Electronics" |
+| SubCategory | Text | Sub-category | "Accessories" |
+| Brand | Text | Brand name | "TechBrand" |
+| UnitCost | Currency | Cost to company | 12.50 |
+| UnitPrice | Currency | List price | 24.99 |
+| Margin | Decimal | Calculated margin | 0.50 |
+| IsActive | Boolean | Currently sold | TRUE |
+| LaunchDate | Date | Product launch | 2023-06-01 |
+
+**Hierarchies:**
+- Category > SubCategory > ProductName
+- Brand > ProductName
+
+---
+
+### DimCustomer
+
+| Column | Data Type | Description | Example |
+|--------|-----------|-------------|---------|
+| CustomerKey | Integer | Surrogate PK | 5001 |
+| CustomerID | Text | Business key | "CUST-12345" |
+| CustomerName | Text | Full name | "John Smith" |
+| Email | Text | Email address | "john@example.com" |
+| Phone | Text | Phone number | "555-0100" |
+| Address | Text | Street address | "123 Main St" |
+| City | Text | City | "Seattle" |
+| State | Text | State code | "WA" |
+| PostalCode | Text | ZIP code | "98101" |
+| Region | Text | Sales region | "West" |
+| Country | Text | Country | "USA" |
+| JoinDate | Date | Customer since | 2022-03-15 |
+| Tier | Text | Customer tier | "Gold" |
+| IsActive | Boolean | Active customer | TRUE |
+
+**Hierarchies:**
+- Region > State > City
+- Tier > CustomerName
+
+---
+
+### DimStore
+
+| Column | Data Type | Description | Example |
+|--------|-----------|-------------|---------|
+| StoreKey | Integer | Surrogate PK | 101 |
+| StoreID | Text | Business key | "STORE-001" |
+| StoreName | Text | Store name | "Downtown Seattle" |
+| StoreType | Text | Store type | "Flagship" |
+| Address | Text | Street address | "100 Pike St" |
+| City | Text | City | "Seattle" |
+| State | Text | State code | "WA" |
+| PostalCode | Text | ZIP code | "98101" |
+| Region | Text | Sales region | "West" |
+| Country | Text | Country | "USA" |
+| Latitude | Decimal | Latitude | 47.6062 |
+| Longitude | Decimal | Longitude | -122.3321 |
+| OpenDate | Date | Store opened | 2020-01-15 |
+| SquareFeet | Integer | Floor space | 25000 |
+| EmployeeCount | Integer | Staff count | 45 |
+| Manager | Text | Manager name | "Jane Doe" |
+| IsActive | Boolean | Currently open | TRUE |
+
+**Hierarchies:**
+- Region > State > City > StoreName
+- StoreType > StoreName
+
+---
+
+## Calculated Columns
+
+### DimDate - Date Table Generation
+
+```m
+// Power Query for DimDate
+let
+    StartDate = #date(2020, 1, 1),
+    EndDate = #date(2026, 12, 31),
+    DateList = List.Dates(StartDate, Duration.Days(EndDate - StartDate) + 1, #duration(1, 0, 0, 0)),
+    DateTable = Table.FromList(DateList, Splitter.SplitByNothing(), {"Date"}),
+
+    // Add columns
+    WithColumns = Table.AddColumn(
+        Table.AddColumn(
+            Table.AddColumn(
+                Table.AddColumn(
+                    Table.AddColumn(
+                        Table.AddColumn(
+                            Table.TransformColumnTypes(DateTable, {{"Date", type date}}),
+                            "DateKey", each Date.ToText([Date], "yyyyMMdd"), type text
+                        ),
+                        "Year", each Date.Year([Date]), Int64.Type
+                    ),
+                    "Month", each Date.Month([Date]), Int64.Type
+                ),
+                "MonthName", each Date.MonthName([Date]), type text
+            ),
+            "Quarter", each "Q" & Text.From(Date.QuarterOfYear([Date])), type text
+        ),
+        "DayOfWeek", each Date.DayOfWeek([Date], Day.Monday) + 1, Int64.Type
+    ),
+
+    // Add more columns
+    WithMoreColumns = Table.AddColumn(
+        Table.AddColumn(
+            Table.AddColumn(WithColumns,
+                "IsWeekend", each Date.DayOfWeek([Date], Day.Monday) >= 5, type logical
+            ),
+            "YearMonth", each Date.ToText([Date], "yyyy-MM"), type text
+        ),
+        "Week", each Date.WeekOfYear([Date]), Int64.Type
+    )
+in
+    WithMoreColumns
+```
+
+### DimProduct - Margin Calculation
+
+```dax
+// DAX Calculated Column
+Margin =
+DIVIDE(
+    DimProduct[UnitPrice] - DimProduct[UnitCost],
+    DimProduct[UnitPrice]
+)
+```
+
+---
+
+## Relationship Diagram
+
+```
+DimDate[DateKey] ─────────────────────────────┐
+                                              │
+DimProduct[ProductKey] ────────────────────┐  │
+                                           │  │
+DimCustomer[CustomerKey] ────────────────┐ │  │
+                                         │ │  │
+DimStore[StoreKey] ────────────────────┐ │ │  │
+                                       │ │ │  │
+                                       ▼ ▼ ▼  ▼
+                                   ┌───────────┐
+                                   │ FactSales │
+                                   └───────────┘
+
+All relationships: Many-to-One, Single direction (Dimension → Fact)
+Cross-filter direction: Single (except DimDate which may be Both for some scenarios)
+```
+
+---
+
+## Model Settings
+
+### Table Properties
+
+| Table | Load to Report | Include in Refresh |
+|-------|----------------|-------------------|
+| FactSales | Yes | Yes |
+| DimDate | Yes | Yes (or No if static) |
+| DimProduct | Yes | Yes |
+| DimCustomer | Yes | Yes |
+| DimStore | Yes | Yes |
+
+### Hidden Columns
+
+Hide these columns from report view (they're for relationships only):
+
+- FactSales[DateKey]
+- FactSales[ProductKey]
+- FactSales[CustomerKey]
+- FactSales[StoreKey]
+- All surrogate key columns (except for debugging)
+
+### Data Categories
+
+| Column | Data Category |
+|--------|---------------|
+| DimCustomer[City] | City |
+| DimCustomer[State] | State or Province |
+| DimCustomer[PostalCode] | Postal Code |
+| DimCustomer[Country] | Country |
+| DimStore[City] | City |
+| DimStore[State] | State or Province |
+| DimStore[Latitude] | Latitude |
+| DimStore[Longitude] | Longitude |
+| DimProduct[ProductName] | Uncategorized |
+
+---
+
+## Sample Data
+
+### FactSales (5 rows)
+
+| SalesKey | DateKey | ProductKey | CustomerKey | StoreKey | Quantity | UnitPrice | Discount | Amount |
+|----------|---------|------------|-------------|----------|----------|-----------|----------|--------|
+| S001 | 20240115 | 1001 | 5001 | 101 | 2 | 24.99 | 0.00 | 49.98 |
+| S002 | 20240115 | 1002 | 5002 | 101 | 1 | 149.99 | 15.00 | 134.99 |
+| S003 | 20240116 | 1001 | 5003 | 102 | 3 | 24.99 | 5.00 | 69.97 |
+| S004 | 20240116 | 1003 | 5001 | 101 | 1 | 599.99 | 0.00 | 599.99 |
+| S005 | 20240117 | 1002 | 5004 | 103 | 2 | 149.99 | 20.00 | 279.98 |
+
+### DimProduct (3 rows)
+
+| ProductKey | ProductID | ProductName | Category | SubCategory | Brand | UnitCost | UnitPrice |
+|------------|-----------|-------------|----------|-------------|-------|----------|-----------|
+| 1001 | SKU-001 | Wireless Mouse | Electronics | Accessories | TechBrand | 12.50 | 24.99 |
+| 1002 | SKU-002 | Bluetooth Headphones | Electronics | Audio | SoundMax | 45.00 | 149.99 |
+| 1003 | SKU-003 | Gaming Monitor | Electronics | Displays | ViewPro | 280.00 | 599.99 |
+
+---
+
+## Performance Tips
+
+1. **Use surrogate keys** - Integer keys are faster for joins
+2. **Avoid high-cardinality columns** in slicers
+3. **Use aggregations** for large fact tables (1M+ rows)
+4. **Partition** by date for incremental refresh
+5. **Set data types** correctly - don't use text for numbers