Criação de uma função definida pelo usuário¶

Criar uma UDF¶

1. Escreva a lógica da função como um manipulador usando uma das várias linguagens compatíveis, incluindo Python, Java e Scala.

2. Escolha uma ferramenta ou API para criar a função com o manipulador que você escreveu.

   Para obter mais informações sobre cada um deles, consulte Ferramentas para criar UDFs.

   SQL	Use o SQL e escreva lógica em uma das várias linguagens.
   Snowpark	Use a Snowpark API para Java, Python ou Scala.
   Linha de comando	Execute os comandos do CLI para criar a função.
   API de Python	Execute os comandos Python no lado do cliente para criar a função.
   REST	Faça solicitações a uma RESTful API para criar a função.

3. Execute a função usando uma das várias ferramentas, dependendo de suas necessidades.

Ferramentas para criar UDFs¶

Você pode criar uma UDF usando qualquer um dos vários métodos disponíveis no Snowflake, dependendo da linguagem e do conjunto de habilidades que tiver disponível. Escolha a ferramenta certa para suas necessidades na tabela a seguir.

Principais propriedades¶

A seguir descrevemos algumas das propriedades necessárias ou tipicamente utilizadas na criação de uma função.

Nome da função:

O nome da função não precisa corresponder ao nome do manipulador. Para saber mais sobre restrições de nome e convenções, consulte Como nomear e sobrecarregar procedimentos e UDFs.

Argumentos:

Para obter mais informações sobre os requisitos, consulte Definição de argumentos para UDFs e procedimentos armazenados.

Seu tipo de retorno:

Para obter mais informações sobre como o Snowflake mapeia tipos de dados SQL para os tipos de dados do manipulador, consulte Mapeamentos de tipos de dados entre linguagens do manipulador e SQL.

Seu nome do manipulador:

Quando necessário, esse é o nome da classe ou do método que contém o código que é executado quando a função é executada. Você precisa especificar um nome de manipulador somente para manipuladores escritos em Java, Python e Scala. Para manipuladores JavaScript e SQL, todos os códigos especificados em linha serão executados como manipuladores.

Dependências:

Para um manipulador escrito em Java, Python ou Scala, talvez você também precise especificar a biblioteca do Snowpark, por exemplo, ao criar a função.

Para saber mais sobre como disponibilizar dependências para seu manipulador, consulte Disponibilização das dependências para seus códigos.

Tempo de execução da linguagem do manipulador:

Quando a linguagem do manipulador for Java, Python ou Scala, especifique a versão de tempo de execução para indicar qual versão de tempo de execução suportada deve ser usada. Lembre-se de que, se você usar a versão padrão, ela será alterada com o tempo.

Requisitos de controle de acesso¶

A função usada para executar essa operação deve ter, no mínimo, os seguintes privilégios:

O privilégio USAGE no banco de dados e no esquema pai é necessário para executar operações em qualquer objeto de um esquema.

Para instruções sobre como criar uma função personalizada com um conjunto específico de privilégios, consulte Criação de funções personalizadas.

Para informações gerais sobre concessões de funções e privilégios para executar ações de SQL em objetos protegíveis, consulte Visão geral do controle de acesso.

Notas de uso¶

As notas a seguir descrevem notas de uso relevantes para as linguagens compatíveis com a escrita de manipuladores. Embora as observações nas seções a seguir se refiram a cláusulas do comando SQL CREATE FUNCTION, essas cláusulas são normalmente representadas de outras formas em outras ferramentas que você pode usar para criar funções.

Criação de uma UDF com SQL¶

Você pode criar uma UDF com SQL usando as seguintes etapas.

Você cria uma UDF com os seguintes passos:

1. Escreva o código do manipulador que executa quando a UDF é chamada.

   Você pode usar uma das linguagens do manipulador suportadas. Para obter mais informações, consulte Linguagens e ferramentas compatíveis.

2. Escolha se você vai manter o código do manipulador em linha com a instrução SQL CREATE FUNCTION ou se vai se referir a ele em um estágio.

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

3. Execute uma instrução CREATE FUNCTION em SQL, especificando as propriedades da função.

   O código no exemplo a seguir cria uma UDF chamada function_name com o manipulador em linha HandlerClass.handlerMethod.

   create function function_name(x integer, y integer)
     returns integer
     language java
     handler='HandlerClass.handlerMethod'
     target_path='@~/HandlerCode.jar'
     as
     $$
         class HandlerClass {
             public static int handlerMethod(int x, int y) {
               return x + y;
             }
         }
     $$;
   

   Copy

   A seguir descrevemos algumas das propriedades necessárias ou tipicamente utilizadas na criação de uma função.

   • Nome da função.

     O nome da UDF não precisa corresponder ao nome do manipulador. A instrução CREATE FUNCTION associa o nome da UDF com o manipulador.

     Para saber mais sobre restrições de nome e convenções, consulte Como nomear e sobrecarregar procedimentos e UDFs.

   • Argumentos de função, se houver.

     Consulte Definição de argumentos para UDFs e procedimentos armazenados.

   • Tipo de retorno com a cláusula RETURNS.

     Para um valor de retorno escalar, a cláusula RETURNS especificará um único tipo de retorno; para um valor de retorno tabular, RETURNS especificará a palavra-chave TABLE, especificando o tipo de coluna no valor de retorno tabular.

     Para obter mais informações sobre como o Snowflake mapeia tipos de dados SQL para os tipos de dados do manipulador, consulte Como nomear e sobrecarregar procedimentos e UDFs.

   • Nome do manipulador com a cláusula HANDLER.

     Quando necessário, este é o nome da classe ou método que contém o código que executa quando a UDF é chamada. Você precisa especificar um nome de manipulador somente para manipuladores escritos em Java e Python. Para manipuladores JavaScript e SQL, todos os códigos especificados em linha serão executados como manipuladores.

     A tabela a seguir descreve a forma do valor da cláusula HANDLER com base na linguagem do manipulador e no tipo de função.

     Linguagem do manipulador	UDF	UDTF
     Java	Nome do método e classe Por exemplo: MyClass.myMethod	Somente o nome da classe. O nome do método do manipulador é pré-determinado pela interface necessária.
     JavaScript	Nenhum.	Nenhum.
     Python	Nome do método e classe se for usada uma classe; caso contrário, nome da função. Por exemplo: module.my_function ou my_function	Somente o nome da classe. O nome do método do manipulador é pré-determinado pela interface necessária.
     SQL	Nenhum.	Nenhum.

   • Dependências exigidas pelo manipulador, se houver, usando as cláusulas IMPORTS ou PACKAGES.

     Para saber mais sobre como disponibilizar dependências para seu manipulador, consulte Disponibilização das dependências para seus códigos.

   • Linguagem do manipulador com a cláusula RUNTIME_VERSION.

     Quando a linguagem do manipulador for Java ou Python, use a cláusula RUNTIME_VERSION para especificar qual versão suportada em tempo de execução deve ser usada. Omitir a cláusula levará o Snowflake a usar o padrão, que pode mudar no futuro.