Novo LookML: como converter um projeto do LookML YAML

O Looker 4.0 introduziu uma nova sintaxe do LookML que melhorou o LookML original no estilo YAML com uma sintaxe familiar, mas mais fácil, e um IDE rico e útil para facilitar o desenvolvimento do LookML. A partir do Looker 4.4, todos os novos projetos do LookML tiveram de ser criados no novo LookML. No entanto, alguns projetos criados antes da conversão podem continuar a ser modelados no LookML YAML (antigo).

O Looker oferece uma forma automática de converter um projeto do LookML YAML para o novo LookML. Esta página explica como realizar esse processo. Cada projeto do LookML tem de ser convertido individualmente, e os programadores têm de preparar e coordenar os esforços. Por isso, certifique-se de que lê toda esta página antes de converter um projeto.

Prepare-se para converter

A tarefa de converter um projeto LookML YAML para o novo LookML tem de ser realizada por apenas um programador do LookML. A conversão ocorre no modo de desenvolvimento desse programador e, em seguida, as alterações são confirmadas e implementadas como qualquer alteração normal do LookML.

Dito isto, o processo requer a cooperação de todos os programadores do LookML. Uma vez que a conversão altera essencialmente todas as linhas do LookML, é importante certificar-se de que outros programadores do LookML confirmaram e implementaram todas as respetivas alterações no projeto antes de o processo de conversão começar. Caso contrário, podem ocorrer conflitos de união do Git muito desagradáveis.

Embora o processo de conversão seja automático, o novo LookML é muito mais completo na verificação de erros do que o LookML YAML. Isto significa que, após a conversão, podem ser apresentados erros que não eram apresentados anteriormente. A resolução destes erros melhora a qualidade do projeto. O número de erros varia necessariamente de projeto para projeto, o que significa que a respetiva correção pode demorar de alguns minutos a algumas horas. De qualquer forma, o desenvolvimento no projeto tem de permanecer pausado por todos os programadores de LookML até que os erros sejam corrigidos.

Encontre projetos YAML na sua instância do Looker

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

1. No menu Desenvolver, selecione a opção Gerir projetos LookML ou Projetos (a opção é ligeiramente diferente consoante o local onde acede ao menu Desenvolver).
2. Na página Projetos do LookML, procure a etiqueta YAML do LookML na linha da tabela de um projeto:

   

   DICA: pode selecionar o nome do projeto na tabela para navegar para o LookML do projeto.

Coordene-se com os programadores antes da conversão

Para se preparar para a conversão para o novo LookML:

1. Escolha um programador do LookML para executar o processo de conversão.
2. Certifique-se de que o projeto não tem erros executando o validador de LookML. Corrija todos os erros e, em seguida, confirme e implemente as alterações antes de continuar para o passo seguinte.
3. Designar uma hora para realizar a conversão.
4. Comunique a todos os outros programadores do LookML que têm de ter todas as alterações em que estão a trabalhar confirmadas e implementadas até à hora designada. Isto significa que todas as cópias do projeto no modo de desenvolvimento devem estar no estado do Git Atualizado com a produção.
5. Comunique a todos os outros programadores do LookML que não devem fazer, confirmar nem implementar alterações até a conversão estar concluída.

Converter para o novo LookML

Para converter para o novo LookML, execute o conversor:

1. Aceda ao modo de programação.
2. Abra o projeto que vai ser convertido.
3. Certifique-se de que o estado do Git no canto superior esquerdo mostra Atualizado com a produção.
4. Execute a Validação de LookML para garantir que não existem erros no projeto — o resultado deve ser Nenhum problema de LookML. (Para executar o validador de LookML, selecione o botão Validar LookML na parte superior direita do IDE do Looker ou selecione o ícone Estado do projeto na parte superior do IDE para abrir o painel Estado do projeto e, em seguida, selecione Validar LookML.)
5. Para converter o projeto do YAML LookML para o novo LookML:

   

   1. Selecione o ícone Ações do Git na barra lateral de navegação do IDE do Looker.
      • Em alternativa, selecione o ícone Estado do projeto na parte superior do IDE:

        

   2. Selecione a opção Converter projeto em novo LookML no painel Ações do Git ou na parte inferior do painel Estado do projeto.
   3. Selecione o botão Converter para novo LookML na caixa de diálogo de confirmação.

Valide o novo LookML

Quando o conversor terminar a execução, o IDE indica que os seus ficheiros foram alterados com um ponto junto a cada nome de ficheiro:

Para validar o novo LookML:

