Criação de UDFs Java¶

Como escrever o manipulador de UDF em Java¶

Use os seguintes requisitos e diretrizes ao escrever seu manipulador de UDF em Java.

• Defina a classe como pública.

• Dentro da classe, declare pelo menos um método público a ser usado como manipulador de UDF.

  Para uma UDF inline, declare apenas um método do manipulador. Se, em vez disso, você pretende inserir a classe em um pacote JAR como uma UDF pré-compilada, você pode declarar vários métodos do manipulador, especificando mais tarde cada um como manipulador com a cláusula HANDLER de uma instrução CREATE FUNCTION.

  Você pode declarar outros métodos, se necessário, a serem chamados pelo método do manipulador.

  Use os seguintes requisitos e diretrizes para cada método do manipulador:

  • Declare o método do manipulador como público, estático ou não estático.

    Se o método não for estático, sua classe também deverá declarar um construtor sem argumentos ou nenhum construtor.

    O Snowflake não passa nenhum argumento para o construtor quando ele instancia a classe. Se o construtor lança um erro, o erro é lançado como um erro do usuário, juntamente com a mensagem de exceção.

  • Especifique um tipo de retorno adequado.

    O tipo de retorno deve ser um dos tipos de dados especificados na coluna Java Data Type da tabela de mapeamento de tipos SQL-Java. O tipo de retorno deve ser compatível com o tipo de dados SQL especificado na cláusula RETURNS da instrução CREATE FUNCTION.

  • Certifique-se de que cada argumento do método do manipulador (se houver) seja um tipo de dados especificado na coluna Java Data Type da tabela de mapeamento de tipos SQL-Java.

    Ao escolher os tipos de dados das variáveis de Java, leve em conta os valores máximos e mínimos possíveis dos dados que poderiam ser enviados do Snowflake (e devolvidos a ele).

  • Siga as restrições impostas pelo Snowflake para UDFs de Java em cada método do manipulador e nos métodos chamados por ele.

Criação da função no Snowflake¶

As informações desta seção se aplicam a todas as UDFs de Java, independentemente de o código estar especificado inline ou pré-compilado.

Você deve executar uma instrução CREATE FUNCTION para especificar aspectos da UDF, inclusive:

• O nome da UDF.

• O nome do método Java que será chamado como manipulador pelo Snowflake quando a UDF for chamada.

O nome da UDF não precisa corresponder ao nome do método do manipulador escrito em Java. A instrução CREATE FUNCTION associa o nome da UDF ao método Java, como mostrado no diagrama a seguir:

Ao escolher um nome para a UDF:

• Siga as regras para Identificadores de objetos.

• Escolha um nome único ou siga as regras para Sobrecarga de nomes de UDF.

  Importante

  Ao contrário da sobrecarga para UDFs do SQL, que distingue entre funções baseadas tanto no número quanto nos tipos de dados dos argumentos, as UDFs de Java distinguem entre métodos baseados apenas no número de argumentos. Se dois métodos de Java tiverem o mesmo nome e o mesmo número de argumentos, mas tipos de dados diferentes, então chamar uma UDF usando um desses métodos como manipulador gerará um erro semelhante ao seguinte:

  Não é possível determinar qual implementação do “nome do manipulador” será invocada, pois existem múltiplas definições com <number of args> argumentos na função <user defined function name> com manipulador <class name>.<handler name>

  Se um warehouse estiver disponível, o erro será detectado no momento em que a UDF for criada. Caso contrário, o erro ocorre quando a UDF é chamada.

  A resolução baseada em tipos de dados não é prática, porque alguns tipos de dados de SQL podem ser mapeados para mais de um tipo de dados de Java e, portanto, potencialmente para mais de uma assinatura de UDF de Java.

Os argumentos do método do manipulador são vinculados a argumentos da UDF por posição, não por nome. Em outras palavras, o primeiro argumento da UDF é passado para o primeiro argumento do método, o segundo argumento da UDF é passado para o segundo argumento do método, e assim por diante.

Nos exemplos abaixo, o argumento da UDF do SQL x corresponde ao argumento do método Java a, e y corresponde a b:

create function add_int_float(x numeric(9, 0), y float)
returns float
language java
handler = 'MyClass.addIntFloat';

public static float addIntFloat(int a, float b) {
  // ...
}

Para obter mais informações sobre os tipos de dados de argumentos, consulte Mapeamentos de tipos de dados SQL-Java para tipos de parâmetros e retorno.

Recomenda-se que você use o parâmetro RUNTIME_VERSION da instrução CREATE FUNCTION para especificar qual versão do Java runtime suportada deve ser usada, porque a versão padrão pode mudar no futuro.

