Introdução a UDFs de Python¶

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.

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

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 em linha 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.

• 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 Registro, rastreamento e métricas.

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