Java UDF 처리기 생성하기

이 항목에서는 UDF(사용자 정의 함수)의 Java 처리기를 작성하는 방법에 대해 설명합니다. Java UDF를 작성할 때 Snowflake가 UDF 논리로 실행되도록 Java 코드를 작성합니다. 이 Java 코드는 UDF의 처리기입니다.

CREATE FUNCTION 과 함께 UDF를 배포하여 UDF의 이름을 지정하고 Java 메서드를 UDF가 호출될 때 사용할 처리기로 지정합니다. SQL을 사용한 UDF 생성에 대한 자세한 내용은 UDF 만들기 섹션을 참조하십시오.

더 많은 예시 코드는 Java UDF 처리기의 예 섹션을 참조하십시오.

이 항목의 내용:

Java로 UDF 처리기 작성하기

Java UDF 처리기를 작성할 때 다음 요구 사항과 지침을 사용하십시오.

  • 클래스를 public으로 정의하십시오.

  • 클래스 내에서 UDF 처리기로 사용할 공용 메서드를 하나 이상 선언합니다.

    인라인 UDF의 경우 처리기 메서드를 하나만 선언합니다. 대신 클래스를 스테이징된 처리기로 JAR에 패키징하려는 경우 여러 개의 처리기 메서드를 선언한 이후에 각각을 CREATE FUNCTION 문의 HANDLER 절을 사용하여 처리기로 지정할 수 있습니다.

    인라인 처리기와 스테이징된 처리기의 차이점에 대한 자세한 내용은 처리기 코드를 인라인 또는 스테이지에 유지하기 섹션을 참조하십시오.

    필요한 경우 처리기 메서드로 호출할 다른 메서드를 선언할 수 있습니다.

    각 처리기 메서드에 대해 다음 요구 사항과 지침을 사용합니다.

    • 정적이든 비정적이든, 처리기 메서드를 공용으로 선언합니다.

      메서드가 비정적인 경우 클래스는 또한 인자가 없는 생성자를 선언하거나 생성자를 전혀 선언하지 않아야 합니다.

      Snowflake는 클래스를 인스턴스화할 때 생성자에 어떤 인자도 전달하지 않습니다. 생성자에서 오류가 발생하는 경우, 이 오류는 예외 메시지와 함께 사용자 오류로서 발생합니다.

    • 적절한 반환 형식을 지정하십시오.

      반환 형식은 SQL-Java 형식 매핑 테이블Java Data Type 열에 지정된 데이터 타입 중 하나여야 합니다. 반환 형식은 CREATE FUNCTION 문의 RETURNS 절에 지정된 SQL 데이터 타입과 호환되어야 합니다.

    • 각 처리기 메서드 인자(있는 경우)가 SQL-Java Type Mappings 테이블Java Data Type 열에 지정된 데이터 타입인지 확인합니다.

      Java 변수의 데이터 타입을 선택할 때 Snowflake에서 전송(및 반환)될 수 있는 데이터의 가능한 최댓값 및 최솟값을 고려하십시오.

    • 주어진 Java 클래스에서 메서드를 오버로드하는 경우 Snowflake는 메서드 인자의 유형 이 아닌 개수 만 사용하여 클래스 내에서 처리기 메서드를 구별한다는 점을 명심하십시오. 데이터 타입을 기반으로 확인하는 것은 비실용적입니다. 일부 SQL 데이터 타입은 둘 이상의 Java 데이터 타입에 맵핑될 수 있고 따라서 잠재적으로 둘 이상의 처리기 메서드 서명에 맵핑될 수 있기 때문입니다.

      예를 들어 어떤 클래스에서 두 Java 메서드가 동일 이름과 동일 수의 인자를 갖고 데이터 타입은 다른 경우, 이러한 메서드 중 하나를 처리기로 사용하는 UDF를 호출하면 다음과 유사한 오류가 생성됩니다.

      Cannot determine which implementation of handler "handler name" to invoke since there are multiple
      definitions with <number of args> arguments in function <user defined function name> with
      handler <class name>.<handler name>
      

      웨어하우스를 사용할 수 있는 경우, UDF가 만들어질 때 오류가 감지됩니다. 그렇지 않은 경우, UDF가 호출될 때 오류가 발생합니다.

    • 각 처리기 메서드와 각 메서드가 호출하는 메서드에서 Java UDF에 대해 Snowflake가 적용한 제약 조건을 준수합니다. 이러한 제약 조건에 대한 자세한 내용은 Snowflake에서 적용한 제약 조건 내에서 유지되는 처리기 설계하기 섹션을 참조하십시오.

클래스 경로에 종속 항목 추가하기

처리기 코드에 외부 JAR 파일에 패키징된 클래스가 필요할 때는 처리기에서 사용할 수 있는 Snowflake 관리 클래스 경로에 이러한 종속 항목을 추가할 수 있습니다. 다음은 Java UDF 처리기에서 볼 수 있는 클래스 경로에 JAR 파일을 추가하는 방법을 설명합니다. 자세한 내용은 코드에 종속성을 사용할 수 있도록 만들기 섹션을 참조하십시오.

