Introdução a UDFs de Java

Você pode escrever o manipulador para uma função definida pelo usuário (UDF) em Java. Os tópicos desta seção descrevem como projetar e escrever um manipulador Java. Você também encontrará exemplos.

Para uma introdução às UDFs, incluindo uma lista de linguagens na qual você pode escrever um manipulador de UDF, consulte Visão geral das funções definidas pelo usuário.

Quando você tiver um manipulador, você criará a UDF com SQL. Para obter mais informações sobre como usar SQL para criar ou chamar uma UDF, consulte Criação de uma UDF ou Como chamar uma UDF.

O Snowflake atualmente oferece suporte à escrita de UDFs nas seguintes versões de Java:

  • 11.x

  • 17.x (O suporte em versão preliminar para esse recurso está disponível para todas as contas.)

Nota

Para limitações relacionadas aos manipuladores da UDF de Java, consulte Limitações da UDF de Java.

Neste tópico:

Como funciona um manipulador de Java

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 Java podem conter tanto código novo como chamadas para bibliotecas existentes, permitindo flexibilidade e reutilização do código. Por exemplo, se você já tem um código de análise de dados em Java, você provavelmente pode incorporá-lo em uma UDF de Java.

Abaixo está uma ilustração simplificada do fluxo de dados:

Fluxo de dados da UDF

Exemplo

O código no exemplo a seguir cria uma UDF chamada echo_varchar com um método do manipulador TestFunc.echoVarchar. O argumento Java e os tipos de retorno são convertidos de e para SQL pelo Snowflake de acordo com os mapeamentos descritos em Mapeamentos de tipos de dados SQL-Java.

create or replace function echo_varchar(x varchar)
returns varchar
language java
called on null input
handler='TestFunc.echoVarchar'
target_path='@~/testfunc.jar'
as
'class TestFunc {
  public static String echoVarchar(String x) {
    return x;
  }
}';
Copy

Considerações sobre o projeto

Tenha em mente o seguinte ao projetar um manipulador útil.

Codificação do manipulador

De exemplos básicos a detalhados, os seguintes tópicos descrevem como escrever um manipulador de UDF em Java.

  • Definição da classe Java. Você escreve a lógica para uma UDF em uma classe Java. Para obter mais informações sobre como Snowflake interage com seu código, consulte Criação da classe.

  • 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 UDFs tabulares (UDTFs) de Java.

  • 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 Visão geral do registro e do rastreamento.

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

  • Organização de arquivos do manipulador. Se você pretende empacotar o código compilado do manipulador em um arquivo JAR, organize e construa seu código usando as sugestões em Organização de seus arquivos.

  • Exemplos de códigos Para uma série de exemplos de manipuladores em Java, consulte Exemplos de manipuladores de UDF em Java.