Power Query: como parâmetros e funções

Seu relatório quebra toda vez que muda o caminho do arquivo#

Se você já abriu um relatório de Power BI na segunda-feira e ele estava vermelho de erro porque alguém moveu a planilha de origem, você conhece o problema. O caminho estava fixo dentro da consulta, a fonte mudou de pasta e cada consulta que apontava para ali parou de funcionar. Multiplique isso por dez arquivos, três ambientes e uma data de corte que muda todo mês, e você tem uma tarde inteira consertando passos repetidos à mão. É exatamente aqui que Power Query parâmetros e funções deixam de ser curiosidade técnica e viram economia de tempo real.

A ideia central é simples: em vez de espalhar valores fixos e repetir a mesma sequência de passos em várias consultas, você isola o que muda em parâmetros e encapsula o que se repete em funções. Neste artigo você vai criar parâmetros de caminho de arquivo, de ambiente e de data de corte, transformar uma consulta em função e invocar essa função linha a linha para tratar vários arquivos de uma vez. Tudo com exemplos de código M que você pode colar no Editor Avançado.

Parâmetros são valores nomeados que você reaproveita nas etapas#

Um parâmetro no Power Query é um valor único, com nome, que você define uma vez e referencia em quantos passos quiser. Ele aparece no painel de consultas como um item separado e pode ter tipo definido (texto, número, data), valor atual e até uma lista de valores sugeridos. Quando você referencia esse parâmetro dentro de uma etapa, o Power Query substitui pelo valor atual no momento da atualização.

Na prática, três parâmetros resolvem a maioria das dores do dia a dia:

Parâmetro	Para que serve	Tipo sugerido
Caminho da pasta	Apontar a fonte sem gravar o endereço em cada consulta	Texto
Ambiente	Alternar entre dev, homologação e produção	Texto (lista)
Data de corte	Filtrar transações a partir de uma data de referência	Data

O ganho não é estético. Quando o caminho está em um parâmetro, trocar de servidor é editar um campo. Quando estava fixo em cada passo, era caçar e substituir string por string.

Passo a passo para criar um parâmetro#

1. No Power BI Desktop ou no Excel, abra o Editor do Power Query em Transformar dados.
2. Na faixa de opções, clique em Gerenciar Parâmetros e depois em Novo Parâmetro.
3. Dê um nome claro, por exemplo pCaminhoPasta. O prefixo p ajuda a diferenciar parâmetros de consultas comuns.
4. Escolha o Tipo como Texto e, se quiser, marque Sugestão de valores para oferecer uma lista fechada.
5. Preencha o Valor Atual com o caminho real, por exemplo C:\Dados\Vendas.
6. Clique em OK. O parâmetro passa a existir no painel esquerdo.

O mesmo fluxo cria o parâmetro de ambiente. A diferença é que, em Sugestão de valores, você usa Lista de valores e digita dev, homolog e prod. Assim, quem for atualizar escolhe de um menu, sem risco de digitar errado.

Referenciar o parâmetro é mais direto do que decorar caminhos#

Depois de criado, o parâmetro é usado como qualquer outro valor em M. Em vez de escrever o caminho literal na fonte, você concatena o parâmetro. Veja a diferença entre a versão engessada e a parametrizada.

Versão com caminho fixo, que quebra quando a pasta muda:

let
    Fonte = Folder.Files("C:\Dados\Vendas")
in
    Fonte

Versão parametrizada, que passa a ler o valor de pCaminhoPasta:

let
    Fonte = Folder.Files(pCaminhoPasta)
in
    Fonte

Para o parâmetro de ambiente, dá para montar o caminho por concatenação. O operador & junta textos em M:

let
    CaminhoBase = "C:\Dados\",
    CaminhoFinal = CaminhoBase & pAmbiente & "\Vendas",
    Fonte = Folder.Files(CaminhoFinal)
in
    Fonte

Quando pAmbiente vale prod, a fonte aponta para C:\Dados\prod\Vendas. Troca o parâmetro para homolog e a mesma consulta lê C:\Dados\homolog\Vendas, sem tocar em nenhum passo. Esse padrão é a base de qualquer estratégia séria de engenharia de dados, porque separa a lógica de transformação da configuração de origem.

A data de corte que filtra sem editar a consulta#

O parâmetro de data segue a mesma lógica. Crie pDataCorte do tipo Data com o valor 01/01/2026 e use-o dentro do filtro. Em M, o filtro de linhas é feito com Table.SelectRows:

let
    Fonte = Excel.Workbook(File.Contents(pCaminhoPasta & "\transacoes.xlsx"), true),
    Dados = Fonte{[Item="Base",Kind="Sheet"]}[Data],
    Filtrado = Table.SelectRows(Dados, each [DataVenda] >= pDataCorte)
