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:

  1. Prepare as funções e pacotes no Snowflake.

  2. Prepare sua planilha para desenvolvimento.

  3. Escreva o código Snowpark em sua planilha Python.

  4. 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 implementar esse código como 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 de terceiros listados no canal Snowflake 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 Preparação de arquivos usando o Snowsight.

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. Para registrar mensagens de nível inferior na saída, use uma biblioteca de registro, como o módulo logging, para definir o nível das mensagens registradas.

  • 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.

  • As planilhas Python usam Python 3.11 por padrão, mas você pode escolher outra versão compatível em Packages.

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:

Revisão e aceitação dos Termos de Serviço do Anaconda

Antes de começar a usar os pacotes fornecidos pelo Anaconda dentro do Snowflake, você deve reconhecer os Termos de ofertas externas.

Nota

Você deve ser o administrador da organização (use a função ORGADMIN) para aceitar os termos. Você só precisa aceitar os termos uma única vez para sua conta Snowflake. Consulte Ativação da função ORGADMIN em uma conta.

  1. Entre em Snowsight.

  2. Selecione Admin » Billing & Terms.

  3. Na seção Anaconda, selecione Enable.

  4. Na caixa de diálogo Anaconda Packages, clique no link para rever a página Termos de ofertas externas.

  5. Se você concordar com os termos, selecione Acknowledge & Continue.

Se você vir um erro ao tentar aceitar os termos de serviço, seu perfil de usuário pode estar sem um nome, sobrenome ou endereço de e-mail. Se você tiver uma função de administrador, consulte Adição dos detalhes do usuário ao seu perfil de usuário para atualizar seu perfil usando Snowsight. Caso contrário, entre em contato com um administrador para atualizar sua conta.

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

Snowflake inclui os pacotes Snowpark do canal Snowflake Anaconda em planilhas Python.

Se quiser usar arquivos ou pacotes Python que não estejam incluídos no Anaconda em sua planilha Python, você deverá carregar os arquivos em um estágio nomeado no Snowflake e, em seguida, adicioná-los à lista de pacotes instalados para sua planilha Python.

Para usar um pacote Python em sua planilha, faça o seguinte:

  1. Entre em Snowsight.

  2. Abra Projects » Worksheets.

  3. Selecione + » Python Worksheet.

  4. Selecione um banco de dados e um esquema.

  5. Selecione Packages » Stage Packages.

  6. 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/example_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/other_package.py.

  7. Selecione Import para adicionar seu pacote à lista de pacotes instalados.

  8. Em seu código, use as instruções import para usar o pacote em sua planilha Python. Por exemplo, depois de importar pacotes dos arquivos example_package.py e other_package.py, escreva o código a seguir para importar uma função chamada function de example_package e importe o pacote other_package para usar em seu código:

    from example_package import function
    import other_package
    
    Copy

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, use este procedimento 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:

  1. Entre em Snowsight.

  2. Abra Projects » Worksheets.

  3. Selecione + » Python Worksheet.

  4. Selecione um banco de dados e um esquema.

  5. 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.

  6. (Opcional) Selecione Packages para instalar bibliotecas Python.

    • O pacote snowflake-snowpark-python é obrigatório e sempre instalado para planilhas Python.

    • Pesquise pacotes listados no canal Snowflake Anaconda, como numpy, pandas, requests e urllib3. Selecione um pacote para instalá-lo para uso em sua planilha e, opcionalmente, altere a versão padrão do pacote na lista de Installed Packages.

    • 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. Consulte Como adicionar um arquivo Python de um estágio a uma planilha.

    Os pacotes instalados por você aparecem em Installed Packages.

  7. Se você instalou bibliotecas Python para sua planilha, adicione instruções import ao seu código para usar as bibliotecas instaladas.

    Por exemplo, se você instalar o pacote scikit-learn para sua planilha Python, adicione uma instrução import para esse pacote no início do seu código

    import scikit-learn
    
    Copy
  8. 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. O manipulador ativo é destacado na 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 Guia do desenvolvedor de Snowpark para Python.

