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:

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.

Considerações gerais. Para considerações comuns a UDFs e procedimentos, consulte Diretrizes de projeto e restrições para funções e procedimentos.
Mapeamento de tipo Python-SQL. Ao trocar argumentos e retornar valores com uma UDF, Snowflake converte entre a linguagem do manipulador e SQL. Para obter mais informações sobre a escolha dos tipos de dados para seu código de manipulador, consulte Como escolher seus tipos de dados.
Empacotamento de código. Você pode disponibilizar seu código de manipulador em linha com a instrução CREATE FUNCTION ou em um estágio. Para obter mais informações sobre a diferença, consulte Como manter o código do manipulador inline ou em um estágio.
Otimização do código. Para obter mais informações sobre a otimização do código do manipulador, como quando o código lida com estado compartilhado entre linhas, consulte Como otimizar a inicialização e controlar o estado global em UDFs escalares e Otimização para escala e desempenho.
Práticas recomendadas. Para obter mais informações sobre as práticas recomendadas, consulte Práticas de segurança para UDFs e procedimentos.

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.
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 Como criar UDFs de Python.