in
    Filtrado

Toda vez que o time quiser mudar o período analisado, edita o valor do parâmetro e atualiza. A consulta permanece intacta.

Uma função em M é uma consulta que recebe argumentos#

Aqui está o conceito que destrava o reaproveitamento de verdade. Uma função em M é, tecnicamente, uma consulta que recebe um ou mais argumentos e devolve um resultado. A forma básica é (x) => corpo, em que x é o argumento de entrada e o corpo é a expressão que usa esse argumento. Se você já entendeu parâmetros, entendeu metade do caminho: a função é o passo seguinte, quando você quer que o valor de entrada mude a cada chamada.

Existem duas maneiras de chegar a uma função. A primeira é converter uma consulta existente em função. A segunda é escrever a função direto no Editor Avançado. Vamos pelas duas.

Converter uma consulta em função#

Suponha que você já tenha uma consulta chamada LerArquivo que abre um Excel específico e limpa as colunas. Para transformá-la em função que aceita o caminho como argumento:

1. Abra a consulta no Editor Avançado.
2. Envolva o bloco let ... in com o cabeçalho de função, declarando o argumento.
3. Substitua o valor fixo pelo nome do argumento onde a consulta usava o caminho literal.
4. Confirme. O ícone da consulta muda para o símbolo de função e o painel passa a oferecer o campo Invocar.

O código sai de algo assim:

let
    Fonte = Excel.Workbook(File.Contents("C:\Dados\Vendas\jan.xlsx"), true),
    Planilha = Fonte{[Item="Base",Kind="Sheet"]}[Data]
in
    Planilha

E vira uma função que aceita o caminho como parâmetro de entrada:

(CaminhoArquivo as text) as table =>
let
    Fonte = Excel.Workbook(File.Contents(CaminhoArquivo), true),
    Planilha = Fonte{[Item="Base",Kind="Sheet"]}[Data]
in
    Planilha

Repare em (CaminhoArquivo as text) as table =>. A parte antes do => declara os argumentos e seus tipos. Tipar os argumentos não é obrigatório, mas evita erros silenciosos e deixa a intenção explícita para quem mantém o relatório depois. Boa prática de código também vale em M, do mesmo jeito que vale na modelagem DAX.

Invocar a função em cada linha é o que elimina a repetição#

Funções brilham quando você tem muitos itens iguais para tratar. O caso clássico é combinar vários arquivos de uma mesma pasta: doze planilhas mensais com o mesmo layout, por exemplo. Sem função, você abriria arquivo por arquivo e repetiria os mesmos passos doze vezes. Com função, você aplica a mesma lógica a cada linha de uma tabela de arquivos.

O fluxo é este:

1. Use Folder.Files(pCaminhoPasta) para listar todos os arquivos da pasta em uma tabela. Cada linha é um arquivo, com colunas de nome, extensão e conteúdo binário.
2. Filtre a extensão desejada, por exemplo apenas .xlsx, com Table.SelectRows.
3. Adicione uma coluna personalizada que invoca a função passando o conteúdo de cada linha como argumento.
4. Expanda a coluna de tabelas resultante para empilhar todos os dados em uma única base.

Em código, a etapa que invoca a função em cada linha usa Table.AddColumn:

let
    Arquivos = Folder.Files(pCaminhoPasta),
    SomenteExcel = Table.SelectRows(Arquivos, each [Extension] = ".xlsx"),
    ComDados = Table.AddColumn(SomenteExcel, "Conteudo", each LerArquivo([Folder Path] & [Name])),
    Expandido = Table.ExpandTableColumn(ComDados, "Conteudo", {"DataVenda", "Produto", "Valor"})
in
    Expandido

A linha do Table.AddColumn é o coração da coisa. Para cada linha, ela chama LerArquivo passando o caminho completo daquele arquivo. O each significa "para cada linha, faça". O resultado é uma coluna em que cada célula guarda uma tabela inteira, e o Table.ExpandTableColumn desempilha tudo em uma base só. Adicionou um arquivo novo na pasta no mês seguinte? Atualiza e ele entra sozinho, sem nenhum passo manual.

Esse é, aliás, o mesmo mecanismo que o Power Query gera automaticamente quando você usa o botão Combinar Arquivos de uma pasta. A diferença é que, escrevendo você mesmo, você entende e controla cada etapa, em vez de depender de uma função de amostra gerada às cegas.

Quando usar parâmetro e quando usar função#

Parâmetro e função resolvem problemas parecidos, mas não idênticos. A tabela abaixo ajuda a decidir.

