@luquimbo/bi-superpowers 1.0.0

package/library/snippets/dax/time-intelligence.md

@@ -0,0 +1,196 @@
+# Time Intelligence DAX Patterns
+
+Reusable DAX measures for time-based calculations.
+
+## Year-to-Date (YTD)
+
+### Basic YTD
+```dax
+SalesYTD =
+TOTALYTD(
+    SUM(Sales[Amount]),
+    'Date'[Date]
+)
+```
+
+### YTD with Fiscal Year (April Start)
+```dax
+SalesYTD_Fiscal =
+TOTALYTD(
+    SUM(Sales[Amount]),
+    'Date'[Date],
+    "3/31"  -- Fiscal year ends March 31
+)
+```
+
+### YTD Same Period Last Year
+```dax
+SalesYTD_PY =
+CALCULATE(
+    [SalesYTD],
+    SAMEPERIODLASTYEAR('Date'[Date])
+)
+```
+
+## Month-to-Date (MTD)
+
+### Basic MTD
+```dax
+SalesMTD =
+TOTALMTD(
+    SUM(Sales[Amount]),
+    'Date'[Date]
+)
+```
+
+### MTD with Comparison
+```dax
+SalesMTD_vs_PY =
+VAR _CurrentMTD = [SalesMTD]
+VAR _PriorYearMTD =
+    CALCULATE(
+        [SalesMTD],
+        SAMEPERIODLASTYEAR('Date'[Date])
+    )
+RETURN
+    DIVIDE(_CurrentMTD - _PriorYearMTD, _PriorYearMTD)
+```
+
+## Quarter-to-Date (QTD)
+
+### Basic QTD
+```dax
+SalesQTD =
+TOTALQTD(
+    SUM(Sales[Amount]),
+    'Date'[Date]
+)
+```
+
+## Rolling Periods
+
+### Rolling 3-Month Average
+```dax
+Sales_Rolling3M_Avg =
+AVERAGEX(
+    DATESINPERIOD(
+        'Date'[Date],
+        MAX('Date'[Date]),
+        -3,
+        MONTH
+    ),
+    CALCULATE(SUM(Sales[Amount]))
+)
+```
+
+### Rolling 12-Month Total
+```dax
+Sales_Rolling12M =
+CALCULATE(
+    SUM(Sales[Amount]),
+    DATESINPERIOD(
+        'Date'[Date],
+        MAX('Date'[Date]),
+        -12,
+        MONTH
+    )
+)
+```
+
+### Rolling 12-Month Average (Safe)
+```dax
+Sales_Rolling12M_Avg =
+VAR _Period =
+    DATESINPERIOD(
+        'Date'[Date],
+        MAX('Date'[Date]),
+        -12,
+        MONTH
+    )
+VAR _MonthsWithData =
+    COUNTROWS(
+        FILTER(
+            _Period,
+            CALCULATE(SUM(Sales[Amount])) > 0
+        )
+    )
+VAR _Total =
+    CALCULATE(
+        SUM(Sales[Amount]),
+        _Period
+    )
+RETURN
+    DIVIDE(_Total, _MonthsWithData)
+```
+
+## Period Comparisons
+
+### Prior Year
+```dax
+Sales_PY =
+CALCULATE(
+    SUM(Sales[Amount]),
+    SAMEPERIODLASTYEAR('Date'[Date])
+)
+```
+
+### Prior Month
+```dax
+Sales_PM =
+CALCULATE(
+    SUM(Sales[Amount]),
+    PREVIOUSMONTH('Date'[Date])
+)
+```
+
+### Year-over-Year Growth %
+```dax
+Sales_YoY_Pct =
+VAR _Current = SUM(Sales[Amount])
+VAR _PY = [Sales_PY]
+RETURN
+    DIVIDE(_Current - _PY, _PY)
+```
+
+### Month-over-Month Growth %
+```dax
+Sales_MoM_Pct =
+VAR _Current = SUM(Sales[Amount])
+VAR _PM = [Sales_PM]
+RETURN
+    DIVIDE(_Current - _PM, _PM)
+```
+
+## Running Totals
+
+### Cumulative Total (Calendar Year)
+```dax
+Sales_Cumulative =
+CALCULATE(
+    SUM(Sales[Amount]),
+    FILTER(
+        ALL('Date'),
+        'Date'[Date] <= MAX('Date'[Date])
+            && 'Date'[Year] = MAX('Date'[Year])
+    )
+)
+```
+
+### Cumulative Total (All Time)
+```dax
+Sales_Cumulative_AllTime =
+CALCULATE(
+    SUM(Sales[Amount]),
+    FILTER(
+        ALL('Date'),
+        'Date'[Date] <= MAX('Date'[Date])
+    )
+)
+```
+
+## Usage Notes
+
+- All patterns assume a properly configured Date table marked as Date Table
+- Replace `Sales[Amount]` with your measure or column
+- Replace `'Date'[Date]` with your date column
+- For fiscal years, adjust the year-end date in TOTALYTD