1. Selecione o botão Validar LookML para executar a Validação de LookML. Se não existirem erros, pode avançar para a secção Confirme e implemente o novo LookML desta página.
2. Pode ver erros onde antes não tinha nenhum. Conforme mencionado anteriormente, o novo LookML é mais rigoroso na verificação de erros do que o LookML YAML. Reveja e corrija os erros. Se tiver dificuldades em resolvê-los, consulte a secção Resolução de erros no final desta página.

Confirme e implemente o novo LookML

Neste ponto, confirme e implemente como faria com qualquer alteração normal do LookML. Tenha em atenção que esta confirmação vai acionar uma reconstrução das suas tabelas derivadas persistentes (PDTs). Assim que a confirmação for implementada, informe todos os outros programadores de LookML de que a conversão foi concluída e que as consultas que dependem de PDTs podem demorar um pouco mais do que o habitual a serem executadas, pelo menos até que tudo seja reconstruído. Os programadores podem extrair da produção no modo de desenvolvimento para incorporar as alterações e, em seguida, continuar a desenvolver, agora com uma sintaxe LookML melhorada e mais intuitiva e um IDE muito mais útil e poderoso.

Resolver erros

Como resultado da validação de modelo mais exaustiva do novo LookML, pode ver erros que não foram apresentados anteriormente após a conversão. Além disso, a nova verificação de erros ad  hoc do LookML requer um pouco mais de informações em alguns casos. O conversor tenta determinar isto por si, mas, em alguns casos, pode ter de adicionar uma linha include adicional num ou dois ficheiros de visualização.

Referências de campos inválidas

Em alguns contextos, o LookML YAML (antigo) não garante que os campos ou os conjuntos aos quais faz referência estejam realmente definidos em algum lugar no modelo. O local mais provável onde isto vai aparecer é em listas e conjuntos de campos de detalhe.

Por exemplo, se o seu LookML antigo incluísse drill_fields: [id, name, email], mas, em algum momento do desenvolvimento do seu modelo, removeu o campo name a favor dos campos first_name e last_name, o YAML LookML não lhe teria avisado de que estava a fazer referência a um campo (name) nesta lista de campos de detalhe que não existe. Isto também pode ocorrer se estiver a fazer referência a um campo num grupo de dimensões e o seu LookML YAML não tiver especificado o campo da mesma forma que o novo LookML.

Por outro lado, o novo LookML apresenta estes tipos de erros. Assim, depois de converter o projeto e executar o validador do LookML, pode ver erros sobre referências de campos inválidas que nunca viu antes. A correção destes erros melhora a qualidade geral do modelo.

Inclusões em falta nos ficheiros de visualização

Em alguns casos, a verificação de erros ad hoc do novo LookML requer um pouco mais de contexto do que era necessário no YAML LookML. Em concreto, pode ser necessário colocar uma linha include em alguns ficheiros de visualização, mais frequentemente quando uma visualização se estende a outra.

Quando não existe ambiguidade sobre o ficheiro que tem de ser incluído numa vista, o conversor adiciona automaticamente a declaração include adequada no novo ficheiro de vista LookML e não são apresentados erros.

No entanto, em alguns casos (como projetos que contêm vários modelos), pode haver duas ou mais vistas com o mesmo nome declaradas em ficheiros de vistas separados. O conversor não consegue determinar qual é o correto para incluir, pelo que adiciona um comentário na parte superior do novo ficheiro LookML para indicar que apenas uma dessas vistas deve ser incluída. Resolva o erro resultante acedendo ao ficheiro de visualização e retirando o comentário da sugestão correta.

Explorações extension_requiredisoladas

Tal como o problema de referências de campos inválidas descrito anteriormente, no novo LookML, o validador de LookML alerta para as explorações declaradas com extension: required mas que não estão a ser efetivamente expandidas. Para resolver este erro, volte a associar estes Explores aos respetivos objetos expandidos ou, se não forem usados, remova-os.

Controlo de versões

Uma vez que o processo de conversão do LookML substitui os ficheiros de .lookml visualização e modelo por versões .lkml, se um ou mais programadores confirmarem o seu projeto durante a conversão, vai acabar por se deparar com um conflito de união. Por este motivo, é extremamente importante que apenas um programador execute o conversor e que este coordene para garantir que as cópias do modo de desenvolvimento de todos estão limpas e atualizadas antes de iniciar o processo de conversão.

Para evitar problemas de controlo de versões, tem de haver um congelamento do código durante a conversão. Outros programadores não devem confirmar alterações durante o período bloqueado para conversão.

Se o programador que executa a conversão encontrar problemas durante o processo de conversão, mas antes de confirmar as alterações e enviá-las para produção, pode ser útil reverter para produção. Esta opção do menu pendente (ilustrada na secção Executar o conversor desta página) anula a conversão, o que permite ao programador reiniciar o processo.