O Looker 4.0 introduziu uma nova sintaxe do LookML que melhorou o estilo YAML original do LookML com uma sintaxe conhecida, mas mais fácil, e um IDE rico e auxiliar para facilitar o desenvolvimento do LookML. A partir do Looker 4.4, todos os novos projetos do LookML precisam 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 do LookML YAML 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 esta página até o fim antes de converter um projeto.
Como se preparar para a conversão
A tarefa de converter um projeto do LookML YAML em um novo LookML precisa ser realizada por apenas 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 exige a cooperação de todos os desenvolvedores do LookML. Como a conversão altera 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, isso pode resultar em alguns conflitos de mesclagem do Git muito desagradáveis.
Embora o processo de conversão seja automatizado, o novo LookML é muito mais completo na verificação de erros do que o LookML YAML. Isso significa que, após a conversão, podem aparecer erros que não foram mostrados anteriormente. A resolução desses erros vai melhorar a qualidade do projeto. O número de erros varia de projeto para projeto, o que significa que a correção pode levar de alguns minutos a algumas horas. De qualquer forma, o desenvolvimento do 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 conferir os projetos YAML na sua instância do Looker:
- No menu Develop, selecione a opção Manage LookML Projects ou Projects. A opção é um pouco diferente dependendo de onde você acessa o menu Develop.
-
Na página Projetos do LookML, procure o rótulo YAML LookML na linha da tabela de um projeto:
Dica: você pode selecionar o nome do projeto na tabela para navegar até o LookML dele.
Coordene com os desenvolvedores antes da conversão
Para se preparar para a conversão para o novo LookML:
- Escolha um desenvolvedor do LookML para executar o processo de conversão.
- Execute o validador do LookML para verificar se o projeto está sem erros. Corrija todos os erros e, em seguida, confirme e implante as mudanças antes de continuar para a próxima etapa.
- Defina um horário para realizar a conversão.
- Comunique a todos os outros desenvolvedores do LookML que eles precisam ter todas as mudanças em que estão trabalhando confirmadas e implantadas até o horário designado. Ou seja, todas as cópias do projeto no modo de desenvolvimento precisam estar no estado Up to Date do Git com a produção.
- Comunique a todos os outros desenvolvedores do LookML que eles não podem fazer, confirmar nem implantar nenhuma mudança até que a conversão seja concluída.
Converter em um novo LookML
Para converter em um novo LookML, execute o conversor:
- Entrar no modo de desenvolvimento.
- Abra o projeto que será convertido.
- Verifique se o status do Git no canto superior esquerdo mostra Up to Date com a produção.
- Execute o validador do LookML para garantir que não haja erros no projeto. O resultado deve ser No LookML Issues. Para executar o validador do LookML, selecione o botão Validar LookML na parte de cima à direita do ambiente de desenvolvimento integrado do Looker. Ou selecione o ícone Saúde do projeto na parte de cima do ambiente de desenvolvimento integrado para abrir o painel Saúde do projeto e, em seguida, selecione Validar LookML.
-
Para converter o projeto do LookML YAML para o novo LookML:
-
Selecione o ícone Ações do Git no painel de navegação
do ambiente de desenvolvimento integrado do Looker.
-
Como alternativa, selecione o ícone Project Health
na parte de cima do ambiente de desenvolvimento integrado:
-
Como alternativa, selecione o ícone Project Health
na parte de cima do ambiente de desenvolvimento integrado:
- Selecione a opção Convert Project to New LookML no painel Git Actions ou na parte de baixo do painel Project Health.
- Selecione o botão Converter para o novo LookML na caixa de diálogo de confirmação.
-
Selecione o ícone Ações do Git no painel de navegação
do ambiente de desenvolvimento integrado do Looker.
Validar o novo LookML
Quando o conversor terminar a execução, o ambiente de desenvolvimento integrado vai indicar que os arquivos foram alterados com um ponto ao lado de cada nome de arquivo:
Para validar o novo LookML:
- Selecione o botão Validar LookML para executar o validador. Se não houver erros, pule para a seção Confirmar e implantar o novo LookML desta página.
- Você pode encontrar erros onde não tinha nenhum antes. Como mencionado anteriormente, o novo LookML é mais completo na verificação de erros do que o LookML YAML. Corrija os erros. Se você tiver problemas para resolvê-los, consulte a seção Como resolver erros no final desta página.
Confirmar e implantar o novo LookML
Neste ponto, faça o commit e implante como faria com qualquer mudança comum do LookML. Este commit vai acionar uma recriação das tabelas derivadas persistentes (PDTs). Depois que o commit for implantado, informe a todos os outros desenvolvedores do LookML que a conversão foi feita e que as consultas que dependem de PDTs podem levar um pouco mais de tempo do que o normal para serem executadas, pelo menos até que tudo seja recriado. Os desenvolvedores podem extrair da produção no modo de desenvolvimento para fazer as mudanças e continuar o desenvolvimento, agora com uma sintaxe do LookML melhorada e mais intuitiva e um ambiente de desenvolvimento integrado muito mais útil e poderoso.
Como resolver erros
Como resultado da validação de modelo mais detalhada do LookML, você pode encontrar erros
após a conversão que não foram mostrados antes. Além disso, a verificação de erros ad hoc do novo 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) LookML não garante que os campos ou conjuntos que você referencia estão realmente definidos em algum lugar do modelo. O lugar mais provável para isso acontecer é em listas e conjuntos de campos de detalhamento.
Por exemplo, se o LookML antigo incluía 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 fazendo referência a um campo (name) na lista de campos de detalhamento que não existe. Isso também pode ocorrer se você estiver referenciando um campo em um grupo de dimensão e o LookML YAML não tiver especificado o campo da mesma forma que o novo LookML.
O novo LookML, por outro lado, vai mostrar esses tipos de erros. Portanto, depois de converter seu projeto e executar o validador do LookML, você poderá encontrar erros sobre referências de campo inválidas que nunca encontrou antes. A correção desses erros vai melhorar a qualidade geral do modelo.
Incluir arquivos de visualização ausentes
Em alguns casos, a verificação de erros ad hoc do novo LookML exige um pouco mais de contexto do que era necessário no LookML YAML. Especificamente, pode ser necessário colocar
uma
linha
include
em alguns arquivos de visualização, mais comumente quando uma visualização estende outra.
Quando não há ambiguidade sobre qual arquivo precisa ser incluído em uma visualização, o
conversor adiciona automaticamente a declaração include adequada
no novo arquivo de visualização do LookML, e você não vai encontrar erros.
No entanto, em alguns casos, como em projetos que contêm vários modelos, pode haver duas ou mais visualizações com o mesmo nome declarado em arquivos de visualização separados. O conversor não vai conseguir determinar qual é a visualização correta a ser incluída. Portanto, ele vai adicionar um comentário na parte de cima do novo arquivo LookML para indicar que apenas uma dessas visualizações deve ser incluída. Para resolver o erro resultante, acesse o arquivo de visualização e remova a sugestão correta.
extension_required "Explores" interrompidas
Assim como o problema de referências de campo inválidas descrito anteriormente, no novo LookML, o validador do LookML vai alertar você sobre análises que são declaradas com extension: required, mas que não estão sendo estendidas. Para resolver esse erro, reconecte essas análises detalhadas aos objetos estendidos ou, se não forem usadas, remova-as.
Controle de versão
Como o processo de conversão do LookML substitui sua visualização .lookml e os arquivos de modelo por versões .lkml, se um ou mais desenvolvedores fizerem um commit no projeto durante a conversão, você vai se deparar com um conflito de mesclagem.
Por esse motivo, é
extremamente importante que apenas um desenvolvedor execute o conversor,
e ele precisa 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ão, é necessário congelar o código durante a conversão. Outros desenvolvedores não devem fazer check-in de mudanças durante o período bloqueado para conversão.
Se o desenvolvedor que executa a conversão encontrar algum problema durante o processo de conversão, mas antes de confirmar as mudanças e enviar para a produção, ele pode reverter para a produção. Essa opção do menu suspenso (mostrada na seção Executar o conversor desta página) desfaz a conversão, permitindo que o desenvolvedor reinicie o processo.