Exemplos de manipuladores de UDF em Java¶

Como passar um NULL para uma UDF de Java inline¶

Isso utiliza a echo_varchar() UDF definida acima. O valor SQL NULL é implicitamente convertido para Java null, e esse null do Java é retornado e implicitamente convertido de volta para SQL NULL:

Chame a UDF:

SELECT echo_varchar(NULL);
+--------------------+
| ECHO_VARCHAR(NULL) |
|--------------------|
| NULL               |
+--------------------+

Passando por uma ARRAY¶

Declare o parâmetro de Java como uma array. Por exemplo, o terceiro parâmetro no método a seguir é uma array de cadeias de caracteres:

static int myMethod(int fixedArgument1, int fixedArgument2, String[] stringArray)

Copy

Abaixo está um exemplo completo:

Criar e carregar a tabela:

CREATE TABLE string_array_table(id INTEGER, a ARRAY);
INSERT INTO string_array_table (id, a) SELECT
        1, ARRAY_CONSTRUCT('Hello');
INSERT INTO string_array_table (id, a) SELECT
        2, ARRAY_CONSTRUCT('Hello', 'Jay');
INSERT INTO string_array_table (id, a) SELECT
        3, ARRAY_CONSTRUCT('Hello', 'Jay', 'Smith');

Copy

Crie a UDF:

create or replace function concat_varchar_2(a ARRAY)
returns varchar
language java
handler='TestFunc_2.concatVarchar2'
target_path='@~/TestFunc_2.jar'
as
$$
    class TestFunc_2 {
        public static String concatVarchar2(String[] strings) {
            return String.join(" ", strings);
        }
    }
$$;

Copy

Chame a UDF:

SELECT concat_varchar_2(a)
    FROM string_array_table
    ORDER BY id;
+---------------------+
| CONCAT_VARCHAR_2(A) |
|---------------------|
| Hello               |
| Hello Jay           |
| Hello Jay Smith     |
+---------------------+

Copy

Como passar usando o Varargs¶

O uso do varargs é muito semelhante ao uso de uma array.

Em seu código de Java, use o estilo de declaração do varargs de Java:

static int myMethod(int fixedArgument1, int fixedArgument2, String ... stringArray)

Copy

Abaixo está um exemplo completo. A única diferença significativa entre este exemplo e o exemplo anterior (para arrays) é a declaração dos parâmetros para o método.

Criar e carregar a tabela:

CREATE TABLE string_array_table(id INTEGER, a ARRAY);
INSERT INTO string_array_table (id, a) SELECT
        1, ARRAY_CONSTRUCT('Hello');
INSERT INTO string_array_table (id, a) SELECT
        2, ARRAY_CONSTRUCT('Hello', 'Jay');
INSERT INTO string_array_table (id, a) SELECT
        3, ARRAY_CONSTRUCT('Hello', 'Jay', 'Smith');

Copy

Crie a UDF:

create or replace function concat_varchar(a ARRAY)
returns varchar
language java
handler='TestFunc.concatVarchar'
target_path='@~/TestFunc.jar'
as
$$
    class TestFunc {
        public static String concatVarchar(String ... stringArray) {
            return String.join(" ", stringArray);
        }
    }
$$;

Copy

Chame a UDF:

SELECT concat_varchar(a)
    FROM string_array_table
    ORDER BY id;
+-------------------+
| CONCAT_VARCHAR(A) |
|-------------------|
| Hello             |
| Hello Jay         |
| Hello Jay Smith   |
+-------------------+

Copy

Pré-requisitos¶

Antes que seu código de manipulador do Java possa ler um arquivo em um estágio, você deve fazer o seguinte para tornar o arquivo disponível para o código:

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

   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.

   Tenha em mente que privilégios adequados no estágio devem ser atribuídos às funções que executam ações SQL que leem do estágio. Para obter mais informações, consulte Granting Privileges for User-Defined Functions.

2. Para o estágio, copie o arquivo que será lido por código.

   Você pode copiar o arquivo 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.

Como ler um arquivo especificado estaticamente em IMPORTS¶

Seu manipulador pode ler um arquivo cujo caminho de estágio foi especificado na cláusula IMPORTS do comando CREATE FUNCTION.

Quando você especifica um arquivo na cláusula IMPORTS, o Snowflake copia esse arquivo do estágio para o diretório inicial do UDF (também chamado de diretório importar), que é o diretório do qual o UDF realmente lê o arquivo.

Como os arquivos importados são copiados para um único diretório e devem ter nomes únicos dentro desse diretório, cada arquivo na cláusula IMPORTS deve ter um nome distinto, mesmo que os arquivos comecem em estágios diferentes ou subdiretórios diferentes dentro de um estágio.

O exemplo seguinte cria e chama um UDF Java que lê um arquivo.

