Trabalhar com a vista TMDL no Power BI Desktop

O modo de exibição TMDL permite criar scripts, modificar e aplicar alterações a objetos de modelo semântico com um editor de código moderno usando TMDL (Tabular Model Definition Language) no Power BI Desktop, melhorando a eficiência do desenvolvimento e fornecendo visibilidade e controle completos sobre metadados de modelo semântico.

A visualizaçã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 visualização Modelo.

A visualização TMDL oferece as seguintes vantagens:

• Maior eficiência de desenvolvimento 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.
• Aumente a capacidade de reutilização criando facilmente scripts, compartilhando e reutilizando 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.
• Obtenha mais controle e transparência, mostrando todos os objetos e propriedades do 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.

Script para TMDL

No Power BI Desktop, selecione o ícone de vista TMDL localizado à esquerda da janela, conforme mostrado na imagem a seguir.

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

Ao usar a visualização TMDL e arrastar o objeto do painel Dados, o Power BI gera um script com todos os metadados do objeto no separador atual como TMDL. Caso o separador atual não esteja vazio, abre-se um novo separador como um script createOrReplace TMDL dos objetos selecionados, como ilustrado na imagem abaixo.

Como alternativa, pode clicar com o botão direito do rato num objeto na vista de Dados e selecionar Script TMDL para uma nova aba ou para a área de transferência, mostrada na imagem a seguir.

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ê pode 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 é incorporado no editor de código, o que melhora a legibilidade aplicando cores diferentes a partes do seu código com base no significado. Essa codificação de cores facilita a compreensão da estrutura e funcionalidade do seu código TMDL, conforme mostrado na imagem a seguir.

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

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.

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

Dicas de ferramentas

A informação contextual é exibida ao colocar o cursor sobre o objeto, fornecendo informações sobre cada objeto ou propriedade TMDL.

Ações de código

Quando o cursor está em um texto irregular ou selecionado, a visualização TMDL exibe um ícone de lâmpada indicando Ações de Código disponíveis, como gerar tags de linhagem ou corrigir erros ortográficos de nomes de propriedades.

Formatação de código

Formate o seu código TMDL premindo Shift + Alt + F ou clicando na opção Formatar no friso.

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

Diagnóstico de erros

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

Aplicar alterações ao modelo semântico

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

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

Em caso de 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.

Visualizar alterações no modelo semântico

A exibição TMDL permite visualizar alterações de script, apresentando uma prévia do modelo semântico antes e depois da execução do script, através de um diff de código TMDL. A visualização de 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 comparação TMDL do modelo semântico antes e depois de executar o script TMDL na guia aberta.

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

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

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 no banner na imagem a seguir.

Há uma barra de ferramentas no canto superior direito do ecrã de pré-visualização que permite a navegação de todas as diferenças de código, permitindo que alterne entre diff embutido ou lado a lado, visualizando ou ocultando regiões inalteradas e fechando a vista de pré-visualização.

Há algumas considerações a ter em mente ao visualizar alterações no modelo semântico:

• A visão TMDL redefine as configurações para o padrão em cada execução de pré-visualização.
• Uma pré-visualização só é executada com uma alteração TMDL válida. Scripts TMDL inválidos não executarão uma pré-visualização e um erro será exibido no Painel de Saída.

Separadores de script TMDL

Na visualização TMDL, você pode ter várias guias de script ao mesmo tempo, qualquer uma das quais pode ser renomeada ou removida.

O conteúdo das abas de vista TMDL é guardado no ficheiro de relatório quando se guarda o relatório do Power BI Desktop, permitindo continuar de onde parou na próxima vez que abrir o ficheiro de relatório do Power BI Desktop. Ao guardar num Projeto Power BI (PBIP), cada guia de script é guardada como um ficheiro .tmdl na pasta \TMDLScripts, como mostrado na imagem a seguir.

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

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

As mensagens são mantidas apenas para cada sessão do Power BI Desktop. Portanto, reiniciar o Power BI Desktop apaga todas as mensagens de saída de todas as abas de script.

Prompt de atualização de nível de compatibilidade

O nível de compatibilidade de um modelo semântico do Power BI determina os recursos que são 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 exija uma atualização de nível de compatibilidade, a visualização TMDL fornece um prompt indicando qual objeto ou objetos exigem a atualização.

