Pipeline Builder에서 Python 함수 사용

Pipeline Builder는 게시한 Python 함수를 사용자 정의 함수(User-defined function, UDF)로 사용할 수 있습니다. Java UDF도 지원하며 이 장은 Python 입력과 실행 방식을 설명합니다.

행 단위 실행

Python 함수는 파이프라인의 sidecar 컨테이너에서 실행합니다. 별도의 함수 배포를 만들지 않아도 파이프라인 크기에 따라 확장하며 다른 변환처럼 출력을 미리 볼 수 있습니다.

UDF는 행마다 한 번 실행합니다. 선택한 입력 열의 셀 값을 함수 인수에 전달하고 반환 값을 출력 열의 셀로 만듭니다. 전체 표나 pandas 또는 Spark DataFrame을 인수로 전달하는 방식은 아닙니다.

from functions.api import function


@function
def full_name(first_name: str, last_name: str) -> str:
    return f"{first_name} {last_name}"

first_name과 last_name 매개변수를 해당 입력 열에 매핑하면 각 행에 대해 계산한 문자열을 새 열에 기록합니다. 문자열, 숫자, Boolean과 datetime 같은 지원 스칼라 타입을 반환할 수 있습니다.

온톨로지 객체와 객체 집합 등 온톨로지 타입을 입력 또는 반환에 쓰는 함수는 Pipeline Builder에서 가져올 수 없으며 함수 목록에 나타나지 않습니다.

여러 값을 구조체로 반환

관련 값을 함께 반환하려면 사용자 지정 구조체 타입을 사용합니다. Pipeline Builder에는 구조체 열 하나가 생기며 Get struct field 변환으로 필드를 나눌 수 있습니다.

from dataclasses import dataclass
from functions.api import Double, function


@dataclass
class Stats:
    total: Double
    average: Double


@function
def compute_stats(a: Double, b: Double) -> Stats:
    total = a + b
    return Stats(total=total, average=total / 2)

파이프라인에 가져오기

함수를 Python 저장소에서 작성하고 게시한 뒤 Pipeline Builder에서 대상 파이프라인을 엽니다.

게시한 Python 함수를 추가할 Pipeline Builder 그래프

그래프에서 가져오는 경로는 다음과 같습니다.

위쪽 Reusables > User-defined functions를 엽니다.

그래프에서 User-defined functions를 여는 Reusables 메뉴

Import UDF를 선택하고 함수를 검색합니다.
함수 옆 Add를 선택해 Imported 표지를 확인합니다.

검색한 Python 함수에 Add를 선택하여 가져오는 창

대화 상자를 닫고 함수가 필요한 위치에서 Transform을 선택합니다. 왼쪽 UDFs 탭에서 가져온 함수를 고릅니다.

변환 선택기에서 바로 가져올 수도 있습니다. 그래프의 Transform에서 함수 이름을 입력하고 Search unimported UDFs를 선택합니다.

원하는 함수에 마우스를 올리고 Import를 선택합니다.

검색 결과의 UDF를 변환 선택기에서 직접 가져오는 Import 항목

입력 열과 매개변수, 출력 열을 지정하고 Apply를 선택합니다.

Python UDF의 입력 열과 출력 매핑을 지정한 변환 정의

그래프에 추가된 함수의 출력을 미리 볼 수 있습니다.

Pipeline Builder 그래프에 연결된 Python UDF와 출력 미리보기

외부 API

외부 시스템 접근 함수를 게시하여 UDF로 사용할 수 있습니다. 사용하는 모든 소스는 파이프라인으로 가져올 수 있도록 설정해야 합니다. Data Connection의 소스에서 Connection settings > Code import configuration을 열고 해당 옵션을 활성화합니다.

외부 소스를 파이프라인에 가져오도록 허용하는 Code import configuration

설정과 함수 게시가 끝나면 다른 UDF와 같은 절차로 가져옵니다. 행 단위 실행이므로 외부 요청도 처리하는 행 수에 따라 발생할 수 있습니다.

직접 온톨로지 접근 제한

Pipeline Builder UDF 안에서 FoundryClient()나 OSDK로 온톨로지에 직접 접근하면 EnvironmentNotConfigured 오류가 발생합니다. 빌드 사이에서 데이터의 보안 표지가 사라지거나 유출되는 것을 막기 위한 제한입니다.

온톨로지 데이터가 필요하면 다음 경로를 사용할 수 있습니다.

별도의 함수나 API가 온톨로지를 조회하도록 구성하고, 그 엔드포인트를 호출하는 외부 소스를 UDF에 가져옵니다. 외부 소스의 인증, 권한과 파이프라인 가져오기 설정이 필요하며 UDF에 OSDK 클라이언트를 직접 생성하는 경로와 다릅니다.
업무에 맞는 온톨로지 관련 데이터를 별도 데이터셋으로 유지하고 파이프라인에 조인합니다. 중복 제거와 존재 여부 확인을 위해 행마다 API를 호출할 필요가 없어집니다.

외부 경로를 선택할 때도 API가 읽는 데이터의 권한 및 출력 데이터셋의 보안 표지를 설정해야 합니다.