파일 정리

Java 코드를 컴파일하여 JAR 파일을 직접 만들 계획이라면 아래와 같이 파일을 구성할 수 있습니다. 이 예에서는 Java의 패키지 메커니즘을 사용할 계획이라고 가정합니다.

  • developmentDirectory

    • packageDirectory

      • class_file1.java

      • class_file2.java

    • classDirectory

      • class_file1.class

      • class_file2.class

    • manifest_file.manifest(선택 사항)

    • jar_file.jar

    • put_command.sql

developmentDirectory

이 디렉터리에는 Java UDF를 만드는 데 필요한 프로젝트별 파일이 포함되어 있습니다.

packageDirectory

이 디렉터리에는 패키지에 컴파일하고 포함할 .java 파일이 포함되어 있습니다.

class_file#.java

이 파일에는 UDF의 Java 소스 코드가 포함되어 있습니다.

class_file#.class

이들은 .java 파일을 컴파일하여 만들어진 .class 파일입니다.

manifest_file.manifest

.class 파일(및 필요에 따라 종속성 JAR 파일)을 JAR 파일에 결합할 때 사용되는 선택적 매니페스트 파일입니다.

jar_file.jar

UDF 코드가 포함된 JAR 파일입니다.

put_command.sql

이 파일에는 JAR 파일을 Snowflake 스테이지 에 복사하는 SQL PUT 명령이 포함되어 있습니다.

Java 코드 컴파일 및 JAR 파일 생성

컴파일된 Java 코드가 포함된 JAR 파일을 만들려면:

  • javac를 사용하여 .java 파일을 .class 파일로 컴파일하십시오.

    버전 11.x보다 최신 버전의 컴파일러를 사용하는 경우, 《-release》 옵션을 사용하여 대상 버전이 버전 11임을 지정할 수 있습니다.

  • .class 파일을 JAR 파일에 넣으십시오. 여러 클래스 파일(및 기타 JAR 파일)을 JAR 파일에 패키지할 수 있습니다.

    예:

    jar cf ./my_udf.jar MyClass.class
    
    Copy

    처리기 클래스가 패키지에 있으면 매니페스트 파일이 필수적이고, 그렇지 않으면 선택 사항입니다. 다음 예에서는 매니페스트 파일을 사용합니다.

    jar cmf my_udf.manifest ./my_udf.jar example/MyClass.class
    
    Copy

    모든 종속성이 포함된 jar 파일을 빌드하려면 maven-assembly-plugin과 함께 Maven의 mvn package 명령을 사용할 수 있습니다. maven-assembly-plugin에 대한 자세한 내용은 Maven 사용 페이지 를 참조하십시오.

    Snowflake는 표준 Java 라이브러리 (예: java.util)를 자동으로 제공합니다. 코드에서 이러한 라이브러리를 호출하는 경우 이를 JAR 파일에 포함할 필요가 없습니다.

    라이브러리에서 호출하는 메서드는 Java 메서드와 동일한 Snowflake 부과 제약 조건을 따라야 합니다. 이러한 제약 조건에 대한 자세한 내용은 Snowflake에서 적용한 제약 조건 내에서 유지되는 처리기 설계하기 섹션을 참조하십시오.

JAR 파일을 스테이지에 복사

Snowflake가 처리기 메서드를 포함한 JAR에서 읽도록 하려면 JAR를 다음 종류의 스테이지 중 하나로 복사해야 합니다.

  • 사용자 또는 명명된 내부 스테이지.

    Snowflake는 현재 테이블 스테이지를 사용하여 UDF 처리기가 있는 JAR 파일을 저장하는 기능을 지원하지 않습니다. 내부 스테이지에 대한 자세한 내용은 로컬 파일을 위한 내부 스테이지 선택하기 섹션을 참조하십시오.

  • 외부 스테이지.

JAR 파일을 호스팅하는 스테이지는 UDF 소유자 가 읽을 수 있어야 합니다.

일반적으로 PUT 명령을 사용하여 명명된 내부 스테이지로 JAR를 업로드합니다. Snowflake GUI를 통해 PUT 명령을 실행할 수 없으며, SnowSQL을 사용해 PUT 을 실행할 수 있습니다. .jar 파일을 스테이지에 복사하는 예제 PUT 명령은 Java UDF 처리기의 예 섹션을 참조하십시오.

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

경고 및 모범 사례

JAR 파일을 삭제하거나 이름을 바꾸면 더 이상 UDF를 호출할 수 없습니다.

JAR 파일을 업데이트해야 하는 경우:

  • UDF를 호출할 수 없는 동안 업데이트하십시오.

  • 이전 .jar 파일이 아직 스테이지에 있는 경우, PUT 명령에 OVERWRITE=TRUE 절이 포함되어야 합니다.

참고

UDF와 관련된 작업을 수행하는 사용자는 작업에 필요한 권한이 할당된 역할이 있어야 합니다. 자세한 내용은 Granting Privileges for User-Defined Functions 섹션을 참조하십시오.