Como escrever o código Snowpark nas planilhas Python¶

Escreva o código Snowpark em planilhas Python para processar dados usando o Snowpark Python em Snowsight. Ao escrever código em planilhas Python, você pode fazer seu desenvolvimento e testes em Snowflake sem a necessidade de instalar bibliotecas dependentes.

Para desenvolver com planilhas Python, faça o seguinte:

Prepare as funções e pacotes no Snowflake.
Prepare sua planilha para desenvolvimento.
Escreva o código Snowpark em sua planilha Python.
Execute sua planilha Python.

Por exemplo, você pode escrever o código em uma planilha Python que extrai dados de estágios ou objetos de banco de dados no Snowflake, transforma os dados e armazena os dados transformados no Snowflake. Você poderia então converter esse código em um procedimento armazenado e criar um pipeline de dados, tudo sem sair do Snowflake.

Neste tópico:

Sobre as planilhas Python¶

As planilhas Python permitem utilizar o Snowpark Python em Snowsight para realizar manipulações e transformações de dados. Você pode usar pacotes disponíveis no Anaconda ou importar seus próprios arquivos Python de estágios para usar em scripts.

Após executar uma planilha Python, revise os resultados e a saída retornada por seu script. Os resultados são exibidos como uma cadeia de cadeia de caracteres, variante ou tabela, dependendo de seu código. Consulte Execução das planilhas Python.

Nota

Como as planilhas Python rodam dentro do Snowflake e não em seu ambiente de desenvolvimento local, você não pode usar session.add_import para adicionar um arquivo do qual seu código Python depende, ou session.add_packages ou session.add_requirements para adicionar pacotes que você precisa usar em seu código Python. Em vez disso, você adiciona esses arquivos a um estágio e os referencia em seu código. Consulte Como adicionar um arquivo Python de um estágio a uma planilha.

As planilhas Python têm as seguintes limitações:

Níveis de log inferiores a WARN não aparecem em Output para uma planilha Python por padrão. Em vez disso, use uma biblioteca de registro como o módulo logging para definir o nível das mensagens registradas. Todas as mensagens que você registra aparecem na saída.
Não há suporte para pontos de parada ou apenas partes do código Python em uma planilha.
Sem suporte para imagens ou páginas da web. Imagens ou páginas da web geradas pelo código Python não podem ser exibidas em planilhas Python.
Snowpark Python usa Python 3.8.

Se você precisar de suporte para qualquer uma dessas opções, considere antes usar seu ambiente de desenvolvimento local. Consulte Configuração do seu ambiente de desenvolvimento para o Snowpark Python.

Pré-requisitos para as planilhas Python¶

Para utilizar planilhas Python, você deve fazer o seguinte:

Revisar e aceitar os Termos de Serviço do Anaconda em Snowsight. Consulte Introdução.
(Opcional) Adicionar arquivos e pacotes Python que não estão incluídos no Anaconda que você deseja utilizar em uma planilha Python a um estágio nomeado. Consulte Como adicionar um arquivo Python de um estágio a uma planilha.
Escolher um warehouse para usar nas planilhas Python. A Snowflake recomenda o uso de um warehouse X-Small para o desenvolvimento. Se você estiver executando uma carga de trabalho muito grande no Snowpark, use um warehouse otimizado para Snowpark. Consulte Tamanho do warehouse para obter detalhes adicionais sobre os tamanhos dos warehouses.

Como adicionar um arquivo Python de um estágio a uma planilha¶

Snowflake inclui os pacotes Anaconda do canal Snowflake conda em planilhas Python. Se você quiser usar outros arquivos ou pacotes Python além daqueles incluídos no Anaconda em sua planilha Python, você deve carregar os arquivos em um estágio nomeado no Snowflake e depois adicioná-los à lista de pacotes para sua planilha Python.

Para usar um pacote Python em sua planilha que não esteja incluído por padrão, faça o seguinte:

Entre em Snowsight.
Abra Worksheets.
Selecione + » Python Worksheet.
Selecione um banco de dados e um esquema.
Selecione Packages » Stage Packages.
Digite o caminho para o pacote no estágio.
- Se o banco de dados e o esquema selecionados para a planilha contiverem o estágio onde o pacote está localizado, você pode referenciar o estágio usando um nome não qualificado. Por exemplo, @YourStage/path/to/package.py.
- Para fazer referência a um estágio em um banco de dados e esquema diferentes, qualifique totalmente o nome do estágio. Por exemplo, @Database.Schema.Stage/path/to/package.py.
Selecione Import para adicionar seu pacote à lista de pacotes instalados. Você pode então usar as instruções import para usar o pacote em sua planilha Python.

Nota

Os pacotes que você adiciona a uma planilha estão disponíveis apenas para essa planilha. Se você quiser usar o mesmo pacote em uma planilha Python diferente, siga estes passos para adicionar o pacote a essa planilha.

Para obter mais detalhes, consulte Disponibilização das dependências para seus códigos.

Como começar a desenvolver com planilhas Python¶

Para abrir uma planilha e configurar seu ambiente de desenvolvimento, faça o seguinte:

Entre em Snowsight.
Abra Worksheets.
Selecione + » Python Worksheet.
Selecione um banco de dados e um esquema.
Selecione um warehouse a ser utilizado para executar a planilha. Se você tiver um warehouse padrão para seu usuário, ele será pré-selecionado.

