Snowpark Migration Accelerator: laboratório de pipeline – avaliação¶
Assim como no SnowConvert, executaremos o código por meio do SMA, avaliaremos o resultado, resolveremos os problemas e o executaremos na nova plataforma. No entanto, diferentemente do SnowConvert, o SMA NÃO se conecta a nenhuma plataforma de origem, nem ao Snowflake. É um aplicativo local que pode ser executado completamente offline. Mas o poder dele está na avaliação. A maior parte do trabalho pesado de conversão foi feita criando a compatibilidade entre a API do Spark e a API do Snowpark.
Extração/Disponibilidade do código¶
Os arquivos que usaremos para o Laboratório da AdventureWorks estão aqui:
end_to_end_lab_source_code.zip
Para fins deste laboratório, assumiremos que o notebook e o arquivo de script que estamos convertendo já estão acessíveis como arquivos. Em geral, o SMA recebe arquivos como entrada e não se conecta a nenhuma plataforma de origem. Se os arquivos estiverem sendo orquestrados por uma ferramenta específica, talvez seja necessário exportá-los. Se você estiver usando notebooks como parte do Databricks ou do EMR, poderá exportá-los como arquivos .ipynb, assim como o notebook Jupyter que executaremos no SMA hoje.
Este laboratório tem apenas alguns arquivos, mas é comum em uma migração grande haver centenas ou milhares deles. Extraia o que puder e execute esses arquivos pelo SMA. A vantagem de usar uma ferramenta como esta é que ela pode indicar o que pode estar faltando.
Observe que também existe um arquivo de dados: “customer_update.csv”. Este é um exemplo do arquivo gerado localmente pelo sistema de Ponto de Venda (POS) que a Adventure Works usa atualmente. Embora esse sistema também esteja sendo atualizado, esta prova de conceito (POC) está focada em fazer o pipeline existente funcionar com o Snowpark em vez do Spark.
Vamos pegar cada um desses arquivos e colocá-los em um único diretório em nossa máquina local:
Recomenda-se criar um diretório de projeto. Você pode dar o nome que quiser, mas como sugestão para este laboratório, vamos usar spark_adw_lab. Isso significa que criaremos uma pasta com o nome spark_adw_lab e, em seguida, outra pasta nesse diretório chamada source_files (o caminho é algo como /your/accessible/directory/spark_adw_lab/source_files). Isso não é obrigatório, mas ajudará a manter tudo organizado. O SMA também analisará qualquer conjunto de subdiretórios, então você pode adicionar pipelines específicos em uma pasta e notebooks em outra.
Acesso ¶
Agora que temos nossos arquivos de origem em um diretório acessível, é hora de executar o SMA.
Se você ainda não o baixou, o SMA está disponível no site da Snowflake. Também é possível acessá-lo na página Migrations no SnowSight, na sua conta Snowflake:
Após baixar a ferramenta, instale-a! Há mais informações sobre a instalação do SMA na documentação do SMA.
Uso do Snowpark Migration Accelerator¶
Após instalar a ferramenta, abra-a! Ao iniciar o SMA, ele será muito semelhante à sua ferramenta parceira, o SnowConvert. Ambas as ferramentas são baseadas em um conceito similar, no qual você insere arquivos de código na ferramenta e ela os executa. Como lembrete, vimos que o SnowConvert pode receber o DDL e os dados diretamente da fonte e inseri-los diretamente no Snowflake. O SMA não faz isso. Ele só aceita arquivos de código como fonte e os gera em um formato compatível com o Snowflake. Isso ocorre principalmente porque a ferramenta não sabe como o usuário vai orquestrar o código Spark, mas também para torná-la mais segura.
Após iniciar a ferramenta, ela perguntará se você deseja criar um novo projeto ou abrir um já existente:
Isso levará você à tela de criação de projeto:
Nesta tela, você vai inserir os detalhes relevantes do seu projeto. Observe que todos os campos são obrigatórios. Para este projeto, você pode inserir algo semelhante a:
Nome do projeto: Spark ADW Lab
Caminho da pasta de entrada: /your/accessible/directory/spark_adw_lab/source_files
Caminho da pasta de saída (o SMA vai gerar automaticamente um diretório para a saída, mas você pode modificá-lo): /your/accessible/directory/spark_adw_lab/source_files_output
Endereço de e-mail: your.name@your_domain.com
Empresa do cliente: sua organização
Algumas observações sobre esta tela de criação de projeto:
Os campos de e-mail e empresa servem para ajudar você a acompanhar projetos que podem estar em andamento. Por exemplo, em qualquer SI grande, pode haver vários endereços de e-mail e várias organizações em nome das quais um único usuário pode executar o SMA. Essas informações são armazenadas no arquivo de projeto criado pelo SMA.
Há um campo oculto para SQL. Observe que o SMA pode analisar/escanear SQL, mas não converte nenhum SQL. Ele também só pode identificar SQL nas seguintes circunstâncias:
SQL que está em arquivos .sql
SQL que está em células SQL em um Jupyter Notebook
SQL que é passado como uma única cadeia de caracteres para uma instrução spark.sql.
Embora essa capacidade de SQL possa ser útil para determinar onde há SQL incompatível com o Snowflake, esse não é o uso principal do SMA. Mais suporte para o Spark SQL e o HiveQL estará disponível em breve.
Depois de inserir todas as informações do projeto, para este HoL, vamos pular a fase de avaliação. (O quê… não estamos criando uma avaliação?) Se você não quiser converter nenhum código, executar uma avaliação pode ser útil, pois permitirá que você obtenha o conjunto completo de relatórios gerados pelo SMA. Você poderá então navegar por esses relatórios ou compartilhá-los com outras pessoas em sua organização sem criar cópias extras do código convertido. No entanto, todos esses mesmos relatórios de avaliação também são gerados durante uma conversão. Portanto, vamos pular o modo de avaliação por enquanto e ir para a conversão.
Selecione “SAVE & SKIP ASSESSMENT” no canto inferior direito do aplicativo.
Observe que o que você está “salvando” é um arquivo de projeto local. Todas as informações que você inseriu na tela de criação do projeto serão salvas neste arquivo de texto local com a extensão “.snowma” no diretório que você acabou de especificar acima.
Isso levará você à tela de conversão. Nesta tela, você verá novamente os campos de diretório de entrada e saída, mas eles já estarão preenchidos com as informações inseridas na página de criação do projeto. O único campo novo aqui será para inserir um código de acesso. Os códigos de acesso são gratuitos, mas expiram. Portanto, mesmo que você já tenha solicitado um código de acesso para usar o Snowpark Migration Accelerator (SMA), talvez precise solicitar outro. Embora o mecanismo para gerar esses códigos de acesso seja semelhante ao do SnowConvert, os códigos de acesso para o SnowConvert não funcionarão com o SMA. Você terá que solicitar e usar um diferente.
Você pode solicitar um código de acesso selecionando “Inquire about an access code” ao lado do campo “Enter access code…”:
Ao selecionar esta opção, um menu pop-up será exibido, solicitando sua identidade para que um código de acesso possa ser gerado:
Preencha todos os campos mostrados acima e insira um endereço de e-mail válido. Na tela de criação do projeto, você inseriu um endereço de e-mail para associar ao projeto que estava criando. No entanto, nada foi enviado para esse e-mail. Isso serviu apenas para rastrear seu projeto localmente. Este formulário acionará um código de acesso a ser enviado para o e-mail que você inserir.
Após enviar o formulário, você deverá receber um e-mail com o código de acesso em breve. O e-mail virá de sma-notifications@snowflakel.com e será parecido com este:
Na imagem acima, onde está escrito <your access code here>, você verá uma série de números, letras e traços. Copie essa cadeia de caracteres e cole-a no campo de código de acesso para o SMA:
Ao colar o valor na caixa, o SMA validará o código de acesso. Uma validação bem-sucedida exibirá os detalhes do código de acesso abaixo da caixa de diálogo do código de acesso:
Para validar o código de acesso, o SMA consultará o sistema de licenciamento da API do Snowflake. Se você não estiver conectado à Internet, a ferramenta não poderá validar o código de acesso e você receberá uma mensagem de erro. Se você precisar executar a ferramenta em um ambiente completamente offline, entre em contato com sma-support@snowflake.com para receber ajuda na validação de um código de acesso.
Agora que o código de acesso foi validado, você pode dar uma olhada nas configurações de conversão:
Há uma configuração que simplificará a saída deste laboratório prático, que consiste em desativar a tentativa de conversão de dataframes do pandas para a API do Snowpark:
Essa configuração está sendo atualizada; portanto, muitos avisos adicionais serão exibidos se essa opção não for desmarcada. A maior parte do dataframe do pandas pode ser utilizada como parte da implementação modin do pandas, então uma simples alteração na chamada de importação deve ser suficiente por enquanto. Procure uma questão sobre esse problema até o fim de junho de 2025. Você pode examinar as outras configurações, mas vamos deixá-las como estão. É importante observar que existe uma biblioteca de testes com a qual o código de saída é compatível, chamada Snowpark Checkpoints. Existem configurações relacionadas a isso, mas não vamos alterá-las neste laboratório.
Selecione “CLOSE” para salvar e fechar suas configurações.
A opção “START CONVERSION” estará disponível no canto inferior direito do aplicativo. Vamos iniciar a conversão selecionando esta opção.
A próxima tela mostrará o progresso da conversão:
Assim como SnowConvert, o SMA está criando um modelo semântico de toda a base de código no diretório de entrada. Ele está construindo relações entre elementos de código, objetos SQL e outros artefatos referenciados, e criando a saída mais próxima possível de um equivalente funcional para o Snowflake. Isso significa principalmente converter referências da API do Spark para a API do Snowpark. A equipe de engenharia do SMA faz parte da equipe de engenharia do Snowpark. Portanto, a maioria das transformações que ocorrem já foi incorporada à API do Snowpark, então as mudanças podem parecer pequenas. Mas a variedade de informações de avaliação geradas pelo SMA permite que um projeto de migração realmente avance. Uma análise detalhada de todas as informações de avaliação geradas terá que ser feita em outro lugar, porque o SMA provavelmente já concluiu essa conversão no tempo que você levou para ler este parágrafo.
Quando o SMA terminar, a opção “VIEW RESULTS” estará disponível no canto inferior direito:
A página de resultados mostrará os… resultados.
A página de resultados contém algumas “Pontuações de preparação”, que são métricas muito simplificadas sobre o grau de “preparação” deste código-fonte para o Snowflake. Analisaremos os resultados a seguir, mas observe que executar o Snowpark Migration Accelerator é a parte fácil. Observe que este é apenas um “acelerador”. Não é uma solução mágica nem uma ferramenta de automação sem intervenção manual. Os pipelines que se conectam a uma fonte de dados e enviam saída para outra, e que não são totalmente migrados por esta ferramenta, sempre precisarão de mais atenção do que uma migração direta de SQL para SQL do DDL, como é feita pelo SnowConvert. Mas a Snowflake trabalha continuamente para tornar isso o mais simples possível.
Interpretação da saída¶
O SMA, ainda mais do que o SnowConvert, gera uma grande quantidade de informações de avaliação. Pode ser difícil analisar os resultados. Existem muitas direções diferentes que você pode seguir, dependendo do que deseja alcançar.
Observe que este é um cenário extremamente simples, então algumas das etapas que vamos realizar parecerão exageradas. (Quero dizer, precisamos mesmo analisar as dependências presentes neste projeto quando há apenas dois arquivos e poderíamos simplesmente… dar uma olhada?) O objetivo é ainda seguir o que normalmente recomendamos, mesmo neste pequeno POC. Mas sejamos claros… que o escopo é claro e que há apenas dois arquivos. Só precisamos que ambas funcionem como na fonte.
Pontuações de preparação¶
Com isso em mente, vamos dar uma olhada na primeira parte da saída que você verá no aplicativo: as pontuações de preparação. Haverá várias pontuações de preparação, e você pode expandir cada uma para entender melhor o que é capturado por elas.
Cada pontuação de preparação é um cálculo muito básico da contagem de funções ou elementos em uma API que são compatíveis com o Snowpark/Snowflake dividida pela contagem de todas as funções ou elementos relacionados a essa API para esta execução. O cálculo que mostra como a pontuação é calculada é exibido quando você expande a janela. Você também pode aprender mais sobre como interpretar as pontuações de preparação selecionando “How to read through the scores” no canto superior esquerdo desta janela.
Esta execução tem uma pontuação de preparação da API do Spark de 97,92%. Observe que a sua pode ser diferente! Essas ferramentas são atualizadas quinzenalmente e pode haver alterações, pois a compatibilidade entre as duas plataformas está em constante evolução. Isso significa que 97,92% das referências à API do Spark identificadas pela ferramenta são compatíveis com o Snowflake. “Compatível”, neste caso, significa que pode haver uma função semelhante já existente ou que o SMA criou uma saída funcionalmente equivalente. Quanto maior for essa pontuação, maior a probabilidade de esse código ser executado rapidamente no Snowflake.
Observe que 97,92% das referências são compatíveis diretamente com a API do Snowpark ou convertidas pelo SMA. A maioria delas provavelmente é compatível diretamente, mas você pode descobrir tudo o que foi convertido e o que foi passado revisando o relatório SparkUsageInventory.csv na pasta de relatórios de saída gerada pelo SMA. Não vamos abordar isso neste laboratório, pois veremos o que NOT é compatível no arquivo issues.csv, mas você pode usar essas informações como referência.
Existem outras pontuações de preparação, e talvez você veja mais do que as mostradas no laboratório, pois elas mudam com o tempo. Este laboratório não abordará cada uma delas, mas observe que sempre vale a pena investigar uma pontuação baixa.
Código analisado¶
Logo abaixo de cada pontuação de preparação, haverá um pequeno indicador que informa se houve algum código que não foi possível processar:
Este número representa a porcentagem de arquivos que foram totalmente analisados. Se esse número for menor que 100%, significa que há algum código que o SMA não conseguiu analisar ou processar. Este é o primeiro lugar onde você deve começar a procurar para resolver problemas. Se o número for menor que 100%, verifique onde ocorreram os erros de análise consultando o resumo do problema. Este é o primeiro lugar que você deve verificar ao analisar a saída do SMA, pois é o único onde pode fazer sentido executar a ferramenta novamente se não foi possível verificar uma grande quantidade de código.
Neste caso, apenas 50% da nossa carga de trabalho foi analisada com sucesso. Trágico. Agora, isso pode parecer motivo para pânico, mas não vamos tirar conclusões precipitadas. Temos apenas dois arquivos e ainda não sabemos quantos erros de análise temos.
Independentemente do resultado, o último lugar que visitaremos nesta página é o resumo de problemas. Role a tela para baixo no aplicativo até encontrar este resumo:
Resumo do problema¶
Os problemas são um dos elementos-chave tanto do SnowConvert quanto do SMA. Cada ferramenta tenta criar uma saída equivalente funcional com base na entrada que recebe, mas nenhuma conversão é 100% automatizada. Essas ferramentas sabem disso e marcam tudo o que não pode ser convertido ou que possa precisar de atenção extra com um problema. Esses problemas são resumidos em uma planilha, mas também são escritos como comentários diretamente no código de saída.
O resumo de problemas na UI destaca os problemas encontrados nesta execução da ferramenta. Esses problemas são muitas vezes referidos com a sigla EWI (erro, aviso e problema). De modo semelhante, mas não idêntico, ao SnowConvert, o SMA gera três tipos de problemas:
Erro de análise – este tipo de problema é considerado crítico e exigirá que você o resolva imediatamente. Devido à forma como o SMA funciona, ter um código que não é analisado pode significar informações ausentes nos relatórios e também a falta de conversão.
Erro de conversão – algo que o SMA reconhece (ou pelo menos pensa que reconhece), mas não consegue converter por um motivo ou outro. Esses erros geralmente têm códigos de problema muito específicos e devem ser tratados em seguida.
Aviso – esses códigos de erro identificam código que o SMA converteu ou que tem um equivalente no Snowpark/Snowflake, mas podem ocorrer problemas durante os testes. Pode não haver 100% de equivalência funcional.
Há mais informações sobre tipos de problemas na página de documentação do SMA, mas o resumo dos problemas para nossa execução é mostrado aqui:
Neste resumo, você pode encontrar o código, a contagem, o nível e a descrição dos problemas únicos presentes. Mesmo que haja muitos problemas presentes, quanto menos problemas únicos houver, maior a probabilidade de que eles possam ser tratados programaticamente. Para obter mais informações sobre cada código de problema único, você pode clicar no código na UI. Isso levará você à página de documentação do SMA para esse problema específico.
Parece que temos alguns erros de conversão, avisos e um erro de análise. Isso significa que houve algo que a ferramenta não conseguiu ler. Observe que, se você receber muitos códigos de erro que começam com PND, pode ser que você não tenha desmarcado essa opção nas configurações de conversão. Não se preocupe, se você vir esses erros, pode ignorá-los.
Independentemente da quantidade de problemas que você encontrar, é sempre recomendável explorar o arquivo de problemas detalhado se você está pronto para iniciar a migração. Este é um arquivo CSV armazenado localmente na máquina em que você executou o SMA. Você pode encontrar este arquivo selecionando a opção “VIEW REPORTS” no canto inferior direito do SMA:
Isso levará você ao diretório local que contém todos os relatórios… e, até o momento desta publicação, há muitos relatórios gerados pelo SMA:
Cada um desses relatórios contém informações valiosas, dependendo de como você está usando o SMA. Por enquanto, vamos analisar apenas o arquivo issues.csv, mas observe que há mais informações sobre EVERY relatório e o inventário gerado pelo SMA na documentação do SMA.
Ao abrir o arquivo issues, ele terá uma aparência semelhante a esta:
Observe o esquema deste relatório. Ele informa o código do problema, uma descrição do problema, o tipo de problema (categoria), o arquivo em que cada problema está, o número da linha do arquivo em que cada problema está e fornece um link para a página de documentação desse problema específico. Todas essas informações são úteis ao navegar pelos problemas.
Você pode analisar isso por arquivo para ver que tipo de problema você tem em cada arquivo:
Parece que temos apenas alguns problemas, e nosso erro de análise está no script Python do pipeline. É por aí que queremos começar.
Normalmente, daríamos uma olhada em outro relatório em nosso diretório Reports, o arquivo ArtifactDependencyInventory.csv. Mas esta é uma execução tão pequena que vamos dar uma olhada no que realmente está nesses arquivos de saída agora e ver se conseguimos executá-lo no Snowflake (ou com ele).