Trabalhar com o modo de exibição TMDL no Power BI Desktop (versão prévia)

2025-05-21

A exibição TMDL permite que você crie scripts, modifique e aplique alterações a objetos de modelo semântico com um editor de código moderno usando o TMDL (Tabular Model Definition Language) no Power BI Desktop, aprimorando a eficiência de desenvolvimento e fornecendo visibilidade e controle completos sobre metadados de modelo semântico.

A exibição TMDL oferece uma experiência alternativa à modelagem semântica usando código, em vez de uma interface gráfica do usuário, como a Exibição do modelo.

O modo de exibição TMDL oferece as seguintes vantagens:

Eficiência de desenvolvimento aprimorada com um editor de código avançado que inclui pesquisa e substituição, atalhos de teclado, edições de várias linhas e muito mais.
Aumentar a reutilização através da facilidade de escrever, compartilhar e reutilizar scripts TMDL entre desenvolvedores de modelos semânticos. Por exemplo, use um site centralizado do SharePoint para compartilhar facilmente objetos de modelo semântico reutilizáveis, como tabelas de calendário ou grupos de cálculo de inteligência de tempo.
Obter mais controle e transparência, mostrando todos os objetos e propriedades de modelo semântico e permitindo alterações em itens não disponíveis na interface do usuário do Power BI Desktop, como IsAvailableInMDX ou DetailRowsDefinition.

Habilitar o recurso de visualização

Para usar a exibição TMDL, você precisa habilitar a versão prévia do recurso. No Power BI Desktop, selecione Arquivo > Opções e configurações > Opções > Versão prévia dos recursos e selecione a caixa ao lado da Exibição TMDL.

Script para TMDL

No Power BI Desktop, selecione o ícone Exibição TMDL localizado no lado esquerdo da janela, conforme mostrado na imagem a seguir.

captura de tela do modo de exibição T-M-D-L da linguagem de definição de modelo tabular.

Quando o modo de exibição TMDL é aberto, o editor de código está inicialmente vazio. Você pode criar um script de qualquer objeto de modelo semântico, como uma tabela, medida ou coluna selecionando os objetos no painel de dados e arrastando-os para o editor de código:

Captura de tela de arrastar um objeto de modelo semântico para a tela de exibição T-M-D-L.

Ao usar a exibição TMDL e arrastar o objeto do painel dados, o Power BI criará scripts de metadados de objeto inteiros na guia atual como TMDL ou abrirá uma nova guia se a guia atual não estiver vazia, como um script TMDL createOrReplace dos objetos selecionados, conforme mostrado na seguinte imagem:

Captura de tela dos metadados T-M-D-L que estão sendo criados automaticamente.

Como alternativa, você pode clicar com o botão direito do mouse em um objeto na exibição de dados e selecionar Script TMDL na nova guia ou na área de transferência, mostrada na seguinte imagem:

Captura de tela do clique com o botão direito do mouse em um objeto no modo de exibição de dados para que o Power BI crie o código de metadados T-M-D-L.

Dica

Há suporte para várias seleções pressionando a tecla CTRL antes de escrever os scripts dos objetos no editor de código da exibição TMDL.

Editor de código

Depois de criar um script de um objeto de modelo semântico ou colar um script TMDL no editor de código, você poderá usar os recursos abrangentes de experiência de código oferecidos pelo editor de código de exibição TMDL. Os recursos de experiência de código permitem explorar os metadados do modelo ou fazer modificações que podem ser aplicadas posteriormente ao modelo semântico.

Realce semântico

O realce semântico é integrado ao editor de código, o que melhora a legibilidade aplicando cores diferentes a partes do código com base no significado. Essa codificação de cores facilita a compreensão da estrutura e da funcionalidade do código TMDL, conforme mostrado na imagem a seguir.

Captura de tela de codificação de cores e realce semântico para código de metadados T-M-D-L.

Você também pode expandir ou recolher seções do script TMDL, conforme mostrado na imagem a seguir:

Captura de tela das seções recolhíveis de código no editor de código.

Preenchimento automático

O preenchimento automático é integrado ao editor de código e oferece sugestões inteligentes enquanto você digita. O preenchimento automático pode acelerar seu fluxo de trabalho, reduzir a chance de erros e ajudá-lo a entender suas opções de código, sugerindo dinamicamente possíveis valores ou propriedades levando em consideração a posição do cursor.

Captura de tela do preenchimento automático no editor de código.

Você também pode disparar o recurso de preenchimento automático em qualquer local pressionando Ctrl+Espaço.

Dicas de ferramentas

A dica de ferramenta aparece ao passar o mouse, fornecendo informações sobre cada objeto ou propriedade TMDL.

Captura de tela de uma dica de ferramenta de contexto mostrada ao passar o mouse no editor de código, exibindo informações sobre um objeto ou propriedade TMDL.

