Lakeflow Designer 커스텀 연산자용 로직 작성

오퍼레이터 로직은 커스텀 오퍼레이터가 실행하는 코드입니다. python-run-function 연산자의 경우, 인라인 Python run() 함수입니다. uc-udf 또는 uc-udtf 연산자의 경우, SQL 또는 Python으로 작성된 Unity 카탈로그 함수입니다.

로직을 작성하는 것은 공유 커스텀 연산자를 빌드하는 과정의 한 단계입니다. 로직을 작성하고 테스트한 후, YAML로 연산자를 설명해서 Lakeflow Designer가 UI에서 어떻게 표시할지 알 수 있게 하고, 등록해서 Operators 창에 나타나도록 합니다. 한 오퍼레이터에 대한 모든 단계를 함께 보려면, Tutorial: 복리 이자 계산기 오퍼레이터와 같은 튜토리얼을 따라가세요.

python-run-function 연산자를 작성합니다

모든 python-run-function 연산자는 다음 함수를 정의해야 합니다.run()

def run(config: Dict[str, Any], inputs: Dict[str, Any], spark) -> Dict[str, Any]:
  • config: 속성 이름으로 키가 지정된 UI에서 사용자가 구성한 값입니다.
  • inputs: 입력 포트 name로 키가 지정된 입력 데이터 프레임입니다.
  • spark: 현재 활성 상태인 SparkSession입니다.
  • 반환: 출력 포트 name 값과 데이터프레임을 매핑하는 사전입니다.

다음 예제에서는 입력 DataFrame에서 행을 필터링합니다.

def run(config, inputs, spark):
    df = inputs["in"]
    filtered = df.filter(config["filter_expression"])
    return {"out": filtered}

함수를 등록하기 전에 테스트하려면 샘플 데이터가 포함된 노트북에서 호출하세요:

test_df = spark.createDataFrame(
    [("Alice", 100), ("Bob", 200)],
    ["name", "amount"]
)

result = run(
    config={"filter_expression": "amount > 100"},
    inputs={"in": test_df},
    spark=spark
)

result["out"].show()

운영자에게 외부 pip 패키지가 필요한 경우 YAML에 environment 필드를 추가합니다.

environment:
  environment_version: '4'
  dependencies:
    - requests==2.31.0
    - beautifulsoup4==4.12.0

UDF 또는 UDTF 연산자를 작성하세요

Unity 카탈로그 함수는 SQL이나 Python으로 작성할 수 있습니다. Python 함수는 SQL CREATE FUNCTION 문에 래핑됩니다.

SQL 함수:

CREATE OR REPLACE FUNCTION my_catalog.my_schema.calculate_bmi(weight_kg DOUBLE, height_m DOUBLE)
RETURNS DOUBLE
LANGUAGE SQL
RETURN
  SELECT weight_kg / (height_m * height_m);

Python 함수(SQL로 래핑):

CREATE OR REPLACE FUNCTION my_catalog.my_schema.calculate_bmi(weight_kg DOUBLE, height_m DOUBLE)
RETURNS DOUBLE
LANGUAGE PYTHON
AS $$
  return weight_kg / (height_m ** 2)
$$;

UDF는 한 번에 단일 값을 처리하고 계산된 값을 반환합니다. UTF는 행별로 테이블 행을 처리하고 모든 행에서 상태를 유지할 수 있습니다. 열 수준 변환에는 uc-udf를 사용하고 ML 클러스터링 또는 집계와 같은 작업에는 uc-udtf를 사용합니다.

UDTF 핸들러 클래스는 각 입력 행마다 실행되는 eval()를 정의합니다. 선택적으로 상태를 설정하는 terminate()와 모든 행 이후 최종 결과를 생성하는 __init__()도 정의합니다. Unity 카탈로그에서 Python 사용자 정의 테이블 함수(UDTF)를 확인하세요.

class MyOperator:
    def __init__(self):
        # Optional. Called before processing - initialize any values needed.
        ...

    def eval(self, row):
        # Required. Called one time per input row - process or accumulate data here.
        ...

    def terminate(self):
        # Optional. Called after all rows - perform final calculations and yield results.
        ...

비고

UDTF 반환 테이블에는 고정된 명시적 형식이 있어야 합니다. 반환 구성에서는 입력 열 형식을 참조할 수 없습니다.

미리보기 중 부수 효과는 건너뛰세요

Lakeflow Designer는 디자인 모드에서 미리 보기를 지원합니다. 외부 API를 호출하거나 외부 시스템에 쓰기 작업을 수행하는 연산자의 경우, 미리 보기 중 부작용을 건너뛸 수 있도록 is_preview 구성 속성을 추가하세요. 사용자는 부작용이 있는 연산자를 실행하기 위해 Run을 클릭합니다. 내장된 Python 연산자는 config["is_preview"]을 자동으로 읽기 때문에 이 속성이 필요하지 않습니다. Python 미리보기 모드를 참조하세요.

config:
  type: object
  properties:
    is_preview:
      type: boolean
      format: is_preview
      default: false

Lakeflow Designer는 미리 보기 중에 이 값을 true 자동으로 설정합니다. 부작용을 건너뛰도록 로직에서 이를 확인하세요.

# In a python-run-function
if config.get("is_preview"):
    return {"out": inputs["in"]}
-- In a UC function (SQL)
CASE WHEN is_preview THEN 'preview' ELSE /* actual work */ END

Unity 카탈로그 HTTP 연결을 사용하여 외부 API를 호출하세요

SQL Unity 카탈로그 함수를 기반으로 외부 API를 호출하는 커스텀 연산자라면, Unity 카탈로그 HTTP 연결을 사용하여 자격 증명을 안전하게 저장하세요:

CREATE CONNECTION my_api_connection TYPE HTTP OPTIONS (
  host 'https://api.example.com',
  port '443',
  base_path '/v1/',
  bearer_token 'your-token-here'
);

그런 다음 SQL UDF에서 http_request() 함수를 사용하여 해당 연결을 사용하세요. 자세한 내용은 외부 HTTP 서비스에 대한 연결을 참조하세요.

WorkspaceClient로 작업 공간 리소스에 접근하기

python-run-function 연산자의 경우 Azure Databricks WorkspaceClient 사용하여 작업 영역 리소스 및 외부 API에 액세스할 수 있습니다.

def run(config, inputs, spark):
    from databricks.sdk import WorkspaceClient
    w = WorkspaceClient()
    # Use w to access workspace resources

추가 리소스