Java UDF 처리기의 예¶

인라인 Java UDF에 NULL 전달¶

이는 위에서 정의한 echo_varchar() UDF를 사용합니다. SQL NULL 값은 암시적으로 Java null 로 변환되고 해당 Java null 이 반환되어 암시적으로 SQL NULL 로 다시 변환됩니다.

UDF를 호출합니다.

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

ARRAY를 통해 전달¶

Java 매개 변수를 배열로 선언하십시오. 예를 들어, 다음 메서드의 세 번째 매개 변수는 문자열 배열입니다.

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

Copy

다음은 완전한 예입니다.

테이블을 만들고 로딩합니다.

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

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

UDF를 호출합니다.

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

Copy

Varargs를 통해 전달¶

varargs를 사용하는 것은 배열을 사용하는 것과 매우 유사합니다.

Java 코드에서 Java의 varargs 선언 스타일을 사용하십시오.

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

Copy

다음은 완전한 예입니다. 이 예와 이전 예(배열의 경우) 간의 유일한 중요한 차이점은 메서드에 대한 매개 변수 선언입니다.

테이블을 만들고 로딩합니다.

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

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

UDF를 호출합니다.

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

Copy

전제 조건¶

다음을 수행하여 코드에 스테이지의 파일을 사용할 수 있도록 해야 Java 처리기 코드가 해당 파일을 읽을 수 있습니다.

1. 처리기가 사용할 수 있는 스테이지를 만듭니다.

   외부 스테이지 또는 내부 스테이지를 사용할 수 있습니다. 내부 스테이지를 사용하는 경우 사용자 또는 명명된 스테이지여야 합니다. Snowflake는 현재 UDF 종속 항목에 테이블 스테이지를 사용할 수 있도록 지원하지 않습니다. 스테이지 생성에 대한 자세한 내용은 CREATE STAGE 섹션을 참조하십시오. 내부 스테이지 유형 선택에 대한 자세한 내용은 로컬 파일을 위한 내부 스테이지 선택하기 섹션을 참조하십시오.

   스테이지에서 읽는 SQL 작업을 수행하는 역할에 스테이지에 대한 적절한 권한을 할당해야 한다는 점에 유의하십시오. 자세한 내용은 Granting Privileges for User-Defined Functions 섹션을 참조하십시오.

2. 코드로 읽을 파일을 스테이지에 복사합니다.

   PUT 명령을 사용하여 로컬 드라이브에서 스테이지로 파일을 복사할 수 있습니다. 명령 참조는 PUT 섹션을 참조하십시오. PUT으로 파일을 스테이징하는 자세한 방법은 로컬 파일 시스템에서 데이터 파일 스테이징하기 섹션을 참조하십시오.

IMPORTS에서 정적으로 지정된 파일 읽기¶

처리기는 CREATE FUNCTION 명령의 IMPORTS 절에 스테이지 경로가 지정된 파일을 읽을 수 있습니다.

IMPORTS 절에 파일을 지정하면 Snowflake는 해당 파일을 스테이지에서 UDF의 홈 디렉터리 (가져오기 디렉터리 라고도 함)로 복사합니다. 이 디렉터리는 UDF가 실제로 파일을 읽는 디렉터리입니다.

가져온 파일은 단일 디렉터리에 복사되고, 해당 디렉터리 내에서 고유한 이름을 가져야 하기 때문에 IMPORTS 절의 각 파일은 고유한 이름을 가져야 합니다. 해당 파일이 다른 스테이지에서 시작하거나 스테이지 내의 다른 하위 디렉터리에서 시작하더라도 마찬가지입니다.

다음 예에서는 파일을 읽는 Java UDF를 만들고 호출합니다.

아래 Java 소스 코드는 readFile 이라는 Java 메서드를 만듭니다. 이 UDF는 이 메서드를 사용합니다.

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();
    }
}

다음 SQL 코드는 UDF를 만듭니다. 이 코드는 Java 소스 코드가 컴파일되어, UDF가 가져오는 TestReadRelativeFile.jar 이라는 JAR 파일에 저장되었다고 가정합니다. 두 번째 및 세 번째 가져온 파일인 my_config_file_1.txt 및 my_config_file_2.txt 는 UDF가 읽을 수 있는 구성 파일입니다.

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';

이 코드는 UDF를 호출합니다.

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

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

SnowflakeFile 을 사용하여 동적으로 지정된 파일 읽기¶

SnowflakeFile 클래스의 메서드를 사용하여 Java 처리기 코드로 스테이지에서 파일을 읽을 수 있습니다. SnowflakeFile 클래스는 Snowflake의 Java UDF 처리기가 사용할 수 있는 클래스 경로에 포함됩니다.

UDF 코드를 로컬에서 개발하려면 SnowflakeFile 이 포함된 Snowpark JAR을 코드의 클래스 경로에 추가하십시오. snowpark.jar 에 대한 정보는 Snowpark Java를 위한 개발 환경 설정하기 섹션을 참조하십시오. Snowpark 클라이언트 애플리케이션은 이 클래스를 사용할 수 없습니다.