Conforme você digita, você vê o preenchimento automático dos métodos Python, variáveis definidas 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 configurar 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:

  1. Entre em Snowsight.

  2. Abra Projects » Worksheets.

  3. Abra a planilha Python para a qual você deseja exibir os resultados como uma tabela.

  4. 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.

  5. Selecione Settings e para o Return type, selecione o tipo retornado pela função do manipulador.

  6. Execute sua planilha Python.

  7. Reveja os resultados no painel Results.

Como passar argumentos adicionais para a função do manipulador

Com uma planilha Python, você pode testar uma função Python que usa um único argumento (um objeto Snowpark Session) designando essa função como o manipulador da planilha. Cada função definida em uma planilha Python precisa passar o argumento session: snowpark.Session.

Para testar uma função que passa argumentos adicionais, faça o seguinte:

  1. Adicione os argumentos à sua função.

  2. Defina uma função separada de argumento único que passe em um Snowpark Session. Nesta função, chame a função com vários argumentos, passando valores para os argumentos adicionais e, em seguida, retorne o valor da função.

    Por exemplo, para escrever o código Snowpark Python que filtra uma tabela de pacotes pela coluna de linguagem do pacote, você pode escrever o seguinte código:

    import snowflake.snowpark as snowpark
    from snowflake.snowpark.functions import col
    
    # Add parameters with optional type hints to the main handler function
    def main(session: snowpark.Session, language: str):
      # Your code goes here, inside the "main" handler.
      table_name = 'information_schema.packages'
      dataFrame = session.table(table_name).filter(col("language") == language)
    
      # Print a sample of the dataFrame to standard output
      dataFrame.show()
    
      # The return value appears in the Results tab
      return dataFrame
    
    # Add a second function to supply a value for the language parameter to validate that your main handler function runs.
    def test_language(session: snowpark.Session):
      return main(session, 'java')
    
    Copy

    Neste exemplo, a função main é a função de vários argumentos e a função test_language é a função de argumento único usada para validar se seu código é executado com os valores de argumento passados.

  3. Defina a função de argumento único como a função do manipulador para executar a planilha e validar se seu código é executado com os valores dos argumentos.

    Neste exemplo, altere o manipulador para a função test_language e selecione Run. Você pode alterar o manipulador na planilha Settings ou selecionar a lâmpada de Show actions ao lado da função do manipulador e selecionar Set function «test_language» as handler.

Ao implantar sua planilha Python como um procedimento armazenado, você pode escolher a função principal do manipulador e revisar os argumentos e os tipos mapeados para seu procedimento armazenado.

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.

Nota

Se você usa um pacote listado no canal Snowflake Anaconda e ainda não aceitou os termos do Anaconda, poderá ver um erro sobre pacotes ausentes. Consulte Como usar pacotes de terceiros do Anaconda.

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 Revisão do histórico de consultas usando o Snowsight.

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

  1. Revise os Results da planilha.

  2. No Query Details da planilha, selecione Mais opções » Copy Query ID

  3. Selecione Projects » Worksheets para retornar à lista de planilhas.

  4. Selecione Monitoring » Query History.

  5. 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.

  6. Revise as consultas feitas da planilha.

Código de exemplo para planilhas Python

Ao escrever planilhas Python, você pode executar tarefas de transformação e manipulação de dados, incluindo a leitura de dados de um estágio nomeado.

Você pode revisar exemplos adicionais em Como trabalhar com DataFrames no Snowpark Python.

Exemplo: escrever um programa Snowpark simples

Neste exemplo, escreva um programa Snowpark Python que gere um pequeno intervalo de números e grave o intervalo em uma tabela que seu código cria ou substitui, se já existir, no Snowflake. Para executar este exemplo de código, você deve ter o privilégio CREATE TABLE no esquema do banco de dados ao qual deseja adicionar a tabela.

  1. Entre em Snowsight.

  2. Abra Projects » Worksheets.

  3. Selecione + » Python Worksheet.

  4. Selecione um banco de dados e um esquema ao qual deseja adicionar a tabela.

  5. 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.

  6. Escreva o código Snowpark Python como parte da função main:

    import snowflake.snowpark as snowpark
    
    def main(session: snowpark.Session):
      tableName = "range_table"
      df_range = session.range(1, 10, 2).to_df('a')
      df_range.write.mode("overwrite").save_as_table(tableName)
      return tableName + " table successfully created"
    
    Copy
  7. Selecione Settings e para o Return type, selecione String para o tipo retornado pela função do manipulador.

  8. Execute o código.

