Funções definidas pelo usuário da DAX

As UDFs (funções definidas pelo usuário) da DaX (Expressões de Análise de Dados) permitem empacotar lógica DAX reutilizável e parametrizada em seus modelos, facilitando a gravação, a manutenção e o compartilhamento do código DAX. Em vez de repetir fórmulas entre medidas, colunas calculadas e visuais, as UDFs trazem flexibilidade de estilo de programação para seus modelos semânticos, permitindo que você defina funções uma vez e use-as em todos os lugares em que o DAX tenha suporte.

Os UDFs da DAX geralmente estão disponíveis no Power BI Desktop e no Serviço de Power BI a partir da versão de junho de 2026. Para saber mais, confira as funções definidas pelo usuário da DAX.

Por que usar funções definidas pelo usuário?

  • Reutilização e consistência: defina um cálculo uma vez e reutilize-o em todos os lugares.
  • Manutenção: atualize a lógica em um só lugar para corrigir ou evoluir regras.
  • Criação mais segura: dicas de tipo opcionais e auxiliares de verificação de tipo dão suporte a códigos previsíveis e resistentes a erros.
  • Objetos de modelo de primeira classe: as UDFs residem no modelo e podem ser exibidas no Gerenciador de Modelos.

Definir uma função

Você pode definir uma função definida pelo usuário no Power BI Desktop usando o modo de exibição de consulta DAX (DQV), o modo de exibição TMDL ou o modo de exibição de Modelo. Você também pode visualizar e editar UDFs no navegador por meio da modelagem na Web do Power BI Service.

Sintaxe geral

A sintaxe geral de uma UDF é:

/// Optional description above the function
/// @param {ParameterType} ParameterName - ParameterDescription
/// ...
/// @returns Return description
FUNCTION <FunctionName> = ( [<ParameterName> [: [<ParameterType>] [<ParameterSubtype>] [<ParameterPassingMode>]] [= <DefaultExpression>], ...] ) => <FunctionBody>

Exemplo: Função fiscal simples

Aqui está um exemplo simples no DQV que adiciona impostos ao valor determinado. Você também pode avaliar UDFs no DQV.

DEFINE
    /// AddTax takes in amount and returns amount including tax
    FUNCTION AddTax = (
            amount : NUMERIC
        ) =>
        amount * 1.1

EVALUATE
{ AddTax ( 10 ) }
// Returns 11

Depois que um UDF é definido, você pode atualizar o modelo ou usar a lente de código para adicionar a função ao seu modelo.

Screenshot do modo de exibição de consulta DAX no Power BI Desktop, destacando dois locais em que você pode salvar uma função definida pelo usuário. O primeiro é o modelo de atualização com o botão de alterações na parte superior do modo de exibição. A segunda é uma linha de status no modelo de atualização rotulado pelo editor de código: Adicionar nova função.

O mesmo exemplo pode ser criado no modo de exibição TMDL.

createOrReplace
    /// AddTax takes in amount and returns amount including tax
    function AddTax = (amount : NUMERIC) => amount * 1.1

Depois que uma UDF for definida, você poderá aplicar alterações para adicionar a função ao seu modelo.

Screenshot do modo de exibição TMDL no Power BI Desktop, realçando o botão Aplicar na parte superior da exibição. Este botão é o local onde você pode salvar uma função definida pelo usuário.

Gerenciar funções definidas pelo usuário

Depois de definido e adicionado ao modelo, você pode exibir e gerenciar todas as funções definidas pelo usuário do Gerenciador de Modelos no nó Funções .

Captura de tela de um painel do explorador de modelos no Power BI Desktop mostrando o nó expandido de Funções. Três funções definidas pelo usuário são listadas: AddTax, AverageOrderValue e CustomerLifetimeValue.

No modo de exibição de consulta DAX (DQV), você pode usar consultas rápidas por meio do Explorador de modelos para definir e avaliar funções facilmente.

Captura de tela de um painel do explorador de modelos no Power BI Desktop exibe o nó Funções expandido. Dois menus de contexto estão abertos: o primeiro menu oferece Consultas rápidas, Renomear, Excluir do modelo, Ocultar no modo de exibição de relatório, Reexibir tudo, Recolher tudo e Expandir tudo. Consultas rápidas está realçado e selecionado. O segundo menu está realçado e oferece as opções de Consultas rápidas: Avaliar, Definir e avaliar, Definir nova função e Definir todas as funções neste modelo.

