Conteúdo: Tipos de Parâmetro em DAX UDF
MUST
- Tratar como extensão de
dax_query_keywords(a palavra-chaveFUNCTIONjá está lá) — este conteúdo é a documentação dos tipos de parâmetro aceitos dentro da sintaxe UDF, não uma nova biblioteca de funções. - Exigir nível de compatibilidade de modelo 1702+ — mencionar isso sempre que a página explicar pré-requisitos (confirmado na doc oficial).
- Deixar claro que a sintaxe
FUNCTIONficou GA em junho de 2026 (após preview desde setembro/2025), mas que os tipos de referência especializados (MeasureRef,ColumnRef,TableRef,CalendarRef) são posteriores dentro do mesmo ciclo — março de 2026 — o que explica por que muito conteúdo antigo sobre UDF só mencionaAnyRef.
AVOID
- Não confundir
ANYREFcom "referência a um objeto existente" — a semântica oficial é "referência a uma expressão qualquer". Esse é o erro conceitual mais comum e vale um aviso destacado na UI. - Não apresentar os tipos REF como opcionais/estéticos — eles mudam comportamento real de validação e IntelliSense, não são só documentação.
1. Os 8 tipos de parâmetro
| Tipo | Modo de passagem | Aceita |
|---|---|---|
ANYVAL | VAL | Qualquer valor escalar (atalho que força passagem por valor) |
SCALAR | VAL / EXPR (VAL é o padrão) | Um valor escalar, com subtipo opcional |
TABLE | VAL / EXPR (VAL é o padrão) | Uma tabela ou expressão que produz tabela |
ANYREF | EXPR (sempre) | Qualquer expressão — o mais permissivo dos tipos de referência |
MEASUREREF | EXPR (sempre) | Apenas referência a uma medida existente |
COLUMNREF | EXPR (sempre) | Apenas referência a uma coluna existente |
TABLEREF | EXPR (sempre) | Apenas referência a uma tabela existente no modelo |
CALENDARREF | EXPR (sempre) | Apenas referência a um calendário do modelo |
Confirmado na documentação oficial: os tipos de valor (AnyVal,
Scalar, Table) suportam conversão implícita de tipo (implicit type
casting); os tipos de expressão (AnyRef, CalendarRef, ColumnRef,
MeasureRef, TableRef) não suportam.
MEASUREREF, COLUMNREF, TABLEREF e CALENDARREF são
especializações de ANYREF — restringem o tipo de expressão aceita sem
mudar o modo de passagem. Regra prática (fonte SQLBI): usar sempre o
tipo mais específico que atenda à necessidade da função; reservar
ANYREF para os casos em que a função genuinamente precisa aceitar
qualquer tipo de expressão.
2. Os 2 modos de passagem (ParameterMode)
- VAL (avaliação antecipada/eager) — o argumento é avaliado uma vez, no contexto de quem chama, antes de entrar na função. Comporta-se como uma variável fixa.
- EXPR (avaliação tardia/lazy) — o DAX substitui sintaticamente o parâmetro pela expressão fornecida, avaliando-a no ponto onde o parâmetro aparece dentro do corpo da função. Todos os tipos REF forçam este modo.
Forma completa do type hint: [tipo] [subtipo] [modoDePassagem] — todos
os componentes são opcionais; omitir tudo equivale a AnyVal val.
3. Os 8 subtipos de SCALAR
VARIANT, INT64, DECIMAL, DOUBLE, STRING, DATETIME,
BOOLEAN, NUMERIC. Definir um subtipo dispensa declarar SCALAR
explicitamente (é assumido automaticamente).
4. Comportamento de transição de contexto — ponto crítico
MEASUREREF é o único tipo de referência com transição de contexto
garantida automaticamente, porque restringe o parâmetro a uma medida de
fato. Para ANYREF/EXPR genérico, a transição de contexto não é
garantida — se o chamador passar uma expressão como SUM(Tabela[Coluna])
em vez de uma referência a medida, o autor da função precisa envolver o
parâmetro em CALCULATE(...) explicitamente dentro do corpo para obter
o comportamento esperado dentro de um iterador.
Este é o exemplo pedagógico central do capítulo-fonte (
Local.TopCustomersAnyRefA→ versão defensiva comCALCULATE) — vale reaproveitar como exemplo de código na página, pois ilustra o conceito de forma mais clara que a doc oficial.
5. Convenção de nomenclatura (comunidade, não é regra da linguagem)
Sufixar nomes de parâmetro ANYREF com Expr (ex.: amountExpr,
targetExpr) para deixar explícito, no ponto de chamada, que se trata de
uma expressão não avaliada — e não um valor resolvido. Sinalizar como
"convenção recomendada pela comunidade", não como regra da linguagem.
Pendência resolvida
Este conteúdo fecha o item "DAX UDFs... sem página dedicada de exemplos
avançados" de 06-pendencias-proximos-passos.md. Sugestão de rota:
/dax/udf como subseção nova, linkada a partir de dax_query_keywords
(linha FUNCTION).
Nota de auditoria
Todas as afirmações técnicas acima foram cruzadas em 2026-08-04 contra:
Microsoft Learn (dax-user-defined-functions,
desktop-user-defined-functions-overview) e o artigo da SQLBI
"Understanding parameter types in DAX user-defined functions (UDF)".
Nenhuma divergência encontrada entre o capítulo-fonte e a documentação
oficial. O exemplo de código (TopCustomersAnyRefA/B) é original do
autor, não uma cópia de exemplo oficial — pode ser usado livremente.