SnowflakeFile 을 사용할 때는 CREATE FUNCTION 문을 포함한 SQL에서처럼 UDF를 생성할 때 스테이징된 파일이나 SnowflakeFile 이 포함된 JAR을 IMPORTS 절로도 지정할 필요가 없습니다.

다음 예제의 코드에서는 SnowflakeFile 을 사용하여 지정된 스테이지 위치에서 파일을 읽습니다. getInputStream 메서드의 InputStream 을 사용하여 파일의 내용을 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;
  }
}
$$;

파일 삽입 공격 가능성을 줄이기 위해 범위가 지정된 URL에서 파일 위치를 전달하는 UDF를 호출합니다.

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);

InputStream 을 사용하여 동적으로 지정된 파일 읽기¶

처리기 함수의 인자를 InputStream 변수로 만들어 파일 내용을 java.io.InputStream 으로 직접 읽을 수 있습니다. 이것은 함수의 호출자가 파일 경로를 인자로 전달하고 싶을 때 유용할 수 있습니다.

다음 예제의 코드에는 InputStream 을 받아 int 를 반환하는 처리기 함수 sumTotalSales 가 있습니다. 런타임에 Snowflake는 file 변수의 경로에 있는 파일의 내용을 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;
  }
}
$$;

파일 삽입 공격 가능성을 줄이기 위해 범위가 지정된 URL에서 파일 위치를 전달하는 UDF를 호출합니다.

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

Java 처리기 코드 생성 및 컴파일하기¶

1. 프로젝트의 루트 디렉터리(이 경우 my_udf)에서 소스 .java 파일을 보관할 src 하위 디렉터리, 그리고 생성된 .class 파일을 보관할 classes 하위 디렉터리를 생성합니다.

   다음과 유사한 디렉터리 계층 구조가 있어야 합니다.

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

   Copy

2. src 디렉터리에서, 클래스가 mypackage 패키지에 있는 .java 파일을 보유할 mypackage 라는 디렉터리를 생성합니다.

3. mypackage 디렉터리에서, 소스 코드가 포함된 MyUDFHandler.java 파일을 생성합니다.

   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. 프로젝트 루트 디렉터리(이 경우 my_udf)에서 javac 명령을 사용하여 소스 코드를 컴파일합니다.

   다음 예의 javac 명령은 MyUDFHandler.java 를 컴파일하여 classes 디렉터리에 MyUDFHandler.class 파일을 생성합니다.

   javac -d classes src/mypackage/MyUDFHandler.java
   

   Copy

   이 예에는 다음 인수가 포함됩니다.

   • -d classes – 생성된 클래스 파일이 기록되어야 하는 디렉터리.

   • src/mypackage/MyUDFHandler.java – 형식의 .java 파일 경로: source_directory/package_directory/Java_file_name.

컴파일된 코드를 JAR 파일로 패키징하기¶

1. 선택적으로, 프로젝트 루트 디렉터리에서, 다음 속성을 포함하는 my_udf.manifest 라는 매니페스트 파일을 생성합니다.

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

   Copy

2. 프로젝트 루트 디렉터리에서 jar 명령을 실행하여, .class 파일과 매니페스트가 포함된 JAR 파일을 생성합니다.

   다음 예의 jar 명령은 mypackage 패키지 폴더에 생성된 MyUDFHandler.class 파일을 my_udf.jar 이라는 .jar 파일에 넣습니다. -C ./classes 플래그는 .class 파일의 위치를 지정합니다.

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

   Copy

   이 예에는 다음 인수가 포함됩니다.

   • cmf – 명령 인수: c 는 JAR 파일을 생성하고, m 은 지정된 .manifest 파일을 사용하고, f 는 지정된 이름을 JAR 파일에 부여합니다.

   • my_udf.manifest – 매니페스트 파일.

   • my_udf.jar – 생성할 JAR 파일의 이름.

   • -C ./classes – 생성된 .class 파일을 포함하는 디렉터리.

   • mypackage/MyUDFHandler.class – JAR에 포함할 .class 파일의 패키지 및 이름.

컴파일된 처리기가 있는 JAR 파일을 스테이지에 업로드하기¶

1. Snowflake에서 jar_stage 라는 스테이지를 생성하여, UDF 핸들러가 포함된 JAR 파일을 저장합니다.

   스테이지 생성에 대한 자세한 내용은 CREATE STAGE 섹션을 참조하십시오.

2. PUT 명령을 사용하여 JAR 파일을 로컬 파일 시스템에서 스테이지로 복사하십시오.

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

Copy

PUT 명령을 스크립트 파일에 저장한 다음, SnowSQL 을 통해 해당 파일을 실행할 수 있습니다.

snowsql 명령은 다음과 유사합니다.

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

Copy

이 예에서는 사용자의 비밀번호가 SNOWSQL_PWD 환경 변수에 지정되어 있다고 가정합니다.

컴파일된 코드를 처리기로 사용하여 UDF 만들기¶

UDF를 만듭니다.

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

UDF를 호출합니다.

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