No modo de exibição TMDL, você pode arrastar e soltar funções para a área de desenho ou usar o Script TMDL por meio do Explorador de Modelos.

Captura de tela de um painel do explorador de modelos no Power BI Desktop exibindo o nó Funções expandido. Dois menus de contexto estão abertos: o primeiro menu exibe as opções Gerar script TMDL para, Renomear, Excluir do modelo, Ocultar na exibição de relatório, Reexibir tudo, Recolher tudo e Expandir tudo. A opção Gerar script TMDL para está realçada e selecionada. O segundo menu está realçado e oferece as opções de Gerar script TMDL para: guia Script e Área de Transferência.

Se estiver usando um Power BI Project, as funções também serão armazenadas na pasta functions.tmdl dentro da pasta definition.

Captura de tela do Visual Studio Code de um projeto do Power BI. O Explorer está aberto à pasta de modelo semântico. 'functions.tmdl' está aberto no editor de código. Três funções são exibidas: CustomerLifetimeValue, AverageOrderValue e AddTax.

Usar funções definidas pelo usuário

Depois de adicionar um UDF ao modelo, você pode usá-lo em qualquer lugar com suporte do DAX. Aqui, usamos AddTax como exemplo.

Use UDFs com contexto de filtro completo com medidas.

Total Sales with Tax = AddTax ( [Total Sales] )

Aplique UDFs a cada linha em uma tabela com colunas calculadas.

Sales Amount with Tax = CONVERT ( AddTax ( 'Sales'[Sales Amount] ), CURRENCY )

Use UDFs diretamente em visuais com cálculos visuais.

Sales Amount with Tax = AddTax ( [Sales Amount] )

Aninhe UDFs para cenários avançados.

DEFINE
    /// AddTax takes in amount and returns amount including tax
    FUNCTION AddTax = (
            amount : NUMERIC
        ) =>
        amount * 1.1

	FUNCTION AddTaxAndDiscount = (
			amount : NUMERIC,
			discount : NUMERIC
		) =>
		AddTax ( amount - discount )

EVALUATE
{ AddTaxAndDiscount ( 10, 2 ) }
// Returns 8.8

Parameters

UDFs DAX dão suporte a zero ou mais parâmetros. Para tornar suas funções mais seguras e previsíveis, você pode, opcionalmente, especificar dicas de tipo de parâmetro:

  • Tipo: que tipo de valor o parâmetro aceita (AnyVal, , Scalar, Table, AnyRef, CalendarRef, , ColumnRef, MeasureRefou TableRef).
  • Subtipo (somente para tipo escalar): o tipo de dados escalar específico (Variant, , Int64, Decimal, Double, String, DateTime, Booleanou Numeric).
  • ParameterMode: quando o argumento é avaliado (val para ansioso ou expr lento).

As anotações de tipo seguem a forma: [type] [subtype] [parameterMode]

Exemplo: conversão de tipo

DEFINE
    /// returns x cast to an Int64
    FUNCTION CastToInt = (
            x : SCALAR INT64 VAL
        ) =>
        x

EVALUATE
{ CastToInt ( 3.4 ), CastToInt ( 3.5 ), CastToInt ( "5" ) }
// returns 3, 4, 5

Este exemplo usa um Scalar tipo, um Int64 subtipo e um val modo de parâmetro. Você também pode obter o mesmo efeito apenas incluindo o Int64 subtipo, conforme visto no exemplo abaixo. Cadeias de caracteres não numéricas resultam em um erro.

DEFINE
    /// returns x as an Int64
    FUNCTION CastToInt = (
            x : INT64
        ) =>
        x

EVALUATE
{ CastToInt ( 3.4 ), CastToInt ( 3.5 ), CastToInt ( "5" ) }
// returns 3, 4, 5

Verificação de tipo

Valide tipos de parâmetro dentro de sua função usando funções internas de verificação de tipo DAX, como:

Para obter uma lista completa das funções de verificação de tipo disponíveis, consulte as funções definidas pelo usuário da DAX.

Conteúdo relacionado

Para obter mais informações sobre como usar funções definidas pelo usuário, consulte os seguintes recursos:

  • Last updated on