Add documentation for user-defined functions in DAX, covering syntax, parameter types, optional parameters, model dependency, and comparison with calculation groups.

Author: marcosqlbi

_mydocs/dax-internals/user-defined-functions/calculate-modifiers.md

@@ -0,0 +1,77 @@
+---
+layout:     page
+title:      Returning CALCULATE modifiers
+published:  true
+order:      /04
+---
+
+Because UDFs expand as macros, a function body can contain expressions that are only syntactically valid in a specific calling position. In particular, a function can "return" a CALCULATE modifier — provided the function is always called as a filter argument of `CALCULATE` or `CALCULATETABLE`.
+
+## Mechanism
+
+`REMOVEFILTERS`, `USERELATIONSHIP`, and other CALCULATE modifiers are not valid as standalone expressions; they are only valid inside `CALCULATE` or `CALCULATETABLE`. When a UDF whose body is a CALCULATE modifier is placed inside `CALCULATE` or `CALCULATETABLE`, macro-expansion substitutes the modifier directly into the correct position, producing a valid expression.
+
+## Pattern 1: function returns a modifier directly
+
+```dax
+DEFINE
+    FUNCTION Gregorian.RemoveFilterKeepColumns = () =>
+        REMOVEFILTERS (
+            'Date'[Day of Week],
+            'Date'[Day of Week Number],
+            'Date'[Day of Week Short]
+        )
+```
+
+Called as a CALCULATE filter argument:
+
+```dax
+CALCULATE (
+    MAX ( 'Date'[Date] ),
+    Gregorian.RemoveFilterKeepColumns ()
+)
+```
+
+After macro-expansion this is equivalent to:
+
+```dax
+CALCULATE (
+    MAX ( 'Date'[Date] ),
+    REMOVEFILTERS (
+        'Date'[Day of Week],
+        'Date'[Day of Week Number],
+        'Date'[Day of Week Short]
+    )
+)
+```
+
+This function **cannot** be called anywhere except as a filter argument of `CALCULATE` or `CALCULATETABLE`. Its return is not a scalar or table, so any other calling position is invalid.
+
+## Pattern 2: CALCULATE encapsulated inside the function
+
+An alternative wraps the `CALCULATE` call inside the function and accepts the target expression as an `EXPR` parameter:
+
+```dax
+DEFINE
+    FUNCTION Gregorian.ComputeRemovingFilterKeepColumns = ( formulaExpr : EXPR ) =>
+        CALCULATE (
+            formulaExpr,
+            REMOVEFILTERS (
+                'Date'[Day of Week],
+                'Date'[Day of Week Number],
+                'Date'[Day of Week Short]
+            )
+        )
+```
+
+Called as:
+
+```dax
+Gregorian.ComputeRemovingFilterKeepColumns ( [Sales Amount] )
+```
+
+This pattern returns a scalar and has no calling-position restriction. The choice between the two patterns is a matter of design preference; Pattern 1 is more composable when the same modifier needs to appear in many different `CALCULATE` calls with different expressions.
+
+## Practical use case
+
+A common application is centralizing the list of **filter-keep columns** — columns on a date table whose filters must be removed when computing a reference date, but preserved by time intelligence functions applied afterward. Placing the `REMOVEFILTERS` list in a function prevents it from being duplicated across many measures and simplifies maintenance when the column list changes.

_mydocs/dax-internals/user-defined-functions/index.md