Renomeação de objetos com o modo de exibição TMDL

Para renomear um objeto dentro da visualização TMDL, é necessário scriptar o seu elemento 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 de modelo de objeto tabular no seguinte documento: Hierarquia de modelo de objeto tabular.

Com a visualização TMDL, a renomeação em massa pode ser realizada de forma eficiente usando padrões simples de localização e substituição. Por exemplo, você pode renomear todas as colunas da tabela para minúsculas seguindo estas etapas.

Abra a vista TMDL, crie um script para a tabela que pretende modificar.

Pressione CTRL+F para abrir a caixa de diálogo de localizar e substituir. Certifique-se de que a opção Expressão Regular está ativada.

Insira os seguintes padrões nos campos ‘Localizar’ e ‘Substituir’ e selecione Substituir tudo.

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

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

A sincronização entre a tabela do modelo semântico e a consulta do Power Query depende de sourceColumn, mantendo os nomes independentes. Quando você abre o editor do Power Query, ele exibirá os nomes de coluna que correspondem à 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 o nome da coluna sejam idênticos.

Visualização TMDL e projeto Power BI

Ao salvar seu trabalho como um projeto do Power BI (PBIP), você obtém acesso aos metadados de definição do modelo semântico como arquivos TMDL, fornecendo uma experiência útil de controle de origem e codesenvolvimento, além de permitir que você faça alterações no modelo semântico fora do Power BI Desktop. No entanto, se você modificar os arquivos TMDL dentro do PBIP, deverá reiniciar o Power BI Desktop para recarregar essas alterações. Por outro lado, a visualização TMDL segue um modelo mental de script, permitindo que você aplique alterações diretamente ao modelo semântico em edição no Power BI Desktop usando TMDL, independentemente do formato de ficheiro ser PBIX ou PBIP.

Você pode integrar perfeitamente ambas as experiências. Por exemplo, você pode atualizar a definição TMDL no PBIP para alterações rápidas sem iniciar o Power BI Desktop e utilizar o modo de 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 rica e consistente.

Casos de uso comuns para a visualização TMDL

Cenário: Preciso de reutilizar ou partilhar uma tabela de modelo semântico com a sua definição completa, incluindo colunas, expressão do Power Query e ordenação por configuração e outras noutro modelo semântico.

Solução: Abra o modelo semântico com a tabela, crie um script usando a visualização TMDL. Copie o script para a outra janela do Power BI Desktop, abra a guia do modo de 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: Abra a vista TMDL, crie scripts para o modelo semântico, procure o prefixo (há suporte para expressões regulares) e substitua-o por um texto vazio.

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

Solução: Abra a vista TMDL, crie um novo separador vazio (ou utilize o script a partir de uma perspetiva existente) e, em seguida, crie ou edite a perspetiva utilizando TMDL. Esse método também se aplica a outros metadados de modelo semântico que não possuem uma interface gráfica, como traduções, expressões de linha de detalhes e outros.

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

Cenário: Preciso de modificar a expressão do Power Query da minha tabela sem acionar uma atualização.

Solução: Crie scripts para a tabela, modifique a expressão do Power Query e aplique as alterações. A visualização TMDL não requer a atualização de seus dados.

Cenário: Preciso alternar o modo de armazenamento da minha tabela de DirectQuery para Importar e vice-versa

Solução: Crie scripts para a tabela, atualize o modo de partição e aplique 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 scripts do modelo semântico ou de partes específicas das quais deseja fazer backup, faça as alterações em outros modos de exibição e, se necessário, retorne ao modo de exibição TMDL para restaurar os metadados anteriores executando o script salvo.

Considerações e limitações

• Você pode usar a visualizaçã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 orientações sobre essas operações, consulte o artigo Criação de modelos.
• A paleta Comandos exibe alguns comandos que não são suportados no momento.
• A configuração inicial da integração do Git do espaço de trabalho não incluirá scripts TMDL View guardados no modelo semântico publicado. Saiba mais sobre a integração do Fabric Git no artigo.

Conteúdo relacionado

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

• Introdução ao TMDL
• TMDL (Tabular Model Definition Language)
• projetos do Power BI Desktop (visualização)
• Pasta do modelo semântico do projeto do Power BI Desktop