As planilhas Python exigem um warehouse em funcionamento para carregar os pacotes Python e executar o código Python.
(Opcional) Selecione Packages para adicionar bibliotecas Python.
- Os pacotes incluídos com Anaconda, tais como numpy, pandas, requests e urllib3, já estão instalados.
- Procure outros pacotes que você deseja instalar e usar em sua planilha, como o scikit-learn. Selecione o pacote nos resultados da busca e opcionalmente modifique a versão do pacote selecionado por padrão. Os pacotes instalados por você aparecem no topo da lista de pacotes.
- Adicione seus próprios pacotes e arquivos Python selecionando Stage Packages e especificando o caminho do arquivo do estágio e do pacote e, em seguida, selecionando Import.
Se você adicionar bibliotecas Python à sua planilha, atualize seu código para usar as instruções import para importar as bibliotecas para sua planilha.
Execute a amostra do código Python para validar sua configuração.

As mensagens de erro ou o valor de retorno de seu código aparecem na seção Results. Para visualizar as mensagens de registro, selecione Output. Consulte Execução das planilhas Python.

Como escrever o código Snowpark nas planilhas Python¶

Depois de seguir os passos para iniciar o desenvolvimento com planilhas Python, você pode substituir o código de amostra pelo seu próprio.

Escreva seu código Snowpark Python dentro da função de manipulador:

import snowflake.snowpark as snowpark

def main(session: snowpark.Session):
    # your code goes here

Copy

A função padrão do manipulador é main, mas você pode alterá-la no Settings para a planilha.

Use o objeto session fornecido no código clichê para acessar dados no Snowflake com as bibliotecas da API Snowpark. Por exemplo, você pode criar um DataFrame para uma tabela ou executar uma instrução SQL. Consulte o Guia do desenvolvedor de Snowpark para Python.

Conforme você digita, você vê o preenchimento automático dos métodos Python, variáveis definidas, objetos de banco de dados e muito mais. Você não vê o preenchimento automático para alguns pacotes ou arquivos de terceiros importados de um estágio. As planilhas Python também incluem destaque de sintaxe e orientação para os parâmetros do método. Você pode habilitar a impressão e o envoltório da linha no Settings para a planilha.

Resultados de retorno de um tipo de dados diferente¶

Ao escrever seu código Python, considere que tipo de dados é retornado pela instrução return em seu código e ajuste como a planilha retorna os resultados. Por padrão, uma planilha Python tem um tipo de retorno de Tabela() porque o código do espaço reservado retorna um DataFrame.

Dependendo do que seu código Python retorna, você pode querer alterar as configurações da planilha para exibir a saída de forma diferente:

Se sua função de manipulador retornar um DataFrame, use o tipo de retorno padrão de Table().
Se sua função do manipulador retornar uma lista de objetos Row, como com o método collect, altere o tipo de retorno para Variant.
Se sua função do manipulador retornar uma cadeia de caracteres, como return "Hello Python", ou um valor que você queira converter em uma cadeia de caracteres, altere o tipo de retorno para String.
Se sua função do manipulador retornar um número inteiro, como com o método count, use um tipo de retorno Variant ou String.

Para obter mais detalhes sobre o tipo de retorno de alguns métodos DataFrame, consulte Como executar uma ação para avaliar um DataFrame.

Para atualizar as configurações da planilha para retornar resultados de um tipo diferente, faça o seguinte:

Entre em Snowsight.
Abra Worksheets.
Abra a planilha Python para a qual você deseja exibir os resultados como uma tabela.
Selecione um warehouse a ser utilizado para executar a planilha. Se você tiver um warehouse padrão para seu usuário, ele será pré-selecionado. Certifique-se de que seu warehouse esteja funcionando.
Selecione Settings e para o Return Type, selecione o tipo retornado pela função do manipulador.
Execute sua planilha Python.
Reveja os resultados no painel Results.

Execução das planilhas Python¶

Depois de escrever sua planilha Python, selecione Run para executar sua planilha Python. A execução de sua planilha executa todo o código de sua planilha Python. A execução parcial ou incremental do código não é suportada.

Revise a saída gerada por seu código¶

Você pode rever as mensagens de saída padrão (stdout) ou de erro padrão (stderr) para seu código Python no painel Output para uma planilha Python.

Você pode ver a saída dos seguintes tipos de funções no painel Output:

Funções que escrevem para o console, tais como print().
Funções que imprimem um DataFrame, tais como o método show da classe DataFrame no Snowpark Python.

Nota

A saída aparece depois que todos os processos Python terminam a execução, em vez de aparecer em um fluxo enquanto o código é executado.

A saída de log é escrita em um estágio temporário e só é capturada se o seguinte for verdadeiro:

Você seleciona um banco de dados e um esquema para a planilha.
O banco de dados selecionado não foi criado a partir de um compartilhamento.
Você executa a planilha usando uma função que tem privilégios USAGE no banco de dados e esquema selecionados.

Como revisar o histórico de consultas de uma planilha Python¶

Quando uma planilha Python é executada em Snowsight, um procedimento armazenado anônimo executa o código e gera consultas que executam os comandos do Snowpark no código.

Você pode usar a página Query History em Snowsight para revisar as consultas que foram feitas. Consulte Histórico de consultas.

Por exemplo, após executar uma planilha, você pode revisar as consultas que foram feitas fazendo o seguinte

Revise os Results da planilha.
No Query Details da planilha, selecione » Copy Query ID
Selecione Worksheets para retornar à lista de planilhas.
Selecione Activity » Query History.
Na página Query History, exiba somente as consultas de sua planilha Python:
1. Selecione Filters e ative a opção Query ID.
2. Insira o ID da consulta de sua planilha Python.
3. Selecione Apply Filters.
Revise as consultas feitas da planilha.