Introdução a UDFs de Python

Você pode escrever o manipulador para uma função definida pelo usuário (UDF) em Python. Os tópicos desta seção descrevem como projetar e escrever um manipulador Python. Você também encontrará exemplos.

Para uma introdução às UDFs, incluindo uma lista de linguagens na qual você pode escrever um manipulador de UDF, consulte Visão geral das funções definidas pelo usuário.

Quando você tiver um manipulador, você criará a UDF com SQL. Para obter mais informações sobre como usar SQL para criar ou chamar uma UDF, consulte Criação de uma UDF ou Como chamar uma UDF.

O Snowflake atualmente oferece suporte para a escrita de UDFs nas seguintes versões Python:

  • 3.8

  • 3.9

  • 3,10

  • 3,11

Nota

Para limitações relacionadas aos manipuladores de UDF Python, consulte Limitações de UDF de Python.

Neste tópico:

Como funciona um manipulador de Python

Quando um usuário chama uma UDF, o usuário passa o nome e os argumentos da UDF para o Snowflake. Snowflake chama o código do manipulador associado (com argumentos, se houver) para executar a lógica da UDF. O método do manipulador então retorna a saída para o Snowflake, que a passa de volta para o cliente.

Para cada linha passada para uma UDF, a UDF retorna um valor escalar (ou seja, único) ou, se definida como uma função de tabela, um conjunto de linhas.

UDFs de Python podem conter tanto código novo como chamadas para bibliotecas existentes, permitindo flexibilidade e reutilização do código. Por exemplo, se você já tiver um código de análise de dados em Python, você provavelmente poderá incorporá-lo em um manipulador de UDF de Python.

Exemplo

O código no exemplo a seguir cria uma UDF chamada addone com um método do manipulador addone_py. O argumento Python e os tipos de retorno são convertidos de e para SQL pelo Snowflake de acordo com os mapeamentos descritos em Mapeamentos de tipos de dados SQL-Python.

create or replace function addone(i int)
returns int
language python
runtime_version = '3.8'
handler = 'addone_py'
as
$$
def addone_py(i):
  return i+1
$$;
Copy

Considerações sobre o projeto

Tenha em mente o seguinte ao projetar um manipulador útil.

Codificação do manipulador

De exemplos básicos a detalhados, os seguintes tópicos descrevem como escrever um manipulador de UDF em Python.

  • Definição do módulo Python. Você escreve a lógica para uma UDF em um módulo Python. Para obter mais informações sobre como Snowflake interage com seu código, consulte Criação do módulo.

  • Tratamento de erros. Para obter mais informações sobre como o Snowflake descobre os erros gerados por manipuladores, consulte Tratamento de erros.

  • Valores tabulares de retorno. Você pode retornar valores tabulares assim como valores escalares (únicos) a partir de uma UDF. Para obter mais informações sobre como escrever um manipulador que retorna valores tabulares, consulte Como escrever uma UDTF em Python.

  • Registro em log e rastreamento de eventos. Para obter mais informações sobre a captura de dados de registro e rastreamento à medida que o código do manipulador é executado, consulte Visão geral do registro e do rastreamento.

  • Dependências. Você pode disponibilizar dependências para seu código no tempo de execução, carregando-as em um estágio. Para obter mais informações, consulte Disponibilização das dependências para seus códigos.

  • Exemplos de códigos Para uma série de exemplos de manipuladores em Python, consulte Exemplos de manipuladores de UDF em Python.