Ações de código

Quando o cursor está em um squiggle ou texto selecionado, o modo de exibição TMDL exibe um ícone de lâmpada indicando ações de código disponíveis, como gerar marcas de linhagem ou corrigir erros de grafia em nomes de propriedades.

Captura de tela da visualização TMDL no editor de código mostrando um ícone de lâmpada ao lado de um rabisco, indicando ações de código disponíveis, como gerar etiquetas de linhagem.

Captura de tela do modo de exibição TMDL no editor de código mostrando um ícone de lâmpada ao lado de um rabisco, indicando ações de código disponíveis, como corrigir erros ortográficos do nome da propriedade.

Formatação de código

Formate o código TMDL pressionando Shift + Alt + F ou clicando na opção Formatar na faixa de opções.

Captura de tela do editor de código com o código TMDL sendo formatado usando a opção Formatar na faixa de opções.

Você também pode formatar o texto selecionado usando a opção "Formatar Seleção" no menu de contexto.

Captura de tela do editor de código com o código TMDL sendo formatado o atalho de teclado Shift + Alt + F.

Diagnóstico de erro

O diagnóstico de erro interno do editor de código ajuda você a identificar e corrigir problemas realçando erros de linguagem TMDL no editor de código, com mensagens detalhadas que fornecem diretrizes sobre como resolvê-los. Além disso, um resumo de erros está disponível no painel Problemas, permitindo fácil navegação para o local de erro no editor de código, conforme mostrado na imagem a seguir.

Captura de tela do diagnóstico de erro no editor de código.

Aplicar alterações ao modelo semântico

Quando estiver pronto, você poderá selecionar o botão Aplicar para executar o script TMDL no modelo semântico e aplicar as alterações de código TMDL.

Captura de tela da aplicação do script usando o botão aplicar no editor de código.

Quando bem-sucedida, uma notificação é exibida e sua alteração de modelagem é aplicada ao modelo semântico.

Captura de tela da faixa de êxito no editor de código indicando que as alterações foram aplicadas com êxito.

No caso de uma falha, uma notificação de erro é exibida para mostrar que as alterações de modelagem não foram aplicadas ao modelo semântico. Você pode exibir mais informações sobre o erro selecionando o link Mostrar detalhes na notificação, que expande o painel Saída e exibe os detalhes do erro.

Captura de tela do banner de erro no editor de código indicando que as alterações não foram bem-sucedidas.

Nota

A exibição TMDL modifica apenas os metadados semânticos do modelo, sem atualizar dados ou afetar o relatório. Se as alterações exigirem uma atualização de dados, como alterar uma expressão do PowerQuery ou uma expressão de coluna calculada, você deverá atualizar manualmente a tabela ou o modelo para que as alterações entrem em vigor. Além disso, renomear um campo na exibição TMDL pode interromper os visuais no relatório que usam esse campo.

Visualizar alterações no modelo semântico

O modo de exibição TMDL permite visualizar as alterações de script mostrando uma visualização do modelo semântico antes e depois da execução do script, mostrada como uma diferença de código TMDL. Visualizar alterações de script é particularmente útil ao copiar scripts de outras fontes, permitindo que você avalie seu impacto antes de executá-los em seu modelo semântico.

Selecionar o botão Visualizar exibe uma diferença TMDL do modelo semântico antes e depois de executar o script TMDL na guia aberta.

Captura de tela do botão de visualização para visualizar as alterações de script.

Uma janela lado a lado aparece no painel direito, conforme mostrado na imagem a seguir.

Caixas vermelhas e verdes destacam as alterações, com as caixas vermelhas indicando linhas removidas ou alteradas e as caixas verdes indicando novas linhas.

Captura de tela mostrando destaques em vermelho e verde para alterações pendentes no script.

Nota

A comparação não é diretamente em relação ao script TMDL exibido no momento, mas sim uma comparação abrangente de modelo semântico antes e depois de executar o script. Portanto, algumas propriedades podem ser ordenadas de forma diferente do que é mostrado na guia, aderindo à ordenação de propriedade/objeto TMDL padrão.

A visualização é somente leitura, mas você pode continuar editando seu script. Para atualizar a visualização após as alterações, selecione o botão Atualizar Visualização , conforme mostrado na faixa na imagem a seguir.

Captura de tela do botão de visualização de atualização.

Há uma barra de ferramentas no canto superior direito da tela de visualização que permite navegar por todos os difs de código, permitindo que você alterne entre difs embutido ou lado a lado, exibir ou ocultar regiões inalteradas e fechar a visualização.

Captura de tela da barra de ferramentas para visualização de script.

Há algumas considerações a serem consideradas ao visualizar alterações no modelo semântico:

A exibição TMDL redefine as configurações de exibição para padrão em cada execução de visualização.
Uma visualização é executada apenas com uma alteração TMDL válida. Scripts TMDL inválidos não executarão a exibição de prévia e um erro será exibido no painel de saída.

Guias de script TMDL

No modo de exibição TMDL, você pode ter várias guias de script ao mesmo tempo, e qualquer uma delas pode ser renomeada ou removida.

Captura de tela de várias guias na exibição TMDL.

O conteúdo das guias da exibição TMDL é salvo no arquivo de relatório ao salvar o relatório do Power BI Desktop, permitindo que você continue de onde parou na próxima vez que abrir o arquivo de relatório do Power BI Desktop. Ao salvar em um PBIP (Projeto do Power BI), cada guia de script é salva como um arquivo .tmdl na pasta \TMDLScripts, conforme mostrado na imagem a seguir.

Captura de tela da estrutura de arquivo para salvar guias em um arquivo do Power BI Desktop.

Dica

Você pode abrir e editar scripts TMDL no Visual Studio Code e eles serão recarregados corretamente após reiniciar o Power BI Desktop.

Os painéis Problemas e Saída exibem erros e mensagens específicas para a guia de script que está selecionada e exibida no momento. Alternar para uma guia de script TMDL diferente atualiza ambos os painéis com informações específicas da guia selecionada e que está em exibição.

Você pode selecionar o botão Limpar para apagar as mensagens do painel Saída.

Captura de tela do botão limpar usado para apagar as mensagens do painel de saída.

As mensagens são mantidas apenas durante cada sessão do Power BI Desktop; assim, ao reiniciar o Power BI Desktop, todas as mensagens de saída de todas as abas de script são apagadas.

Aviso de atualização do nível de compatibilidade

O nível de compatibilidade de um modelo semântico do Power BI determina os recursos acessíveis. O modo de exibição TMDL permite adicionar qualquer objeto ou propriedade do Analysis Services, mesmo que ele não esteja disponível no nível de compatibilidade atual. Ao aplicar uma alteração que exige uma atualização de nível de compatibilidade, o modo de exibição TMDL fornece um prompt que indica quais objetos ou objetos exigem a atualização.

Captura de tela do modo de exibição TMDL no Power BI com um prompt de Atualização em Nível de Compatibilidade. A mensagem indica que o nível de compatibilidade atual de 1550 está abaixo do nível necessário de 1601 para a propriedade FormatStringDefinition e pergunta se deseja atualizar e aplicar novamente a alteração.

Renomeação de objeto com visualização TMDL

Para renomear um objeto na visualização do TMDL, é necessário scriptar o objeto pai. Por exemplo, renomear uma coluna requer o script da tabela, enquanto renomear uma tabela requer o script de todo o modelo semântico. Saiba mais sobre a hierarquia do modelo de objeto tabular no seguinte documento: hierarquia do modelo de objeto tabular.

Com a exibição TMDL, a renomeação em massa pode ser executada com eficiência usando padrões simples de localização e substituição. Por exemplo, você pode renomear todas as colunas de tabela para minúsculas seguindo estas etapas.

Abra o modo de exibição TMDL, crie um script na tabela que você pretende modificar.

Pressione CTRL+F para abrir a Caixa de Diálogo Localizar e Substituir, e verifique se a opção Expressão Regular está habilitada.

Captura de tela do modo de exibição TMDL no Power BI mostrando o recurso Localizar e Substituir em uso. A entrada Substituir está ativa com uma opção para alternar entre os modos Localizar e Substituir, realçado na barra de ferramentas acima do editor de código.

Insira os seguintes padrões nos campos de localizar e substituir e selecione Substituir Tudo.

Ação	Padrão/Substituição
Localizar	`(^\s+column\s+)(.+)`
Substituir	`$1\L$2`

Captura de tela de uma tela de configuração do modelo de dados do Power BI mostrando uma definição de tabela de produto com duas colunas: produto (cadeia de caracteres) e productkey (int64), juntamente com suas propriedades de metadados.

Execute o script TMDL para renomear todas as colunas de tabela para minúsculas instantaneamente:

Captura de tela de uma tabela do Produto do Power BI mostrando 14 colunas, incluindo marca, categoria, cor, fabricante, produto, productkey, subcategoria, custo unitário, preço unitário e atributos de peso.

Observe que o nome da coluna será diferente da propriedade sourceColumn.

Captura de tela de uma configuração de modelo de dados do Power BI mostrando a definição da coluna productKey com o tipo de dados int64, em que o sourceColumn é mapeado para ProductKey nos dados de origem.

A sincronização entre a tabela de modelo semântico e a consulta do Power Query depende de sourceColumn, mantendo os nomes independentes. Quando você abrir o editor do Power Query, ele exibirá os nomes de coluna que correspondem ao sourceColumn, em vez do nome da coluna do modelo. Além disso, renomear uma coluna na interface do usuário não adicionará automaticamente uma etapa de renomeação à consulta até que sourceColumn e nome da coluna sejam idênticos.