Exemplo: transformar dados em uma planilha Python

Neste exemplo, escreva o código Python que agrega as entradas na exibição TASK_HISTORY no esquema ACCOUNT_USAGE do banco de dados SNOWFLAKE por horário e estado agendados e salva a saída agregada em uma tabela, aggregate_task_history.

Nota

Como este exemplo consulta dados de Account Usage, você deve usar uma função com:

  1. Entre em Snowsight.

  2. Abra Projects » Worksheets.

  3. Selecione + » Python Worksheet.

  4. Selecione um banco de dados e um esquema ao qual deseja adicionar a tabela.

  5. 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.

  6. Escreva o código Snowpark Python como parte da função main:

    import snowflake.snowpark as snowpark
    from snowflake.snowpark.functions import col
    from snowflake.snowpark.dataframe_reader import *
    from snowflake.snowpark.functions import *
    
    def main(session: snowpark.Session):
    
      inputTableName = "snowflake.account_usage.task_history"
      outputTableName = "aggregate_task_history"
    
      df = session.table(inputTableName)
      df.filter(col("STATE") != "SKIPPED")\
        .group_by(("SCHEDULED_TIME"), "STATE").count()\
        .write.mode("overwrite").save_as_table(outputTableName)
      return outputTableName + " table successfully written"
    
    Copy
  7. Selecione Settings e para o Return type, selecione String para o tipo retornado pela função do manipulador.

  8. Execute o código.

Depois de executar seu código em uma planilha Python, você poderá abrir uma planilha SQL e consultar a tabela. Consulte Consulta de dados usando planilhas.

Exemplo: ler arquivos de um estágio com planilhas Python

Snowpark Python permite ler arquivos de um estágio e gravar o conteúdo em uma tabela ou salvá-los como uma exibição no Snowflake. Neste exemplo, o código Python lê o conteúdo de um arquivo compactado no formato CSV contendo dados de funcionários, data_0_0_0.csv.gz do estágio nomeado db1.public.files e grava o conteúdo em uma tabela chamada employees.

Nota

Para executar este exemplo de código, você deve usar uma função que tenha:

  • O privilégio USAGE no estágio, banco de dados e esquema usado no código.

  • O privilégio CREATE TABLE no esquema do banco de dados ao qual você deseja adicionar a tabela.

  1. Entre em Snowsight.

  2. Abra Projects » Worksheets.

  3. Selecione + » Python Worksheet.

  4. Selecione um banco de dados e um esquema ao qual deseja adicionar a tabela.

  5. 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.

  6. Escreva o código Snowpark Python como parte da função main:

    import snowflake.snowpark as snowpark
    from snowflake.snowpark.types import *
    
    schema_for_file = StructType([
      StructField("name", StringType()),
      StructField("role", StringType())
    ])
    
    fileLocation = "@DB1.PUBLIC.FILES/data_0_0_0.csv.gz"
    outputTableName = "employees"
    
    def main(session: snowpark.Session):
      df_reader = session.read.schema(schema_for_file)
      df = df_reader.csv(fileLocation)
      df.write.mode("overwrite").save_as_table(outputTableName)
    
      return outputTableName + " table successfully written from stage"
    
    Copy
  7. Selecione Settings e para o Return type, selecione String para o tipo retornado pela função do manipulador.

  8. Execute o código.

Depois de executar seu código em uma planilha Python, você poderá abrir uma planilha SQL e consultar a tabela. Consulte Consulta de dados usando planilhas.

Para obter mais detalhes sobre como trabalhar com arquivos em um estágio usando o Snowpark, consulte Como trabalhar com DataFrames no Snowpark Python.