Funções definidas pelo utilizador do DAX

As funções definidas pelo usuário (UDFs) DAX (Data Analysis Expressions) permitem empacotar lógica DAX parametrizada e reutilizável em seus modelos, tornando o código DAX mais fácil de escrever, manter e compartilhar. 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 onde o DAX é suportado.

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

Porquê utilizar funções definidas pelo utilizador?

  • Reutilização e consistência: defina um cálculo uma vez e reutilize-o em qualquer lugar.
  • Manutenibilidade : 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 suportam código previsível e resistente a erros.
  • Objetos de modelo de primeira classe: UDFs vivem no modelo e podem ser visualizados no Gerenciador de Modelos.

Definir uma função

Pode definir uma função definida pelo utilizador no Power BI Desktop usando a vista de consulta DAX (DQV), a vista TMDL ou a vista do modelo. Também pode visualizar e editar UDFs no navegador através da modelação web do Power BI Service.

Sintaxe geral

A sintaxe geral para 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 em DQV que adiciona imposto sobre o valor determinado. Você também pode avaliar UDFs em 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.

Captura de ecrã da vista de consulta DAX no Power BI Desktop, destacando dois locais onde pode guardar uma função definida pelo utilizador. O primeiro é o modelo Atualizar com o botão de alterações no topo da vista. A segunda é uma linha de estado no editor de código rotulada Atualizar modelo: Adicionar nova função.

O mesmo exemplo pode ser criado na visualização TMDL.

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

Depois de definir um UDF, pode aplicar alterações para adicionar a função ao seu modelo.

Captura de ecrã da vista TMDL no Power BI Ambiente de Trabalho, a destacar o botão Aplicar no topo da vista. Este botão é o local onde pode guardar uma função definida pelo utilizador.

Gerir funções definidas pelo utilizador

Uma vez definido e adicionado ao modelo, pode visualizar e gerir todas as funções definidas pelo utilizador a partir do explorador de modelos , no nó Funções .

Captura de ecrã de um painel do explorador de modelos no Power BI Desktop que mostra o nó Funções expandido. Estão indicadas três funções definidas pelo utilizador: AddTax, AverageOrderValue e CustomerLifetimeValue.

Na vista de consultas DAX (DQV), pode usar consultas rápidas através do explorador de modelos para definir e avaliar funções facilmente.

Captura de ecrã de um painel do explorador de modelos no Power BI Desktop mostra o nó expandido Funções. Dois menus de contexto estão abertos: o primeiro menu oferece Consultas Rápidas, Renomear, Eliminar do modelo, Ocultar na vista de relatório, Mostrar tudo, Colapsar tudo e Expandir tudo. A consulta rápida é destacada e selecionada. O segundo menu está destacado 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.

Na visualização TMDL, podes arrastar e largar funções para a tela ou usar o Script TMDL através do explorador de modelos.

Uma captura de ecrã de um painel Explorador de modelos no Power BI Desktop mostra o nó Funções expandido. Estão abertos dois menus de contexto: o primeiro apresenta as opções Script para TMDL, Mudar o nome, Eliminar do modelo, Ocultar na vista de relatório, Mostrar tudo novamente, Colapsar tudo e Expandir tudo. A opção Script para TMDL está destacada e selecionada. O segundo menu também está destacado e apresenta as opções de Script para TMDL: separador Script e Área de Transferência.

Se usar um Power BI Project, as funções também são armazenadas em functions.tmdl dentro da pasta definição.

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

Utilizar funções definidas pelo utilizador

Depois de adicionar um UDF ao modelo, pode usá-lo em qualquer lugar onde o DAX seja suportado. Aqui usamos AddTax como exemplo.

Utilize UDFs com contexto de filtro completo com medidas.

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

Aplicar UDFs a cada linha de uma tabela com colunas calculadas.

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

Usa os UDFs diretamente nos visuais com cálculos visuais.

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

Nest 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

Os DAX UDFs suportam zero ou mais parâmetros. Para tornar as suas funções mais seguras e previsíveis, pode opcionalmente especificar dicas de tipo de parâmetro:

  • Tipo: que tipo de valor o parâmetro aceita (AnyVal, Scalar, Table, AnyRef, CalendarRef, ColumnRef, , MeasureRef, , ou TableRef).
  • Subtipo (apenas para tipo escalar): o tipo de dados escalares específico (Variant, Int64, Decimal, Double, String, DateTime, Boolean, ou Numeric).
  • ParameterMode: quando o argumento é avaliado (val para entusiasta ou expr preguiçoso).

As anotações de tipo têm a forma: [type] [subtype] [parameterMode]

Exemplo: Tipo de fundição

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 utiliza um Scalar tipo, Int64 subtipo e val parameterMode. Também pode obter o mesmo efeito simplesmente incluindo o Int64 subtipo, como se vê no exemplo abaixo. Cadeias não numéricas resultam num 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 os tipos de parâmetros dentro da sua função usando funções de verificação de tipos DAX incorporadas, tais como:

Para uma lista completa das funções de verificação de tipos disponíveis, consulte as funções definidas pelo utilizador DAX.

Conteúdo relacionado

Para mais informações sobre a utilização de funções definidas pelo utilizador, consulte os seguintes recursos:

  • Last updated on