Novo LookML: como converter um projeto YAML do LookML

O Looker 4.0 introduziu uma nova sintaxe do LookML que aprimorou o LookML original no estilo YAML com sintaxe conhecida, mas mais fácil, e um ambiente de desenvolvimento integrado avançado e adaptativo para facilitar o desenvolvimento do LookML. Do Looker 4.4 em diante, todos os novos projetos do LookML precisaram ser criados no novo LookML. No entanto, alguns projetos criados antes da conversão ainda podem ser modelados no LookML YAML (antigo).

O Looker oferece uma maneira automatizada de converter um projeto YAML do LookML em um novo LookML. Esta página explica como realizar esse processo. Cada projeto do LookML precisa ser convertido individualmente, e os desenvolvedores precisam preparar e coordenar os esforços. Portanto, leia toda esta página antes de converter um projeto.

Preparar para converter

A tarefa de converter um projeto YAML do LookML em um novo LookML só pode ser realizada por um desenvolvedor do LookML. A conversão ocorre no Modo de Desenvolvimento do desenvolvedor, e as mudanças são confirmadas e implantadas como qualquer mudança comum do LookML.

Dito isso, o processo requer a cooperação de todos os desenvolvedores do LookML. Como a conversão muda essencialmente todas as linhas do LookML, é importante garantir que outros desenvolvedores do LookML tenham confirmado e implantado todas as mudanças no projeto antes do início do processo de conversão. Caso contrário, pode resultar em alguns conflitos de mesclagem do Git muito desagradáveis.

O processo de conversão é automatizado, mas o novo LookML é muito mais completo sobre a verificação de erros do que o LookML do YAML. Isso significa que, após a conversão, podem ocorrer erros que não foram mostrados anteriormente. A resolução desses erros vai melhorar a qualidade do projeto. O número de erros varia necessariamente de projeto para projeto, o que significa que a correção deles pode levar de alguns minutos a algumas horas. De qualquer forma, o desenvolvimento no projeto precisa permanecer pausado por todos os desenvolvedores do LookML até que os erros sejam corrigidos.

Encontrar projetos YAML na sua instância do Looker

Para consultar os projetos YAML na sua instância do Looker:

1. No menu Desenvolver, selecione Gerenciar projetos do LookML ou a opção Projetos. A opção é um pouco diferente, dependendo de onde você acessa o menu Desenvolver.
2. Na página Projetos do LookML, procure o rótulo YAML LookML na linha da tabela de um projeto:

   

   DICA: selecione o nome do projeto na tabela para navegar até o LookML dele.

Coordene com os desenvolvedores antes de converter

Para se preparar para converter em um novo LookML:

1. Escolha um desenvolvedor do LookML para executar o processo de conversão.
2. Verifique se o projeto não contém erros executando o LookML Validator. Corrija todos os erros e confirme e implante as alterações antes de prosseguir para a próxima etapa.
3. Indique um horário para realizar a conversão.
4. Comunique a todos os outros desenvolvedores do LookML que eles precisam ter as alterações em que estão trabalhando confirmadas e implantadas no horário designado. Ou seja, todas as cópias do Modo de Desenvolvimento do projeto precisam estar no estado do Git Atualizado com a Production.
5. Comunicar a todos os outros desenvolvedores do LookML que eles não devem fazer, confirmar nem implantar nenhuma alteração até que a conversão seja concluída.

Converter em um novo LookML

Para converter em um novo LookML, execute o conversor:

1. Entrar no Modo de Desenvolvimento.
2. Abra o projeto que será convertido.
3. Verifique se o status do Git no canto superior esquerdo mostra Atualizado com Production.
4. Execute o LookML Validator para garantir que não haja erros no projeto. O resultado será No LookML issues. Para executar o LookML Validator, selecione o botão Validate LookML no canto superior direito do ambiente de desenvolvimento integrado do Looker. Ou então, selecione o ícone Project Health na parte superior do ambiente de desenvolvimento integrado para abrir o painel Project Health e, em seguida, Validate LookML.
5. Para converter o projeto do LookML YAML em um novo LookML:

   

   1. Selecione o ícone Git Actions na barra lateral de navegação do ambiente de desenvolvimento integrado do Looker.
      • Como alternativa, selecione o ícone Project Health na parte superior do ambiente de desenvolvimento integrado:

        

   2. Selecione a opção Convert Project to New LookML no painel Git Actions ou na parte inferior do painel Project Health.
   3. Selecione o botão Convert to New LookML na caixa de diálogo de confirmação.

Validar o novo LookML

Quando a execução do conversor terminar, o ambiente de desenvolvimento integrado vai indicar que seus arquivos foram alterados com um ponto ao lado de cada nome de arquivo:

Para validar o novo LookML:

1. Selecione o botão Validate LookML para executar o LookML Validator. Se não houver erros, avance para a seção Confirmar e implantar o novo LookML desta página.
2. Talvez você veja erros onde não havia nenhum. Conforme mencionado anteriormente, o novo LookML é mais completo na verificação de erros do que o LookML do YAML. Siga em frente e corrija os erros. Se você tiver dificuldades para resolvê-los, consulte a seção Como resolver erros no final desta página.

Confirmar e implantar o novo LookML

Agora, confirme e implante como faria com qualquer mudança comum do LookML. Esteja ciente de que essa confirmação acionará uma recriação das suas tabelas derivadas persistentes (TDPs). Depois que a confirmação for implantada, informe a todos os outros desenvolvedores do LookML que a conversão foi concluída e que as consultas que dependem de TDPs podem demorar um pouco mais do que o normal para serem executadas, pelo menos até que tudo seja recriado. Os desenvolvedores podem extrair o código da produção no Modo de Desenvolvimento para implementar as mudanças e continuar desenvolvendo, agora com uma sintaxe LookML aprimorada e mais intuitiva e um ambiente de desenvolvimento integrado muito mais útil e eficiente.

Como resolver erros

Como resultado da validação de modelo mais completa do novo LookML, é possível que, após a conversão, você encontre erros que não foram mostrados antes. Além disso, a verificação de erros ad hoc do LookML exige um pouco mais de informações em alguns casos. O conversor tenta descobrir isso para você, mas em alguns casos pode ser necessário adicionar uma linha include extra em um ou dois arquivos de visualização.

Referências de campo inválidas

Em alguns contextos, o YAML (antigo) do LookML não garante que os campos ou conjuntos usados sejam realmente definidos em algum lugar no modelo. O lugar mais provável que isso vai aparecer é em listas e conjuntos de campos de detalhamento.

Por exemplo, se o LookML antigo incluísse drill_fields: [id, name, email], mas em algum momento do desenvolvimento do modelo você removeu o campo name em favor dos campos first_name e last_name, o LookML do YAML não vai avisar que você estava se referindo a um campo (name) nessa lista de campos de detalhamento. Isso também pode ocorrer se você estiver referenciando um campo em um grupo de dimensões e o LookML do YAML não tiver especificado o campo da maneira como no novo LookML.

O novo LookML, por outro lado, mostra esses tipos de erros. Portanto, depois de converter o projeto e executar o validador do LookML, talvez você encontre erros sobre referências de campos inválidas que nunca foram vistas antes. A correção desses erros melhorará a qualidade geral do seu modelo.

Inclusões ausentes nos arquivos de visualização

Em alguns casos, a verificação de erros ad hoc do LookML exige um pouco mais de contexto do que o necessário no LookML do YAML. Especificamente, pode ser necessário colocar uma linha include em alguns arquivos de visualização, geralmente quando uma visualização estende outra.

Quando não houver ambiguidade sobre qual arquivo precisa ser incluído em uma visualização, o conversor vai adicionar automaticamente a declaração include adequada ao novo arquivo de visualização do LookML, e nenhum erro vai aparecer.

No entanto, em alguns casos (como com projetos que contêm vários modelos), pode haver duas ou mais visualizações com o mesmo nome declaradas em arquivos de visualização separados. O conversor não conseguirá determinar qual é a correta a ser incluída. Portanto, ele adicionará um comentário na parte de cima do novo arquivo LookML para indicar que apenas uma dessas visualizações precisa ser incluída. Resolva o erro resultante acessando o arquivo de visualização e removendo a marca de comentário da sugestão correta.

extension_required Explores com estado perdido

Assim como o problema de referências de campos inválidas descrito anteriormente, no novo LookML, o validador do LookML alertará você sobre as Análises declaradas com extension: required, mas que não estão sendo estendidas. Para resolver esse erro, reconecte essas Explores aos objetos estendidos ou, se elas não forem usadas, remova-as.

Controle de versão

Como o processo de conversão do LookML substitui os arquivos de visualização e modelo .lookml por versões .lkml, se um ou mais desenvolvedores se comprometerem com o projeto durante a conversão, você vai acabar em meio de um conflito de combinação. Por esse motivo, é extremamente importante que apenas um desenvolvedor execute o conversor. Além disso, ele precisa se coordenar para garantir que todas as cópias do Modo de Desenvolvimento estejam limpas e atualizadas antes de iniciar o processo de conversão.

Para evitar problemas de controle de versões, é preciso que haja um congelamento de código durante a conversão. Outros desenvolvedores não devem verificar as mudanças durante o período em que a conversão está bloqueada.

Se o desenvolvedor que executa a conversão tiver problemas durante o processo de conversão, mas antes de confirmar as alterações e enviá-las para a produção, pode ser útil reverter para a etapa de produção. Essa opção no menu suspenso (mostrada na seção Executar o conversor desta página) vai desfazer a conversão, permitindo que o desenvolvedor reinicie o processo.