O código fonte Java abaixo cria um método Java chamado readFile. Este UDF usa este método.

import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.stream.Stream;

class TestReadRelativeFile {
    public static String readFile(String fileName) throws IOException {
        StringBuilder contentBuilder = new StringBuilder();
        String importDirectory = System.getProperty("com.snowflake.import_directory");
        String fPath = importDirectory + fileName;
        Stream<String> stream = Files.lines(Paths.get(fPath), StandardCharsets.UTF_8);
        stream.forEach(s -> contentBuilder.append(s).append("\n"));
        return contentBuilder.toString();
    }
}

O seguinte código SQL cria o UDF. Este código assume que o código fonte Java foi compilado e colocado em um arquivo JAR chamado TestReadRelativeFile.jar, que o UDF importa. O segundo e terceiro arquivos importados, my_config_file_1.txt e my_config_file_2.txt, são arquivos de configuração que o UDF pode ler.

CREATE FUNCTION file_reader(file_name VARCHAR)
RETURNS VARCHAR
LANGUAGE JAVA
IMPORTS = ('@my_stage/my_package/TestReadRelativeFile.jar',
           '@my_stage/my_path/my_config_file_1.txt',
           '@my_stage/my_path/my_config_file_2.txt')
HANDLER = 'my_package.TestReadRelativeFile.readFile';

Este código chama o UDF:

SELECT file_reader('my_config_file_1.txt') ...;
...
SELECT file_reader('my_config_file_2.txt') ...;

... imports = ('@MyStage/MyData.txt.gz', ...)

Como ler um arquivo especificado dinamicamente com SnowflakeFile¶

Usando métodos da classe SnowflakeFile, você pode ler arquivos de um estágio com seu código do manipulador em Java. A classe SnowflakeFile está incluída no classpath disponível para os manipuladores de UDF de Java no Snowflake.

Para desenvolver seu código da UDF localmente, adicione o JAR do Snowpark contendo SnowflakeFile ao caminho da classe do seu código. Para obter mais informações sobre snowpark.jar, consulte Configuração do seu ambiente de desenvolvimento para o Snowpark Java. Observe que os aplicativos clientes do Snowpark não podem usar essa classe.

Quando você usa SnowflakeFile, não é necessário especificar também o arquivo preparado ou o JAR contendo SnowflakeFile com uma cláusula IMPORTS quando você cria a UDF, como no SQL com uma instrução CREATE FUNCTION.

O código no exemplo a seguir usa SnowflakeFile para ler um arquivo a partir de um local de estágio especificado. Usando um InputStream do método getInputStream, ele lê o conteúdo do arquivo em uma variável String.

CREATE OR REPLACE FUNCTION sum_total_sales(file string)
RETURNS INTEGER
LANGUAGE JAVA
HANDLER = 'SalesSum.sumTotalSales'
TARGET_PATH = '@jar_stage/sales_functions2.jar'
AS
$$
import java.io.InputStream;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import com.snowflake.snowpark_java.types.SnowflakeFile;

public class SalesSum {

  public static int sumTotalSales(String filePath) throws IOException {
    int total = -1;

    // Use a SnowflakeFile instance to read sales data from a stage.
    SnowflakeFile file = SnowflakeFile.newInstance(filePath);
    InputStream stream = file.getInputStream();
    String contents = new String(stream.readAllBytes(), StandardCharsets.UTF_8);

    // Omitted for brevity: code to retrieve sales data from JSON and assign it to the total variable.

    return total;
  }
}
$$;

Chame a UDF, passando a localização do arquivo em uma URL com escopo para reduzir a probabilidade de ataques de injeção de arquivo.

SELECT sum_total_sales(BUILD_SCOPED_FILE_URL('@sales_data_stage', '/car_sales.json'));

String filename = "@my_stage/filename.txt";
String sfFile = SnowflakeFile.newInstance(filename, false);

Como ler um arquivo especificado dinamicamente com InputStream¶

Você pode ler o conteúdo do arquivo diretamente em um java.io.InputStream tornando o argumento de sua função de manipulador uma variável InputStream. Isto pode ser útil quando o executor da função quiser passar um caminho de arquivo como um argumento.

O código no exemplo a seguir tem uma função de manipulador sumTotalSales que obtém um InputStream e retorna um int. Durante a execução, o Snowflake atribui automaticamente o conteúdo do arquivo no caminho da variável file para a variável de argumento stream.

CREATE OR REPLACE FUNCTION sum_total_sales(file string)
RETURNS INTEGER
LANGUAGE JAVA
HANDLER = 'SalesSum.sumTotalSales'
TARGET_PATH = '@jar_stage/sales_functions2.jar'
AS
$$
import java.io.InputStream;
import java.io.IOException;
import java.nio.charset.StandardCharsets;