package/library/snippets/dax/user-defined-functions.md

@@ -0,0 +1,477 @@
+# DAX User-Defined Functions (UDFs) — Reference Wiki
+
+> **Status**: Public Preview (since September 2025)
+> **Compatibility**: Level 1702+ (Fabric / recent Power BI Desktop)
+> **Last updated**: March 2026
+
+This document is a ground-truth reference for DAX User-Defined Functions. Most LLMs lack training data on this feature because it was announced in April 2025 and entered public preview in September 2025.
+
+---
+
+## What Are DAX UDFs?
+
+User-Defined Functions (UDFs) let you encapsulate reusable DAX logic as named, parameterized functions. Before UDFs, the only reuse mechanism was copy-pasting measure logic or using calculation groups (a different concept).
+
+**Key benefits:**
+- Write once, call from any measure or query
+- Typed parameters with explicit evaluation modes
+- Shareable via DAX Lib community repository
+- Git-friendly storage in TMDL format
+
+---
+
+## Complete Syntax
+
+### Query-Scoped (DEFINE FUNCTION)
+
+Used in DAX queries (DAX Studio, Fabric notebooks, XMLA):
+
+```dax
+DEFINE
+    FUNCTION <FunctionName>(
+        <param1> : <Type> [<Mode>] [= <default>],
+        <param2> : <Type> [<Mode>] [= <default>]
+    ) = <SingleDAXExpression>
+
+EVALUATE <query using FunctionName>
+```
+
+### Model-Scoped (TMDL)
+
+Stored permanently in the semantic model:
+
+```tmdl
+/// Optional description comment
+createOrReplace function <FunctionName>(
+    <param1> : <Type> [<Mode>] [= <default>],
+    <param2> : <Type> [<Mode>] [= <default>]
+) = <SingleDAXExpression>
+```
+
+Model UDFs are stored in `functions.tmdl` within PBIP projects.
+
+---
+
+## Parameter Type Reference
+
+### Scalar Types
+
+| Type | DAX Equivalent | Example Values |
+|------|---------------|----------------|
+| `Variant` | Untyped | Any single value |
+| `Int64` | Whole number | `42`, `-7`, `0` |
+| `Decimal` | Fixed decimal | `3.14`, `99.99` |
+| `Double` | Floating point | `1.23e10` |
+| `String` | Text | `"Hello"`, `"North"` |
+| `DateTime` | Date/time | `DATE(2025, 1, 1)` |
+| `Boolean` | True/false | `TRUE`, `FALSE` |
+| `Numeric` | Any number | Int64, Decimal, or Double |
+
+### Aggregate Types
+
+| Type | Description | Use Case |
+|------|-------------|----------|
+| `Scalar` | Any single value | General-purpose params |
+| `AnyVal` | Default if type omitted | Loosely typed params |
+| `Table` | Table expression | Iterator-style functions |
+| `AnyRef` | Column/table reference | Advanced reference passing |
+
+---
+
+## VAL vs EXPR — Deep Dive
+
+### VAL (Value Mode) — Default
+
+```
+Evaluation: EAGER — computed once at call site
+Analogy: Like assigning to a DAX variable (VAR x = ...)
+```
+
+The caller evaluates the expression, and the function receives the **result**.
+
+```dax
+DEFINE
+    FUNCTION Double(x : Int64 VAL) = x * 2
+
+EVALUATE { Double(SUM(Sales[Amount])) }
+-- SUM(Sales[Amount]) runs once, result is doubled
+```
+
+### EXPR (Expression Mode) — Lazy
+
+```
+Evaluation: LAZY — re-computed in each row context inside the function
+Analogy: Like a callback or lambda expression
+```
+
+The function receives the **unevaluated expression** and evaluates it in its own context.
+
+```dax
+DEFINE
+    FUNCTION SumPositive(data : Table, expr : Scalar EXPR) =
+        SUMX(FILTER(data, expr > 0), expr)
+
+EVALUATE { SumPositive(Sales, Sales[Amount]) }
+-- Sales[Amount] is evaluated per-row inside FILTER and SUMX
+```
+
+### Decision Matrix
+
+| Scenario | Use | Why |
+|----------|-----|-----|
+| Param is a total/aggregate | VAL | Already computed, no row context needed |
+| Param used inside SUMX/FILTER | EXPR | Needs per-row evaluation |
+| Param is a fixed threshold | VAL | Constant value |
+| Param is a column expression | EXPR | Must resolve per row |
+| Performance is critical | VAL | Single evaluation |
+| Building iterator abstractions | EXPR | Requires lazy evaluation |
+
+### The Classic Bug
+
+```dax
+-- BUG: VAL mode inside an iterator
+DEFINE
+    FUNCTION BrokenSum(t : Table, val : Scalar VAL) =
+        SUMX(t, val)
+-- 'val' is a fixed number. SUMX just multiplies it by row count!
+
+-- FIX: Use EXPR
+DEFINE
+    FUNCTION CorrectSum(t : Table, expr : Scalar EXPR) =
+        SUMX(t, expr)
+-- 'expr' re-evaluates per row as expected
+```
+
+---
+
+## Model-Independent vs Model-Dependent UDFs
+
+### Model-Independent (Portable — Recommended)
+
+All data the function needs is passed through parameters. The function body does NOT reference any model objects directly.
+
+```dax
+-- Model-independent: all inputs via parameters
+DEFINE
+    FUNCTION GrowthRate(current : Scalar, previous : Scalar) =
+        DIVIDE(current - previous, ABS(previous))
+
+EVALUATE { GrowthRate([TotalSales], [PriorYearSales]) }
+```
+
+**Benefits:**
+- Portable across models
+- Compatible with DAX Lib sharing
+- Easy to test in isolation
+- No hidden dependencies
+
+### Model-Dependent (Tied to Model)
+
+The function body directly references model objects:
+
+```dax
+-- Model-dependent: references Sales table directly
+DEFINE
+    FUNCTION TotalSalesInRegion(region : String) =
+        CALCULATE(SUM(Sales[Amount]), Region[Name] = region)
+```
+
+### Refactoring Tip
+
+Convert model-dependent to model-independent by extracting references to parameters:
+
+```dax
+-- Before (model-dependent)
+FUNCTION TopNSales(n : Int64) =
+    CALCULATE(SUM(Sales[Amount]), TOPN(n, ALL(Products), SUM(Sales[Amount])))
+
+-- After (model-independent)
+FUNCTION TopNByMeasure(measure : Scalar EXPR, n : Int64, data : Table) =
+    CALCULATE(measure, TOPN(n, data, measure))
+```
+
+---
+
+## NAMEOF and TABLEOF (February 2026)
+
+These companion functions enable safe model-object references inside UDFs:
+
+| Function | Returns | Example |
+|----------|---------|---------|
+| `NAMEOF(column)` | Full column path as string | `NAMEOF(Sales[Amount])` → `"Sales[Amount]"` |
+| `TABLEOF(column)` | Table name as string | `TABLEOF(Sales[Amount])` → `"Sales"` |
+
+**Why they matter:** If you reference `Sales[Amount]` as a string in a UDF and the column is renamed to `Sales[Revenue]`, the string breaks silently. NAMEOF/TABLEOF track renames automatically.
+
+```dax
+-- Safe reference pattern
+DEFINE
+    FUNCTION DescribeColumn(col : AnyRef) =
+        "Column " & NAMEOF(col) & " in table " & TABLEOF(col)
+```
+
+---
+
+## Practical Patterns
+
+### Financial Calculations
+
+```dax
+DEFINE
+    -- Compound Annual Growth Rate
+    FUNCTION CAGR(
+        beginValue : Decimal,
+        endValue : Decimal,
+        years : Decimal
+    ) = IF(
+            beginValue > 0 && years > 0,
+            POWER(endValue / beginValue, 1 / years) - 1,
+            BLANK()
+        )
+
+    -- Safe Margin
+    FUNCTION SafeMargin(revenue : Decimal, cost : Decimal) =
+        IF(revenue = 0, BLANK(), (revenue - cost) / revenue)
+
+    -- Safe Division with alternate result
+    FUNCTION SafeDivide(
+        numerator : Scalar,
+        denominator : Scalar,
+        alternateResult : Scalar VAL = BLANK()
+    ) = IF(denominator = 0 || ISBLANK(denominator), alternateResult, numerator / denominator)
+```
+
+### Statistical Functions
+
+```dax
+DEFINE
+    -- Coefficient of Variation
+    FUNCTION CoeffOfVariation(
+        data : Table,
+        expr : Scalar EXPR
+    ) =
+        VAR _avg = AVERAGEX(data, expr)
+        VAR _stdev = STDEVX.P(data, expr)
+        RETURN DIVIDE(_stdev, _avg)
+
+    -- Z-Score
+    FUNCTION ZScore(value : Numeric, mean : Numeric, stdDev : Numeric) =
+        IF(stdDev <> 0, (value - mean) / stdDev, BLANK())
+```
+
+### Date Utilities
+
+```dax
+DEFINE
+    -- Working days between two dates (simplified, no holidays)
+    FUNCTION WorkingDays(startDate : DateTime, endDate : DateTime) =
+        VAR _totalDays = INT(endDate - startDate)
+        VAR _fullWeeks = INT(_totalDays / 7)
+        VAR _remainingDays = MOD(_totalDays, 7)
+        RETURN _fullWeeks * 5 + MIN(_remainingDays, 5)
+
+    -- Fiscal quarter with configurable start month
+    FUNCTION FiscalQuarter(
+        dateValue : DateTime,
+        fiscalStartMonth : Int64 VAL = 7
+    ) =
+        VAR _adjustedMonth = MOD(MONTH(dateValue) - fiscalStartMonth + 12, 12)
+        RETURN INT(_adjustedMonth / 3) + 1
+
+    -- Fiscal year
+    FUNCTION FiscalYear(
+        dateValue : DateTime,
+        fiscalStartMonth : Int64 VAL = 7
+    ) = IF(
+            MONTH(dateValue) >= fiscalStartMonth,
+            YEAR(dateValue) + 1,
+            YEAR(dateValue)
+        )
+```
+
+### Data Quality
+
+```dax
+DEFINE
+    -- Coalesce: return first non-blank value
+    FUNCTION Coalesce3(a : Scalar, b : Scalar, c : Scalar) =
+        IF(NOT(ISBLANK(a)), a, IF(NOT(ISBLANK(b)), b, c))
+
+    -- Clamp value to range
+    FUNCTION Clamp(
+        value : Decimal,
+        minVal : Decimal,
+        maxVal : Decimal
+    ) = MIN(MAX(value, minVal), maxVal)
+
+    -- Check if value is in range
+    FUNCTION IsInRange(value : Numeric, minVal : Numeric, maxVal : Numeric) =
+        value >= minVal && value <= maxVal
+```
+
+### Text Utilities
+
+```dax
+DEFINE
+    -- Extract initials from full name
+    FUNCTION GetInitials(fullName : String) =
+        VAR _Cleaned = TRIM(fullName)
+        RETURN
+            CONCATENATEX(
+                GENERATESERIES(1, LEN(_Cleaned) - LEN(SUBSTITUTE(_Cleaned, " ", "")) + 1),
+                UPPER(MID(_Cleaned, IF([Value] = 1, 1, FIND("§", SUBSTITUTE(_Cleaned, " ", "§", [Value] - 1)) + 1), 1)),
+                ""
+            )
+```
+
+### Conditional Aggregation (Iterator-Style)
+
+```dax
+DEFINE
+    -- Sum values matching a condition (uses EXPR mode)
+    FUNCTION SumWhere(
+        data : Table,
+        amount : Scalar EXPR,
+        condition : Boolean EXPR
+    ) = SUMX(FILTER(data, condition), amount)
+
+EVALUATE
+    { SumWhere(Sales, Sales[Amount], Sales[Status] = "Completed") }
+```
+
+---
+
+## DAX Lib — Community UDF Repository
+
+[DAX Lib](https://daxlib.org) is the community repository for model-independent UDFs.
+
+### Consuming Packages
+
+1. Open **Tabular Editor 3**
+2. Navigate to **Tools > DAX Package Manager**
+3. Browse or search packages
+4. Click **Install** — functions are added to your model's `functions.tmdl`
+
+### Popular Package Categories
+
+| Category | Examples |
+|----------|---------|
+| Financial | CAGR, IRR, NPV, XIRR |
+| Statistical | Median, Percentile, StdDev, ZScore |
+| Date | FiscalYear, WorkingDays, DateDiff |
+| Text | ProperCase, ExtractNumber, Slugify |
+| Data Quality | Coalesce, Clamp, IsInRange |
+
+### Publishing Your Own
+
+1. Write model-independent functions
+2. Add documentation comments (`///`)
+3. Follow DAX Lib naming conventions
+4. Submit via the DAX Lib GitHub repository
+
+---
+
+## Workflow: Creating Your First UDF
+
+### Step 1: Prototype in DAX Studio
+
+```dax
+-- Test the logic with DEFINE FUNCTION
+DEFINE
+    FUNCTION GrowthRate(current : Decimal, previous : Decimal) =
+        DIVIDE(current - previous, ABS(previous))
+
+    MEASURE Sales[TestGrowth] =
+        GrowthRate([TotalSales], [PriorYearSales])
+
+EVALUATE
+    SUMMARIZECOLUMNS(
+        'Date'[Year],
+        "Sales", [TotalSales],
+        "PY", [PriorYearSales],
+        "Growth", [TestGrowth]
+    )
+```
+
+### Step 2: Promote to Model (TMDL)
+
+```tmdl
+/// Growth rate between two values, handling zero and negative denominators
+createOrReplace function GrowthRate(
+    current : Decimal,
+    previous : Decimal
+) = DIVIDE(current - previous, ABS(previous))
+```
+
+### Step 3: Use in Measures
+
+```dax
+SalesGrowthYoY = GrowthRate([TotalSales], [PriorYearSales])
+MarginGrowth = GrowthRate([Margin], [PriorYearMargin])
+```
+
+---
+
+## Tooling Support
+
+| Tool | Create | Edit | Execute | Notes |
+|------|--------|------|---------|-------|
+| **Tabular Editor 3** | Yes | Yes | Yes | Best authoring experience |
+| **DAX Studio** | Query-scoped | Query-scoped | Yes | DEFINE FUNCTION only |
+| **PBIP / TMDL** | Yes | Yes | Yes | Edit `functions.tmdl` directly |
+| **XMLA endpoint** | Yes | Yes | Yes | Script deployment |
+| **Power BI Desktop** | Via TE3 | Via TE3 | Yes | No native UI yet |
+| **Power BI Service** | No | No | Yes | Read-only consumption |
+| **Fabric notebooks** | Query-scoped | Query-scoped | Yes | DAX cell magic |
+
+---
+
+## Limitations Summary
+
+| Limitation | Status |
+|-----------|--------|
+| No recursion | By design |
+| No function overloading | By design |
+| No optional params in DEFINE FUNCTION | Query-scoped only; model UDFs support defaults |
+| No explicit return type annotation | Inferred from body |
+| Cannot create via Power BI Service UI | Use TMDL, TE3, or XMLA |
+| Compatibility level 1702+ required | Fabric and recent Desktop |
+| Public preview | Behavior may change before GA |
+
+---
+
+## Naming Conventions
+
+| Convention | Example | When |
+|-----------|---------|------|
+| PascalCase | `GrowthRate`, `SafeDivide` | All UDFs |
+| Verb-first | `CalculateGrowth`, `FormatCurrency` | Action functions |
+| Is/Has prefix | `IsInRange`, `HasValue` | Boolean-returning functions |
+| Underscore prefix | `_InternalHelper` | Private/helper functions |
+| Category prefix | `Fin_CAGR`, `Stat_Median` | Library/package functions |
+
+---
+
+## UDFs vs Measures vs Calculation Groups
+
+| Aspect | UDFs | Measures | Calculation Groups |
+|--------|------|----------|--------------------|
+| **Parameters** | Yes, typed | No | Implicit (selected item) |
+| **Storage** | Model or query | Model | Model |
+| **Reusability** | Call from anywhere | Reference in visuals | Apply to any measure |
+| **Use case** | Shared logic | Business metrics | Format/time intelligence templates |
+| **Composable** | Yes | Via other measures | Limited |
+
+---
+
+## External References
+
+- [Microsoft Learn — DAX User-Defined Functions](https://learn.microsoft.com/dax/user-defined-functions)
+- [SQLBI — Introduction to DAX UDFs](https://www.sqlbi.com/articles/introduction-to-dax-user-defined-functions/)
+- [SQLBI — VAL vs EXPR Deep Dive](https://www.sqlbi.com/articles/val-and-expr-evaluation-modes-in-dax-user-defined-functions/)
+- [DAX Lib — Community Repository](https://daxlib.org)
+- [Tabular Editor — DAX Package Manager](https://docs.tabulareditor.com/dax-package-manager)
+
+---
+
+*This wiki is maintained as part of BI Agent Superpowers. If you find outdated information, please update this file and run `bi-superpowers recharge`.*