Captura de tela do Editor de Consultas do Power BI mostrando dados do produto com colunas para ProductKey, Código do Produto, Produto e Fabricante, com 16 consultas visíveis no painel de navegação.

Visão TMDL e projeto Power BI

Ao salvar seu trabalho como um PBIP (projeto do Power BI), você obtém acesso aos metadados de definição de modelo semântico como arquivos TMDL, fornecendo uma experiência útil de controle do código-fonte e co-desenvolvimento, permitindo também que você faça alterações ao modelo semântico fora do Power BI Desktop. No entanto, se você modificar os arquivos TMDL dentro do PBIP, será necessário reiniciar o Power BI Desktop para recarregar essas alterações. Por outro lado, a exibição TMDL segue um modelo mental de script, permitindo que você aplique com eficiência as alterações diretamente ao modelo semântico que está sendo editado no Power BI Desktop usando TMDL, independentemente de o formato de arquivo ser PBIX ou PBIP.

Você pode integrar perfeitamente ambas as experiências. Por exemplo, você pode atualizar a definição de TMDL no PBIP para alterações rápidas sem iniciar o Power BI Desktop e utilizar a exibição TMDL quando o Power BI Desktop já estiver aberto para implementar com eficiência uma série de alterações no modelo semântico usando TMDL. Ambas as abordagens oferecem uma experiência de codificação TMDL avançada e consistente.

Casos de uso comuns para exibição TMDL

Cenário: preciso reutilizar ou compartilhar uma tabela de modelo semântico com sua definição completa, incluindo colunas, expressão Power Query, configuração de ordenação e outros em outro modelo semântico.

Solução: Abrir o modelo semântico com a tabela e criar um script usando o modo de exibição TMDL. Copie o script para a outra janela do Power BI Desktop, abra a guia exibição TMDL e aplique o script.

Cenário: nomeei todas as minhas tabelas com os prefixos "dim_" ou "fact_". Gostaria de remover esses prefixos sem atualizar manualmente cada uma das mais de 100 tabelas.

Solução: Abrir a visualização TMDL, scriptar o modelo semântico, buscar o prefixo (expressões regulares são suportadas) e substituí-lo por um texto vazio.

Cenário: preciso criar uma perspectiva no meu modelo semântico para usar o recurso de visuais personalizados. No entanto, não consigo criá-lo ou editá-lo usando a interface gráfica do Power BI Desktop.

Solução: Abra a visualização do TMDL, crie uma nova guia vazia (ou use o script de uma perspectiva existente) e, em seguida, crie ou edite a perspectiva usando TMDL. Esse método também se aplica a outros metadados de modelo semântico que não têm uma interface gráfica, como traduções, expressões de linha de detalhes e outras.

createOrReplace
      perspective SalesView
        perspectiveTable Sales
            perspectiveMeasure 'Sales Amount'
            perspectiveMeasure 'Sales Qty'
            perspectiveColumn Quantity
            perspectiveColumn 'Amount'

Cenário: preciso modificar a expressão Power Query da minha tabela sem provocar uma atualização.

Solução: Criptografar a tabela, modificar a expressão Power Query e aplicar as alterações. A exibição TMDL não requer atualizar seus dados.

Cenário: preciso alternar o modo de armazenamento da minha tabela do DirectQuery para Importação, e vice-versa

Solução: Faça o script da tabela, atualize o modo de partição e aplique as alterações.

Cenário: preciso fazer backup da minha definição de modelo semântico antes de fazer alterações significativas e reverter facilmente para uma definição anterior, se necessário.

Solução: Crie o script do modelo semântico ou das partes específicas das quais você deseja fazer backup, realize suas alterações em outras visualizações e, se necessário, retorne à visualização TMDL para restaurar os metadados anteriores executando o script salvo.

Considerações e limitações

O modo de exibição TMDL está atualmente em versão prévia, portanto, tenha em mente as seguintes limitações:

Você pode usar a exibição TMDL para editar qualquer objeto ou propriedade dentro de um modelo semântico. No entanto, modificações incompletas ou incorretas podem levar a um comportamento inesperado. Para obter mais diretrizes sobre essas operações, consulte o artigo criação de modelo.
A paleta de comandos exibe alguns comandos que não têm suporte no momento.
A configuração inicial da integração do Git do workspace não incluirá scripts de exibição TMDL salvos no modelo semântico publicado. Saiba mais no artigo de integração do Fabric com o Git.
Você não pode criar scripts de grupos do gerenciador de modelos, como Medidas, Colunas, assim por diante.

Os artigos a seguir descrevem mais sobre o TMDL e seus usos.