public class SalesSum {

  public static int sumTotalSales(InputStream stream) throws IOException {
    int total = -1;
    String contents = new String(stream.readAllBytes(), StandardCharsets.UTF_8);

    // Omitted for brevity: code to retrieve sales data from JSON and assign it to the total variable.

    return total;
  }
}
$$;

Chame a UDF, passando a localização do arquivo em uma URL com escopo para reduzir a probabilidade de ataques de injeção de arquivo.

SELECT sum_total_sales(BUILD_SCOPED_FILE_URL('@sales_data_stage', '/car_sales.json'));

Crie e compile o código do manipulador em Java¶

1. No diretório raiz de seu projeto (aqui, my_udf), crie um subdiretório src para manter os arquivos .java de origem e um subdiretório classes para manter os arquivos .class gerados.

   Você deve ter uma hierarquia de diretórios semelhante à seguinte:

   my_udf/
   |-- classes/
   |-- src/
   

   Copy

2. No diretório src, crie um diretório chamado mypackage para armazenar arquivos .java cujas classes estão no pacote mypackage.

3. No diretório mypackage, crie um arquivo MyUDFHandler.java que contenha seu código fonte.

   package mypackage;
   
   public class MyUDFHandler {
   
     public static int decrementValue(int i)
     {
         return i - 1;
     }
   
     public static void main(String[] argv)
     {
         System.out.println("This main() function won't be called.");
     }
   }
   

   Copy

4. A partir do diretório raiz de seu projeto (aqui, my_udf), use o comando javac para compilar o código fonte.

   O comando javac no seguinte exemplo compila MyUDFHandler.java para gerar um arquivo MyUDFHandler.class no diretório classes.

   javac -d classes src/mypackage/MyUDFHandler.java
   

   Copy

   Este exemplo inclui os seguintes argumentos:

   • -d classes – Diretório no qual os arquivos de classe gerados devem ser gravados.

   • src/mypackage/MyUDFHandler.java – Caminho para o arquivo .java na forma: source_directory/package_directory/Java_file_name.

Empacote o código compilado em um arquivo JAR.¶

1. Opcionalmente, no diretório raiz do projeto, crie um arquivo do manifesto chamado my_udf.manifest que contenha os seguintes atributos:

   Manifest-Version: 1.0
   Main-Class: mypackage.MyUDFHandler
   

   Copy

2. A partir do diretório raiz de seu projeto, execute o comando jar para criar um arquivo JAR contendo o arquivo .class e do manifesto.

   O comando jar no exemplo a seguir coloca o arquivo MyUDFHandler.class gerado em uma pasta de pacotes mypackage em um arquivo .jar chamado my_udf.jar. O sinalizador -C ./classes especifica a localização dos arquivos .class.

   jar cmf my_udf.manifest my_udf.jar -C ./classes mypackage/MyUDFHandler.class
   

   Copy

   Este exemplo inclui os seguintes argumentos:

   • cmf – Argumentos de comando: c para criar um arquivo JAR, m para usar o arquivo .manifest especificado, e f para dar ao arquivo JAR o nome especificado.

   • my_udf.manifest – Arquivo do manifesto.

   • my_udf.jar – Nome do arquivo JAR a ser criado.

   • -C ./classes – Diretório contendo os arquivos .class gerados.

   • mypackage/MyUDFHandler.class – Pacote e nome do arquivo .class a ser incluído no arquivo JAR.

Faça o upload do arquivo JAR com o manipulador compilado para um estágio¶

1. No Snowflake, crie um estágio chamado jar_stage para armazenar o arquivo JAR contendo seu manipulador de UDF.

   Para obter mais informações sobre a criação de um estágio, consulte CREATE STAGE.

2. Use o comando PUT para copiar o arquivo JAR do sistema de arquivo local para um estágio.

put
    file:///Users/Me/my_udf/my_udf.jar
    @jar_stage
    auto_compress = false
    overwrite = true
    ;

Copy

Você pode armazenar o comando PUT em um arquivo de script e depois executar esse arquivo através do SnowSQL.

O comando snowsql se assemelha ao seguinte:

snowsql -a <account_identifier> -w <warehouse> -d <database> -s <schema> -u <user> -f put_command.sql

Copy

Este exemplo assume que a senha do usuário é especificada na variável de ambiente SNOWSQL_PWD.

Criar a UDF com o código compilado como manipulador¶

Crie a UDF:

create function decrement_value(i numeric(9, 0))
  returns numeric
  language java
  imports = ('@jar_stage/my_udf.jar')
  handler = 'mypackage.MyUDFHandler.decrementValue'
  ;

Chame a UDF:

select decrement_value(-15);
+----------------------+
| DECREMENT_VALUE(-15) |
|----------------------|
|                  -16 |
+----------------------+