Situação	Use parâmetro	Use função
Um único valor que muda entre ambientes	Sim	Não
Mesma lógica aplicada a muitos itens	Não	Sim
Caminho de origem trocado manualmente	Sim	Não
Combinar 12 arquivos com o mesmo layout	Não	Sim
Data de corte editável por quem atualiza	Sim	Não
Transformação reaproveitada em várias consultas	Talvez	Sim

Uma regra de bolso: se o que muda é um valor, use parâmetro. Se o que se repete é uma sequência de passos, use função. E os dois se combinam bem. É comum uma função receber um parâmetro como argumento, como fizemos ao alimentar o caminho da pasta na leitura dos arquivos. Estruturar isso desde o começo é parte do que a gente entrega em projetos de Power BI que precisam durar mais de um trimestre sem virar dívida técnica.

Erros comuns que fazem parâmetro e função virarem dor de cabeça#

• Referenciar o parâmetro pelo texto e não pelo nome. Escrever "pCaminhoPasta" entre aspas passa a string literal, não o valor. Sem aspas, o M lê o valor atual.
• Esquecer de tipar os argumentos. Uma função (x) => ... sem tipo aceita qualquer coisa e falha só na atualização. Declare (x as text) sempre que possível.
• Deixar a função de amostra gerada pelo assistente. O botão de combinar arquivos cria consultas auxiliares. Se você não as entende, mantê-las é risco. Renomeie, documente ou reescreva.
• Concatenar caminho sem a barra. [Folder Path] & [Name] costuma funcionar porque o Power Query já inclui a barra final no caminho da pasta, mas confira antes de assumir.

Manter isso sob controle é o que separa um relatório que sobrevive à rotatividade do time de um que só o autor original consegue mexer. Governança de transformação é tema de sustentação de BI tanto quanto de desenvolvimento.

Perguntas frequentes#

Qual a diferença entre um parâmetro e uma variável dentro do let?

O parâmetro é uma entidade própria no painel de consultas, com nome, tipo e valor atual, e pode ser reaproveitado por qualquer consulta do arquivo. A variável dentro de um bloco let existe apenas naquela consulta e some fora dela. Use parâmetro quando o valor precisa ser compartilhado ou editado por quem atualiza o relatório.

Preciso saber programar em M para usar funções?

Não para começar. A maior parte do código M é gerada pela interface quando você clica nos botões de transformação. Para converter uma consulta em função, você mexe em poucas linhas, basicamente adicionar o cabeçalho (argumento) => e trocar um valor fixo pelo nome do argumento. Com o tempo, ler e ajustar M vira natural.

Dá para invocar uma função sem combinar arquivos de pasta?

Sim. A combinação de arquivos é o exemplo mais popular, mas você invoca funções em qualquer cenário de repetição: aplicar a mesma limpeza a várias abas de um Excel, chamar uma API uma vez por linha de uma tabela de IDs, ou padronizar o tratamento de datas em consultas diferentes. O padrão com Table.AddColumn e each serve para todos eles.

Como o parâmetro se comporta na atualização no serviço do Power BI?

Parâmetros publicados aparecem nas configurações do conjunto de dados no serviço, na seção de parâmetros. Lá dá para alterar o valor sem reabrir o Desktop, o que é útil para trocar de ambiente ou ajustar a data de corte direto na nuvem. Confira se o gateway e as credenciais da fonte parametrizada estão configurados.

Funções em Power Query servem para o mesmo que medidas em DAX?

Não. Funções em M atuam na etapa de transformação, antes de os dados entrarem no modelo, moldando as tabelas. Medidas DAX atuam depois, sobre o modelo já carregado, para calcular resultados na visualização. São camadas diferentes e complementares dentro de um projeto de analytics avançado.

Vale a pena parametrizar tudo desde o primeiro relatório?

Nem tudo. Parametrizar o que de fato muda, como caminho de origem, ambiente e período, compensa. Parametrizar valores que nunca mudam só adiciona camadas de indireção sem ganho. O critério é honesto: parametrize o que você já sabe que vai mexer mais de uma vez.

Menos passos repetidos, mais relatório que dura#

Parâmetros isolam o que muda e funções encapsulam o que se repete. Com esses dois recursos você para de caçar caminhos fixos, troca de ambiente em um campo e trata dez arquivos com a mesma lógica que aplicaria a um. É a diferença entre um relatório que quebra na primeira mudança de pasta e um que atravessa o ano sem sobressalto. Se a sua área vive apagando incêndio de consulta quebrada, dá para estruturar isso de forma sustentável. Fale com a gente e a gente ajuda a montar sua camada de transformação do jeito certo.