Visão geral das funções definidas pelo usuário¶

Variações de funções definidas pelo usuário¶

Você pode escrever uma UDF em uma das diversas variações, dependendo dos requisitos de entrada e saída que sua função deve atender.

Linguagens e ferramentas compatíveis¶

Você pode criar e gerenciar UDFs (e outras entidades do Snowflake) usando qualquer uma das várias ferramentas, dependendo de como prefere trabalhar.

Ao escolher uma linguagem, considere também o seguinte:

• Locais do manipulador com suporte. Nem todas as linguagens oferecem suporte à referência ao manipulador em um estágio (o código do manipulador deve ser em linha em vez disso). Para obter mais informações, consulte Como manter o código do manipulador em linha ou em um estágio.

• Se o manipulador resultar em uma UDF que é compartilhável. Uma UDF compartilhável pode ser usada com o recurso Secure Data Sharing do Snowflake.

Considerações¶

• Se uma consulta chamar uma UDF para acessar arquivos preparados, a operação falhará com um erro do usuário se a instrução SQL também consultar uma exibição que chame qualquer UDF ou UDTF, não importando se a função na exibição acessa arquivos preparados ou não.

• UDTFs podem processar vários arquivos paralelamente; entretanto, UDFs atualmente processam arquivos em série. Para contornar isso, agrupe linhas em uma subconsulta usando a cláusula GROUP BY. Para obter um exemplo, consulte Processamento de um CSV com uma UDTF.

• Atualmente, se os arquivos preparados referenciados em uma consulta forem modificados ou excluídos enquanto a consulta estiver em execução, a chamada de função falhará com um erro.

• Se você especificar a função CURRENT_DATABASE ou CURRENT_SCHEMA no código do manipulador da UDF, a função retornará o banco de dados ou esquema que contém a UDF, não o banco de dados ou esquema em uso para a sessão.

Exemplo de UDF¶

O código no exemplo a seguir cria uma UDF chamada addone com um manipulador escrito em Python. A função do manipulador é addone_py. Esta UDF retorna um int.

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 no exemplo a seguir executa a UDF addone.

SELECT addone(3);

Diretrizes e restrições¶

Restrições do Snowflake:

Você pode garantir a estabilidade dentro do ambiente Snowflake desenvolvendo dentro das restrições do Snowflake. Para obter mais informações, consulte Criação de manipuladores que ficam dentro das restrições impostas pelo Snowflake.

Nomeação:

Certifique-se de nomear as funções de forma a evitar colisões com outras funções. Para obter mais informações, consulte Como nomear e sobrecarregar procedimentos e UDFs.

Argumentos:

Especifique os argumentos e indique quais argumentos são opcionais. Para obter mais informações, consulte Definição de argumentos para UDFs e procedimentos armazenados.

Mapeamentos de tipos de dados:

Para cada linguagem do manipulador, há um conjunto separado de mapeamentos entre os tipos de dados da linguagem e os tipos SQL usados para valores de retorno e argumentos. Para saber mais sobre os mapeamentos para cada linguagem, consulte Mapeamentos de tipos de dados entre linguagens do manipulador e SQL.

Como escrever o manipulador¶

Linguagens do manipulador:

Para obter conteúdo específico da linguagem ao escrever um manipulador, consulte Linguagens e ferramentas compatíveis.

Acesso à rede externa:

Você pode acessar locais de rede externos com acesso à rede externa. Você pode criar acesso seguro a locais de rede específicos externos ao Snowflake e usar esse acesso de dentro do código do manipulador.

Registro, rastreamento e métricas:

É possível registrar a atividade do código capturando mensagens de log, eventos de rastreamento e dados de métricas, armazenando os dados em um banco de dados que pode ser consultado posteriormente.

Segurança¶

Você pode conceder privilégios nos objetos necessários para que realizem ações SQL específicas com uma UDF ou UDTF. Para obter mais informações, consulte Concessão de privilégios para funções definidas pelo usuário

As funções têm certas preocupações de segurança como os procedimentos armazenados. Para obter mais informações, consulte o seguinte:

• Você pode ajudar o código do manipulador de um procedimento a ser executado com segurança, seguindo as práticas recomendadas descritas em Práticas de segurança para UDFs e procedimentos

• Certifique-se de que as informações sensíveis sejam ocultadas dos usuários que não deveriam ter acesso a elas. Para obter mais informações, consulte Proteção de informações sensíveis com UDFs e procedimentos armazenados seguros

Implementação do código do manipulador¶

Ao criar uma função, você pode especificar seu manipulador - que implementa a lógica da função - como código em linha com a definição da função ou como código externo à definição, como código empacotado e copiado para um estágio.

Para obter mais informações, consulte Como manter o código do manipulador em linha ou em um estágio.