Como criar UDFs de Python¶

Como escrever o módulo e a função Python¶

Escreva um módulo que siga as especificações abaixo:

• Defina o módulo. Um módulo é um arquivo contendo definições e instruções de Python.

• Defina uma função dentro do módulo.

• Se a função aceitar argumentos, cada argumento deve ser um dos tipos de dados especificados na coluna Python Data Type da tabela de mapeamento entre tipos de SQL e Python.

  Os argumentos de função estão vinculados à posição, não ao nome. O primeiro argumento passado para a UDF é o primeiro argumento recebido pela função de Python.

• Especifique um valor de retorno adequado. Como uma UDF de Python deve ser uma função escalar, ela deve retornar um valor cada vez que for invocada. O tipo do valor de retorno deve ser um dos tipos de dados especificados na coluna Python Data Type da tabela de mapeamento entre tipos de SQL e Python. O tipo do valor de retorno deve ser compatível com o tipo de dados de SQL especificado na cláusula RETURNS da instrução CREATE FUNCTION.

• Seu módulo pode conter mais de uma função. A função que é chamada pelo Snowflake pode chamar outras funções no mesmo módulo ou em outros módulos.

• Sua função (e quaisquer funções chamadas por sua função) devem estar de acordo com as restrições impostas pelo Snowflake para UDFs de Python.

Como criar uma UDF Python em linha¶

Para criar uma UDF inline, forneça o código-fonte de Python como parte da instrução CREATE FUNCTION.

Por exemplo, a seguinte instrução cria uma UDF de Python inline que adiciona um a um determinado número inteiro:

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
$$;

O código-fonte de Python é especificado na cláusula AS. O código-fonte pode ser colocado entre aspas simples ou entre um par de cifrões ($$). O uso dos cifrões geralmente é mais fácil se o código-fonte contiver aspas simples incorporadas.

Chame a UDF:

select addone(10);

Aqui está a saída:

+------------+
| ADDONE(10) |
|------------|
|         11 |
+------------+

O código-fonte de Python pode conter mais de um módulo, e mais de uma função em um módulo. Portanto, a cláusula HANDLER especifica o módulo e a função a ser chamada.

Uma UDF de Python inline pode chamar código em módulos que estão incluídos na cláusula IMPORTS.

Para obter mais detalhes sobre a sintaxe da instrução CREATE FUNCTION, consulte CREATE FUNCTION.

Para obter mais exemplos, consulte exemplos de UDF de Python inline.

Como criar uma UDF Python com código carregado de um estágio¶

As instruções a seguir criam uma UDF de Python simples usando código carregado de um estágio. O estágio que hospeda o arquivo deve ser legível pelo proprietário da UDF. Além disso, arquivos ZIP devem ser autocontidos e não confiar em nenhum script de configuração adicional para serem executados.

Crie um arquivo de Python chamado sleepy.py contendo seu código-fonte:

def snore(n):   # return a series of n snores
    result = []
    for a in range(n):
        result.append("Zzz")
    return result

Inicie o comando SnowSQL (cliente CLI) e use o comando PUT para copiar o arquivo do sistema de arquivos local para o estágio padrão do usuário, chamado @~. (O comando PUT não pode ser executado pela GUI do Snowflake).

put
file:///Users/Me/sleepy.py
@~/
auto_compress = false
overwrite = true
;

Se você apagar ou renomear o arquivo, você não poderá mais chamar a UDF. Se você precisar atualizar seu arquivo, atualize-o enquanto nenhuma chamada para a UDF possa ser feita. Se o arquivo antigo ainda estiver no estágio, o comando PUT deverá incluir a cláusula OVERWRITE=TRUE.

Crie a UDF. O manipulador especifica o módulo e a função.

create or replace function dream(i int)
returns variant
language python
RUNTIME_VERSION = '3.9'
handler = 'sleepy.snore'
imports = ('@~/sleepy.py')

Chame a UDF:

select dream(3);

+----------+
| DREAM(3) |
|----------|
| [        |
|   "Zzz", |
|   "Zzz", |
|   "Zzz"  |
| ]        |
+----------+

create or replace function multiple_import_files(s string)
returns string
language python
RUNTIME_VERSION = 3.9
imports=('@python_udf_dep/bar/python_imports_a.zip', '@python_udf_dep/foo/python_imports_b.zip')
handler='compute'
as
$$
def compute(s):
  return s
$$;