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

Você pode escrever funções definidas pelo usuário (UDFs) para estender o sistema para realizar operações que não estão disponíveis nas funções internas e definidas pelo sistema fornecidas pelo Snowflake. Quando uma UDF é criada, você pode reutilizá-la várias vezes.

Uma UDF é apenas uma forma de estender o Snowflake. Para outras forma, veja o seguinte:

Nota

Uma UDF é como um procedimento armazenado, mas os dois diferem de forma importante. Para obter mais informações, consulte Escolha se deseja escrever um procedimento armazenado ou uma função definida pelo usuário.

Neste tópico:

O que é uma função definida pelo usuário (UDF)?¶

Uma função definida pelo usuário (UDF) é uma função definida por você para que você possa chamá-la de SQL. Assim como as funções internas que você pode chamar de SQL, a lógica da UDF normalmente se estende ou melhora o SQL com funcionalidade que SQL não tem ou não executa bem. A UDF também lhe dá uma maneira de encapsular a funcionalidade para que você possa chamá-la repetidamente de vários lugares no código.

Você escreve a lógica de uma UDF– seu manipulador – em uma das linguagens suportadas. Uma vez que você tenha um manipulador, você pode criar uma UDF com um comando CREATE FUNCTION, depois chamar a UDF com uma instrução SELECT.

Funções escalares e tabulares¶

Você pode escrever uma UDF que retorna um único valor (uma UDF escalar) ou que retorna um valor tabular (uma função de tabela definida pelo usuário ou UDTF).

Uma função escalar (UDF) retorna uma linha de saída para cada linha de entrada. A linha retornada consiste em uma única coluna/valor.
Uma função tabular (UDTF) retorna um valor tabular para cada linha de entrada. No manipulador de uma UDTF, você escreve métodos que estão em conformidade com uma interface exigida pelo Snowflake. Estes métodos serão:
- Processar cada linha em uma partição (obrigatório).
- Inicializar o manipulador uma vez para cada partição (opcional).
- Finalizar o processamento para cada partição (opcional).
Os nomes dos métodos variam de acordo com a linguagem do manipulador. Para obter uma lista das linguagens suportadas, consulte Linguagens suportadas.

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.
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 a definição da UDF chamar a função CURRENT_DATABASE ou CURRENT_SCHEMA, a função avalia o banco de dados ou o esquema que contém a UDF, não o banco de dados ou o esquema da sessão que você especifica com um comando USE <objeto> ou seleciona com o seletor de contexto em Snowsight.

Introdução¶

Para um tutorial pelo qual você escreve uma UDTF com um manipulador escrito em SQL, consulte Início rápido: Introdução às funções de SQL definidas pelo usuário

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.8'
HANDLER = 'addone_py'
as
$$
def addone_py(i):
  return i+1
$$;

Copy

O código no exemplo a seguir executa a UDF addone.

SELECT addone(3);

Copy

Linguagens suportadas¶

Você escreve o manipulador de uma função – sua lógica – em qualquer uma das várias linguagens de programação. Cada linguagem permite a manipulação de dados dentro das restrições da linguagem e de seu ambiente de tempo de execução. Independentemente da linguagem do manipulador, você cria o procedimento em si da mesma forma usando SQL, especificando a linguagem idioma do manipulador e o manipulador.

Você pode escrever um manipulador em qualquer uma das seguintes linguagens:

Linguagem	Guias do desenvolvedor
Java	UDFs Java UDTFs Java
JavaScript	JavaScript UDFs JavaScript UDTFs
Python	UDFs Python UDTFs Python
Scala	UDFs Scala
SQL	SQL UDFs SQL UDTFs

Escolha da linguagem¶

Você escreve um manipulador da UDF – sua lógica – em qualquer uma das várias linguagens de programação. Cada linguagem permite a manipulação de dados dentro das restrições da linguagem e de seu ambiente de tempo de execução.

Você pode escolher uma linguagem em particular se:

Você já tem o código nesta linguagem.

Por exemplo, se você já tiver um método Java que funcionará como um manipulador, e o objeto do método estiver em um arquivo .jar, você poderia copiar o .jar para um estágio, especificar o manipulador como a classe e o método, e então especificar a linguagem como Java.
A linguagem tem capacidades que as outras não têm.
A linguagem tem bibliotecas que podem ajudar você a fazer o processamento desejado.

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 inline 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.

Linguagem	Localização do manipulador	Compartilhável
Java	Inline ou no estágio	Não 1
JavaScript	Inline	Sim
Python	Inline ou no estágio	Não 2
Scala	Inline ou no estágio	Não 3
SQL	Inline	Sim

1: Para obter mais informações sobre os limites de compartilhamento de Java UDFs, consulte Limitações gerais.
2: Para obter mais informações sobre os limites de compartilhamento de UDFs de Python, consulte Limitações gerais.
3: Para obter mais informações sobre os limites de compartilhamento de UDFs Scala, consulte Limitações da UDF de Scala.

Guias do desenvolvedor¶

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 suportadas.
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 e rastreamento: Você pode registrar a atividade do código capturando mensagens de registro e eventos de rastreamento e armazenando os dados em um banco de dados que poderá consultar 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 Granting Privileges for User-Defined Functions

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

Implantaçã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 instrução CREATE FUNCTION ou como código externo à instrução, como o código compilado em pacote e copiado em um estágio.

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

Criação e chamada de funções¶

Você usa SQL para criar e chamar uma função definida pelo usuário.

Para criar uma função, execute a instrução CREATE FUNCTION, especificando o manipulador da função. Para obter mais informações, consulte Criação de uma UDF.
Para chamar uma função, execute uma instrução SQL SELECT que especifique a função como parâmetro. Para obter mais informações, consulte Como chamar uma UDF.