@@ -0,0 +1,18 @@
+---
+layout:     page
+title:      User-defined functions (UDF)
+published:  true
+order:      /
+next_reading: true
+next_reading_title: false
+---
+
+A DAX user-defined function (UDF) is a named, reusable expression declared with the `DEFINE FUNCTION` statement. UDFs are not subroutines invoked on a call stack; they expand inline at the call site as macros. The function body is substituted wherever the function is called, which means that expressions only valid in certain positions — such as CALCULATE modifiers — can be encapsulated inside a function and remain valid after expansion.
+
+UDFs can be defined at query level inside a `DEFINE` block or stored in a semantic model and shared across all measures and calculated columns in that model.
+
+Related SQLBI articles: 
+- [Introducing user-defined functions in DAX](https://www.sqlbi.com/articles/introducing-user-defined-functions-in-dax/)
+- [Model-dependent and model-independent user-defined functions in DAX](https://www.sqlbi.com/articles/model-dependent-and-model-independent-user-defined-functions-in-dax/)
+- [Understanding parameter types in DAX user-defined functions](https://www.sqlbi.com/articles/understanding-parameter-types-in-dax-user-defined-functions-udf/)
+- [UDFs vs. calculation groups](https://www.sqlbi.com/articles/dax-user-defined-functions-udf-vs-calculation-groups/)

_mydocs/dax-internals/user-defined-functions/model-dependency.md

@@ -0,0 +1,57 @@
+---
+layout:     page
+title:      Model dependency
+published:  true
+order:      /05
+---
+
+A UDF is **model-dependent** when its body references model objects directly — tables, columns, measures, or calendars — by name. It is **model-independent** when all such references arrive exclusively through parameters, making the function portable across semantic models without modification.
+
+## Hidden dependencies
+
+A function accepting a `TABLE` or `TABLE EXPR` parameter may appear model-independent while harboring implicit structural dependencies. If the function body accesses specific column names inside that table (e.g., `tableParam[Quantity]`), it implicitly requires those columns to exist in whatever table the caller passes. To make the function truly model-independent, expose each required column as a separate `COLUMNREF` or `ANYREF` parameter.
+
+## Naming conventions
+
+### Function names
+
+Use dot notation to namespace functions and communicate their intended scope:
+
+| Prefix | Meaning |
+|---|---|
+| `Local.` | Model-specific; not intended for sharing across models |
+| `<LibraryName>.` | Distributed library function (e.g., `DaxPatterns.LikeForLike.EntityStatus`) |
+
+### Parameter names
+
+Use camelCase with a type-indicating suffix when the parameter type carries semantic meaning:
+
+| Suffix | Parameter type |
+|---|---|
+| `Expr` or `Measure` | EXPR scalar or `MEASUREREF` |
+| `Column` | `COLUMNREF` |
+| `Table` | `TABLEREF` or `TABLE EXPR` |
+| `Calendar` | `CALENDARREF` |
+
+Example: `( salesMeasure : MEASUREREF, dateColumn : COLUMNREF, salesTable : TABLEREF )`
+
+## Validating column parameters
+
+When a function accepts multiple `COLUMNREF` parameters that must belong to the same table, use `TABLEOF` and `NAMEOF` to verify at runtime:
+
+```dax
+IF (
+    NAMEOF ( TABLEOF ( col1 ) ) <> NAMEOF ( TABLEOF ( col2 ) ),
+    ERROR ( "col1 and col2 must belong to the same table" )
+)
+```
+
+This pattern does not work reliably today: when the column parameters are used incorrectly in the function body, DAX generates its own internal error from that usage before the `IF`/`ERROR` validation code executes, hiding the custom error message. See the same limitation noted in [Parameter types / Introspection functions](parameter-types.md#introspection-functions).
+
+## Portability pattern
+
+Wrapping a model-independent function in a thin model-dependent function is a common pattern to simplify call sites without sacrificing the underlying function's portability. The model-independent function is shared (e.g., via a library); the model-dependent wrapper maps concrete model objects to the required parameters and exposes a shorter signature to measure authors.
+
+Model-independent functions can be published to and consumed from shared DAX libraries such as [daxlib.org](https://daxlib.org).
+
+See [Model-dependent and model-independent user-defined functions in DAX](https://www.sqlbi.com/articles/model-dependent-and-model-independent-user-defined-functions-in-dax/).

_mydocs/dax-internals/user-defined-functions/optional-parameters.md

@@ -0,0 +1,87 @@
+---
+layout:     page
+title:      Optional parameters
+published:  true
+order:      /03
+---
+
+A parameter is optional when its declaration includes a **default expression**. When the caller omits the argument, DAX evaluates the default expression and uses its result as the parameter value.
+
+## Syntax
+
+```
+<ParameterName> [ : <TypeHint> ] = <DefaultExpression>
+```
+
+A parameter without `=` is mandatory; a parameter with `=` is optional.
+
+```dax
+DEFINE
+    FUNCTION Increment = ( x : NUMERIC, y : NUMERIC = 1 ) => x + y
+```
+
+`x` is mandatory; `y` is optional with a default of `1`.
+
+## Omitting arguments
+
+### Trailing omission
+
+Optional parameters at the end of the parameter list are omitted by stopping the argument list early:
+
+```dax
+Increment ( 3 )       -- y uses default 1; returns 4
+Increment ( 10, 20 )  -- y is 20; returns 30
+```
+
+### Skipping a middle parameter
+
+To skip an optional parameter that is not the last one, write an **empty position** — a comma with no value before it:
+
+```dax
+IncrementLimit ( 5, , 20 )  -- y uses its default; limit is 20
+```
+
+## Position and arity
+
+Optional parameters can appear in any position in the signature; required parameters can follow optional ones. Callers can always reach a required parameter by leaving an empty position for each optional parameter before it (`MyFunc ( 1, , 3 )` omits the second argument).
+
+The minimum number of arguments a caller must supply — the function's arity — is determined by the **position of the rightmost required parameter**. If a function has three parameters and only the second is optional, callers must still supply at least three arguments: there is no way to omit the third, because it is required and comes last.
+
+The recommended practice is: **once a parameter is optional, all following parameters should also be optional.** Placing a required parameter after an optional one forces callers to write empty positions just to reach it, which is harder to read and easy to get wrong.
+
+## Detecting absent arguments with BLANK
+
+When no fixed value is a natural default, use `BLANK()` as the default expression and test with `ISBLANK` inside the function body:
+
+```dax
+DEFINE
+    FUNCTION RoundDivision =
+        (
+            x        : NUMERIC,
+            y        : NUMERIC,
+            digits   = BLANK ()
+        ) =>
+            VAR Result = DIVIDE ( x, y )
+            RETURN
+                IF (
+                    ISBLANK ( digits ),
+                    Result,
+                    ROUND ( Result, digits )
+                )
+```
+
+**Limitation:** The function cannot distinguish an omitted argument from an explicitly passed `BLANK()`. `RoundDivision ( 2, 3, BLANK() )` is indistinguishable from `RoundDivision ( 2, 3 )`.
+
+## Rules for default expressions
+
+### Context
+
+Like the function expression body, a default expression inherits the **filter context of the caller** but does **not** inherit any row context. It is evaluated as if written at the call site, outside any iterator.
+
+### Scope
+
+A default expression can only reference names — columns, tables, measures, variables, functions — that are **visible at the point where the UDF is defined**, not where it is called. It cannot reference another parameter of the same function.
+
+### Type
+
+Type checking of the default expression against the parameter's type hint is enforced only **when the default is used** (i.e., the caller omitted the argument). When the caller provides an explicit argument, the type hint is applied to that argument instead.

_mydocs/dax-internals/user-defined-functions/parameter-types.md

@@ -0,0 +1,113 @@
+---
+layout:     page
+title:      Parameter types
+published:  true
+order:      /02
+---
+
+Each parameter has two independent properties: a **data type** (what expressions it accepts) and a **passing mode** (how the argument is transferred from call site to function body).
+
+## Passing modes
+
+### VAL
+
+The argument is evaluated once, in the evaluation context of the caller, before the function body runs. The parameter behaves like a `VAR` bound to that value. Changes in filter or row context inside the function body have no effect on the parameter's value.
+
+Semantic equivalent for a call `F( SUM ( Sales[Quantity] ) )` with parameter `qty : VAL`:
+
+```dax
+VAR qty = SUM ( Sales[Quantity] )
+RETURN <body>
+```
+
+### EXPR
+
+The argument expression is captured unevaluated and substituted inline at every reference to the parameter inside the function body. The expression is re-evaluated each time it is referenced, in the evaluation context present at that point in the body.
+
+Semantic equivalent for a call `F( SUM ( Sales[Quantity] ) )` with parameter `qty : EXPR`:
+
+```dax
+-- every reference to qty in the body becomes SUM ( Sales[Quantity] )
+```
+
+**Context transition:** EXPR parameters do **not** receive automatic context transition in row contexts, unlike a measure reference. To ensure correct behavior inside iterators, wrap the parameter reference in CALCULATE:
+
+```dax
+CALCULATE ( paramExpr )
+```
+
+`MEASUREREF` (see below) is the only reference type that guarantees context transition automatically.
+
+## Data types
+
+| Type | Accepts | Passing mode | Notes |
+|---|---|---|---|
+| `ANYVAL` | Any scalar or table | VAL (default) | Default when no type hint is specified |
+| `SCALAR` | Scalar expressions only | VAL or EXPR | Accepts a subtype to restrict the data type |
+| `TABLE` | Table expressions only | VAL or EXPR | |
+| `ANYREF` | Any expression | EXPR (forced) | No semantic guarantee on the expression kind |
+| `MEASUREREF` | Measure references only | EXPR (forced) | Guarantees context transition in row contexts |
+| `COLUMNREF` | Column references only | EXPR (forced) | Enables model-independent column access |
+| `TABLEREF` | Model table references only | EXPR (forced) | Provides full column and relationship access |
+| `CALENDARREF` | Calendar references only | EXPR (forced) | Intended for time intelligence functions |
+
+`ANYREF`, `MEASUREREF`, `COLUMNREF`, `TABLEREF`, and `CALENDARREF` force EXPR passing mode and cannot be declared as VAL.
+
+### Scalar subtypes
+
+`SCALAR` can be qualified with a subtype that restricts the accepted data type and enables automatic coercion:
+
+| Subtype | Accepts |
+|---|---|
+| `VARIANT` (default) | Any scalar data type |
+| `INT64` | Integer |
+| `DECIMAL` | Fixed-decimal number |
+| `DOUBLE` | Floating-point number |
+| `NUMERIC` | Any numeric type (INT64, DECIMAL, DOUBLE) |
+| `STRING` | Text |
+| `DATETIME` | Date or timestamp |
+| `BOOLEAN` | True/False |
+
+Coercion applies independently to each parameter; it does not propagate across parameters.
+
+## Type declaration syntax
+
+```
+<ParameterName> : <Type> [<Subtype>] [<PassingMode>]
+```
+
+When only a passing mode is written without a type, the type defaults to `ANYVAL`:
+
+```dax
+FUNCTION F = ( a : VAL, b : EXPR ) => ...
+```
+
+## Type checking
+
+Type checking and coercion apply differently depending on the parameter category:
+
+**Scalar subtypes** (`INT64`, `DECIMAL`, `DOUBLE`, etc.) do not reject incompatible arguments — they coerce them. Each argument is independently converted to the declared type before the function body runs. No error is raised; see the coercion note under *Scalar subtypes* above.
+
+**Reference types** (`MEASUREREF`, `COLUMNREF`, `TABLEREF`, `CALENDARREF`) perform genuine type checking at call time. Passing an incompatible expression produces an error that identifies the expected and received types, for example: *"An invalid argument type was passed into parameter 'amountMeasure' of the user-defined function. Expected 'MEASUREREF' but got 'SCALAR'."* There is a known limitation for `COLUMNREF`: when a column reference is invalid, the internal syntax error from the function body surfaces before any custom validation error the function author may have written.
+
+**`ANYREF`** performs no type checking. An incompatible argument may produce confusing errors deep inside the function body or, in the worst case, incorrect results with no error at all. Functions using `ANYREF` must handle the general case defensively — for example, wrapping every reference to the parameter in `CALCULATE` to guarantee context transition regardless of what was passed.
+
+## Introspection functions
+
+Two functions are available for use inside a function body with `COLUMNREF` or `TABLEREF` parameters:
+
+- **`TABLEOF ( columnRef )`** — returns the table in which the referenced column is defined.
+- **`NAMEOF ( columnRef )`** — returns the column's fully qualified name as a string.
+
+These functions are intended to support runtime validation — for example, checking that two `COLUMNREF` parameters belong to the same table:
+
+```dax
+IF (
+    NAMEOF ( TABLEOF ( col1 ) ) <> NAMEOF ( TABLEOF ( col2 ) ),
+    ERROR ( "col1 and col2 must belong to the same table" )
+)
+```
+
+This pattern does not work reliably today: when the column parameters are used incorrectly in the function body, DAX generates its own internal error from that usage before the `IF`/`ERROR` validation code executes, hiding the custom error message. The intent is correct and the pattern is expected to work once the evaluation order is enforced.
+
+See [Understanding parameter types in DAX user-defined functions](https://www.sqlbi.com/articles/understanding-parameter-types-in-dax-user-defined-functions-udf/).