UDFs inline vs. UDFs pré-compiladas¶

Você pode definir um manipulador de UDF de Java de uma das seguintes maneiras:

• Pré-compilada, na qual você insere o manipulador de Java compilado em um JAR e a coloca em um local onde o Snowflake pode lê-la.

  A instrução CREATE FUNCTION especifica a localização do arquivo JAR que contém o manipulador. Antes de executar CREATE FUNCTION, você copia o arquivo JAR para um estágio do qual o Snowflake pode lê-lo.

• Inline, incluindo o código em Java com a própria declaração da UDF.

  A própria instrução CREATE FUNCTION especifica o código-fonte em Java. O Snowflake compila o código-fonte e armazena o código compilado em um arquivo JAR. Você pode especificar um local para o arquivo JAR resultante com a cláusula TARGET_PATH ao executar CREATE FUNCTION.

  • Se CREATE FUNCTION especificar um local para o arquivo JAR, o Snowflake compilará o código uma vez e manterá o arquivo JAR para uso futuro.

  • Se CREATE FUNCTION não especificar um local para o arquivo JAR, o Snowflake recompilará o código para cada instrução SQL que chama a UDF, e o Snowflake limpará automaticamente o arquivo JAR após o término da instrução SQL.

Adição de dependências ao Classpath¶

Se o código de seu manipulador exigir classes empacotadas em arquivos JAR externos, você poderá adicionar essas dependências ao classpath gerenciado pelo Snowflake disponível para seu manipulador. A seção a seguir descreve como adicionar arquivos JAR ao classpath visível a um manipulador de UDF de Java.

1. Crie um estágio que esteja disponível para seu manipulador.

   Para dependências de UDF, você pode usar um estágio externo ou interno. Se você usar um estágio interno, ele deve ser um usuário ou um estágio nomeado; atualmente, o Snowflake não oferece suporte ao uso de um estágio de tabela para dependências de UDF. Para saber mais sobre a criação de um estágio, consulte CREATE STAGE. Para saber mais sobre a escolha de um tipo de estágio interno, consulte Escolha de um estágio interno para os arquivos locais.

2. Copie o JAR de dependências para o estágio.

   Você pode copiar o JAR de um drive local para um estágio usando o comando PUT. Para obter uma referência do comando, consulte PUT. Para obter mais informações sobre a preparação de arquivos com PUT, consulte Preparação de arquivos de dados de um sistema de arquivo local.

3. Referencie a dependência JAR ao criar a UDF.

   Quando você executar CREATE FUNCTION para criar a UDF, especifique o local do estágio e o caminho e nome do arquivo de todos arquivos de dependências JAR como valores da cláusula IMPORTS. No runtime, o Snowflake adiciona o JAR ao classpath. Para informações de referência, veja CREATE FUNCTION.

   O código no exemplo a seguir cria uma UDF chamada my_udf, especificando uma dependência my_handler_dependency.jar no estágio @mystage.

   CREATE FUNCTION my_udf(i NUMERIC)
     RETURNS NUMERIC
     LANGUAGE JAVA
     IMPORTS = ('@mystage/dependencies/my_handler_dependency.jar')
     HANDLER = 'MyClass.myFunction'
     AS
     $$
       // Handler code omitted.
     $$
   

Criação de uma UDF de Java inline¶

Para uma UDF inline, você fornece o código-fonte de Java como parte da instrução CREATE FUNCTION.

Você coloca o código-fonte de Java na cláusula AS, delimitando o código com aspas simples ou um par de cifrões ($$). O uso dos cifrões duplos pode ser mais fácil, por exemplo, quando o código-fonte contém aspas simples.

O código no exemplo a seguir declara uma add UDF cujo manipulador é o método add na classe TestAddFunc.

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

Dado que o código-fonte de Java pode conter mais de uma classe e mais de um método em uma classe, a cláusula HANDLER especifica a classe e o método a ser usado como manipulador.

Uma UDF de Java inline (como uma UDF de Java pré-compilada) pode chamar código em arquivos JAR que estão incluídos na cláusula CREATE FUNCTION da instrução IMPORTS.

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

Para obter mais exemplos, consulte Exemplos de manipuladores de UDF em Java.

Criação de uma UDF de Java pré-compilada¶

Se você pretender criar uma UDF que especifique a localização de um JAR existente para seu manipulador, você desenvolverá o manipulador:

• Organizando seus arquivos de código em uma hierarquia para empacotá-los em um arquivo JAR.

• Compilando o código e colocando-o em um pacote JAR.

• Copiando o JAR com sua função de manipulador para um estágio onde o Snowflake poderá lê-lo no runtime.