Como escrever o código Snowpark nas planilhas Python¶

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.

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

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

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.

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.

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

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.

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.

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.